@postman-cse/onboarding-repo-sync 2.1.8 → 2.1.9

package/dist/cli.cjs

@@ -123219,6 +123219,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
     bifrostBaseUrl: "https://bifrost-premium-https-v4.gw.postman.com",
     fallbackBaseUrl: "https://go.postman.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn.io/install/unix.sh",
+    cliWindowsInstallUrl: "https://dl-cli.pstmn.io/install/win64.ps1",
     iapubBaseUrl: "https://iapub.postman.co"
   },
   beta: {
@@ -123226,6 +123227,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
     bifrostBaseUrl: "https://bifrost-https-v4.gw.postman-beta.com",
     fallbackBaseUrl: "https://go.postman-beta.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn-beta.io/install/unix.sh",
+    cliWindowsInstallUrl: "https://dl-cli.pstmn-beta.io/install/win64.ps1",
     iapubBaseUrl: "https://iapub.postman.co"
   }
 };
@@ -123259,6 +123261,7 @@ function resolvePostmanEndpointProfile(stack, region = "us") {
 
 // src/lib/ci-workflow-template.ts
 var DEFAULT_POSTMAN_CLI_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliInstallUrl;
+var DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliWindowsInstallUrl;
 function validateHttpsInstallUrl(url) {
   const safeUrlPattern = /^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._~/?=&%-]+$/;
   if (!safeUrlPattern.test(url)) {
@@ -123275,7 +123278,18 @@ function resolvePostmanRegion(postmanRegionOption) {
   }
   return postmanRegion;
 }
+function resolveCiRunnerOs(runnerOsOption) {
+  const runnerOs = String(runnerOsOption || "").trim() || "linux";
+  if (runnerOs === "linux" || runnerOs === "windows") {
+    return runnerOs;
+  }
+  throw new Error("ci-runner-os must be one of: linux, windows; got: " + runnerOs);
+}
 function renderCiWorkflowTemplate(options = {}) {
+  const runnerOs = resolveCiRunnerOs(options.runnerOs);
+  if (runnerOs === "windows") {
+    throw new Error("ci-runner-os=windows is currently supported for azure-devops workflows only");
+  }
   const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
   const installUrl = validateHttpsInstallUrl(rawUrl);
   const postmanRegion = resolvePostmanRegion(options.postmanRegion);
@@ -123382,6 +123396,132 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
   ];
 }
 var CI_WORKFLOW_TEMPLATE = renderCiWorkflowTemplate();
