swallowkit 2.0.0-alpha.1 → 2.0.0-alpha.10

package/src/machine/index.ts

@@ -3,7 +3,7 @@ import { isSwallowKitProject } from "../core/config";
 import { createModelOperation } from "../core/operations/create-model";
 import { applyScaffoldOperation } from "../core/operations/scaffold-apply";
 import { applyAuthOperation, planAuthOperation } from "../core/operations/auth-operations";
-import { applyProvisionOperation, planProvisionOperation } from "../core/operations/provision-operations";
+import { applyProvisionOperation, inspectProvisionOperation, planProvisionOperation } from "../core/operations/provision-operations";
 import { ProcessExitInterceptError } from "../core/operations/runtime";
 import { inspectInfra } from "../core/project/infra";
 import { runMachineScaffoldOperation } from "../core/operations/scaffold-machine";
@@ -58,6 +58,7 @@ function writeMachineError(command: string, error: unknown): void {
     ok: false,
     command,
     status: resolveMachineErrorStatus(error),
+    ...(error instanceof MachineCommandError && error.nextActions?.length ? { nextActions: error.nextActions } : {}),
     error: toMachineError(error),
   };
   writeMachineResponse(response);
@@ -140,6 +141,17 @@ function createMachineProgram(): Command {
     .showHelpAfterError(false);
 
   const inspect = new Command("inspect");
+  inspect
+    .command("provision")
+    .description("Read/wait for an original provision deployment without writes or replay")
+    .requiredOption("--plan <runId>", "Original provision plan/execution checkpoint ID")
+    .option("--wait-seconds <seconds>", "Bounded read-only wait, 0-3600 seconds (default: 0)", Number)
+    .action(async (options: { plan: string; waitSeconds?: number }) => {
+      await handleMachineAction("inspect-provision", async () => {
+        ensureProjectForMachine();
+        return inspectProvisionOperation({ planId: options.plan, waitSeconds: options.waitSeconds });
+      }, (result) => ({ status: result.status, nextActions: result.nextActions }));
+    });
   inspect
     .command("project")
     .description("Inspect SwallowKit project metadata")
@@ -274,7 +286,8 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets", false)
-    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+    .option("--skip-infra", "Do not create or update anything under infra/ (container migration is reported as pending)", false)
+    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       await handleMachineAction("generate-scaffold", async () => {
         ensureProjectForMachine();
         return runMachineScaffoldOperation({
@@ -282,6 +295,7 @@ function createMachineProgram(): Command {
         functionsDir: options.functionsDir,
         apiDir: options.apiDir,
         apiOnly: options.apiOnly,
+        skipInfra: options.skipInfra,
       });
       });
     });
