swallowkit 2.0.0-alpha.6 → 2.0.0-alpha.8

package/src/__tests__/provision-runtime.test.ts

@@ -8,7 +8,7 @@ import {
 } from "../core/operations/provision-operations";
 import * as migrations from "../core/project/migrations";
 import { loadProvisionRun, saveProvisionRun } from "../core/project/state";
-import { formatProvisionResult } from "../cli/commands/provision";
+import { formatProvisionResult, formatProvisionError } from "../cli/commands/provision";
 import { formatCliError, runCli } from "../cli";
 import { runMachineCli } from "../machine";
 import { buildSwallowKitToolDefinitions } from "../mcp";
@@ -120,11 +120,14 @@ interface FixtureState {
   submitStderr?: string;
   submitDelay?: number;
   queryMode?: string;
+  transientQueryFailures?: number;
   template: Record<string, unknown>;
   remoteTemplate?: Record<string, unknown>;
   parameters: Record<string, { value: unknown; type?: string }>;
   error?: unknown;
   operations?: unknown[];
+  outputs?: Record<string, string>;
+  outputQueryFails?: boolean;
 }
 
 describe("provision execution, diagnosis and recovery using an az subprocess fixture", () => {
@@ -226,6 +229,53 @@ describe("provision execution, diagnosis and recovery using an az subprocess fix
     expect(read().deploymentCreates).toBe(1);
   });
 
+  function advanceClock(stepMs: number) {
+    const realNow = Date.now.bind(Date);
+    let offset = 0;
+    jest.spyOn(Date, "now").mockImplementation(() => realNow() + (offset += stepMs));
+  }
+
+  it("waits past the old bounded budget until Azure finishes when the human CLI asks for completion", async () => {
+    update({ states: ["Accepted", "Running", "Running", "Running", "Running", "Succeeded"] });
+    advanceClock(120_000);
+    const result = await executeProvisionPlan(await planProvisionOperation(options), { approve: true, waitUntilComplete: true, pollIntervalMs: 10 });
+    expect(result).toMatchObject({ status: "complete", outcome: "succeeded" });
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+  });
+
+  it("keeps the bounded default wait for machine/MCP apply", async () => {
+    update({ states: ["Accepted", "Running", "Running", "Running", "Running", "Succeeded"] });
+    const plan = await planProvisionOperation(options);
+    advanceClock(120_000);
+    const result = await executeProvisionPlan(plan, { approve: true, pollIntervalMs: 10 });
+    expect(result).toMatchObject({ status: "in-progress", outcome: "in-progress" });
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 0 });
+  });
+
+  it("reports an Azure terminal failure after a long unbounded wait", async () => {
+    update({ states: ["Running", "Running", "Failed"], error: { code: "Conflict", message: "fixture conflict" } });
+    advanceClock(200_000);
+    await expect(executeProvisionPlan(await planProvisionOperation(options), { approve: true, waitUntilComplete: true, pollIntervalMs: 10 }))
+      .rejects.toMatchObject({ code: "azure-deployment-failed", message: expect.stringContaining("Conflict: fixture conflict") });
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 0 });
+  });
+
+  it("rides through transient state-read failures while waiting until completion", async () => {
+    update({ states: ["Running", "Succeeded"] });
+    const plan = await planProvisionOperation(options);
+    update({ transientQueryFailures: 3 });
+    const result = await executeProvisionPlan(plan, { approve: true, waitUntilComplete: true, pollIntervalMs: 10 });
+    expect(result.status).toBe("complete");
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+  });
+
+  it("does not poll forever when the submitted deployment never becomes visible", async () => {
+    update({ queryMode: "not-found" });
+    const result = await executeProvisionPlan(await planProvisionOperation(options), { approve: true, waitUntilComplete: true, pollIntervalMs: 1 });
+    expect(result).toMatchObject({ status: "blocked", outcome: "unknown" });
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 0 });
+  }, 60_000);
+
   it.each(["communication", "nonzero", "slow"])("distinguishes local %s from Azure Running", async (submitMode) => {
     update({ submitMode, states: ["Running"] });
     const original = azureCli.runAzCliAsync;
@@ -511,7 +561,7 @@ describe("provision execution, diagnosis and recovery using an az subprocess fix
     expect(read().deploymentCreates).toBe(3);
     expect(read().calls.filter(args => args[0] === "deployment" && args[2] === "create").map(args => args[args.indexOf("--name") + 1]))
       .toEqual(expect.arrayContaining(["swallowkit-baseline", ...plan.pendingMigrations.map(migration => `swallowkit-migration-${migration.version}-${migration.checksum.slice(0, 12)}`)]));
-  });
+  }, 20000);
 
   it("recovers an older untracked Running deployment using matching ARM/parameter evidence and no create", async () => {
     update({ groupExists: true, states: ["Running"], deployments: { "swallowkit-baseline": { correlationId: "old-correlation", templateHash: "fixture-template-hash" } } });
@@ -559,4 +609,89 @@ describe("provision execution, diagnosis and recovery using an az subprocess fix
     expect(runner).toHaveBeenCalledWith(["inspect", "provision", "--plan", runId, "--wait-seconds", "0"]);
     expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 0 });
   });