+function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName) {
+  return [
+    "  - pwsh: |",
+    "      $ErrorActionPreference = 'Stop'",
+    "      function Resolve-AdoOptional([string]$Value) {",
+    "        if ($Value -match '^\\$\\([^)]+\\)$') { return '' }",
+    "        return $Value",
+    "      }",
+    `      $collectionUid = $env:${collectionEnvironmentName}`,
+    "      $ciEnvironment = Resolve-AdoOptional $env:CI_ENVIRONMENT",
+    "      if ([string]::IsNullOrWhiteSpace($ciEnvironment)) { $ciEnvironment = 'Production' }",
+    `      $arguments = @('collection', 'run', $collectionUid, '-e', $env:POSTMAN_ENVIRONMENT_UID, '--report-events', '--env-var', "CI_ENVIRONMENT=$ciEnvironment")`,
+    "      $sslRoot = Join-Path $env:AGENT_TEMPDIRECTORY 'postman-ssl'",
+    "      $clientCert = Join-Path $sslRoot 'client.crt'",
+    "      $clientKey = Join-Path $sslRoot 'client.key'",
+    "      $caCert = Join-Path $sslRoot 'ca.crt'",
+    "      if (Test-Path -LiteralPath $clientCert) {",
+    "        $arguments += @('--ssl-client-cert', $clientCert, '--ssl-client-key', $clientKey)",
+    "        $passphrase = Resolve-AdoOptional $env:POSTMAN_SSL_CLIENT_PASSPHRASE",
+    "        if (-not [string]::IsNullOrWhiteSpace($passphrase)) {",
+    "          $arguments += @('--ssl-client-passphrase', $passphrase)",
+    "        }",
+    "        if (Test-Path -LiteralPath $caCert) {",
+    "          $arguments += @('--ssl-extra-ca-certs', $caCert)",
+    "        }",
+    "      }",
+    "      & postman @arguments",
+    `      if ($LASTEXITCODE -ne 0) { throw '${displayName} failed with exit code ' + $LASTEXITCODE }`,
+    `    displayName: ${displayName}`,
+    "    env:",
+    `      ${collectionEnvironmentName}: $(${collectionEnvironmentName})`,
+    "      POSTMAN_ENVIRONMENT_UID: $(POSTMAN_ENVIRONMENT_UID)",
+    "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
+    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)"
+  ];
+}
+function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
+  return [
+    "trigger:",
+    "  branches:",
+    "    include:",
+    "      - main",
+    "schedules:",
+    '  - cron: "0 */6 * * *"',
+    "    displayName: Scheduled run",
+    "    branches:",
+    "      include:",
+    "        - main",
+    "    always: true",
+    "pool:",
+    "  vmImage: windows-latest",
+    "steps:",
+    "  - checkout: self",
+    "    persistCredentials: true",
+    "  - pwsh: |",
+    "      $ErrorActionPreference = 'Stop'",
+    "      if (-not (Get-Command postman -ErrorAction SilentlyContinue)) {",
+    "        [System.Net.ServicePointManager]::SecurityProtocol = 3072",
+    "        Invoke-Expression ((New-Object System.Net.WebClient).DownloadString($env:POSTMAN_CLI_INSTALL_URL))",
+    "      }",
+    "      & postman --version",
+    "      if ($LASTEXITCODE -ne 0) { throw 'Postman CLI installation failed' }",
+    "    displayName: Install Postman CLI",
+    "    env:",
+    `      POSTMAN_CLI_INSTALL_URL: ${installUrl}`,
+    "  - pwsh: |",
+    "      $ErrorActionPreference = 'Stop'",
+    "      $arguments = @('login', '--with-api-key', $env:POSTMAN_API_KEY)",
+    ...postmanRegion === "eu" ? ["      $arguments += @('--region', 'eu')"] : [],
+    "      & postman @arguments",
+    "      if ($LASTEXITCODE -ne 0) { throw 'Postman CLI login failed' }",
+    "    displayName: Login to Postman CLI",
+    "    env:",
+    "      POSTMAN_API_KEY: $(POSTMAN_API_KEY)",
+    "  - pwsh: |",
+    "      $ErrorActionPreference = 'Stop'",
+    "      $section = ''",
+    "      $smoke = ''",
+    "      $contract = ''",
+    "      $environment = ''",
+    "      $fallbackEnvironment = ''",
+    "      foreach ($line in Get-Content -LiteralPath '.postman/resources.yaml') {",
+    "        if ($line -match '^  (collections|environments):\\s*$') { $section = $Matches[1]; continue }",
+    "        if ($line -notmatch '^    (.+?):\\s+(.+?)\\s*$') { continue }",
+    `        $key = $Matches[1].Trim().Trim("'").Trim('"')`,
+    `        $value = $Matches[2].Trim().Trim("'").Trim('"')`,
+    "        if ($section -eq 'collections' -and $key -match '\\[Smoke\\]') { $smoke = $value }",
+    "        if ($section -eq 'collections' -and $key -match '\\[Contract\\]') { $contract = $value }",
+    "        if ($section -eq 'environments') {",
+    "          if ([string]::IsNullOrWhiteSpace($fallbackEnvironment)) { $fallbackEnvironment = $value }",
+    "          if ($key -match 'prod\\.postman_environment\\.json$') { $environment = $value }",
+    "        }",
+    "      }",
+    "      if ([string]::IsNullOrWhiteSpace($environment)) { $environment = $fallbackEnvironment }",
+    "      if ([string]::IsNullOrWhiteSpace($smoke)) { throw 'Missing smoke collection UID in .postman/resources.yaml' }",
+    "      if ([string]::IsNullOrWhiteSpace($contract)) { throw 'Missing contract collection UID in .postman/resources.yaml' }",
+    "      if ([string]::IsNullOrWhiteSpace($environment)) { throw 'Missing environment UID in .postman/resources.yaml' }",
+    '      Write-Host "##vso[task.setvariable variable=POSTMAN_SMOKE_COLLECTION_UID]$smoke"',
+    '      Write-Host "##vso[task.setvariable variable=POSTMAN_CONTRACT_COLLECTION_UID]$contract"',
+    '      Write-Host "##vso[task.setvariable variable=POSTMAN_ENVIRONMENT_UID]$environment"',
+    "    displayName: Resolve Postman Resource IDs",
+    "  - pwsh: |",
+    "      $ErrorActionPreference = 'Stop'",
+    "      function Resolve-AdoOptional([string]$Value) {",
+    "        if ($Value -match '^\\$\\([^)]+\\)$') { return '' }",
+    "        return $Value",
+    "      }",
+    "      $sslRoot = Join-Path $env:AGENT_TEMPDIRECTORY 'postman-ssl'",
+    "      New-Item -ItemType Directory -Path $sslRoot -Force | Out-Null",
+    "      [IO.File]::WriteAllBytes((Join-Path $sslRoot 'client.crt'), [Convert]::FromBase64String($env:POSTMAN_SSL_CLIENT_CERT_B64))",
+    "      [IO.File]::WriteAllBytes((Join-Path $sslRoot 'client.key'), [Convert]::FromBase64String($env:POSTMAN_SSL_CLIENT_KEY_B64))",
+    "      $extraCa = Resolve-AdoOptional $env:POSTMAN_SSL_EXTRA_CA_CERTS_B64",
+    "      if (-not [string]::IsNullOrWhiteSpace($extraCa)) {",
+    "        [IO.File]::WriteAllBytes((Join-Path $sslRoot 'ca.crt'), [Convert]::FromBase64String($extraCa))",
+    "      }",
+    "    condition: ne(variables['POSTMAN_SSL_CLIENT_CERT_B64'], '')",
+    "    displayName: Decode SSL certificates",
+    "    env:",
+    "      POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)",
+    "      POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)",
+    "      POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)",
+    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID"),
+    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID"),
+    ""
+  ];
+}
 function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
   return [
     "trigger:",
@@ -123561,10 +123701,12 @@ function renderGcWorkflowTemplate() {
 }
 var GC_WORKFLOW_TEMPLATE = renderGcWorkflowTemplate();
 function getCiWorkflowTemplate(provider, options = {}) {
+  const runnerOs = resolveCiRunnerOs(options.runnerOs);
   if (provider === "azure-devops") {
-    const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
+    const rawUrl = runnerOs === "windows" ? String(options.postmanCliWindowsInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL : String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
     const postmanRegion = resolvePostmanRegion(options.postmanRegion);
-    return buildAdoCiWorkflowLines(validateHttpsInstallUrl(rawUrl), postmanRegion).join("\n");
+    const installUrl = validateHttpsInstallUrl(rawUrl);
+    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) : buildAdoCiWorkflowLines(installUrl, postmanRegion)).join("\n");
   }
   return renderCiWorkflowTemplate(options);
 }
@@ -124959,6 +125101,17 @@ var BifrostInternalIntegrationAdapter = class {
       mask: this.secretMasker
     };
   }
+  /**
+   * One-line non-fatal preflight reason: operation + entity (repo/path) + cause +
+   * operator action. Secrets are redacted via secretMasker, then CR/LF and other
+   * line-breaking whitespace are collapsed to spaces so CI logs stay one line.
+   * Display-only: does not alter request repoUrl/path or probe classification.
+   */
+  unknownFilesystemLookupReason(repoUrl, fsPath, cause) {
+    return this.secretMasker(
+      `filesystem lookup for repository ${repoUrl} path ${fsPath} ${cause}; verify Bifrost connectivity/credentials then rerun`
+    ).replace(/[\r\n\v\f\u2028\u2029]+/g, " ");
+  }
   async associateSystemEnvironments(workspaceId, associations) {
     if (associations.length === 0) {
       return;
@@ -125029,7 +125182,11 @@ var BifrostInternalIntegrationAdapter = class {
       } catch {
         return {
           state: "unknown",
-          reason: `filesystem lookup returned non-JSON body (HTTP ${response.status})`
+          reason: this.unknownFilesystemLookupReason(
+            repoUrl,
+            fsPath,
+            `returned non-JSON body (HTTP ${response.status})`
+          )
         };
       }
       const errorMetaWorkspaceId = typeof parsed?.error?.meta?.workspaceId === "string" && parsed.error.meta.workspaceId.trim() ? parsed.error.meta.workspaceId.trim() : void 0;
@@ -125044,7 +125201,11 @@ var BifrostInternalIntegrationAdapter = class {
         if (!id) {
           return {
             state: "unknown",
-            reason: "filesystem lookup returned 200 without a workspace id"
+            reason: this.unknownFilesystemLookupReason(
+              repoUrl,
+              fsPath,
+              "returned 200 without a workspace id"
+            )
           };
         }
         const name = typeof parsed.data.name === "string" && parsed.data.name.trim() ? parsed.data.name.trim() : void 0;
@@ -125062,17 +125223,30 @@ var BifrostInternalIntegrationAdapter = class {
         }
         return {
           state: "unknown",
-          reason: "filesystem lookup returned 403 without error.meta.workspaceId"
+          reason: this.unknownFilesystemLookupReason(
+            repoUrl,
+            fsPath,
+            "returned 403 without error.meta.workspaceId"
+          )
         };
       }
       return {
         state: "unknown",
-        reason: `filesystem lookup returned HTTP ${response.status}`
+        reason: this.unknownFilesystemLookupReason(
+          repoUrl,
+          fsPath,
+          `returned HTTP ${response.status}`
+        )
       };
     } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error);
       return {
         state: "unknown",
-        reason: error instanceof Error ? error.message : String(error)
+        reason: this.unknownFilesystemLookupReason(
+          repoUrl,
+          fsPath,
+          `failed: ${cause}`
+        )
       };
     }
   }
@@ -125286,6 +125460,12 @@ var postmanRepoSyncActionContract = {
       required: false,
       default: ".github/workflows/ci.yml"
     },
+    "ci-runner-os": {
+      description: "Runner operating system for the generated CI workflow.",
+      required: false,
+      default: "linux",
+      allowedValues: ["linux", "windows"]
+    },
     "project-name": {
       description: "Service project name used for environment, mock, and monitor naming.",
       required: true
@@ -126945,6 +127125,25 @@ function parseAssetMarker(description) {
 }
 
 // src/index.ts
+var identitySecretMasker = (input) => input;
+function resolveRepoSyncMasker(dependencies) {
+  return dependencies.secretMasker ?? identitySecretMasker;
+}
+function causeText(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+function toOneLineDisplay(value) {
+  return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
+}
+function formatOrchestrationIssue(params) {
+  const operation = toOneLineDisplay(params.mask(params.operation));
+  const entity = toOneLineDisplay(params.mask(params.entity));
+  const maskedCause = toOneLineDisplay(params.mask(causeText(params.cause)));
+  const detail = toOneLineDisplay(params.mask(params.detail ?? ""));
+  const remediation = toOneLineDisplay(params.mask(params.remediation));
+  const body = `${operation} failed for ${entity}: ${maskedCause}${detail}`.replace(/[.]+$/u, "");
+  return toOneLineDisplay(`${body}. ${remediation}`);
+}
 function parseBooleanInput(value, defaultValue) {
   const normalized = String(value || "").trim().toLowerCase();
   if (!normalized) return defaultValue;
@@ -127041,6 +127240,17 @@ function parseBranchStrategy(value) {
     `Unsupported branch-strategy "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseCiRunnerOs(value) {
+  const definition = postmanRepoSyncActionContract.inputs["ci-runner-os"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "linux");
+  if (allowed.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(
+    `Unsupported ci-runner-os "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function normalizeReleaseLabel(value) {
   const cleaned = normalizeInputValue(value).replace(/^refs\/heads\//, "").replace(/^refs\/tags\//, "").replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
   return cleaned;
@@ -127118,6 +127328,7 @@ function resolveInputs(env = process.env) {
     provider: repoContext.provider,
     ciWorkflowBase64: getInput("ci-workflow-base64", env),
     generateCiWorkflow: parseBooleanInput(getInput("generate-ci-workflow", env), true),
+    ciRunnerOs: parseCiRunnerOs(getInput("ci-runner-os", env)),
     monitorType: getInput("monitor-type", env) || "cloud",
     ciWorkflowPath: getInput("ci-workflow-path", env) || (repoContext.provider === "azure-devops" ? "azure-pipelines.yml" : ".github/workflows/ci.yml"),
     orgMode: parseBooleanInput(getInput("org-mode", env), false),
@@ -127136,6 +127347,7 @@ function resolveInputs(env = process.env) {
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
     postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
+    postmanCliWindowsInstallUrl: endpointProfile.cliWindowsInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl
   };
 }
@@ -127384,19 +127596,34 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
   if (!inputs.workspaceId) {
     return envUids;
   }
+  const mask = resolveRepoSyncMasker(dependencies);
+  const envRemediation = "verify access-token/team/workspace permissions then rerun";
   for (const envName of inputs.environments) {
     const runtimeUrl = String(inputs.envRuntimeUrls[envName] || "").trim();
     const displayName = `${inputs.projectName} - ${envName}`;
     let existingUid = String(envUids[envName] || "").trim();
     if (!existingUid) {
-      const discovered = await dependencies.postman.findEnvironmentByName(
-        inputs.workspaceId,
-        displayName
-      );
-      if (discovered?.uid) {
-        existingUid = discovered.uid;
-        dependencies.core.info(
-          `Discovered existing environment for ${displayName}: ${existingUid}`
+      try {
+        const discovered = await dependencies.postman.findEnvironmentByName(
+          inputs.workspaceId,
+          displayName
+        );
+        if (discovered?.uid) {
+          existingUid = discovered.uid;
+          dependencies.core.info(
+            `Discovered existing environment for ${displayName}: ${existingUid}`
+          );
+        }
+      } catch (error) {
+        throw new Error(
+          formatOrchestrationIssue({
+            operation: "Environment discovery",
+            entity: `workspace ${inputs.workspaceId} environment "${displayName}"`,
+            cause: error,
+            remediation: envRemediation,
+            mask
+          }),
+          { cause: error }
         );
       }
     }
@@ -127416,17 +127643,43 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
       }
       const values2 = buildEnvironmentValues(envName, runtimeUrl);
       if (marker) values2.push({ key: "x-pm-onboarding", value: JSON.stringify(marker), type: "default" });
-      await dependencies.postman.updateEnvironment(existingUid, displayName, values2);
+      try {
+        await dependencies.postman.updateEnvironment(existingUid, displayName, values2);
+      } catch (error) {
+        throw new Error(
+          formatOrchestrationIssue({
+            operation: "Environment update",
+            entity: `workspace ${inputs.workspaceId} environment "${displayName}" (uid ${existingUid})`,
+            cause: error,
+            remediation: envRemediation,
+            mask
+          }),
+          { cause: error }
+        );
+      }
       envUids[envName] = existingUid;
       continue;
     }
     const values = buildEnvironmentValues(envName, runtimeUrl);
     if (assetMarker) values.push({ key: "x-pm-onboarding", value: JSON.stringify(assetMarker), type: "default" });
-    envUids[envName] = await dependencies.postman.createEnvironment(
-      inputs.workspaceId,
-      displayName,
-      values
-    );
+    try {
+      envUids[envName] = await dependencies.postman.createEnvironment(
+        inputs.workspaceId,
+        displayName,
+        values
+      );
+    } catch (error) {
+      throw new Error(
+        formatOrchestrationIssue({
+          operation: "Environment create",
+          entity: `workspace ${inputs.workspaceId} environment "${displayName}"`,
+          cause: error,
+          remediation: envRemediation,
+          mask
+        }),
+        { cause: error }
+      );
+    }
   }
   return envUids;
 }
@@ -127683,11 +127936,15 @@ function renderCiWorkflow(inputs) {
   if (inputs.provider === "azure-devops") {
     return getCiWorkflowTemplate(inputs.provider, {
       postmanCliInstallUrl: inputs.postmanCliInstallUrl,
+      postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
+      runnerOs: inputs.ciRunnerOs,
       postmanRegion: inputs.postmanRegion
     });
   }
   return renderCiWorkflowTemplate({
     postmanCliInstallUrl: inputs.postmanCliInstallUrl,
+    postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
+    runnerOs: inputs.ciRunnerOs,
     postmanRegion: inputs.postmanRegion
   });
 }
@@ -127782,6 +128039,7 @@ async function runRepoSync(inputs, dependencies) {
   }
 }
 async function runRepoSyncInner(inputs, dependencies) {
+  const mask = resolveRepoSyncMasker(dependencies);
   const branchDecision = decideBranchTier(inputs);
   assertBranchAssetIds(inputs, branchDecision);
   const isCanonicalWriter = branchDecision.tier === "legacy" || branchDecision.tier === "canonical";
@@ -127891,8 +128149,15 @@ async function runRepoSyncInner(inputs, dependencies) {
         outputs["environment-sync-status"] = "success";
       } catch (error) {
         outputs["environment-sync-status"] = "failed";
+        const associationSummary = associations.map((entry) => `${entry.envUid}->${entry.systemEnvId}`).join(", ");
         dependencies.core.warning(
-          `System environment association failed: ${error instanceof Error ? error.message : String(error)}`
+          formatOrchestrationIssue({
+            operation: "System environment association",
+            entity: `workspace ${inputs.workspaceId} (${associationSummary})`,
+            cause: error,
+            remediation: "verify access-token/team/system-env mapping then rerun",
+            mask
+          })
         );
       }
     } else if (Object.keys(envUids).length > 0) {
@@ -127920,37 +128185,72 @@ async function runRepoSyncInner(inputs, dependencies) {
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
-        const discovered = await dependencies.postman.findMockByCollection(
-          inputs.baselineCollectionId,
-          mockEnvUid,
-          mockName
-        );
-        if (discovered) {
-          resolvedMockUrl = discovered.mockUrl;
-          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        try {
+          const discovered = await dependencies.postman.findMockByCollection(
+            inputs.baselineCollectionId,
+            mockEnvUid,
+            mockName
+          );
+          if (discovered) {
+            resolvedMockUrl = discovered.mockUrl;
+            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+          }
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Mock discovery",
+              entity: `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error,
+              remediation: "verify collection/environment access then rerun",
+              mask
+            }),
+            { cause: error }
+          );
         }
       }
       if (!resolvedMockUrl) {
-        const mock = await retry(
-          () => dependencies.postman.createMock(
-            inputs.workspaceId,
-            mockName,
-            inputs.baselineCollectionId,
-            mockEnvUid
-          ),
-          {
-            maxAttempts: 3,
-            delayMs: 2e3,
-            backoffMultiplier: 2,
-            onRetry: ({ attempt, error }) => {
-              dependencies.core.warning(
-                `Mock create attempt ${attempt} failed (${error instanceof Error ? error.message : String(error)}); retrying`
-              );
+        const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
+        const mockRemediation = "verify collection/environment access then rerun";
+        try {
+          const mock = await retry(
+            () => dependencies.postman.createMock(
+              inputs.workspaceId,
+              mockName,
+              inputs.baselineCollectionId,
+              mockEnvUid
+            ),
+            {
+              maxAttempts: 3,
+              delayMs: 2e3,
+              backoffMultiplier: 2,
+              onRetry: ({ attempt, maxAttempts, error }) => {
+                dependencies.core.warning(
+                  formatOrchestrationIssue({
+                    operation: `Mock create attempt ${attempt}/${maxAttempts}`,
+                    entity: mockEntity,
+                    cause: error,
+                    remediation: mockRemediation,
+                    mask,
+                    detail: "; retrying"
+                  })
+                );
+              }
             }
-          }
-        );
-        resolvedMockUrl = mock.url;
-        dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
+          );
+          resolvedMockUrl = mock.url;
+          dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Mock create",
+              entity: mockEntity,
+              cause: error,
+              remediation: mockRemediation,
+              mask
+            }),
+            { cause: error }
+          );
+        }
       }
       outputs["mock-url"] = resolvedMockUrl;
     }
@@ -127961,35 +128261,71 @@ async function runRepoSyncInner(inputs, dependencies) {
     if (monitorEnvUid && inputs.monitorType !== "cli") {
       let resolvedMonitorId = "";
       const monitorName = `${assetProjectName} - Smoke Monitor`;
+      const monitorRemediation = "verify monitor IDs/access or set monitor-cron then rerun";
       if (inputs.monitorId) {
         const valid = await dependencies.postman.monitorExists(inputs.monitorId);
         if (valid) {
           resolvedMonitorId = inputs.monitorId;
           dependencies.core.info(`Reusing monitor from explicit input: ${resolvedMonitorId}`);
         } else {
-          dependencies.core.warning(`Explicit monitor-id ${inputs.monitorId} not found in Postman, falling through to discovery.`);
+          dependencies.core.warning(
+            formatOrchestrationIssue({
+              operation: "Explicit monitor-id lookup",
+              entity: `monitor-id ${inputs.monitorId} workspace ${inputs.workspaceId} collection ${inputs.smokeCollectionId} environment ${monitorEnvUid}`,
+              cause: "not found in Postman",
+              remediation: monitorRemediation,
+              mask,
+              detail: "; falling through to discovery"
+            })
+          );
         }
       }
       if (!resolvedMonitorId && inputs.smokeCollectionId) {
-        const discovered = await dependencies.postman.findMonitorByCollection(
-          inputs.smokeCollectionId,
-          monitorEnvUid,
-          monitorName
-        );
-        if (discovered) {
-          resolvedMonitorId = discovered.uid;
-          dependencies.core.info(`Discovered existing monitor for collection ${inputs.smokeCollectionId}: ${resolvedMonitorId}`);
+        try {
+          const discovered = await dependencies.postman.findMonitorByCollection(
+            inputs.smokeCollectionId,
+            monitorEnvUid,
+            monitorName
+          );
+          if (discovered) {
+            resolvedMonitorId = discovered.uid;
+            dependencies.core.info(`Discovered existing monitor for collection ${inputs.smokeCollectionId}: ${resolvedMonitorId}`);
+          }
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Monitor discovery",
+              entity: `monitor "${monitorName}" workspace ${inputs.workspaceId} collection ${inputs.smokeCollectionId} environment ${monitorEnvUid}`,
+              cause: error,
+              remediation: monitorRemediation,
+              mask
+            }),
+            { cause: error }
+          );
         }
       }
       if (!resolvedMonitorId) {
-        resolvedMonitorId = await dependencies.postman.createMonitor(
-          inputs.workspaceId,
-          monitorName,
-          inputs.smokeCollectionId,
-          monitorEnvUid,
-          effectiveCron || void 0
-        );
-        dependencies.core.info(`Created new monitor: ${resolvedMonitorId}${effectiveCron ? "" : " (disabled \u2014 no cron configured; will trigger a one-time run)"}`);
+        try {
+          resolvedMonitorId = await dependencies.postman.createMonitor(
+            inputs.workspaceId,
+            monitorName,
+            inputs.smokeCollectionId,
+            monitorEnvUid,
+            effectiveCron || void 0
+          );
+          dependencies.core.info(`Created new monitor: ${resolvedMonitorId}${effectiveCron ? "" : " (disabled \u2014 no cron configured; will trigger a one-time run)"}`);
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Monitor create",
+              entity: `monitor "${monitorName}" workspace ${inputs.workspaceId} collection ${inputs.smokeCollectionId} environment ${monitorEnvUid}`,
+              cause: error,
+              remediation: monitorRemediation,
+              mask
+            }),
+            { cause: error }
+          );
+        }
       }
       outputs["monitor-id"] = resolvedMonitorId;
       if (!effectiveCron && resolvedMonitorId) {
@@ -127998,7 +128334,13 @@ async function runRepoSyncInner(inputs, dependencies) {
           dependencies.core.info(`Triggered one-time run for monitor: ${resolvedMonitorId}`);
         } catch (error) {
           dependencies.core.warning(
-            `Failed to trigger one-time run for monitor ${resolvedMonitorId}: ${error instanceof Error ? error.message : String(error)}`
+            formatOrchestrationIssue({
+              operation: "Monitor one-time run",
+              entity: `monitor ${resolvedMonitorId} name "${monitorName}" workspace ${inputs.workspaceId} collection ${inputs.smokeCollectionId} environment ${monitorEnvUid}`,
+              cause: error,
+              remediation: monitorRemediation,
+              mask
+            })
           );
         }
       }
@@ -128063,18 +128405,57 @@ async function runRepoSyncInner(inputs, dependencies) {
       dependencies.core.info(`Tagged spec version at finalize: ${tag.name || tagName}`);
     } catch (error) {
       const status = error.status;
+      const specEntity = `spec ${inputs.specId} tag "${tagName}" workspace ${inputs.workspaceId}`;
+      const specRemediation = "inspect existing tags/access and rerun";
       if (status === 409) {
-        const tags = await dependencies.postman.listSpecVersionTags?.(inputs.specId).catch(() => []) ?? [];
+        let tags = [];
+        let listError;
+        if (dependencies.postman.listSpecVersionTags) {
+          try {
+            tags = await dependencies.postman.listSpecVersionTags(inputs.specId);
+          } catch (lookupError) {
+            listError = lookupError;
+          }
+        }
         const latest = tags[0];
-        if (latest && (latest.name === tagName || /\([0-9a-f]{7}\)$/.test(latest.name) || /^[0-9a-f]{7}$/.test(latest.name))) {
+        if (!listError && latest && (latest.name === tagName || /\([0-9a-f]{7}\)$/.test(latest.name) || /^[0-9a-f]{7}$/.test(latest.name))) {
           outputs["spec-version-tag"] = latest.name;
           outputs["spec-version-url"] = `https://web.postman.co/workspace/${encodeURIComponent(inputs.workspaceId)}/specification/${encodeURIComponent(inputs.specId)}?tagId=${encodeURIComponent(latest.id)}&versionLabel=${encodeURIComponent(latest.name)}`;
           dependencies.core.info(`Latest changelog group already tagged as "${latest.name}"; adopting.`);
+        } else if (listError) {
+          dependencies.core.warning(
+            formatOrchestrationIssue({
+              operation: "Spec Hub tagging conflict",
+              entity: specEntity,
+              cause: `create=${causeText(error)}; listSpecVersionTags=${causeText(listError)}`,
+              remediation: specRemediation,
+              mask,
+              detail: "; could not list existing tags to confirm adoption"
+            })
+          );
         } else {
-          dependencies.core.warning("Latest changelog group already carries a hand-applied tag; leaving it in place.");
+          dependencies.core.warning(
+            formatOrchestrationIssue({
+              operation: "Spec Hub tagging conflict",
+              entity: specEntity,
+              cause: error,
+              remediation: specRemediation,
+              mask,
+              detail: "; latest changelog group already carries a hand-applied or nonmatching tag; leaving it in place"
+            })
+          );
         }
       } else {
-        dependencies.core.warning(`Spec version tagging failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+        dependencies.core.warning(
+          formatOrchestrationIssue({
+            operation: "Spec version tagging",
+            entity: specEntity,
+            cause: error,
+            remediation: specRemediation,
+            mask,
+            detail: " (non-fatal)"
+          })
+        );
       }
     }
   }
@@ -128105,7 +128486,16 @@ async function resolvePostmanApiKeyAndTeamId(inputs, actionCore, actionExec, mas
       }
     } catch (error) {
       if (typeof error === "object" && error !== null && "status" in error && (error.status === 401 || error.status === 403)) {
-        actionCore.warning("Provided postman-api-key is invalid or expired.");
+        const status = error.status;
+        actionCore.warning(
+          formatOrchestrationIssue({
+            operation: "PMAK GET /me validation",
+            entity: `status ${status}`,
+            cause: error,
+            remediation: "replace postman-api-key or provide a valid postman-access-token then rerun",
+            mask: masker
+          })
+        );
       } else {
         throw error;
       }
@@ -128127,6 +128517,7 @@ async function resolvePostmanApiKeyAndTeamId(inputs, actionCore, actionExec, mas
     const keyName = `repo-sync-action-${Date.now()}`;
     apiKey = await internalIntegration.createApiKey(keyName);
     actionCore.setSecret(apiKey);
+    const persistSecretRemediation = "grant Actions secrets write permission or set POSTMAN_API_KEY manually then rerun";
     if (inputs.provider === "azure-devops") {
       if (options.persistGeneratedApiKeySecret ?? true) {
         actionCore.warning(
@@ -128153,16 +128544,48 @@ async function resolvePostmanApiKeyAndTeamId(inputs, actionCore, actionExec, mas
             ignoreReturnCode: true
           });
           if (ghCommand.exitCode !== 0) {
-            actionCore.warning(`Failed to save POSTMAN_API_KEY secret: ${ghCommand.stderr}`);
+            actionCore.warning(
+              formatOrchestrationIssue({
+                operation: "gh secret set POSTMAN_API_KEY",
+                entity: `repository ${repo}`,
+                cause: ghCommand.stderr || `exit code ${ghCommand.exitCode}`,
+                remediation: persistSecretRemediation,
+                mask: masker
+              })
+            );
           }
         } catch (error) {
           actionCore.warning(
-            `Error saving POSTMAN_API_KEY secret: ${error instanceof Error ? error.message : String(error)}`
+            formatOrchestrationIssue({
+              operation: "gh secret set POSTMAN_API_KEY",
+              entity: `repository ${repo}`,
+              cause: error,
+              remediation: persistSecretRemediation,
+              mask: masker
+            })
           );
         }
+      } else {
+        actionCore.warning(
+          formatOrchestrationIssue({
+            operation: "gh secret set POSTMAN_API_KEY",
+            entity: "repository (missing)",
+            cause: "repository context is empty",
+            remediation: "set repository context or persist POSTMAN_API_KEY manually then rerun",
+            mask: masker
+          })
+        );
       }
     } else if (options.persistGeneratedApiKeySecret ?? true) {
-      actionCore.warning("No GitHub token provided; cannot save generated POSTMAN_API_KEY secret.");
+      actionCore.warning(
+        formatOrchestrationIssue({
+          operation: "gh secret set POSTMAN_API_KEY",
+          entity: inputs.repository ? `repository ${inputs.repository}` : "repository (unknown)",
+          cause: "no GitHub token provided",
+          remediation: "provide github-token/gh-fallback-token or set POSTMAN_API_KEY manually then rerun",
+          mask: masker
+        })
+      );
     } else {
       actionCore.info("Skipping generated POSTMAN_API_KEY GitHub secret persistence for this run.");
     }
@@ -128201,7 +128624,13 @@ async function resolvePostmanApiKeyAndTeamId(inputs, actionCore, actionExec, mas
       const isNonOrgSquads = error instanceof HttpError && error.status === 400 && /squad feature is not available/i.test(error.responseBody);
       if (!isNonOrgSquads) {
         actionCore.warning(
-          `Org-mode auto-detection via ums squads failed (non-fatal; set org-mode explicitly if Bifrost calls fail): ${error instanceof Error ? error.message : String(error)}`
+          formatOrchestrationIssue({
+            operation: "Org-mode auto-detection via ums squads",
+            entity: `team ${teamId}`,
+            cause: error,
+            remediation: "set org-mode and team-id explicitly then rerun",
+            mask: masker
+          })
         );
       }
     }
@@ -128321,7 +128750,8 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     core: factories.core,
     postman,
     internalIntegration,
-    repoMutation
+    repoMutation,
+    secretMasker: masker
   };
 }
 function decideBranchTier(inputs, env = process.env) {
@@ -128755,6 +129185,7 @@ var CLI_INPUT_NAMES = [
   "gh-fallback-token",
   "ci-workflow-base64",
   "generate-ci-workflow",
+  "ci-runner-os",
   "monitor-type",
   "ci-workflow-path",
   "org-mode",