swallowkit 2.0.0-alpha.5 → 2.0.0-alpha.6

package/src/core/project/agent-templates/AGENTS.md

@@ -401,6 +401,24 @@ Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
 approval gate. A broad request to deploy does not itself grant the explicit
 approval required by that workflow.
 
+Provision applies Bicep once and tracks the original Azure deployment with a
+bounded wait. A local timeout/error, output truncation, or Ctrl+C is not proof
+that Azure failed. `in-progress` means Azure is Running/Accepted; `unknown`
+means its result could not be read; `partial` means Azure succeeded but
+tag/ledger completion is pending. Never re-submit Bicep, reconcile, adopt,
+cancel, or delete just to repair waiting or migration bookkeeping.
+
+Retain `.swallowkit/state/provision/` execution checkpoints. Use
+`{{runCmd}} swallowkit machine inspect provision --plan <runId> --wait-seconds 300`
+for read-only status/wait, and after explicit human approval use
+`{{runCmd}} swallowkit machine apply provision --plan <runId> --approve`
+to resume. `runId` equals the original `planId`; fingerprints, subscription,
+deployment identity and migration checks remain in force. Only
+`status: "complete"` / `outcome: "succeeded"` means Azure Succeeded plus verified
+tags and local ledger. Do not print deployment output secrets or raw `az --debug`.
+For older untracked baselines use `plan provision --resume-deployment <name>`
+with original target/regions; it blocks unless ARM/parameter evidence matches.
+
 ## SwallowKit Agent Skills and Runbooks
 
 SwallowKit installs task-specific Agent Skills under:

package/src/core/project/agent-templates/CLAUDE.md

@@ -24,6 +24,11 @@ Always-on rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Inspect the original
+  execution checkpoint with `machine inspect provision --plan <runId>`; resume
+  `machine apply provision --plan <runId> --approve` only after explicit human
+  approval. Preserve checkpoints; never re-submit Bicep/reconcile/cancel/delete
+  to repair waiting or tag/ledger failures. Do not print deployment output secrets.
 - Run SwallowKit verification before considering implementation complete.
 - Default verification includes `backend-build` for standalone Functions.
   Skipped toolchains are not validation; Python compilation checks syntax only.

package/src/core/project/agent-templates/copilot-instructions.md

@@ -23,6 +23,12 @@ Key rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Read `status`, `outcome`,
+  and `nextActions`; inspect the original run with `machine inspect provision
+  --plan <runId>`, then resume `machine apply provision --plan <runId> --approve`
+  only after explicit human approval. Preserve execution checkpoints; never
+  re-submit Bicep or use reconcile/cancel/delete to repair waiting or tag/ledger
+  failures. Do not print deployment output secrets.
 - Run SwallowKit verification before completion.
 - Default verification includes `backend-build` for standalone Functions.
   Skipped toolchains are not validation; Python compilation checks syntax only.

package/src/core/project/capabilities.ts

@@ -61,6 +61,14 @@ export interface CapabilitiesContract {
     notes: string[];
   };
   machineCommands: string[];
+  provisioning: {
+    execution: string;
+    completion: string;
+    tracking: string;
+    recovery: string;
+    diagnostics: string;
+    approval: string;
+  };
   verifyChecks: {
     defaultChecks: string[];
     optInChecks: string[];
@@ -214,16 +222,24 @@ export function inspectCapabilities(): CapabilitiesContract {
       notes: ["Editing dev-seeds/*.json alone does nothing; seeds are only applied via dev --seed-env."],
     },
     machineCommands: [
-      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities",
+      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities; inspect provision --plan <runId> [--wait-seconds <0-3600>]",
       "validate project",
       "generate model <names...> | generate scaffold <model>",
-      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if]",
-      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve",
+      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if] [--resume-deployment <name>]",
+      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve [--wait-seconds <0-3600>] (also resumes the same execution checkpoint)",
       "verify project [--checks <ids>] [--compact]",
       "explain failure [--check <id>]",
       "(regular CLI) migrations add-model <model> [--dry-run] — generate only the container migration after scaffold --skip-infra",
       "(regular CLI) configure-mcp [--version auto|latest|<semver>] — re-select the MCP launcher version in .mcp.json",
     ],
+    provisioning: {
+      execution: "Submit Bicep once with az deployment group create --no-wait, then bounded state polling (default 300 seconds, configurable 0-3600). Azure CLI invocations are bounded separately. Warning-only stderr with exit 0 is not a failure; output capture limits do not terminate az.",
+      completion: "status complete/outcome succeeded requires Azure Succeeded plus verified migration tags and local ledger completion. Running/Accepted -> in-progress; unreadable/not-found state -> blocked/outcome unknown; bookkeeping interruption after Azure Succeeded -> blocked/outcome partial; Failed/Canceled -> failed with Azure causes.",
+      tracking: "Approved runs persist before Azure writes under .swallowkit/state/provision/. runId equals the original planId and preserves the subscription, RG, deployment ID/correlation, fingerprints and migration state. inspect provision is read-only; apply provision --plan resumes without re-submitting attempted deployments. Ctrl+C/termination may leave Azure running; never cancel/delete without explicit consent.",
+      recovery: "For an older untracked baseline, plan provision --resume-deployment <name> compares the existing ARM template and non-secure parameters to the local Bicep/parameters. It observes that deployment and only tags/records it after Succeeded. Mismatches, unreadable evidence, secure parameters or non-baseline migrations block; do not use reconcile just to repair bookkeeping.",
+      diagnostics: "Results include bounded/redacted stdout/stderr, omitted-output flags, exit code, signal, failure kind, elapsed time and deployment identity. Deployment output values are not returned. Never print --debug output, keys, tokens or connection strings.",
+      approval: "Initial apply and every resume require explicit human approval. A passing local command or an ok envelope is not proof of completed Azure provisioning; inspect status, outcome and nextActions.",
+    },
     verifyChecks: {
       defaultChecks: ["structure", "drift", "typecheck", "backend-build"],
       optInChecks: ["build", "lint", "test"],

package/src/core/project/state.ts

@@ -57,6 +57,76 @@ export function deletePlanState(planId: string, projectRoot: string = process.cw
   }
 }
 
+function provisionRunPath(runId: string, projectRoot: string): string {
+  if (!/^[a-f0-9]{12}$/.test(runId)) throw new Error("Invalid provision run ID.");
+  return path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision", `${runId}.json`);
+}
+
+export function saveProvisionRun<T extends { runId: string }>(run: T, projectRoot: string = process.cwd()): void {
+  ensureStateDir(projectRoot);
+  const file = provisionRunPath(run.runId, projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(run, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+export function loadProvisionRun<T>(runId: string, projectRoot: string = process.cwd()): T | null {
+  const file = provisionRunPath(runId, projectRoot);
+  if (!fs.existsSync(file)) return null;
+  // Unlike a preview, discarding a corrupt execution checkpoint could replay Azure writes.
+  return JSON.parse(fs.readFileSync(file, "utf-8")) as T;
+}
+
+export function listProvisionRuns<T>(projectRoot: string = process.cwd()): T[] {
+  const directory = path.join(projectRoot, SWALLOWKIT_STATE_DIR, "provision");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory).filter((name) => /^[a-f0-9]{12}\.json$/.test(name))
+    .map((name) => loadProvisionRun<T>(name.slice(0, -5), projectRoot)!);
+}
+
+/** A live local executor must not share an Azure target with another executor. */
+export function lockProvisionTarget(key: string, projectRoot: string = process.cwd()): () => void {
+  if (!/^[a-f0-9]{64}$/.test(key)) throw new Error("Invalid provision lock key.");
+  const directory = path.join(ensureStateDir(projectRoot), "provision");
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, `${key}.lock`);
+  const create = () => {
+    const descriptor = fs.openSync(file, "wx", 0o600);
+    try { fs.writeFileSync(descriptor, String(process.pid)); } finally { fs.closeSync(descriptor); }
+  };
+  try {
+    create();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const recoveryFile = `${file}.recovery`;
+    let descriptor: number;
+    try {
+      descriptor = fs.openSync(recoveryFile, "wx", 0o600);
+    } catch (recoveryError) {
+      if ((recoveryError as NodeJS.ErrnoException).code !== "EEXIST") throw recoveryError;
+      throw new Error("Provision lock recovery is already in progress. Inspect the checkpoint before retrying.");
+    }
+    fs.closeSync(descriptor);
+    try {
+      const pid = Number(fs.readFileSync(file, "utf-8"));
+      if (!Number.isInteger(pid) || pid < 1) throw new Error("Invalid provision lock; inspect the checkpoint before removing the lock.");
+      try {
+        process.kill(pid, 0);
+      } catch (probeError) {
+        if ((probeError as NodeJS.ErrnoException).code !== "ESRCH") throw probeError;
+        fs.unlinkSync(file);
+        create();
+        return () => fs.unlinkSync(file);
+      }
+      throw new Error("Another local provision executor is using this Azure target. Inspect its run; do not start a second deployment.");
+    } finally {
+      fs.unlinkSync(recoveryFile);
+    }
+  }
+  return () => fs.unlinkSync(file);
+}
+
 const LAST_VERIFY_FILE = "last-verify.json";
 
 export function saveLastVerifyState(result: unknown, projectRoot: string = process.cwd()): void {

package/src/core/project/workflows.ts

@@ -214,6 +214,9 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
 - Inspect infra locally first — no \`az\` calls are needed for inspection.
 - Never edit an applied migration. Create a corrective migration instead.
 - Never use \`--reconcile\` for an ordinary model or resource addition.
+- A local az error/timeout or Ctrl+C does not prove Azure failed. Never
+  re-submit, cancel, or delete a deployment to repair a wait or bookkeeping failure.
+- Respect \`status\`, \`outcome\`, and \`nextActions\`, not just \`ok\`.
 
 ## Steps
 
@@ -221,7 +224,7 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
    \`${runCmd} swallowkit machine inspect infra\`
    - review parameters, modules, outputs, and container wiring warnings.
 2. Compute the provisioning plan (no resources are created):
-   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region>\`
+   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region> --swa-location <swa-region>\`
   - the plan reports \`bootstrap\`, \`migrate\`, \`noop\`, or \`adoption-required\`.
   - it lists only pending migrations and the exact \`az\` commands that would run.
   - for an older untagged environment, first run \`${runCmd} swallowkit migrations init --legacy-baseline\`, then plan with \`--adopt-existing --baseline 0 --what-if\`.
@@ -229,12 +232,35 @@ Goal: bootstrap Azure once, then apply only pending versioned infrastructure mig
 3. Present the plan to the human and wait for explicit approval.
 4. Only after approval:
    \`${runCmd} swallowkit machine apply provision --plan <planId> --approve\`
-5. Verify the deployment outputs and report them.
+5. If \`in-progress\`, \`unknown\`, or \`partial\`, retain the execution
+   checkpoint and read/wait for the original deployment:
+   \`${runCmd} swallowkit machine inspect provision --plan <runId> --wait-seconds 300\`.
+   Inspection never writes Azure tags or the local ledger.
+6. After fresh explicit human approval, resume:
+   \`${runCmd} swallowkit machine apply provision --plan <runId> --approve\`.
+   Attempted deployments are not re-submitted; remaining reviewed steps and
+   tags/ledger finish only after Azure \`Succeeded\`.
+7. Report completion only when \`status: "complete"\` and
+   \`outcome: "succeeded"\`. Never report deployment output secrets.
+
+For an older untracked bootstrap, plan with \`--resume-deployment <name>\`
+and the original RG, subscription and regions. Recovery compares its ARM
+template and non-secure parameters to local Bicep before approval. Mismatch,
+unreadable evidence or secure parameters block; do not work around this by
+using reconcile/adoption or replacing the migration manifest.
 
 ## Terminal states
 
 \`apply provision\` without \`--approve\` fails with \`approval-required\` —
 this is the guardrail working as intended, not an error to work around.
+
+Azure \`Running\`/\`Accepted\` means \`in-progress\`. An unreadable or missing
+deployment means \`unknown\`, not Azure failure. Azure \`Failed\`/\`Canceled\`
+returns sanitized Azure and operation causes. Azure \`Succeeded\` with incomplete
+tag/ledger writes means \`partial\`; resume bookkeeping without redeploying.
+The default wait is 300 seconds (0-3600 via \`--wait-seconds\`), not unlimited.
+Warning-only stderr with exit 0 is accepted. Diagnostics report local exit,
+signal, elapsed time and truncated/redacted output separately from Azure state.
 `,
   };
 

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";
@@ -141,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")
@@ -373,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")
@@ -382,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 () => {
@@ -396,6 +408,7 @@ function createMachineProgram(): Command {
             adoptExisting: options.adoptExisting,
             baseline: options.baseline,
             reconcile: options.reconcile,
+            resumeDeployment: options.resumeDeployment,
           });
         },
         (planData) => ({
@@ -546,22 +559,15 @@ 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 })
       );
     });
 

package/src/mcp/index.ts

@@ -8,6 +8,7 @@ import * as z from "zod/v4";
 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,
@@ -24,7 +25,7 @@ interface MachineSuccessPayload<TData> {
   data: TData;
 }
 
-type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+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) {
@@ -35,7 +36,7 @@ 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");
 
@@ -48,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.");
   }
 
@@ -423,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));
@@ -438,16 +457,32 @@ 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));
       },
     },
@@ -456,9 +491,9 @@ export function buildSwallowKitToolDefinitions(
   // Every response reports which SwallowKit version answered and why it was selected.
   return definitions.map((definition) => ({
     ...definition,
-    handler: async (input: unknown) => {
+    handler: async (input: unknown, signal?: AbortSignal) => {
       try {
-        const result = await definition.handler(input);
+        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.
@@ -488,7 +523,7 @@ export function createSwallowKitMcpServer(
         description: tool.description,
         inputSchema: tool.inputSchema,
       },
-      tool.handler
+      (input, extra) => tool.handler(input, extra.signal)
     );
   }