+
+  it("waits for a long normal provision to finish and then prints CI/CD settings", async () => {
+    update({ states: ["Running", "Succeeded"], outputs: { functionsAppName: "func-fixture", staticWebAppName: "swa-fixture" } });
+    advanceClock(400_000);
+    const logs: string[] = [];
+    jest.spyOn(console, "log").mockImplementation((text: unknown) => { logs.push(String(text)); });
+    await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation]);
+    const output = logs.join("\n");
+    expect(output).toContain("Provisioning completed");
+    expect(output).toContain("AZURE_FUNCTIONAPP_NAME: func-fixture");
+    expect(output).not.toMatch(/still in progress|local wait ended|--wait-seconds/);
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+  }, 30_000);
+
+  it("treats normal provision invocation as consent without an extra prompt or machine instructions", async () => {
+    update({ outputs: { functionsAppName: "func-fixture", staticWebAppName: "swa-fixture", apiKey: "secret-not-for-terminal" } });
+    const logs: string[] = [];
+    jest.spyOn(console, "log").mockImplementation((text: unknown) => { logs.push(String(text)); });
+    await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation]);
+    const output = logs.join("\n");
+    expect(output).toContain("Provisioning completed");
+    expect(output).toContain("AZURE_FUNCTIONAPP_NAME: func-fixture");
+    expect(output).toContain("AZURE_STATIC_WEB_APPS_API_TOKEN");
+    expect(output).not.toContain("secret-not-for-terminal");
+    expect(output).not.toMatch(/machine |--approve|Run these Azure commands|Plan /);
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+    expect(read().calls.some(args => args[0] === "staticwebapp" && args[1] === "secrets")).toBe(false);
+  });
+
+  it("keeps normal CLI terminal failure instructions human-only and does not suggest resuming as a repair", async () => {
+    update({ states: ["Failed"], error: { code: "NotFound", message: "Request url is invalid." } });
+    let failure: unknown;
+    try {
+      await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation]);
+    } catch (error) { failure = error; }
+    const output = formatCliError(failure);
+    expect(output).toContain("NotFound: Request url is invalid.");
+    expect(output).toContain("swallowkit provision --status");
+    expect(output).not.toMatch(/machine |--plan|--approve|Resume:/);
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 0 });
+  });
+
+  it("shows human commands when existing execution state blocks a new provision", async () => {
+    update({ states: ["Running"] });
+    const running = await executeProvisionPlan(await planProvisionOperation(options), { approve: true, waitSeconds: 0 });
+    let failure: unknown;
+    try { await planProvisionOperation(options); } catch (error) { failure = error; }
+    const output = formatProvisionError(failure);
+    expect(output).toContain(`swallowkit provision --status ${running.runId}`);
+    expect(output).not.toMatch(/machine |--plan|--approve/);
+    expect(read().deploymentCreates).toBe(1);
+  });
+
+  it("does not redeploy or report deployment failure when resource outputs cannot be read after success", async () => {
+    update({ outputQueryFails: true });
+    const warnings: string[] = [];
+    jest.spyOn(console, "log").mockImplementation(() => {});
+    jest.spyOn(console, "warn").mockImplementation((text: unknown) => { warnings.push(String(text)); });
+    await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation]);
+    expect(warnings.join("\n")).toContain("Deployment succeeded, but resource information could not be read");
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+  });
+
+  it("resumes a human-invoked run without an additional approval and never resubmits Bicep", async () => {
+    update({ states: ["Running"] });
+    jest.spyOn(console, "log").mockImplementation(() => {});
+    await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation, "--wait-seconds", "0"]);
+    const file = fs.readdirSync(path.join(project, ".swallowkit", "state", "provision")).find(name => name.endsWith(".json"))!;
+    const runId = file.slice(0, -5);
+    update({ states: ["Succeeded"] });
+    await runCli(["node", "swallowkit", "provision", "--resume", runId]);
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+    expect(loadProvisionRun<{ outcome: string }>(runId)?.outcome).toBe("succeeded");
+  });
+
+  it("retains successful deployment when the output-reading helper throws", async () => {
+    const original = azureCli.runAzCliAsync;
+    jest.spyOn(azureCli, "runAzCliAsync").mockImplementation((args, runOptions) =>
+      args.some(arg => arg.includes("properties.outputs.")) ? Promise.reject(new Error("Fixture output transport failed")) : original(args, runOptions));
+    jest.spyOn(console, "log").mockImplementation(() => {});
+    const warning = jest.spyOn(console, "warn").mockImplementation(() => {});
+    await runCli(["node", "swallowkit", "provision", "-g", options.resourceGroup, "--location", options.location, "--swa-location", options.swaLocation]);
+    expect(warning).toHaveBeenCalledWith(expect.stringContaining("Deployment succeeded, but resource information could not be read"));
+    expect(read()).toMatchObject({ deploymentCreates: 1, tagAttempts: 1 });
+  });
 });