@@ -294,7 +308,8 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components in the plan", false)
-    .action(async (models: string[], options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+    .option("--skip-infra", "Exclude all infra/ changes (container migration) from the plan", false)
+    .action(async (models: string[], options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       await handleMachineAction(
         "plan-scaffold",
         async () => {
@@ -307,6 +322,7 @@ function createMachineProgram(): Command {
                 functionsDir: options.functionsDir,
                 apiDir: options.apiDir,
                 apiOnly: options.apiOnly,
+                skipInfra: options.skipInfra,
               })
             );
           }
@@ -316,12 +332,20 @@ function createMachineProgram(): Command {
           const plans = "plans" in data ? data.plans : [data];
           return {
             status: plans.some((planData) => planData.requiresApproval) ? "requires-human" : "complete",
-            nextActions: plans.map((planData) => ({
-              command: `swallowkit machine apply scaffold --plan ${planData.planId}${planData.requiresApproval ? " --approve" : ""}`,
-              description: planData.requiresApproval
-                ? `Apply the plan for ${planData.model} after reviewing the listed conflicts (requires --approve).`
-                : `Apply the plan for ${planData.model}.`,
-            })),
+            nextActions: [
+              ...plans.map((planData) => ({
+                command: `swallowkit machine apply scaffold --plan ${planData.planId}${planData.requiresApproval ? " --approve" : ""}`,
+                description: planData.requiresApproval
+                  ? `Apply the plan for ${planData.model} after reviewing the listed conflicts (requires --approve).`
+                  : `Apply the plan for ${planData.model}.`,
+              })),
+              ...plans
+                .filter((planData) => planData.warnings.some((warning) => warning.startsWith("infra-skipped:")))
+                .map((planData) => ({
+                  command: `swallowkit migrations add-model ${planData.model}`,
+                  description: `Later, when infrastructure changes are allowed, generate only the Cosmos DB container migration for ${planData.model}.`,
+                })),
+            ],
           };
         }
       );
@@ -360,7 +384,7 @@ function createMachineProgram(): Command {
 
   plan
     .command("provision")
-    .description("Preflight Azure provisioning locally; use --what-if for an az what-if analysis (requires az login)")
+    .description("Review local infrastructure and current Azure state without writes (requires az login)")
     .requiredOption("-g, --resource-group <name>", "Resource group name")
     .requiredOption("--location <region>", "Primary location for Functions and Cosmos DB")
     .requiredOption("--swa-location <region>", "Static Web App location")
@@ -369,7 +393,8 @@ function createMachineProgram(): Command {
     .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
     .option("--baseline <version>", "Baseline version for adoption", (value) => Number(value))
     .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
-    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
+    .option("--resume-deployment <name>", "Recover a matching older baseline deployment without re-submitting Bicep")
+    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean; resumeDeployment?: string }) => {
       await handleMachineAction(
         "plan-provision",
         async () => {
@@ -383,6 +408,7 @@ function createMachineProgram(): Command {
             adoptExisting: options.adoptExisting,
             baseline: options.baseline,
             reconcile: options.reconcile,
+            resumeDeployment: options.resumeDeployment,
           });
         },
         (planData) => ({
@@ -408,10 +434,11 @@ function createMachineProgram(): Command {
     .option("--functions-dir <dir>", "Functions directory")
     .option("--api-dir <dir>", "API routes directory")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets")
+    .option("--skip-infra", "Do not create or update anything under infra/ (container migration is reported as pending)")
     .action(
       async (
         models: string[],
-        options: { plan?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }
+        options: { plan?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }
       ) => {
         await handleMachineAction(
           "apply-scaffold",
@@ -433,6 +460,7 @@ function createMachineProgram(): Command {
                 functionsDir: options.functionsDir,
                 apiDir: options.apiDir,
                 apiOnly: options.apiOnly,
+                skipInfra: options.skipInfra,
               });
             }
             const results = [];
@@ -444,20 +472,30 @@ function createMachineProgram(): Command {
                   functionsDir: options.functionsDir,
                   apiDir: options.apiDir,
                   apiOnly: options.apiOnly,
+                  skipInfra: options.skipInfra,
                 })
               );
             }
             return { applyType: "scaffold-batch" as const, results };
           },
-          () => ({
-            status: "complete",
-            nextActions: [
-              {
-                command: "swallowkit machine verify project",
-                description: "Verify the project after applying scaffold changes.",
-              },
-            ],
-          })
+          (data) => {
+            const results = "results" in data ? data.results : [data];
+            return {
+              status: "complete",
+              nextActions: [
+                {
+                  command: "swallowkit machine verify project",
+                  description: "Verify the project after applying scaffold changes.",
+                },
+                ...results
+                  .filter((result) => result.warnings.some((warning) => warning.startsWith("infra-skipped:")))
+                  .map((result) => ({
+                    command: `swallowkit migrations add-model ${result.model}`,
+                    description: `The Cosmos DB container migration for ${result.model} is still pending; generate it when infrastructure changes are allowed.`,
+                  })),
+              ],
+            };
+          }
         );
       }
     );
