@postman-cse/onboarding-repo-sync 2.1.7 → 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;
@@ -124998,7 +125151,106 @@ var BifrostInternalIntegrationAdapter = class {
       throw advised ?? httpErr;
     }
   }
-  async connectWorkspaceToRepository(workspaceId, repoUrl) {
+  /**
+   * Probe who (if anyone) already owns the global `(repo, path)` filesystem
+   * link. Non-fatal: unexpected statuses / network errors yield `unknown` so
+   * callers can proceed and rely on reactive POST conflict handling.
+   *
+   * Bifrost states (FileSystemController.fetchWorkspaceForFileSystem):
+   *   - 200 + data null  -> free
+   *   - 200 + data       -> linked-visible (workspace payload)
+   *   - 403 + error.meta.workspaceId -> linked-invisible
+   *   - 200 + error.meta.workspaceId -> linked-invisible (proxy envelope)
+   */
+  async findWorkspaceForRepo(repoUrl, path5 = "/") {
+    const fsPath = path5 && path5.trim() ? path5.trim() : "/";
+    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+    const payload = {
+      service: "workspaces",
+      method: "GET",
+      path: `/workspaces/filesystem?repo=${encodeURIComponent(repoUrl)}&path=${encodeURIComponent(fsPath)}`
+    };
+    try {
+      const response = await this.fetchImpl(url, {
+        method: "POST",
+        headers: this.bifrostHeaders(),
+        body: JSON.stringify(payload)
+      });
+      let parsed = {};
+      try {
+        parsed = await response.json();
+      } catch {
+        return {
+          state: "unknown",
+          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;
+      if (errorMetaWorkspaceId) {
+        return { state: "linked-invisible", workspaceId: errorMetaWorkspaceId };
+      }
+      if (response.ok) {
+        if (parsed?.data == null) {
+          return { state: "free" };
+        }
+        const id = typeof parsed.data.id === "string" ? parsed.data.id.trim() : "";
+        if (!id) {
+          return {
+            state: "unknown",
+            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;
+        return {
+          state: "linked-visible",
+          workspace: name ? { id, name } : { id }
+        };
+      }
+      if (response.status === 403) {
+        const workspaceId = extractDuplicateWorkspaceId(
+          JSON.stringify(parsed)
+        );
+        if (workspaceId) {
+          return { state: "linked-invisible", workspaceId };
+        }
+        return {
+          state: "unknown",
+          reason: this.unknownFilesystemLookupReason(
+            repoUrl,
+            fsPath,
+            "returned 403 without error.meta.workspaceId"
+          )
+        };
+      }
+      return {
+        state: "unknown",
+        reason: this.unknownFilesystemLookupReason(
+          repoUrl,
+          fsPath,
+          `returned HTTP ${response.status}`
+        )
+      };
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error);
+      return {
+        state: "unknown",
+        reason: this.unknownFilesystemLookupReason(
+          repoUrl,
+          fsPath,
+          `failed: ${cause}`
+        )
+      };
+    }
+  }
+  async connectWorkspaceToRepository(workspaceId, repoUrl, options) {
     const url = `${this.bifrostBaseUrl}/ws/proxy`;
     const payload = {
       service: "workspaces",
@@ -125025,6 +125277,11 @@ var BifrostInternalIntegrationAdapter = class {
         if (isDuplicate) {
           const existingWorkspaceId = extractDuplicateWorkspaceId(body);
           if (existingWorkspaceId && existingWorkspaceId !== workspaceId) {
+            if (options?.preflightWasFree) {
+              throw new Error(
+                `REPOSITORY_LINK_CONFLICT_UNRESOLVED: Preflight found no active owner, but link creation reported workspace ${existingWorkspaceId}. Stop and contact Postman support; do not alter the repository URL.`
+              );
+            }
             throw new Error(
               await this.describeWorkspaceLinkConflict(existingWorkspaceId, workspaceId, repoUrl)
             );
@@ -125203,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
@@ -126862,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;
@@ -126958,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;
@@ -127035,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),
@@ -127053,6 +127347,7 @@ function resolveInputs(env = process.env) {
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
     postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
+    postmanCliWindowsInstallUrl: endpointProfile.cliWindowsInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl
   };
 }
@@ -127301,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 }
         );
       }
     }
@@ -127333,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;
 }
@@ -127600,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
   });
 }
@@ -127699,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";
@@ -127758,6 +128099,39 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
     }
   }
+  let skipRepositoryLinkPost = false;
+  let repositoryLinkPreflightWasFree = false;
+  if (inputs.workspaceLinkEnabled && inputs.workspaceId && inputs.repoUrl && dependencies.internalIntegration?.findWorkspaceForRepo) {
+    const probe = await dependencies.internalIntegration.findWorkspaceForRepo(
+      inputs.repoUrl,
+      "/"
+    );
+    if (probe.state === "linked-visible") {
+      if (probe.workspace.id === inputs.workspaceId) {
+        skipRepositoryLinkPost = true;
+        dependencies.core.info(
+          `REPOSITORY_LINK_ALREADY_TARGET: Repository ${inputs.repoUrl} at path / is already linked to target workspace ${inputs.workspaceId}; continuing.`
+        );
+      } else {
+        const ownerName = probe.workspace.name?.trim() || "unknown";
+        throw new Error(
+          `REPOSITORY_LINK_CONFLICT_VISIBLE: Repository ${inputs.repoUrl} at path / is already linked to workspace ${probe.workspace.id} ("${ownerName}"). No Postman assets were changed. Reuse that workspace or disconnect it in Workspace Settings, then rerun.`
+        );
+      }
+    } else if (probe.state === "linked-invisible") {
+      let message = `REPOSITORY_LINK_CONFLICT_INVISIBLE: Repository ${inputs.repoUrl} at path / is linked to workspace ${probe.workspaceId}, but these credentials cannot view it. No Postman assets were changed. Ask its owner or a team admin to disconnect it.`;
+      if (inputs.orgMode) {
+        message += " Verify workspace-team-id; if the owner is in another sub-team, ask that sub-team's admin to disconnect it.";
+      }
+      throw new Error(message);
+    } else if (probe.state === "free") {
+      repositoryLinkPreflightWasFree = true;
+    } else {
+      dependencies.core.warning(
+        `REPOSITORY_LINK_PREFLIGHT_UNKNOWN: Unable to determine the existing repository link (${probe.reason}); continuing and relying on link creation conflict handling.`
+      );
+    }
+  }
   const branchAssetMarker = buildBranchAssetMarker(branchDecision, inputs);
   const envUids = await upsertEnvironments(inputs, dependencies, resourcesState, branchAssetMarker);
   outputs["environment-uids-json"] = JSON.stringify(envUids);
@@ -127775,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) {
@@ -127804,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;
     }
@@ -127845,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) {
@@ -127882,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
+            })
           );
         }
       }
@@ -127890,18 +128348,33 @@ async function runRepoSyncInner(inputs, dependencies) {
   }
   if (inputs.workspaceLinkEnabled && inputs.workspaceId && inputs.repoUrl && dependencies.internalIntegration) {
     try {
-      await dependencies.internalIntegration.connectWorkspaceToRepository(
-        inputs.workspaceId,
-        inputs.repoUrl
-      );
-      outputs["workspace-link-status"] = "success";
-      dependencies.core.info(
-        `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl}`
-      );
+      if (skipRepositoryLinkPost) {
+        outputs["workspace-link-status"] = "success";
+        dependencies.core.info(
+          `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl} (preflight already-target; link POST skipped)`
+        );
+      } else {
+        await dependencies.internalIntegration.connectWorkspaceToRepository(
+          inputs.workspaceId,
+          inputs.repoUrl,
+          repositoryLinkPreflightWasFree ? { preflightWasFree: true } : void 0
+        );
+        outputs["workspace-link-status"] = "success";
+        dependencies.core.info(
+          `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl}`
+        );
+      }
     } catch (error) {
       outputs["workspace-link-status"] = "failed";
-      const message = `Workspace link failed: ${error instanceof Error ? error.message : String(error)}`;
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const isUnresolvedContract = rawMessage.startsWith(
+        "REPOSITORY_LINK_CONFLICT_UNRESOLVED:"
+      );
+      const message = isUnresolvedContract ? rawMessage : `Workspace link failed: ${rawMessage}`;
       if (branchDecision.tier === "canonical") {
+        if (isUnresolvedContract && error instanceof Error) {
+          throw error;
+        }
         throw new Error(message, { cause: error });
       }
       dependencies.core.warning(message);
@@ -127932,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)"
+          })
+        );
       }
     }
   }
@@ -127974,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;
       }
@@ -127996,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(
@@ -128022,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.");
     }
@@ -128070,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
+          })
         );
       }
     }
@@ -128190,7 +128750,8 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     core: factories.core,
     postman,
     internalIntegration,
-    repoMutation
+    repoMutation,
+    secretMasker: masker
   };
 }
 function decideBranchTier(inputs, env = process.env) {
@@ -128624,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",