package/src/cli/commands/provision.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
 import {
@@ -12,6 +12,88 @@ import {
 } from "../../core/operations/provision-operations";
 import { MachineCommandError } from "../../machine/errors";
 import { formatAzureDiagnostic } from "../../utils/azure-diagnostics";
+import { runAzCliAsync } from "../../utils/azure-cli";
+
+function humanProvisionMessage(message: string): string {
+  return message
+    .replace(/swallowkit machine inspect provision --plan/g, "swallowkit provision --status")
+    .replace(/swallowkit machine apply provision --plan/g, "swallowkit provision --resume")
+    .replace(/plan provision/g, "swallowkit provision")
+    .replace(/\b[Pp]lan\b/g, "Execution")
+    .replace(/preview/g, "deployment preparation")
+    .replace(/after approval/g, "")
+    .replace(/--approve/g, "")
+    .replace(/ {2,}/g, " ");
+}
+
+export function formatProvisionError(error: unknown): string {
+  if (!(error instanceof MachineCommandError)) return error instanceof Error ? error.message : String(error);
+  const message = error.code === "azure-deployment-failed" ? error.message : humanProvisionMessage(error.message);
+  const lines = [...new Set(message.split("\n"))];
+  const details = error.details as Partial<ApplyProvisionResult> | undefined;
+  if (details?.deployment) {
+    lines.push(`Deployment: ${details.deployment.reference.name}; state: ${details.deployment.state}`);
+  }
+  for (const diagnostic of details?.diagnostics ?? []) {
+    if (diagnostic.failureKind || diagnostic.outputTruncated) lines.push(formatAzureDiagnostic(diagnostic));
+  }
+  const runId = details?.runId;
+  if (runId) {
+    lines.push(`Check: swallowkit provision --status ${runId}`);
+    if (error.code !== "azure-deployment-failed") lines.push(`Resume: swallowkit provision --resume ${runId}`);
+    else lines.push("Azure reported a terminal failure. Resuming only observes that failed deployment; correct its cause before explicitly deploying again.");
+  } else {
+    for (const action of error.nextActions ?? []) {
+      const command = humanProvisionMessage(action.command);
+      if (!command.includes("machine ")) lines.push(command);
+    }
+  }
+  return lines.join("\n");
+}
+
+async function printProvisionSetup(result: ApplyProvisionResult): Promise<void> {
+  if (!result.deployment || result.status !== "complete") return;
+  const reference = result.deployment.reference;
+  const fields = ["staticWebAppName", "staticWebAppUrl", "functionsAppName", "functionsAppUrl", "cosmosDbAccountName", "cosmosDatabaseName"] as const;
+  let outputs: Record<string, unknown>;
+  try {
+    const response = await runAzCliAsync(
+      [
+        "deployment",
+        "group",
+        "show",
+        "--name",
+        reference.name.startsWith("swallowkit-migration-") ? "swallowkit-baseline" : reference.name,
+        "--resource-group",
+        reference.resourceGroup,
+        "--subscription",
+        reference.subscription,
+        "--query",
+        `{${fields.map((field) => `${field}:properties.outputs.${field}.value`).join(",")}}`,
+        "-o",
+        "json",
+      ],
+      { timeout: 30_000 }
+    );
+    if (response.status !== 0 || response.failureKind || response.stdoutTruncated) throw new Error("Output query did not complete.");
+    const parsed: unknown = JSON.parse(response.stdout);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid resource output.");
+    outputs = parsed as Record<string, unknown>;
+  } catch {
+    console.warn(
+      "Deployment succeeded, but resource information could not be read. Inspect the deployment's named outputs in Azure Portal; do not redeploy just to retrieve them."
+    );
+    return;
+  }
+  console.log("\nResource information:");
+  for (const field of fields) {
+    if (typeof outputs[field] === "string") console.log(`  ${field}: ${outputs[field]}`);
+  }
+  console.log("\nCI/CD settings:");
+  console.log(`  AZURE_FUNCTIONAPP_NAME: ${typeof outputs.functionsAppName === "string" ? outputs.functionsAppName : "<functions-app-name>"}`);
+  console.log("  Retrieve AZURE_STATIC_WEB_APPS_API_TOKEN and AZURE_FUNCTIONAPP_PUBLISH_PROFILE privately from Azure Portal and save them in your CI/CD secrets.");
+  console.log("  Secret values are not printed or stored by SwallowKit. Trigger the first application deployment after configuring CI/CD.");
+}
 
 export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "resourceGroup" | "location" | "pendingMigrations">): string {
   switch (plan.mode) {
@@ -67,25 +149,31 @@ interface ProvisionCliOptions {
 }
 
 export function formatProvisionResult(result: ApplyProvisionResult): string {
-  const outcome = result.outcome === "succeeded" ? "✅ Provisioning completed, including migration tags and the local ledger."
-    : result.outcome === "in-progress" ? "⏳ Azure deployment is still in progress. The local wait ended; this is not an Azure failure."
-      : result.outcome === "partial" ? "⚠️ Provisioning is partially complete. Finish migration bookkeeping from the checkpoint; do not redeploy the baseline."
-        : result.outcome === "failed" ? "❌ Azure deployment reached a failed/cancelled terminal state."
-          : "⚠️ Azure deployment result is unknown. A local az interruption does not prove an Azure failure.";
-  const lines = [outcome, `Run: ${result.runId}; resource group: ${result.resourceGroup}`];
+  const outcome =
+    result.outcome === "succeeded"
+      ? "✅ Provisioning completed, including migration tags and the local ledger."
+      : result.outcome === "in-progress"
+        ? "⏳ Azure deployment is still in progress. The local wait ended; this is not an Azure failure."
+        : result.outcome === "partial"
+          ? "⚠️ Provisioning is partially complete. Finish migration bookkeeping from the checkpoint; do not redeploy the baseline."
+          : result.outcome === "failed"
+            ? "❌ Azure deployment reached a failed/cancelled terminal state."
+            : "⚠️ Azure deployment result is unknown. A local az interruption does not prove an Azure failure.";
+  const lines = [outcome, `Resource group: ${result.resourceGroup}`];
   if (result.deployment) {
     const reference = result.deployment.reference;
     lines.push(`Deployment: ${reference.name}; subscription: ${reference.subscription}; state: ${result.deployment.state}${reference.id ? `; ID: ${reference.id}` : ""}`);
     for (const error of result.deployment.errors) lines.push(`${error.code}: ${error.message}`);
   }
-  for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
+  for (const warning of result.warnings) lines.push(`Warning: ${humanProvisionMessage(warning)}`);
   for (const diagnostic of result.diagnostics.filter((entry) => entry.failureKind || entry.outputTruncated)) {
     lines.push(formatAzureDiagnostic(diagnostic));
   }
   if (result.status !== "complete") {
-    lines.push(`Check/wait: swallowkit provision --status ${result.runId} --wait-seconds 300`);
-    lines.push(`Resume after approval: swallowkit provision --resume ${result.runId} --approve`);
-    lines.push("Azure may continue after Ctrl+C or process termination. No Azure cancellation or deletion is performed.");
+    lines.push(`Check status: swallowkit provision --status ${result.runId}`);
+    if (result.outcome !== "failed") lines.push(`Resume and wait until completion: swallowkit provision --resume ${result.runId}`);
+    if (result.outcome !== "failed") lines.push("Azure may continue after Ctrl+C or process termination. No Azure cancellation or deletion is performed.");
+    else lines.push("Azure reported a terminal failure. Correct its cause before explicitly deploying again; resuming does not repair a failed deployment.");
   }
   return lines.join("\n");
 }
@@ -119,106 +207,130 @@ async function resolveLocations(options: ProvisionCliOptions): Promise<{ locatio
   return { location, swaLocation };
 }
 
-export const provisionCommand = new Command("provision")
-  .description("Bootstrap, adopt, migrate, or explicitly reconcile Azure resources")
-  .option("-g, --resource-group <name>", "Resource group name (required for a new preview)")
-  .option("--subscription <id>", "Azure subscription ID")
-  .option("--location <region>", "Primary location for Functions and Cosmos DB")
-  .option("--swa-location <region>", "Static Web App location")
-  .option("--what-if", "Include Azure what-if evidence in the preview", false)
-  .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
-  .option("--baseline <version>", "Baseline version for adoption (currently 0)")
-  .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
-  .option("--approve", "Run the displayed Azure commands without the confirmation prompt", false)
-  .option("--status <runId>", "Read an existing execution checkpoint and Azure deployment state without writes")
-  .option("--resume <runId>", "Resume an approved checkpoint without resubmitting attempted deployments")
-  .option("--resume-deployment <name>", "Recover an older untracked baseline deployment after verifying its template and parameters")
-  .option("--wait-seconds <seconds>", "Bounded state wait, 0-3600 seconds (default: 300; status: 0)")
-  .action(async (options: ProvisionCliOptions) => {
-    ensureSwallowKitProject("provision");
-    const waitSeconds = options.waitSeconds === undefined ? undefined : Number(options.waitSeconds);
-    if ((options.resume && options.status) || ((options.resume || options.status) && (options.resourceGroup || options.resumeDeployment || options.reconcile || options.adoptExisting || options.subscription || options.location || options.swaLocation || options.whatIf || options.baseline !== undefined))) {
-      throw new MachineCommandError("invalid-arguments", "Use --status or --resume with the checkpoint ID alone; its original Azure target and reviewed files are preserved.", undefined, "blocked");
-    }
-    if (options.status) {
-      const result = await inspectProvisionOperation({ planId: options.status, waitSeconds });
-      console.log(formatProvisionResult(result));
-      if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
-      return;
-    }
-    if (options.resume) {
-      let approved = options.approve === true;
-      if (!approved && process.stdin.isTTY && process.stdout.isTTY) {
-        const answer = await prompts({ type: "confirm", name: "approved", message: "Resume the original reviewed run and finish pending steps? This requires explicit approval.", initial: false });
-        approved = answer.approved === true;
-      }
-      const result = await applyProvisionOperation({ planId: options.resume, approve: approved, waitSeconds });
-      console.log(formatProvisionResult(result));
-      if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
-      return;
-    }
-    if (!options.resourceGroup) throw new MachineCommandError("invalid-arguments", "New provision previews require --resource-group.", undefined, "blocked");
-    const locations = await resolveLocations(options);
-    const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
-    // Preview in memory: the same Azure checks as the agent workflow, but no saved plan file.
-    const preview = await planProvisionOperation({
-      resourceGroup: options.resourceGroup,
-      subscription: options.subscription,
-      location: locations.location,
-      swaLocation: locations.swaLocation,
-      whatIf: options.whatIf,
-      adoptExisting: options.adoptExisting,
-      baseline,
-      reconcile: options.reconcile,
-      resumeDeployment: options.resumeDeployment,
-    }, { persist: false });
-
-    for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
-
-    if (preview.mode === "offline") {
-      console.log([
-        "",
-        "❌ Azure CLI is unavailable, so the current state of Azure could not be checked. Nothing was changed in Azure.",
-        "   1. Make sure `az --version` works in this terminal (install: https://aka.ms/azure-cli).",
-        "   2. Sign in with `az login` (and `az account set --subscription <id>` if needed).",
-        "   3. Run this command again.",
-      ].join("\n"));
-      process.exitCode = 1;
-      return;
-    }
+export function createProvisionCommand(): Command {
+  return new Command("provision")
+    .description("Deploy Azure infrastructure and show resource information and CI/CD setup")
+    .option("-g, --resource-group <name>", "Resource group name (required for deployment)")
+    .option("--subscription <id>", "Azure subscription ID")
+    .option("--location <region>", "Primary location for Functions and Cosmos DB")
+    .option("--swa-location <region>", "Static Web App location")
+    .option("--what-if", "Check Azure what-if before deployment", false)
+    .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
+    .option("--baseline <version>", "Baseline version for adoption (currently 0)")
+    .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
+    .addOption(new Option("--approve", "Compatibility option; invoking provision already requests execution").hideHelp())
+    .option("--status <runId>", "Read an existing execution checkpoint and Azure deployment state without writes")
+    .option("--resume <runId>", "Continue the original execution without resubmitting attempted deployments")
+    .option("--resume-deployment <name>", "Recover an older untracked baseline deployment after verifying its template and parameters")
+    .addOption(new Option("--wait-seconds <seconds>", "Optional limit on waiting, 0-3600 seconds (default: wait until Azure finishes; status: 0)").hideHelp())
+    .action(async (options: ProvisionCliOptions) => {
+      try {
+        ensureSwallowKitProject("provision");
+        const waitSeconds = options.waitSeconds === undefined ? undefined : Number(options.waitSeconds);
+        if (
+          (options.resume && options.status) ||
+          ((options.resume || options.status) &&
+            (options.resourceGroup ||
+              options.resumeDeployment ||
+              options.reconcile ||
+              options.adoptExisting ||
+              options.subscription ||
+              options.location ||
+              options.swaLocation ||
+              options.whatIf ||
+              options.baseline !== undefined))
+        ) {
+          throw new MachineCommandError(
+            "invalid-arguments",
+            "Use --status or --resume with the checkpoint ID alone; its original Azure target and reviewed files are preserved.",
+            undefined,
+            "blocked"
+          );
+        }
+        if (options.status) {
+          const result = await inspectProvisionOperation({
+            planId: options.status,
+            waitSeconds,
+          });
+          console.log(formatProvisionResult(result));
+          if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+          return;
+        }
+        if (options.resume) {
+          const result = await applyProvisionOperation({
+            planId: options.resume,
+            approve: true,
+            waitSeconds,
+            waitUntilComplete: waitSeconds === undefined,
+          });
+          console.log(formatProvisionResult(result));
+          await printProvisionSetup(result);
+          if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+          return;
+        }
+        if (!options.resourceGroup) throw new MachineCommandError("invalid-arguments", "Provision requires --resource-group.", undefined, "blocked");
+        const locations = await resolveLocations(options);
+        const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
+        // Preview in memory: the same Azure checks as the agent workflow, but no saved plan file.
+        const preview = await planProvisionOperation(
+          {
+            resourceGroup: options.resourceGroup,
+            subscription: options.subscription,
+            location: locations.location,
+            swaLocation: locations.swaLocation,
+            whatIf: options.whatIf,
+            adoptExisting: options.adoptExisting,
+            baseline,
+            reconcile: options.reconcile,
+            resumeDeployment: options.resumeDeployment,
+          },
+          { persist: false }
+        );
 
-    if (preview.mode === "adoption-required") {
-      throw new Error('The existing resource group has no migration tag. For an interrupted baseline use --resume-deployment <original-name> to verify/observe it without redeploying. Legacy adoption applies only to a legacy manifest; do not replace an existing manifest.');
-    }
+        for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
 
-    if (preview.mode === "noop") {
-      console.log(`Resource group ${preview.resourceGroup} is already up to date. Nothing to do.`);
-      return;
-    }
+        if (preview.mode === "offline") {
+          console.log(
+            [
+              "",
+              "❌ Azure CLI is unavailable, so the current state of Azure could not be checked. Nothing was changed in Azure.",
+              "   1. Make sure `az --version` works in this terminal (install: https://aka.ms/azure-cli).",
+              "   2. Sign in with `az login` (and `az account set --subscription <id>` if needed).",
+              "   3. Run this command again.",
+            ].join("\n")
+          );
+          process.exitCode = 1;
+          return;
+        }
+
+        if (preview.mode === "adoption-required") {
+          throw new Error(
+            "The existing resource group has no migration tag. For an interrupted baseline use --resume-deployment <original-name> to verify/observe it without redeploying. Legacy adoption applies only to a legacy manifest; do not replace an existing manifest."
+          );
+        }
+
+        if (preview.mode === "noop") {
+          console.log(`Resource group ${preview.resourceGroup} is already up to date. Nothing to do.`);
+          return;
+        }
 
-    console.log(`\n${describeProvisionAction(preview)}`);
-    console.log("The following Azure CLI commands will run:");
-    for (const command of preview.commands) console.log(`  ${command}`);
+        console.log(`\n${describeProvisionAction(preview)}`);
+        console.log("Deploying Azure infrastructure. Azure resources may incur charges.");
+        console.log("Waiting for the Azure deployment to finish. This often takes 10-20 minutes; resource information and CI/CD settings are shown when it completes.");
 
-    let approved = options.approve === true;
-    if (!approved) {
-      if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw new Error("Non-interactive provision requires --approve after reviewing the commands above.");
+        const result = await executeProvisionPlan(preview, {
+          approve: true,
+          retryHint: INTERACTIVE_PROVISION_RETRY_HINT,
+          waitSeconds,
+          waitUntilComplete: waitSeconds === undefined,
+        });
+        console.log(formatProvisionResult(result));
+        await printProvisionSetup(result);
+        if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+      } catch (error) {
+        throw new Error(formatProvisionError(error));
       }
-      const answer = await prompts({
-        type: "confirm",
-        name: "approved",
-        message: "Run these Azure commands? This may create billable resources.",
-        initial: false,
-      });
-      approved = answer.approved === true;
-    }
-    if (!approved) {
-      console.log("Provision cancelled. Nothing was changed in Azure.");
-      return;
-    }
+    });
+}
 
-    const result = await executeProvisionPlan(preview, { approve: true, retryHint: INTERACTIVE_PROVISION_RETRY_HINT, waitSeconds });
-    console.log(formatProvisionResult(result));
-    if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
-  });
+export const provisionCommand = createProvisionCommand();

package/src/cli/index.ts

@@ -5,7 +5,7 @@ import { readFileSync } from "fs";
 import * as path from "path";
 import { Command } from "commander";
 import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelCommand } from "./commands";
-import { provisionCommand } from "./commands/provision";
+import { createProvisionCommand } from "./commands/provision";
 import { AzureCliDiagnostic, formatAzureDiagnostic } from "../utils/azure-diagnostics";
 import { createMigrationCommand } from "./commands/create-migration";
 import { migrationsCommand } from "./commands/migrations";
@@ -140,7 +140,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   program.addCommand(devCommandOverride);
   program.addCommand(devSeedsCommand);
 
-  program.addCommand(provisionCommand);
+  program.addCommand(createProvisionCommand());
   program.addCommand(migrationsCommand);
   program.addCommand(createMigrationCommand);
   program.addCommand(configureMcpCommand);

package/src/core/operations/provision-deployment.ts

@@ -4,6 +4,8 @@ import { AzureCliDiagnostic, azureCliDiagnostic, redactAzureText } from "../../u
 export const DEPLOYMENT_QUERY = "{id:id,name:name,state:properties.provisioningState,correlationId:properties.correlationId,templateHash:properties.templateHash,timestamp:properties.timestamp,error:properties.error}";
 export const DEFAULT_PROVISION_WAIT_SECONDS = 300;
 export const MAX_PROVISION_WAIT_SECONDS = 3_600;
+/** Consecutive transient state-read failures tolerated while the human CLI waits for a terminal state. */
+export const UNBOUNDED_WAIT_TRANSIENT_RETRIES = 24;
 
 export interface DeploymentReference {
   subscription: string;
@@ -116,9 +118,15 @@ export async function waitForAzureDeployment(
     onObservation?: (observation: DeploymentObservation) => void;
     secretValues?: readonly string[];
     queryTimeoutMs?: number;
+    /**
+     * Consecutive non-terminal "unknown" reads (query failure, not yet visible) to keep polling through.
+     * Required for an unbounded deadline so a missing deployment cannot be polled forever.
+     */
+    transientRetries?: number;
   }
 ): Promise<DeploymentObservation> {
   let observation: DeploymentObservation;
+  let unknownReads = 0;
   do {
     const remaining = options.deadline - Date.now();
     // Even when the wait budget is exhausted, one bounded read can identify an accepted submission.
@@ -130,7 +138,15 @@ export async function waitForAzureDeployment(
     if (observation.state !== "unknown") reference = observation.reference;
     options.onObservation?.(observation);
     if (observation.state === "Succeeded" || observation.state === "Failed" || observation.state === "Canceled") return observation;
-    if (observation.state === "unknown" && observation.reason !== "not-yet-observed" && observation.reason !== "not-found") return observation;
+    if (observation.state === "unknown") {
+      unknownReads += 1;
+      const retryable = observation.reason === "not-yet-observed" || observation.reason === "not-found"
+        || (options.transientRetries !== undefined && (observation.reason === "query-failed" || observation.reason === "invalid-response"));
+      if (!retryable) return observation;
+      if (!Number.isFinite(options.deadline) && unknownReads > (options.transientRetries ?? 0)) return observation;
+    } else {
+      unknownReads = 0;
+    }
     if (Date.now() >= options.deadline || options.signal?.aborted) return observation;
     await new Promise<void>((resolve) => {
       const done = () => {