@@ -521,32 +559,25 @@ function createMachineProgram(): Command {
     .description("Apply an approved provisioning plan (always requires --approve; creates billable Azure resources)")
     .requiredOption("--plan <planId>", "Provision plan to apply")
     .option("--approve", "Confirm human approval of the provisioning plan", false)
-    .action(async (options: { plan: string; approve?: boolean }) => {
+    .option("--wait-seconds <seconds>", "Bounded state wait, 0-3600 seconds (default: 300)", Number)
+    .action(async (options: { plan: string; approve?: boolean; waitSeconds?: number }) => {
       await handleMachineAction(
         "apply-provision",
         async () => {
           ensureProjectForMachine();
-          return applyProvisionOperation({ planId: options.plan, approve: options.approve });
+          return applyProvisionOperation({ planId: options.plan, approve: options.approve, waitSeconds: options.waitSeconds });
         },
-        () => ({
-          status: "complete",
-          nextActions: [
-            {
-              command: "swallowkit machine inspect infra",
-              description: "Re-inspect infra assets after provisioning.",
-            },
-          ],
-        })
+        (result) => ({ status: result.status, nextActions: result.nextActions })
       );
     });
 
   const verify = new Command("verify");
   verify
     .command("project")
-    .description("Run verification checks (structure, drift, typecheck) with machine-readable evidence")
+    .description("Run verification checks (structure, drift, typecheck, backend-build) with machine-readable evidence")
     .option(
       "--checks <ids>",
-      "Comma-separated check ids to run (structure,drift,typecheck,build,lint,test, plus custom ids from swallowkit.config verify.checks)"
+      "Comma-separated check ids to run (structure,drift,typecheck,backend-build,build,lint,test, plus custom ids from swallowkit.config verify.checks); quote CSV values in PowerShell"
     )
     .option("--compact", "Suppress info-severity findings/violations from evidence to keep agent-facing output small", false)
     .action(async (options: { checks?: string; compact?: boolean }) => {

package/src/mcp/index.ts

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
 
+import { spawn } from "child_process";
 import * as path from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
-import type { MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
+import type { MachineErrorResponse, MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
 import { getSwallowKitVersion } from "../version";
+import { detectFromProject, getCommands } from "../utils/package-manager";
+import { provisionNextActions } from "../core/operations/provision-operations";
+import {
+  MCP_DELEGATED_FROM_ENV,
+  McpVersionContext,
+  buildPinnedUpdateNotice,
+  decideMcpLaunch,
+  resolveProjectSwallowKit,
+} from "./version-selection";
 
 interface MachineSuccessPayload<TData> {
   ok: true;
@@ -15,13 +25,18 @@ interface MachineSuccessPayload<TData> {
   data: TData;
 }
 
-type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
-type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type MachineCliRunner = (args: string[], signal?: AbortSignal) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+type ToolContentResult = { content: Array<{ type: "text"; text: string }>; isError?: boolean };
+class MachineCliError extends Error {
+  constructor(message: string, readonly response: MachineErrorResponse) {
+    super(message);
+  }
+}
 type ToolDefinition = {
   name: string;
   description: string;
   inputSchema: z.ZodTypeAny;
-  handler: (input: any) => Promise<ToolContentResult>;
+  handler: (input: any, signal?: AbortSignal) => Promise<ToolContentResult>;
 };
 type ExecaModule = typeof import("execa");
 
@@ -34,29 +49,45 @@ function resolveMachineCliEntrypoint(): string {
   return path.resolve(__dirname, "..", "cli", "index.js");
 }
 
-async function defaultMachineCliRunner(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+async function defaultMachineCliRunner(args: string[], signal?: AbortSignal): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const { execa } = await importModule("execa");
-  const result = await execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
+  const child = execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
     reject: false,
   });
-
+  const abort = () => child.kill("SIGTERM", { forceKillAfterTimeout: 6_000 });
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+  let result: Awaited<typeof child>;
+  try { result = await child; } finally { signal?.removeEventListener("abort", abort); }
   return {
     stdout: result.stdout,
     stderr: result.stderr,
-    exitCode: result.exitCode ?? 0,
+    exitCode: result.exitCode ?? 1,
   };
 }
 
 async function executeMachineCommand<TData>(
   args: string[],
-  runMachineCli: MachineCliRunner
+  runMachineCli: MachineCliRunner,
+  signal?: AbortSignal
 ): Promise<MachineSuccessPayload<TData>> {
-  const result = await runMachineCli(args);
+  const interrupted = () => {
+    const runId = args[args.indexOf("--plan") + 1];
+    const response: MachineErrorResponse = {
+      ok: false, command: args.slice(0, 2).join("-"), status: "blocked",
+      error: { code: "provision-interrupted", message: "The local MCP wait was interrupted. Azure may continue; inspect the original checkpoint. No Azure cancellation or successful result is implied.", details: { runId, outcome: "unknown", localFailure: "cancelled" } },
+      nextActions: /^[a-f0-9]{12}$/.test(runId) ? provisionNextActions(runId) : [],
+    };
+    return new MachineCliError(response.error.message, response);
+  };
+  if (signal?.aborted) throw interrupted();
+  const result = await (signal ? runMachineCli(args, signal) : runMachineCli(args));
 
   let parsed: MachineResponse<TData>;
   try {
     parsed = JSON.parse(result.stdout) as MachineResponse<TData>;
   } catch {
+    if (signal?.aborted) throw interrupted();
     throw new Error(result.stderr || result.stdout || "Machine CLI returned invalid JSON.");
   }
 
@@ -64,12 +95,35 @@ async function executeMachineCommand<TData>(
     const detailsSuffix =
       parsed.error.details !== undefined ? `\ndetails: ${JSON.stringify(parsed.error.details)}` : "";
     const statusSuffix = parsed.status ? ` (status: ${parsed.status})` : "";
-    throw new Error(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`);
+    throw new MachineCliError(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`, parsed);
   }
 
   return parsed;
 }
 
+function defaultVersionContext(): McpVersionContext {
+  return {
+    mcpVersion: getSwallowKitVersion(),
+    requestedVersion: "latest",
+    projectVersion: null,
+    selection: "running-version",
+    delegated: false,
+    warnings: [],
+    nextActions: [],
+  };
+}
+
+function mergeNextActions(
+  first: MachineNextAction[] | undefined,
+  second: MachineNextAction[]
+): MachineNextAction[] {
+  const merged = [...(first ?? [])];
+  for (const action of second) {
+    if (!merged.some((existing) => existing.command === action.command)) merged.push(action);
+  }
+  return merged;
+}
+
 function withOperationStatus<TData>(response: MachineSuccessPayload<TData>): Record<string, unknown> {
   const data = response.data && typeof response.data === "object"
     ? (response.data as Record<string, unknown>)
@@ -92,25 +146,41 @@ function jsonTextContent(value: unknown): { content: Array<{ type: "text"; text:
   };
 }
 
-function withSwallowKitMetadata<TData>(data: TData): TData & { metadata: Record<string, unknown> } {
-  const value = data && typeof data === "object" ? data as Record<string, unknown> : { data };
+function withVersionMetadata(data: unknown, context: McpVersionContext): Record<string, unknown> {
+  const value = data && typeof data === "object" && !Array.isArray(data)
+    ? data as Record<string, unknown>
+    : { data };
   const metadata = value.metadata && typeof value.metadata === "object"
     ? value.metadata as Record<string, unknown>
     : {};
+  const existingNextActions = Array.isArray(value.nextActions) ? value.nextActions as MachineNextAction[] : undefined;
+  const nextActions = mergeNextActions(existingNextActions, context.nextActions);
 
   return {
     ...value,
+    ...(nextActions.length > 0 ? { nextActions } : {}),
     metadata: {
       ...metadata,
-      swallowkitVersion: getSwallowKitVersion(),
+      swallowkitVersion: context.mcpVersion,
+      mcp: {
+        version: context.mcpVersion,
+        requestedVersion: context.requestedVersion,
+        projectVersion: context.projectVersion,
+        selection: context.selection,
+        delegated: context.delegated,
+        ...(context.delegatedFrom ? { delegatedFrom: context.delegatedFrom } : {}),
+      },
+      ...(context.warnings.length > 0 ? { warnings: [...context.warnings] } : {}),
     },
-  } as TData & { metadata: Record<string, unknown> };
+  };
 }
 
 export function buildSwallowKitToolDefinitions(
-  runMachineCli: MachineCliRunner = defaultMachineCliRunner
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
 ): ToolDefinition[] {
-  return [
+  const withSwallowKitMetadata = (data: unknown) => withVersionMetadata(data, versionContext);
+  const definitions: ToolDefinition[] = [
     {
       name: "swallowkit_inspect_project",
       description: "Return framework-owned SwallowKit project metadata.",
@@ -169,8 +239,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/; the container migration stays pending."),
       }),
-      handler: async ({ model, functionsDir, apiDir, apiOnly }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, functionsDir, apiDir, apiOnly, skipInfra }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       const args = ["generate", "scaffold", model];
       if (functionsDir) {
         args.push("--functions-dir", functionsDir);
@@ -181,6 +252,9 @@ export function buildSwallowKitToolDefinitions(
       if (apiOnly) {
         args.push("--api-only");
       }
+      if (skipInfra) {
+        args.push("--skip-infra");
+      }
 
       const response = await executeMachineCommand(args, runMachineCli);
       return jsonTextContent(response.data);
@@ -195,14 +269,16 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Exclude all infra/ changes (container migration) from the plan."),
       }),
-      handler: async ({ model, models, functionsDir, apiDir, apiOnly }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, models, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const targets = models && models.length > 0 ? models : model ? [model] : [];
         if (targets.length === 0) throw new Error("Provide model or models.");
         const args = ["plan", "scaffold", ...targets];
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -218,8 +294,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/ (defaults to the plan's setting)."),
       }),
-      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const args = ["apply", "scaffold"];
         if (model) args.push(model);
         if (planId) args.push("--plan", planId);
@@ -227,6 +304,7 @@ export function buildSwallowKitToolDefinitions(
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -252,7 +330,7 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_verify_project",
-      description: "Run verification checks (structure, drift, typecheck by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. summary.done=true means the project passed all checks. Set compact=true to suppress info-severity findings and keep the output small.",
+      description: "Run verification checks (structure, drift, typecheck, backend-build by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. backend-build compiles standalone C#/TypeScript Functions or checks Python syntax; unavailable toolchains are skipped with a reason. summary.done=true means no checks failed, not that skipped checks were validated or runtime/auth flows work. Set compact=true to suppress info-severity findings and keep the output small.",
       inputSchema: z.object({
         checks: z.array(z.string()).optional(),
         compact: z.boolean().optional(),
@@ -362,14 +440,16 @@ export function buildSwallowKitToolDefinitions(
         adoptExisting: z.boolean().optional(),
         baseline: z.number().int().nonnegative().optional(),
         reconcile: z.boolean().optional(),
+        resumeDeployment: z.string().optional(),
       }),
-      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf, adoptExisting, baseline, reconcile }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
+      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf, adoptExisting, baseline, reconcile, resumeDeployment }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean; resumeDeployment?: string }) => {
         const args = ["plan", "provision", "--resource-group", resourceGroup, "--location", location, "--swa-location", swaLocation];
         if (subscription) args.push("--subscription", subscription);
         if (whatIf) args.push("--what-if");
         if (adoptExisting) args.push("--adopt-existing");
         if (baseline !== undefined) args.push("--baseline", String(baseline));
         if (reconcile) args.push("--reconcile");
+        if (resumeDeployment) args.push("--resume-deployment", resumeDeployment);
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -377,46 +457,156 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_apply_provision",
-      description: "Apply an approved provisioning plan. Creates billable Azure resources; approve=true is always required and must reflect explicit human consent.",
+      description: "Apply or resume an approved provision checkpoint with bounded state polling. Never resubmit an attempted deployment; finish tags/ledger only after Azure Succeeded. Check status/nextActions, not just ok. approve=true always requires explicit human consent.",
       inputSchema: z.object({
         planId: z.string(),
         approve: z.boolean().optional(),
+        waitSeconds: z.number().int().min(0).max(3600).optional(),
       }),
-      handler: async ({ planId, approve }: { planId: string; approve?: boolean }) => {
+      handler: async ({ planId, approve, waitSeconds }: { planId: string; approve?: boolean; waitSeconds?: number }, signal?: AbortSignal) => {
         const args = ["apply", "provision", "--plan", planId];
         if (approve) args.push("--approve");
+        if (waitSeconds !== undefined) args.push("--wait-seconds", String(waitSeconds));
 
-        const response = await executeMachineCommand(args, runMachineCli);
+        const response = await executeMachineCommand(args, runMachineCli, signal);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_inspect_provision",
+      description: "Read or bounded-wait for the original provision deployment. No create, cancel, delete, tag, or ledger writes. Azure Succeeded alone is partial until the original approved checkpoint finishes bookkeeping.",
+      inputSchema: z.object({
+        planId: z.string(),
+        waitSeconds: z.number().int().min(0).max(3600).optional(),
+      }),
+      handler: async ({ planId, waitSeconds }: { planId: string; waitSeconds?: number }, signal?: AbortSignal) => {
+        const args = ["inspect", "provision", "--plan", planId];
+        if (waitSeconds !== undefined) args.push("--wait-seconds", String(waitSeconds));
+        const response = await executeMachineCommand(args, runMachineCli, signal);
         return jsonTextContent(withOperationStatus(response));
       },
     },
   ];
+
+  // Every response reports which SwallowKit version answered and why it was selected.
+  return definitions.map((definition) => ({
+    ...definition,
+    handler: async (input: unknown, signal?: AbortSignal) => {
+      try {
+        const result = await definition.handler(input, signal);
+        return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+      } catch (error) {
+        // Prerequisite failures carry nextActions; keep them structured so agents can follow them.
+        if (error instanceof MachineCliError && error.response.nextActions?.length) {
+          return { ...jsonTextContent(withSwallowKitMetadata(error.response)), isError: true };
+        }
+        throw error;
+      }
+    },
+  }));
 }
 
-export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defaultMachineCliRunner): McpServer {
-  const version = getSwallowKitVersion();
+export function createSwallowKitMcpServer(
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
+): McpServer {
+  const version = versionContext.mcpVersion;
   const server = new McpServer({
     name: "swallowkit-mcp",
     version,
   });
 
-  for (const tool of buildSwallowKitToolDefinitions(runMachineCli)) {
+  for (const tool of buildSwallowKitToolDefinitions(runMachineCli, versionContext)) {
     server.registerTool(
       tool.name,
       {
         description: tool.description,
         inputSchema: tool.inputSchema,
       },
-      tool.handler
+      (input, extra) => tool.handler(input, extra.signal)
     );
   }
 
   return server;
 }
 
+function resolveExecCommand(cwd: string): string {
+  try {
+    return getCommands(detectFromProject(cwd)).exec;
+  } catch {
+    return "npx";
+  }
+}
+
+async function fetchPublishedLatest(): Promise<string | null> {
+  if (process.env.SWALLOWKIT_MCP_UPDATE_CHECK === "0") return null;
+  const registry = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+  try {
+    const response = await fetch(`${registry}/swallowkit/latest`, { signal: AbortSignal.timeout(3000) });
+    if (!response.ok) return null;
+    const body = await response.json() as { version?: unknown };
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function delegateToProjectMcp(entrypoint: string, fromVersion: string): void {
+  const child = spawn(process.execPath, [entrypoint], {
+    stdio: "inherit",
+    env: { ...process.env, [MCP_DELEGATED_FROM_ENV]: fromVersion },
+  });
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("error", (error) => {
+    console.error(`[swallowkit-mcp] failed to start the project-installed MCP: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.on("exit", (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
 export async function runMcpServer(): Promise<void> {
-  console.error(`[swallowkit-mcp] version: ${getSwallowKitVersion()}`);
-  const server = createSwallowKitMcpServer();
+  const selfVersion = getSwallowKitVersion();
+  const cwd = process.cwd();
+  const execCommand = resolveExecCommand(cwd);
+  const decision = decideMcpLaunch({
+    selfVersion,
+    selfPackageRoot: path.resolve(__dirname, "..", ".."),
+    env: process.env,
+    project: resolveProjectSwallowKit(cwd),
+    execCommand,
+  });
+
+  if (decision.action === "delegate") {
+    console.error(
+      `[swallowkit-mcp] version: ${selfVersion}; delegating to the project-installed swallowkit-mcp ${decision.toVersion} (newer than the launcher).`
+    );
+    delegateToProjectMcp(decision.entrypoint, decision.fromVersion);
+    return;
+  }
+
+  const context = decision.context;
+  // One write keeps the version line and its warnings together for log readers.
+  console.error([
+    `[swallowkit-mcp] version: ${selfVersion} (selection: ${context.selection}${context.delegatedFrom ? `, delegated from ${context.delegatedFrom}` : ""})`,
+    ...context.warnings.map((warning) => `[swallowkit-mcp] warning: ${warning}`),
+  ].join("\n"));
+
+  if (context.selection === "pinned") {
+    void fetchPublishedLatest().then((latest) => {
+      const notice = buildPinnedUpdateNotice(context, latest, execCommand);
+      if (notice) {
+        context.warnings.push(notice.warning);
+        context.nextActions.push(notice.nextAction);
+        console.error(`[swallowkit-mcp] warning: ${notice.warning}`);
+      }
+    });
+  }
+
+  const server = createSwallowKitMcpServer(defaultMachineCliRunner, context);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }