swallowkit 2.0.0-alpha.5 → 2.0.0-alpha.7

package/src/cli/commands/provision.ts

@@ -1,12 +1,99 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
 import {
   INTERACTIVE_PROVISION_RETRY_HINT,
+  ApplyProvisionResult,
   ProvisionPlanData,
+  applyProvisionOperation,
   executeProvisionPlan,
+  inspectProvisionOperation,
   planProvisionOperation,
 } 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) {
@@ -18,6 +105,8 @@ export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "
       return `The existing resource group ${plan.resourceGroup} will be recorded as SwallowKit baseline 0. Nothing will be deployed.`;
     case "reconcile":
       return `infra/main.bicep will be redeployed to ${plan.resourceGroup}. Template-managed settings may be reset.`;
+    case "recover":
+      return `The existing baseline deployment in ${plan.resourceGroup} will be observed and its migration tag/ledger completed after Azure Succeeded. Bicep will not be submitted again.`;
     default:
       return `Resource group ${plan.resourceGroup}:`;
   }
@@ -44,7 +133,7 @@ const SWA_REGIONS = [
 ];
 
 interface ProvisionCliOptions {
-  resourceGroup: string;
+  resourceGroup?: string;
   subscription?: string;
   location?: string;
   swaLocation?: string;
@@ -53,6 +142,40 @@ interface ProvisionCliOptions {
   baseline?: string;
   reconcile?: boolean;
   approve?: boolean;
+  resume?: string;
+  status?: string;
+  resumeDeployment?: string;
+  waitSeconds?: string;
+}
+
+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, `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: ${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`);
+    if (result.outcome !== "failed") lines.push(`Resume: 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");
 }
 
 async function resolveLocations(options: ProvisionCliOptions): Promise<{ location: string; swaLocation: string }> {
@@ -84,77 +207,127 @@ 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")
-  .requiredOption("-g, --resource-group <name>", "Resource group name")
-  .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)
-  .action(async (options: ProvisionCliOptions) => {
-    ensureSwallowKitProject("provision");
-    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,
-    }, { 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")
+    .option("--wait-seconds <seconds>", "Bounded state wait, 0-3600 seconds (default: 300; status: 0)")
+    .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,
+          });
+          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('Existing resource group requires: migrations init --legacy-baseline, then provision --adopt-existing --baseline 0 --what-if.');
-    }
+        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.");
 
-    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,
+        });
+        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 });
-    console.log(`✅ Provisioning completed. ${result.executedCommands.length} Azure CLI command(s) ran.`);  });
+export const provisionCommand = createProvisionCommand();

package/src/cli/index.ts

@@ -5,7 +5,8 @@ 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";
 import { configureMcpCommand } from "./commands/configure-mcp";
@@ -139,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);
@@ -365,7 +366,16 @@ export function formatCliError(error: unknown): string {
     if (details && typeof details === "object") {
       if (typeof details.nextAction === "string") lines.push(`   Next: ${details.nextAction}`);
       if (Array.isArray(details.changedFiles)) lines.push(`   Changed files: ${details.changedFiles.join(", ")}`);
+      if (typeof details.runId === "string") lines.push(`   Run: ${details.runId}`);
+      if (details.deployment && typeof details.deployment === "object") {
+        const deployment = details.deployment as { state?: string; reference?: { name?: string; id?: string; resourceGroup?: string; subscription?: string } };
+        lines.push(`   Deployment: ${deployment.reference?.id ?? deployment.reference?.name ?? "unknown"}; state: ${deployment.state ?? "unknown"}`);
+      }
+      if (Array.isArray(details.diagnostics)) {
+        for (const diagnostic of details.diagnostics as AzureCliDiagnostic[]) lines.push(formatAzureDiagnostic(diagnostic));
+      }
     }
+    for (const action of error.nextActions ?? []) lines.push(`   Next: ${action.command} — ${action.description}`);
     return lines.join("\n");
   }
   if (error instanceof Error) {

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

@@ -0,0 +1,167 @@
+import { runAzCliAsync } from "../../utils/azure-cli";
+import { AzureCliDiagnostic, azureCliDiagnostic, redactAzureText } from "../../utils/azure-diagnostics";
+
+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;
+
+export interface DeploymentReference {
+  subscription: string;
+  resourceGroup: string;
+  name: string;
+  id?: string;
+  correlationId?: string;
+  templateHash?: string;
+  /** Do not mistake a previous deployment under the same name for this submission. */
+  previousCorrelationId?: string;
+}
+
+export interface AzureDeploymentError {
+  code: string;
+  message: string;
+}
+
+export interface DeploymentObservation {
+  state: "Accepted" | "Running" | "Succeeded" | "Failed" | "Canceled" | "unknown";
+  reference: DeploymentReference;
+  reason?: "not-found" | "query-failed" | "invalid-response" | "identity-changed" | "not-yet-observed" | "cancelled";
+  errors: AzureDeploymentError[];
+  diagnostic: AzureCliDiagnostic;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+export function extractAzureErrors(value: unknown, secretValues: readonly string[] = []): AzureDeploymentError[] {
+  const result: AzureDeploymentError[] = [];
+  const visit = (entry: unknown, depth: number) => {
+    if (depth > 8 || result.length >= 20) return;
+    if (typeof entry === "string") {
+      try { visit(JSON.parse(entry), depth + 1); } catch { /* Only structured Azure errors are projected. */ }
+      return;
+    }
+    const item = record(entry);
+    if (!item) return;
+    if (typeof item.code === "string" && typeof item.message === "string") {
+      result.push({ code: redactAzureText(item.code, secretValues).slice(0, 200), message: redactAzureText(item.message, secretValues).slice(0, 2_000) });
+    }
+    if (item.error) visit(item.error, depth + 1);
+    if (Array.isArray(item.details)) item.details.forEach((detail) => visit(detail, depth + 1));
+  };
+  visit(value, 0);
+  return result;
+}
+
+export function deploymentId(reference: DeploymentReference): string {
+  return reference.id ?? `/subscriptions/${reference.subscription}/resourceGroups/${reference.resourceGroup}/providers/Microsoft.Resources/deployments/${reference.name}`;
+}
+
+export async function queryAzureDeployment(
+  reference: DeploymentReference,
+  options: { timeoutMs?: number; signal?: AbortSignal; secretValues?: readonly string[] } = {}
+): Promise<DeploymentObservation> {
+  const result = await runAzCliAsync([
+    "deployment", "group", "show", "--name", reference.name,
+    "--resource-group", reference.resourceGroup, "--subscription", reference.subscription,
+    "--query", DEPLOYMENT_QUERY, "-o", "json",
+  ], { timeout: options.timeoutMs ?? 30_000, signal: options.signal });
+  const diagnostic = azureCliDiagnostic(result, "deployment-state", options.secretValues);
+  const unknown = (reason: DeploymentObservation["reason"]): DeploymentObservation => ({
+    state: "unknown", reference, reason, errors: [], diagnostic,
+  });
+  if (result.status !== 0 || result.failureKind) {
+    if (result.failureKind === "cancelled") return unknown("cancelled");
+    return unknown(/DeploymentNotFound|ResourceGroupNotFound/i.test(`${result.stderr}\n${result.stdout}`) ? "not-found" : "query-failed");
+  }
+  if (result.stdoutTruncated) return unknown("invalid-response");
+  let parsed: Record<string, unknown> | null;
+  try { parsed = record(JSON.parse(result.stdout)); } catch { return unknown("invalid-response"); }
+  if (!parsed || typeof parsed.id !== "string" || typeof parsed.state !== "string" || typeof parsed.correlationId !== "string") {
+    return unknown("invalid-response");
+  }
+  if (parsed.id.toLowerCase() !== deploymentId(reference).toLowerCase()
+    || (reference.correlationId && parsed.correlationId !== reference.correlationId)
+    || (reference.templateHash && parsed.templateHash !== reference.templateHash)) {
+    return unknown("identity-changed");
+  }
+  if (reference.previousCorrelationId && parsed.correlationId === reference.previousCorrelationId) {
+    return unknown("not-yet-observed");
+  }
+  const states: Record<string, DeploymentObservation["state"]> = {
+    accepted: "Accepted", running: "Running", creating: "Running", updating: "Running",
+    succeeded: "Succeeded", failed: "Failed", canceled: "Canceled", cancelled: "Canceled",
+  };
+  const state = states[parsed.state.toLowerCase()];
+  if (!state) return unknown("invalid-response");
+  return {
+    state,
+    reference: {
+      ...reference,
+      id: parsed.id,
+      correlationId: parsed.correlationId,
+      ...(typeof parsed.templateHash === "string" ? { templateHash: parsed.templateHash } : {}),
+    },
+    errors: extractAzureErrors(parsed.error, options.secretValues),
+    diagnostic,
+  };
+}
+
+export async function waitForAzureDeployment(
+  reference: DeploymentReference,
+  options: {
+    deadline: number;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    onObservation?: (observation: DeploymentObservation) => void;
+    secretValues?: readonly string[];
+    queryTimeoutMs?: number;
+  }
+): Promise<DeploymentObservation> {
+  let observation: DeploymentObservation;
+  do {
+    const remaining = options.deadline - Date.now();
+    // Even when the wait budget is exhausted, one bounded read can identify an accepted submission.
+    observation = await queryAzureDeployment(reference, {
+      timeoutMs: remaining > 0 ? Math.min(options.queryTimeoutMs ?? 30_000, remaining) : options.queryTimeoutMs ?? 30_000,
+      signal: options.signal,
+      secretValues: options.secretValues,
+    });
+    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 (Date.now() >= options.deadline || options.signal?.aborted) return observation;
+    await new Promise<void>((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", done);
+        resolve();
+      };
+      const timer = setTimeout(done, Math.min(options.pollIntervalMs ?? 5_000, Math.max(options.deadline - Date.now(), 0)));
+      options.signal?.addEventListener("abort", done, { once: true });
+      if (options.signal?.aborted) done();
+    });
+  } while (!options.signal?.aborted);
+  return observation;
+}
+
+export async function queryDeploymentOperationErrors(reference: DeploymentReference, secretValues: readonly string[] = [], signal?: AbortSignal): Promise<{
+  errors: AzureDeploymentError[];
+  diagnostic: AzureCliDiagnostic;
+}> {
+  const result = await runAzCliAsync([
+    "deployment", "operation", "group", "list",
+    "--resource-group", reference.resourceGroup, "--name", reference.name, "--subscription", reference.subscription,
+    "--query", "[?properties.provisioningState=='Failed' || properties.provisioningState=='Canceled'].{error:properties.statusMessage}",
+    "-o", "json",
+  ], { timeout: 30_000, signal });
+  const errors: AzureDeploymentError[] = [];
+  if (result.status === 0 && !result.failureKind && !result.stdoutTruncated) {
+    try {
+      const parsed: unknown = JSON.parse(result.stdout);
+      if (Array.isArray(parsed)) parsed.slice(0, 20).forEach((item) => errors.push(...extractAzureErrors(item, secretValues)));
+    } catch { /* The separate diagnostic explicitly records an unreadable operations response. */ }
+  }
+  return { errors: errors.slice(0, 20), diagnostic: azureCliDiagnostic(result, "deployment-operations", secretValues) };
+}