@postman-cse/onboarding-repo-sync 2.1.4 → 2.1.6

package/dist/cli.cjs

@@ -92334,11 +92334,11 @@ var require_valid = __commonJS({
 var require_clean = __commonJS({
   "node_modules/postman-collection/node_modules/semver/functions/clean.js"(exports2, module2) {
     var parse2 = require_parse5();
-    var clean = (version2, options) => {
+    var clean2 = (version2, options) => {
       const s = parse2(version2.trim().replace(/^[=v]+/, ""), options);
       return s ? s.version : null;
     };
-    module2.exports = clean;
+    module2.exports = clean2;
   }
 });
 
@@ -93649,7 +93649,7 @@ var require_semver2 = __commonJS({
     var identifiers = require_identifiers();
     var parse2 = require_parse5();
     var valid = require_valid();
-    var clean = require_clean();
+    var clean2 = require_clean();
     var inc = require_inc();
     var diff = require_diff();
     var major = require_major();
@@ -93687,7 +93687,7 @@ var require_semver2 = __commonJS({
     module2.exports = {
       parse: parse2,
       valid,
-      clean,
+      clean: clean2,
       inc,
       diff,
       major,
@@ -119798,7 +119798,7 @@ __export(cli_exports, {
 });
 module.exports = __toCommonJS(cli_exports);
 var import_node_child_process = require("node:child_process");
-var import_node_fs4 = require("node:fs");
+var import_node_fs5 = require("node:fs");
 var import_promises = require("node:fs/promises");
 var import_node_path3 = __toESM(require("node:path"), 1);
 var import_node_util = require("node:util");
@@ -120166,7 +120166,7 @@ var ExitCode;
 })(ExitCode || (ExitCode = {}));
 
 // src/index.ts
-var import_node_fs3 = require("node:fs");
+var import_node_fs4 = require("node:fs");
 var path3 = __toESM(require("node:path"), 1);
 
 // node_modules/js-yaml/dist/js-yaml.mjs
@@ -123289,6 +123289,9 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     "    branches: [main]",
     "  schedule:",
     '    - cron: "0 */6 * * *"',
+    "concurrency:",
+    "  group: postman-onboard-${{ github.head_ref || github.ref_name }}",
+    "  cancel-in-progress: false",
     "jobs:",
     "  test:",
     "    runs-on: ubuntu-latest",
@@ -123305,7 +123308,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     "          ruby <<'RUBY'",
     "          require 'yaml'",
     "          config = YAML.load_file('.postman/resources.yaml') || {}",
-    "          cloud = config.fetch('cloudResources', {})",
+    "          cloud = config.fetch('canonical', config.fetch('cloudResources', {}))",
     "          collections = cloud.fetch('collections', {})",
     "          environments = cloud.fetch('environments', {})",
     "          smoke = collections.find { |path, _| path.include?('[Smoke]') }&.last",
@@ -123503,6 +123506,58 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     ""
   ];
 }
+function renderGcWorkflowTemplate() {
+  return [
+    "name: Postman Preview GC",
+    "on:",
+    "  delete:",
+    '    branches: ["**"]',
+    "  pull_request:",
+    "    types: [closed]",
+    "  schedule:",
+    '    - cron: "0 2 * * *"',
+    "  workflow_dispatch:",
+    "    inputs:",
+    "      branch:",
+    "        description: Branch name to GC (optional, otherwise sweep by TTL/branch-existence)",
+    "        required: false",
+    "concurrency:",
+    "  group: postman-preview-gc-${{ github.ref_name }}",
+    "  cancel-in-progress: false",
+    "jobs:",
+    "  gc:",
+    "    runs-on: ubuntu-latest",
+    "    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - name: Run Postman preview GC (provider-neutral cli.cjs gc)",
+    "        env:",
+    "          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}",
+    "          POSTMAN_ACCESS_TOKEN: ${{ secrets.POSTMAN_ACCESS_TOKEN }}",
+    "          POSTMAN_WORKSPACE_ID: ${{ vars.POSTMAN_WORKSPACE_ID }}",
+    "          REPO_URL: https://github.com/${{ github.repository }}",
+    "        run: |",
+    "          set -euo pipefail",
+    "          # The repo-sync action bundles a provider-neutral gc command (cli.cjs gc)",
+    "          # that uses the Postman access token for inventory/deletion and the",
+    "          # provider ambient credential (GITHUB_TOKEN via git ls-remote) for branch existence.",
+    "          # Daily scheduled run is the retention executor (TTL contract of last resort).",
+    '          if [ -n "${{ inputs.branch }}" ]; then',
+    '            npx @postman-cse/onboarding-repo-sync gc --branch "${{ inputs.branch }}" --workspace-id "$POSTMAN_WORKSPACE_ID" --repo-url "$REPO_URL"',
+    "          else",
+    '            npx @postman-cse/onboarding-repo-sync gc --workspace-id "$POSTMAN_WORKSPACE_ID" --repo-url "$REPO_URL"',
+    "          fi",
+    "      - name: Orphan audit summary (job summary)",
+    "        if: always()",
+    "        run: |",
+    '          echo "### Preview GC orphan audit" >> "$GITHUB_STEP_SUMMARY"',
+    '          echo "Marker-guarded deletion only \u2014 strangers (no marker) are never deleted. See gc-summary-json for structured counts." >> "$GITHUB_STEP_SUMMARY"',
+    ""
+  ].join("\n");
+}
+var GC_WORKFLOW_TEMPLATE = renderGcWorkflowTemplate();
 function getCiWorkflowTemplate(provider, options = {}) {
   if (provider === "azure-devops") {
     const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
@@ -125073,6 +125128,53 @@ function createInternalIntegrationAdapter(options) {
   return new BifrostInternalIntegrationAdapter(options);
 }
 
+// src/lib/retry.ts
+function sleep(delayMs) {
+  return new Promise((resolve2) => {
+    setTimeout(resolve2, delayMs);
+  });
+}
+function normalizeRetryOptions(options) {
+  return {
+    maxAttempts: Math.max(1, options.maxAttempts ?? 3),
+    delayMs: Math.max(0, options.delayMs ?? 2e3),
+    backoffMultiplier: Math.max(1, options.backoffMultiplier ?? 1),
+    maxDelayMs: options.maxDelayMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, options.maxDelayMs),
+    onRetry: options.onRetry ?? (async () => void 0),
+    shouldRetry: options.shouldRetry ?? (() => true),
+    sleep: options.sleep ?? sleep
+  };
+}
+async function retry(operation, options = {}) {
+  const normalized = normalizeRetryOptions(options);
+  let nextDelayMs = normalized.delayMs;
+  for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      const shouldRetry = attempt < normalized.maxAttempts && normalized.shouldRetry(error, {
+        attempt,
+        maxAttempts: normalized.maxAttempts
+      });
+      if (!shouldRetry) {
+        throw error;
+      }
+      await normalized.onRetry({
+        attempt,
+        maxAttempts: normalized.maxAttempts,
+        delayMs: nextDelayMs,
+        error
+      });
+      await normalized.sleep(nextDelayMs);
+      nextDelayMs = Math.min(
+        normalized.maxDelayMs,
+        Math.round(nextDelayMs * normalized.backoffMultiplier)
+      );
+    }
+  }
+  throw new Error("Retry exhausted without returning or throwing");
+}
+
 // src/contracts.ts
 var postmanRepoSyncActionContract = {
   name: "postman-repo-sync-action",
@@ -125242,6 +125344,25 @@ var postmanRepoSyncActionContract = {
       default: "warn",
       allowedValues: ["enforce", "warn"]
     },
+    "branch-strategy": {
+      description: "Branch-aware sync strategy. legacy (default) keeps branch-blind behavior; publish-gate restricts canonical writes to the canonical branch and skips repo-sync on other branches; preview additionally maintains suffixed per-branch preview asset sets.",
+      required: false,
+      default: "legacy",
+      allowedValues: ["legacy", "preview", "publish-gate"]
+    },
+    "canonical-branch": {
+      description: "Explicit canonical branch (the sole writer of canonical assets and tracked state). Defaults to the provider-resolved default branch; required on providers without a default-branch variable (Bitbucket, Azure DevOps) when branch-strategy is not legacy.",
+      required: false
+    },
+    "channels": {
+      description: 'Comma-separated channel map for long-lived promotion branches, e.g. "develop=DEV, staging=STAGE, release/*=RC". Channel branches maintain prefix-named parallel asset sets and never mutate canonical assets.',
+      required: false
+    },
+    "preview-ttl": {
+      description: "Sliding TTL in days for preview asset sets (refreshed on every successful preview sync; the retention contract of last resort when no provider credential is available for branch-existence checks).",
+      required: false,
+      default: "30"
+    },
     "github-token": {
       description: "GitHub token used for repo variable persistence and commits.",
       required: false
@@ -125279,6 +125400,11 @@ var postmanRepoSyncActionContract = {
       description: "Spec UID from bootstrap, persisted into .postman/resources.yaml cloudResources.",
       required: false
     },
+    "spec-content-changed": {
+      description: "Whether bootstrap changed canonical spec content; controls final native Spec Hub tag publication.",
+      required: false,
+      default: "true"
+    },
     "spec-path": {
       description: "Optional repo-root-relative path to the local spec file for resources/workflows metadata.",
       required: false
@@ -125323,6 +125449,18 @@ var postmanRepoSyncActionContract = {
     },
     "commit-sha": {
       description: "Commit SHA produced by repo-write-mode, if any."
+    },
+    "sync-status": {
+      description: "Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy."
+    },
+    "branch-decision": {
+      description: "Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION)."
+    },
+    "spec-version-tag": {
+      description: "Native Spec Hub version tag created after successful canonical repo-sync finalization."
+    },
+    "spec-version-url": {
+      description: "Read-only URL for the tagged Spec Hub snapshot."
     }
   },
   behavior: {
@@ -125390,53 +125528,6 @@ var PostmanAssetsClient = class {
   }
 };
 
-// src/lib/retry.ts
-function sleep(delayMs) {
-  return new Promise((resolve2) => {
-    setTimeout(resolve2, delayMs);
-  });
-}
-function normalizeRetryOptions(options) {
-  return {
-    maxAttempts: Math.max(1, options.maxAttempts ?? 3),
-    delayMs: Math.max(0, options.delayMs ?? 2e3),
-    backoffMultiplier: Math.max(1, options.backoffMultiplier ?? 1),
-    maxDelayMs: options.maxDelayMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, options.maxDelayMs),
-    onRetry: options.onRetry ?? (async () => void 0),
-    shouldRetry: options.shouldRetry ?? (() => true),
-    sleep: options.sleep ?? sleep
-  };
-}
-async function retry(operation, options = {}) {
-  const normalized = normalizeRetryOptions(options);
-  let nextDelayMs = normalized.delayMs;
-  for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
-    try {
-      return await operation();
-    } catch (error) {
-      const shouldRetry = attempt < normalized.maxAttempts && normalized.shouldRetry(error, {
-        attempt,
-        maxAttempts: normalized.maxAttempts
-      });
-      if (!shouldRetry) {
-        throw error;
-      }
-      await normalized.onRetry({
-        attempt,
-        maxAttempts: normalized.maxAttempts,
-        delayMs: nextDelayMs,
-        error
-      });
-      await normalized.sleep(nextDelayMs);
-      nextDelayMs = Math.min(
-        normalized.maxDelayMs,
-        Math.round(nextDelayMs * normalized.backoffMultiplier)
-      );
-    }
-  }
-  throw new Error("Retry exhausted without returning or throwing");
-}
-
 // src/lib/postman/postman-gateway-assets-client.ts
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
@@ -125462,6 +125553,84 @@ var PostmanGatewayAssetsClient = class {
     if (!envelope) return null;
     return this.asRecord(envelope.data) ?? envelope;
   }
+  /** Native Spec Hub tags attach to the latest changelog group. */
+  async tagSpecVersion(specId, name) {
+    const trimmed = name.trim().slice(0, 255);
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "post",
+      path: `/specifications/${specId}/tags`,
+      body: { name: trimmed }
+    });
+    const record = this.dataOf(response) ?? {};
+    return { id: String(record.id ?? "").trim(), name: String(record.name ?? trimmed).trim() };
+  }
+  async listSpecVersionTags(specId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/tags`,
+      query: { limit: "50" }
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({
+      id: String(entry.id ?? "").trim(),
+      // listTags returns `message`; createTag returns `name`. Accept both.
+      name: String(entry.name ?? entry.message ?? "").trim()
+    })).filter((entry) => entry.id || entry.name);
+  }
+  async deleteCollection(collectionUid) {
+    const bareId = String(collectionUid).split("-").slice(-5).join("-") || collectionUid;
+    await this.gateway.requestJson({
+      service: "collection",
+      method: "delete",
+      path: `/v3/collections/${bareId}`
+    });
+  }
+  async listSpecifications(workspaceId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications?containerType=workspace&containerId=${workspaceId}`
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({ uid: String(entry.id ?? entry.uid ?? "").trim(), name: String(entry.name ?? "").trim() })).filter((entry) => entry.uid && entry.name);
+  }
+  async getSpecContent(specId) {
+    const files = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/files`
+    });
+    const entries = Array.isArray(files?.data) ? files.data : [];
+    const root = entries.map((entry) => this.asRecord(entry)).find((entry) => entry?.type === "ROOT") ?? entries.map((entry) => this.asRecord(entry)).find((entry) => entry !== null);
+    const fileId = String(root?.id ?? "").trim();
+    if (!fileId) return void 0;
+    const file = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/files/${fileId}`,
+      query: { fields: "content" }
+    });
+    const record = this.dataOf(file);
+    return typeof record?.content === "string" ? record.content : void 0;
+  }
+  async listSpecCollections(specId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/collections`
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({ uid: String(entry.collection ?? entry.collectionId ?? entry.id ?? "").trim(), name: String(entry.name ?? "").trim() })).filter((entry) => entry.uid);
+  }
+  async deleteSpec(specId) {
+    await this.gateway.requestJson({
+      service: "specification",
+      method: "delete",
+      path: `/specifications/${specId}`
+    });
+  }
   idOf(record) {
     if (!record) return "";
     const id = record.uid ?? record.id;
@@ -125746,6 +125915,9 @@ var PostmanGatewayAssetsClient = class {
             path: `/mocks?workspace=${ws}`,
             body
           },
+          // Unsafe create: never blind re-POST. An ESOCKETTIMEDOUT after accept
+          // may still have created the mock; reconcile via discovery below and
+          // let the orchestrator retry the whole create-or-adopt cycle.
           { retryTransient: false }
         );
         const record = this.dataOf(response);
@@ -125784,6 +125956,33 @@ var PostmanGatewayAssetsClient = class {
       environment: String(m.environment ?? "")
     }));
   }
+  /**
+   * Delete an environment through the sync service (GC path). The path id is
+   * the bare model id (public uid tail), mirroring updateEnvironment.
+   */
+  async deleteEnvironment(uid) {
+    await this.gateway.requestJson({
+      service: "sync",
+      method: "delete",
+      path: `/environment/${this.toModelId(uid)}`
+    });
+  }
+  /** Delete a mock server (GC path). */
+  async deleteMock(uid) {
+    await this.gateway.requestJson({
+      service: "mock",
+      method: "delete",
+      path: `/mocks/${this.toModelId(uid)}`
+    });
+  }
+  /** Delete a collection-based monitor (jobTemplate) (GC path). */
+  async deleteMonitor(uid) {
+    await this.gateway.requestJson({
+      service: "monitors",
+      method: "delete",
+      path: `/jobTemplates/${this.toModelId(uid)}`
+    });
+  }
   async mockExists(uid) {
     try {
       await this.gateway.requestJson({
@@ -126238,6 +126437,331 @@ var AccessTokenGatewayClient = class {
   }
 };
 
+// src/lib/repo/branch-decision.ts
+var import_node_fs3 = require("node:fs");
+var import_node_crypto2 = require("node:crypto");
+var ContractError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "ContractError";
+  }
+};
+function clean(value) {
+  const trimmed = (value ?? "").trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function stripRefPrefix(ref) {
+  const raw = clean(ref);
+  if (!raw) {
+    return { kind: "unknown" };
+  }
+  if (raw.startsWith("refs/heads/")) {
+    return { name: raw.slice("refs/heads/".length), kind: "branch" };
+  }
+  if (raw.startsWith("refs/tags/")) {
+    return { name: raw.slice("refs/tags/".length), kind: "tag" };
+  }
+  if (raw.startsWith("refs/pull/") || raw.startsWith("refs/merge")) {
+    return { kind: "unknown" };
+  }
+  return { name: raw, kind: "branch" };
+}
+function detectProvider(env) {
+  if (clean(env.GITHUB_ACTIONS) || clean(env.GITHUB_REPOSITORY)) return "github";
+  if (clean(env.GITLAB_CI) || clean(env.CI_PROJECT_PATH)) return "gitlab";
+  if (clean(env.BITBUCKET_REPO_SLUG) || clean(env.BITBUCKET_BRANCH)) return "bitbucket";
+  if (clean(env.TF_BUILD) || clean(env.BUILD_REPOSITORY_URI)) return "azure-devops";
+  return "unknown";
+}
+function readGithubEvent(env) {
+  const path5 = clean(env.GITHUB_EVENT_PATH);
+  if (!path5) return void 0;
+  try {
+    return JSON.parse((0, import_node_fs3.readFileSync)(path5, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function resolveBranchIdentity(env = process.env, overrides = {}) {
+  const provider = detectProvider(env);
+  const explicitDefault = clean(overrides.defaultBranch);
+  let headBranch;
+  let rawRef;
+  let refKind;
+  let isPrContext = false;
+  let isForkPr = false;
+  let defaultBranch = explicitDefault;
+  let headSha;
+  switch (provider) {
+    case "github": {
+      const event = readGithubEvent(env);
+      headSha = clean(env.GITHUB_SHA);
+      defaultBranch ??= clean(event?.repository?.default_branch);
+      const headRef = clean(env.GITHUB_HEAD_REF);
+      if (headRef) {
+        isPrContext = true;
+        headBranch = headRef;
+        rawRef = clean(env.GITHUB_REF) ?? headRef;
+        refKind = "branch";
+        const headRepo = event?.pull_request?.head?.repo?.full_name;
+        const baseRepo = event?.pull_request?.base?.repo?.full_name ?? event?.repository?.full_name;
+        isForkPr = Boolean(headRepo && baseRepo && headRepo !== baseRepo);
+        headSha = clean(event?.pull_request?.head?.sha) ?? headSha;
+      } else {
+        rawRef = clean(env.GITHUB_REF) ?? clean(env.GITHUB_REF_NAME);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    case "gitlab": {
+      headSha = clean(env.CI_COMMIT_SHA);
+      defaultBranch ??= clean(env.CI_DEFAULT_BRANCH);
+      const mrSource = clean(env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME);
+      if (mrSource) {
+        isPrContext = true;
+        headBranch = mrSource;
+        rawRef = mrSource;
+        refKind = "branch";
+        const sourceProject = clean(env.CI_MERGE_REQUEST_SOURCE_PROJECT_ID);
+        const targetProject = clean(env.CI_MERGE_REQUEST_PROJECT_ID);
+        isForkPr = Boolean(sourceProject && targetProject && sourceProject !== targetProject);
+      } else if (clean(env.CI_COMMIT_TAG)) {
+        rawRef = clean(env.CI_COMMIT_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.CI_COMMIT_BRANCH) ?? clean(env.CI_COMMIT_REF_NAME);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+      }
+      break;
+    }
+    case "bitbucket": {
+      headSha = clean(env.BITBUCKET_COMMIT);
+      if (clean(env.BITBUCKET_TAG)) {
+        rawRef = clean(env.BITBUCKET_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.BITBUCKET_BRANCH);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+        isPrContext = Boolean(clean(env.BITBUCKET_PR_ID));
+      }
+      break;
+    }
+    case "azure-devops": {
+      headSha = clean(env.BUILD_SOURCEVERSION);
+      const prSource = clean(env.SYSTEM_PULLREQUEST_SOURCEBRANCH);
+      if (prSource) {
+        isPrContext = true;
+        const parsed = stripRefPrefix(prSource);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        rawRef = prSource;
+        refKind = parsed.kind;
+        const forkFlag = clean(env.SYSTEM_PULLREQUEST_ISFORK);
+        isForkPr = forkFlag?.toLowerCase() === "true";
+      } else {
+        rawRef = clean(env.BUILD_SOURCEBRANCH);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    default: {
+      refKind = "unknown";
+    }
+  }
+  if (refKind === "branch" && headBranch && defaultBranch && headBranch === defaultBranch) {
+    refKind = "default-branch";
+  }
+  return { provider, headBranch, rawRef, defaultBranch, refKind, isPrContext, isForkPr, headSha };
+}
+function parseChannelRules(input) {
+  const raw = clean(input);
+  const rules = [];
+  for (const part of raw ? raw.split(",") : []) {
+    const entry = part.trim();
+    if (!entry) continue;
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channels entry "${entry}" must be <branch-or-glob>=<CODE>`
+      );
+    }
+    const pattern = entry.slice(0, eq).trim();
+    const code = entry.slice(eq + 1).trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_-]{0,15}$/.test(code)) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channel code "${code}" must be 1-16 chars, A-Z 0-9 _ -, starting with a letter`
+      );
+    }
+    rules.push({ pattern, code });
+  }
+  if (!rules.some((rule) => rule.pattern === "release/*")) {
+    rules.push({ pattern: "release/*", code: "RC" });
+  }
+  return rules;
+}
+function matchChannel(branch, rules) {
+  for (const rule of rules) {
+    if (rule.pattern.endsWith("*")) {
+      const prefix = rule.pattern.slice(0, -1);
+      if (branch.startsWith(prefix)) return rule;
+    } else if (branch === rule.pattern) {
+      return rule;
+    }
+  }
+  return void 0;
+}
+function resolveBranchDecision(options) {
+  const { strategy, identity } = options;
+  const channels = options.channels ?? [];
+  if (strategy === "legacy") {
+    return {
+      tier: "legacy",
+      strategy,
+      identity,
+      canonicalBranch: clean(options.canonicalBranch) ?? identity.defaultBranch,
+      reason: "branch-strategy legacy: branch-blind pre-v2 behavior"
+    };
+  }
+  const canonicalBranch = clean(options.canonicalBranch) ?? identity.defaultBranch;
+  if (!canonicalBranch) {
+    throw new ContractError(
+      "CONTRACT_DEFAULT_BRANCH_UNRESOLVED",
+      `cannot resolve the canonical branch on ${identity.provider} (no explicit canonical-branch input and the provider exposes no default-branch variable). Set the canonical-branch input.`
+    );
+  }
+  if (identity.refKind === "tag" || identity.refKind === "unknown" || !identity.headBranch) {
+    return {
+      tier: "gated",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `ref kind ${identity.refKind}: never canonical/preview-eligible; no-op with annotation`
+    };
+  }
+  if (identity.headBranch === canonicalBranch) {
+    return {
+      tier: "canonical",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `head branch equals canonical branch ${canonicalBranch}`
+    };
+  }
+  const channel = matchChannel(identity.headBranch, channels);
+  if (channel) {
+    return {
+      tier: "channel",
+      strategy,
+      identity,
+      canonicalBranch,
+      channel,
+      reason: `branch ${identity.headBranch} matches channel ${channel.pattern}=${channel.code}`
+    };
+  }
+  if (strategy === "preview") {
+    if (identity.isForkPr) {
+      return {
+        tier: "gated",
+        strategy,
+        identity,
+        canonicalBranch,
+        reason: "fork PR: preview-ineligible (same-repo gate), gated instead"
+      };
+    }
+    return {
+      tier: "preview",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `branch ${identity.headBranch} under branch-strategy preview`
+    };
+  }
+  return {
+    tier: "gated",
+    strategy,
+    identity,
+    canonicalBranch,
+    reason: `branch ${identity.headBranch} under branch-strategy publish-gate`
+  };
+}
+var BRANCH_DECISION_ENV = "POSTMAN_BRANCH_DECISION";
+function serializeBranchDecision(decision) {
+  return JSON.stringify(decision);
+}
+function parseBranchDecision(raw) {
+  const value = clean(raw);
+  if (!value) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION is not valid JSON");
+  }
+  const candidate = parsed;
+  const tiers = ["canonical", "channel", "preview", "gated", "legacy"];
+  if (!candidate || typeof candidate !== "object" || !tiers.includes(candidate.tier) || !candidate.identity) {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION does not carry a valid BranchDecision");
+  }
+  return candidate;
+}
+function resolveEffectiveBranchDecision(options, env = process.env) {
+  const inherited = parseBranchDecision(env[BRANCH_DECISION_ENV]);
+  if (inherited) return inherited;
+  return resolveBranchDecision(options);
+}
+var PREVIEW_SLUG_MAX = 30;
+function buildBranchSlug(rawBranch) {
+  const sanitized = rawBranch.replace(/^refs\/heads\//, "").replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  const truncated = sanitized.slice(0, PREVIEW_SLUG_MAX);
+  const lossy = truncated !== rawBranch.replace(/^refs\/heads\//, "");
+  if (!lossy) {
+    return { suffix: truncated, slug: truncated, lossy };
+  }
+  const hash = (0, import_node_crypto2.createHash)("sha256").update(rawBranch).digest("hex").slice(0, 6);
+  return { suffix: `${truncated}-${hash}`, slug: truncated, lossy };
+}
+function previewAssetName(baseName, rawBranch) {
+  return `${baseName} @${buildBranchSlug(rawBranch).suffix}`;
+}
+function channelAssetName(baseName, code) {
+  return `[${code}] ${baseName}`;
+}
+var MARKER_KEY = "x-pm-onboarding";
+function parseAssetMarker(description) {
+  if (!description) return void 0;
+  const index = description.indexOf(`${MARKER_KEY}:`);
+  if (index === -1) return void 0;
+  const jsonStart = description.indexOf("{", index);
+  if (jsonStart === -1) return void 0;
+  let depth = 0;
+  for (let i = jsonStart; i < description.length; i += 1) {
+    const ch = description[i];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          const parsed = JSON.parse(description.slice(jsonStart, i + 1));
+          if (parsed && typeof parsed === "object" && parsed.repo && parsed.role) return parsed;
+        } catch {
+          return void 0;
+        }
+        return void 0;
+      }
+    }
+  }
+  return void 0;
+}
+
 // src/index.ts
 function parseBooleanInput(value, defaultValue) {
   const normalized = String(value || "").trim().toLowerCase();
@@ -126256,16 +126780,16 @@ function getInput(name, env = process.env) {
   const runnerRaw = runnerName === normalizedName ? void 0 : env[runnerName];
   const hasNormalized = normalizedRaw !== void 0;
   const hasRunner = runnerRaw !== void 0;
+  const normalizedValue = normalizeInputValue(normalizedRaw);
+  const runnerValue = normalizeInputValue(runnerRaw);
   if (hasNormalized && hasRunner) {
-    const normalizedValue = normalizeInputValue(normalizedRaw);
-    const runnerValue = normalizeInputValue(runnerRaw);
-    if (normalizedValue !== runnerValue) {
+    if (normalizedValue && runnerValue && normalizedValue !== runnerValue) {
       throw new Error(
         `Conflicting values for ${name}: ${normalizedName}=${JSON.stringify(normalizedValue)} vs ${runnerName}=${JSON.stringify(runnerValue)}`
       );
     }
   }
-  return normalizeInputValue(hasNormalized ? normalizedRaw : runnerRaw);
+  return normalizedValue || runnerValue;
 }
 function hasInput(name, env = process.env) {
   const normalizedName = `INPUT_${name.replace(/-/g, "_").toUpperCase()}`;
@@ -126324,6 +126848,17 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseBranchStrategy(value) {
+  const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "legacy");
+  if (allowed.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(
+    `Unsupported branch-strategy "${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;
@@ -126368,6 +126903,7 @@ function resolveInputs(env = process.env) {
     smokeCollectionId: getInput("smoke-collection-id", env),
     contractCollectionId: getInput("contract-collection-id", env),
     specId: getInput("spec-id", env),
+    specContentChanged: parseBooleanInput(getInput("spec-content-changed", env), true),
     specPath: getInput("spec-path", env),
     collectionSyncMode: normalizeCollectionSyncMode(getInput("collection-sync-mode", env) || "refresh"),
     specSyncMode: normalizeSpecSyncMode(getInput("spec-sync-mode", env) || "update"),
@@ -126390,6 +126926,10 @@ function resolveInputs(env = process.env) {
     postmanApiKey: getInput("postman-api-key", env),
     postmanAccessToken: getInput("postman-access-token", env),
     credentialPreflight: parseCredentialPreflight(getInput("credential-preflight", env)),
+    branchStrategy: parseBranchStrategy(getInput("branch-strategy", env)),
+    canonicalBranch: getInput("canonical-branch", env) || void 0,
+    channels: getInput("channels", env) || void 0,
+    previewTtlDays: Math.max(1, Number.parseInt(getInput("preview-ttl", env) || "30", 10) || 30),
     adoToken: getInput("ado-token", env) || normalizeInputValue(env.SYSTEM_ACCESSTOKEN),
     githubToken: getInput("github-token", env),
     ghFallbackToken: getInput("gh-fallback-token", env),
@@ -126416,6 +126956,40 @@ function resolveInputs(env = process.env) {
     postmanIapubBase: endpointProfile.iapubBaseUrl
   };
 }
+function buildBranchAssetMarker(decision, inputs, now = /* @__PURE__ */ new Date()) {
+  if (decision.tier !== "preview" && decision.tier !== "channel") {
+    return void 0;
+  }
+  const rawBranch = decision.identity.headBranch;
+  const repo = inputs.repoUrl || inputs.repository;
+  if (!rawBranch || !repo) {
+    return void 0;
+  }
+  const ttlMs = inputs.previewTtlDays * 24 * 60 * 60 * 1e3;
+  return {
+    repo,
+    rawBranch,
+    sanitizedBranch: buildBranchSlug(rawBranch).suffix,
+    role: decision.tier,
+    headSha: decision.identity.headSha,
+    createdAt: now.toISOString(),
+    lastSyncedAt: now.toISOString(),
+    ...decision.tier === "preview" ? { expiresAt: new Date(now.getTime() + ttlMs).toISOString() } : {}
+  };
+}
+function assertBranchAssetIds(inputs, decision, branchOwnedIds = process.env.POSTMAN_BRANCH_ASSET_IDS === "owned") {
+  if (decision.tier === "legacy" || decision.tier === "canonical" || branchOwnedIds) return;
+  const provided = [
+    ["baseline-collection-id", inputs.baselineCollectionId],
+    ["smoke-collection-id", inputs.smokeCollectionId],
+    ["contract-collection-id", inputs.contractCollectionId]
+  ].filter(([, value]) => Boolean(value));
+  if (provided.length > 0) {
+    throw new Error(
+      `CONTRACT_BRANCH_CANONICAL_WRITE: a ${decision.tier} repo-sync run cannot accept explicit collection IDs (${provided.map(([name]) => name).join(", ")}). Run bootstrap in the same branch-aware pipeline so it can produce branch-owned IDs.`
+    );
+  }
+}
 function buildEnvironmentValues(envName, baseUrl) {
   return [
     { key: "baseUrl", value: baseUrl, type: "default" },
@@ -126428,12 +127002,48 @@ function buildEnvironmentValues(envName, baseUrl) {
   ];
 }
 var LEGACY_BASELINE_COLLECTION_PREFIX = "[Baseline]";
+var RESOURCES_STATE_VERSION = 2;
+var SUPPORTED_STATE_VERSIONS = /* @__PURE__ */ new Set([1, RESOURCES_STATE_VERSION]);
+var StateUnreadableError = class extends Error {
+  code = "CONTRACT_STATE_UNREADABLE";
+  constructor(message) {
+    super(`CONTRACT_STATE_UNREADABLE: ${message}`);
+    this.name = "StateUnreadableError";
+  }
+};
 function readResourcesState() {
+  let raw;
   try {
-    return load((0, import_node_fs3.readFileSync)(".postman/resources.yaml", "utf8"));
+    raw = (0, import_node_fs4.readFileSync)(".postman/resources.yaml", "utf8");
   } catch {
     return null;
   }
+  let parsed;
+  try {
+    parsed = load(raw);
+  } catch (error) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml exists but is not parseable YAML (${error instanceof Error ? error.message : String(error)}). Fix or delete the file; refusing to treat tracked state as absent.`
+    );
+  }
+  if (parsed === null || parsed === void 0) {
+    return null;
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new StateUnreadableError(
+      ".postman/resources.yaml exists but does not contain a YAML mapping. Fix or delete the file; refusing to treat tracked state as absent."
+    );
+  }
+  const state = parsed;
+  if (state.version !== void 0 && !SUPPORTED_STATE_VERSIONS.has(Number(state.version))) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml declares unsupported state version ${String(state.version)} (supported: 1, ${RESOURCES_STATE_VERSION}). Upgrade the action or fix the file.`
+    );
+  }
+  if (state.canonical && !state.cloudResources) {
+    state.cloudResources = { ...state.canonical };
+  }
+  return state;
 }
 function findCloudResourceId(map, matcher) {
   if (!map) {
@@ -126468,7 +127078,7 @@ function isOpenApiSpecFile(filePath) {
     return false;
   }
   try {
-    const raw = (0, import_node_fs3.readFileSync)(filePath, "utf8");
+    const raw = (0, import_node_fs4.readFileSync)(filePath, "utf8");
     const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : load(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return false;
@@ -126497,7 +127107,7 @@ function scanLocalSpecReferences(baseDir = ".") {
   const found = /* @__PURE__ */ new Set();
   const refs = [];
   const visit2 = (currentDir) => {
-    for (const entry of (0, import_node_fs3.readdirSync)(currentDir, { withFileTypes: true })) {
+    for (const entry of (0, import_node_fs4.readdirSync)(currentDir, { withFileTypes: true })) {
       if (ignoredDirs.has(entry.name)) {
         continue;
       }
@@ -126527,7 +127137,7 @@ function resolveMappedSpecReference(explicitSpecPath, discoveredSpecs) {
   const normalizedExplicitPath = normalizeToPosix(explicitSpecPath.trim());
   if (normalizedExplicitPath) {
     const explicitFullPath = path3.resolve(normalizedExplicitPath);
-    if ((0, import_node_fs3.existsSync)(explicitFullPath) && (0, import_node_fs3.statSync)(explicitFullPath).isFile()) {
+    if ((0, import_node_fs4.existsSync)(explicitFullPath) && (0, import_node_fs4.statSync)(explicitFullPath).isFile()) {
       return {
         repoRelativePath: normalizedExplicitPath,
         configRelativePath: normalizeToPosix(path3.join("..", normalizedExplicitPath))
@@ -126554,7 +127164,11 @@ function createOutputs(inputs) {
     "mock-url": "",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
-    "commit-sha": ""
+    "commit-sha": "",
+    "sync-status": "",
+    "branch-decision": "",
+    "spec-version-tag": "",
+    "spec-version-url": ""
   };
 }
 function buildGhCliEnv(env, token) {
@@ -126579,7 +127193,7 @@ function buildGhCliEnv(env, token) {
   }
   return filtered;
 }
-async function upsertEnvironments(inputs, dependencies, resourcesState) {
+async function upsertEnvironments(inputs, dependencies, resourcesState, assetMarker) {
   const envUids = {
     ...getEnvironmentUidsFromResources(resourcesState),
     ...inputs.environmentUids
@@ -126589,7 +127203,6 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
   }
   for (const envName of inputs.environments) {
     const runtimeUrl = String(inputs.envRuntimeUrls[envName] || "").trim();
-    const values = buildEnvironmentValues(envName, runtimeUrl);
     const displayName = `${inputs.projectName} - ${envName}`;
     let existingUid = String(envUids[envName] || "").trim();
     if (!existingUid) {
@@ -126605,10 +127218,27 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
       }
     }
     if (existingUid) {
-      await dependencies.postman.updateEnvironment(existingUid, displayName, values);
+      let marker = assetMarker;
+      if (marker) {
+        try {
+          const existing = await dependencies.postman.getEnvironment(existingUid);
+          const values3 = existing.data?.values ?? existing.values ?? [];
+          const prior = values3.find((value) => value.key === "x-pm-onboarding")?.value;
+          const priorMarker = parseAssetMarker(prior ? `x-pm-onboarding: ${prior}` : void 0);
+          if (priorMarker?.repo === marker.repo && priorMarker.rawBranch === marker.rawBranch) {
+            marker = { ...marker, createdAt: priorMarker.createdAt };
+          }
+        } catch {
+        }
+      }
+      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);
       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,
@@ -126618,7 +127248,7 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
   return envUids;
 }
 function ensureDir(path5) {
-  (0, import_node_fs3.mkdirSync)(path5, { recursive: true });
+  (0, import_node_fs4.mkdirSync)(path5, { recursive: true });
 }
 function getCollectionDirectoryName(kind, projectName) {
   if (kind === "Baseline") {
@@ -126655,7 +127285,7 @@ function stripVolatileFields(obj) {
 }
 function writeJsonFile(path5, content, normalize3 = false) {
   const data = normalize3 ? stripVolatileFields(content) : content;
-  (0, import_node_fs3.writeFileSync)(path5, JSON.stringify(data, null, 2));
+  (0, import_node_fs4.writeFileSync)(path5, JSON.stringify(data, null, 2));
 }
 function buildMappedSpecCloudKey(mappedSource, specSyncMode, releaseLabel) {
   if (specSyncMode !== "version") {
@@ -126679,31 +127309,30 @@ function resolveDurableWorkspaceId(options) {
   }
   return prior === candidate ? prior : void 0;
 }
-function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId, existingSpecs) {
-  const manifest = {};
+function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId, existingSpecs, priorState) {
+  const manifest = { ...priorState ?? {} };
+  delete manifest.version;
+  delete manifest.workspace;
+  delete manifest.localResources;
+  delete manifest.cloudResources;
+  delete manifest.canonical;
+  manifest.version = RESOURCES_STATE_VERSION;
   if (workspaceId) {
     manifest.workspace = { id: workspaceId };
   }
-  const localResources = {};
   const cloudResources = {};
   const collectionKeys = Object.keys(collectionMap);
   if (collectionKeys.length > 0) {
-    localResources.collections = collectionKeys;
     cloudResources.collections = collectionMap;
   }
   const envEntries = Object.entries(envMap);
   if (envEntries.length > 0) {
-    localResources.environments = envEntries.map(
-      ([envName]) => `../${artifactDir}/environments/${envName}.postman_environment.json`
-    );
     cloudResources.environments = {};
     for (const [envName, envUid] of envEntries) {
       cloudResources.environments[`../${artifactDir}/environments/${envName}.postman_environment.json`] = envUid;
     }
   }
-  if (localSpecRefs.length > 0) {
-    localResources.specs = localSpecRefs;
-  }
+  void localSpecRefs;
   const specs = { ...existingSpecs || {} };
   if (mappedSpecRef && specId) {
     specs[mappedSpecRef] = specId;
@@ -126711,11 +127340,8 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
   if (Object.keys(specs).length > 0) {
     cloudResources.specs = specs;
   }
-  if (Object.keys(localResources).length > 0) {
-    manifest.localResources = localResources;
-  }
   if (Object.keys(cloudResources).length > 0) {
-    manifest.cloudResources = cloudResources;
+    manifest.canonical = cloudResources;
   }
   return dump(manifest, {
     lineWidth: -1,
@@ -126756,21 +127382,21 @@ function assertPathWithinCwd(targetPath, fieldName) {
   if (!rawPath || hasControlCharacter2(originalPath) || path3.isAbsolute(rawPath) || path3.win32.isAbsolute(rawPath) || segments.includes("..") || rawPath.startsWith(":") || hasControlCharacter2(rawPath)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
   }
-  const base = (0, import_node_fs3.realpathSync)(process.cwd());
+  const base = (0, import_node_fs4.realpathSync)(process.cwd());
   const resolved = path3.resolve(base, rawPath);
   const relative3 = path3.relative(base, resolved);
   if (relative3.startsWith("..") || path3.isAbsolute(relative3)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
   }
   let existingPath = resolved;
-  while (!(0, import_node_fs3.existsSync)(existingPath)) {
+  while (!(0, import_node_fs4.existsSync)(existingPath)) {
     const parent = path3.dirname(existingPath);
     if (parent === existingPath) {
       break;
     }
     existingPath = parent;
   }
-  const realExistingPath = (0, import_node_fs3.realpathSync)(existingPath);
+  const realExistingPath = (0, import_node_fs4.realpathSync)(existingPath);
   const realRelative = path3.relative(base, realExistingPath);
   if (realRelative.startsWith("..") || path3.isAbsolute(realRelative)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
@@ -126798,8 +127424,8 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
   ensureDir(specsDir);
   ensureDir(".postman");
   const globalsFilePath = `${globalsDir}/workspace.globals.yaml`;
-  if (!(0, import_node_fs3.existsSync)(globalsFilePath)) {
-    (0, import_node_fs3.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
+  if (!(0, import_node_fs4.existsSync)(globalsFilePath)) {
+    (0, import_node_fs4.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
   }
   if (inputs.generateCiWorkflow) {
     const ciDir = inputs.ciWorkflowPath.split("/").slice(0, -1).join("/");
@@ -126846,7 +127472,7 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
     workspaceLinkEnabled: inputs.workspaceLinkEnabled,
     workspaceLinkStatus: options.workspaceLinkStatus
   });
-  (0, import_node_fs3.writeFileSync)(".postman/resources.yaml", buildResourcesManifest(
+  (0, import_node_fs4.writeFileSync)(".postman/resources.yaml", buildResourcesManifest(
     durableWorkspaceId,
     manifestCollections,
     envUids,
@@ -126854,10 +127480,11 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
     discoveredSpecs.map((spec) => spec.configRelativePath),
     mappedSpecCloudKey,
     inputs.specId || void 0,
-    options.existingSpecs
+    options.existingSpecs,
+    options.priorState
   ));
   if (mappedSpec && Object.keys(manifestCollections).length > 0) {
-    (0, import_node_fs3.writeFileSync)(
+    (0, import_node_fs4.writeFileSync)(
       ".postman/workflows.yaml",
       buildSpecCollectionWorkflowManifest(
         mappedSpec.configRelativePath,
@@ -126902,19 +127529,29 @@ async function commitAndPushGeneratedFiles(inputs, dependencies) {
       const dir = parts.slice(0, -1).join("/");
       ensureDir(dir);
     }
-    (0, import_node_fs3.writeFileSync)(inputs.ciWorkflowPath, ciWorkflow);
+    (0, import_node_fs4.writeFileSync)(inputs.ciWorkflowPath, ciWorkflow);
+    if (inputs.provider === "github" || inputs.provider === "unknown") {
+      const gcPath = ".github/workflows/postman-preview-gc.yml";
+      if (inputs.ciWorkflowPath.endsWith(".github/workflows/ci.yml") || inputs.ciWorkflowPath === ".github/workflows/ci.yml") {
+        ensureDir(".github/workflows");
+        (0, import_node_fs4.writeFileSync)(gcPath, renderGcWorkflowTemplate());
+      }
+    }
   }
   if (!dependencies.repoMutation || inputs.repoWriteMode === "none") {
     return { commitSha: "", resolvedCurrentRef: "", pushed: false };
   }
   const provisionPath = ".github/workflows/provision.yml";
-  const provisionExists = inputs.provider === "github" && (0, import_node_fs3.existsSync)(provisionPath);
+  const provisionExists = inputs.provider === "github" && (0, import_node_fs4.existsSync)(provisionPath);
+  const gcWorkflowPath = ".github/workflows/postman-preview-gc.yml";
+  const gcExists = inputs.generateCiWorkflow && (0, import_node_fs4.existsSync)(gcWorkflowPath);
   const stagePaths = [
     inputs.artifactDir,
     ".postman",
     inputs.generateCiWorkflow ? inputs.ciWorkflowPath : null,
+    gcExists ? gcWorkflowPath : null,
     provisionExists ? provisionPath : null
-  ].filter((entry) => typeof entry === "string" && ((0, import_node_fs3.existsSync)(entry) || entry === provisionPath));
+  ].filter((entry) => typeof entry === "string" && ((0, import_node_fs4.existsSync)(entry) || entry === provisionPath));
   if (stagePaths.length === 0) {
     dependencies.core.info("No generated repository paths were found; skipping repo mutation.");
     return {
@@ -126962,6 +127599,31 @@ async function runRepoSync(inputs, dependencies) {
   }
 }
 async function runRepoSyncInner(inputs, dependencies) {
+  const branchDecision = decideBranchTier(inputs);
+  assertBranchAssetIds(inputs, branchDecision);
+  const isCanonicalWriter = branchDecision.tier === "legacy" || branchDecision.tier === "canonical";
+  if (!isCanonicalWriter) {
+    if (branchDecision.tier === "preview" && branchDecision.identity.headBranch) {
+      inputs = {
+        ...inputs,
+        projectName: previewAssetName(inputs.projectName, branchDecision.identity.headBranch),
+        workspaceLinkEnabled: false,
+        environmentSyncEnabled: false,
+        repoWriteMode: "none"
+      };
+    } else if (branchDecision.tier === "channel" && branchDecision.channel) {
+      inputs = {
+        ...inputs,
+        projectName: channelAssetName(inputs.projectName, branchDecision.channel.code),
+        workspaceLinkEnabled: false,
+        environmentSyncEnabled: false,
+        repoWriteMode: "none"
+      };
+    }
+    dependencies.core.info(
+      `branch-aware sync: ${branchDecision.tier} run \u2014 branch-scoped asset set "${inputs.projectName}", no workspace repo-link mutation, no state write-back`
+    );
+  }
   const outputs = createOutputs(inputs);
   const versionRequested = inputs.collectionSyncMode === "version" || inputs.specSyncMode === "version";
   const releaseLabel = deriveReleaseLabel(inputs);
@@ -126969,7 +127631,8 @@ async function runRepoSyncInner(inputs, dependencies) {
     throw new Error("release-label is required when collection-sync-mode or spec-sync-mode is version");
   }
   const assetProjectName = createAssetProjectName(inputs, releaseLabel);
-  const resourcesState = readResourcesState();
+  const trackedState = readResourcesState();
+  const resourcesState = isCanonicalWriter ? trackedState : trackedState?.workspace ? { workspace: trackedState.workspace } : null;
   if (resourcesState) {
     if (!inputs.workspaceId && resourcesState.workspace?.id) {
       inputs.workspaceId = resourcesState.workspace.id;
@@ -126995,7 +127658,8 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
     }
   }
-  const envUids = await upsertEnvironments(inputs, dependencies, resourcesState);
+  const branchAssetMarker = buildBranchAssetMarker(branchDecision, inputs);
+  const envUids = await upsertEnvironments(inputs, dependencies, resourcesState, branchAssetMarker);
   outputs["environment-uids-json"] = JSON.stringify(envUids);
   if (inputs.environmentSyncEnabled && inputs.workspaceId && dependencies.internalIntegration) {
     const associations = Object.entries(envUids).map(([envName, envUid]) => ({
@@ -127015,6 +127679,19 @@ async function runRepoSyncInner(inputs, dependencies) {
           `System environment association failed: ${error instanceof Error ? error.message : String(error)}`
         );
       }
+    } else if (Object.keys(envUids).length > 0) {
+      const configuredKeys = Object.keys(inputs.systemEnvMap).filter(
+        (key) => Boolean(String(inputs.systemEnvMap[key] ?? "").trim())
+      );
+      if (configuredKeys.length === 0) {
+        dependencies.core.warning(
+          'system-env-map-json is empty while environment-sync-enabled is true. Workspace\u2194git linking still registers the service in API Catalog, but Catalog system-environment filters (Prod/Stage/Dev) hide services until Postman environments are associated. Pass system-env-map-json like {"prod":"<system-env-uuid>"} or clear the Catalog system-environment filter to see the service.'
+        );
+      } else {
+        dependencies.core.warning(
+          `system-env-map-json keys (${configuredKeys.join(", ")}) did not match any synced environment (${Object.keys(envUids).join(", ")}). No system-environment associations were made; Catalog system-environment filters may hide this service.`
+        );
+      }
     }
   }
   if (inputs.workspaceId && inputs.baselineCollectionId && Object.keys(envUids).length > 0) {
@@ -127038,11 +127715,23 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       if (!resolvedMockUrl) {
-        const mock = await dependencies.postman.createMock(
-          inputs.workspaceId,
-          mockName,
-          inputs.baselineCollectionId,
-          mockEnvUid
+        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`
+              );
+            }
+          }
         );
         resolvedMockUrl = mock.url;
         dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
@@ -127106,18 +127795,24 @@ async function runRepoSyncInner(inputs, dependencies) {
         inputs.repoUrl
       );
       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";
-      dependencies.core.warning(
-        `Workspace link failed: ${error instanceof Error ? error.message : String(error)}`
-      );
+      const message = `Workspace link failed: ${error instanceof Error ? error.message : String(error)}`;
+      if (branchDecision.tier === "canonical") {
+        throw new Error(message, { cause: error });
+      }
+      dependencies.core.warning(message);
     }
   }
   await exportArtifacts(inputs, dependencies, envUids, assetProjectName, {
     workspaceLinkStatus: outputs["workspace-link-status"],
     priorWorkspaceId: resourcesState?.workspace?.id,
     existingSpecs: resourcesState?.cloudResources?.specs,
-    releaseLabel
+    releaseLabel,
+    priorState: resourcesState
   });
   const commit = await commitAndPushGeneratedFiles(inputs, dependencies);
   outputs["commit-sha"] = commit.commitSha;
@@ -127125,6 +127820,38 @@ async function runRepoSyncInner(inputs, dependencies) {
     outputs["resolved-current-ref"] = commit.resolvedCurrentRef;
   }
   outputs["repo-sync-summary-json"] = createRepoSummary(outputs, envUids, commit.pushed);
+  if (branchDecision.tier === "canonical" && inputs.specId && inputs.specContentChanged !== false && dependencies.postman.tagSpecVersion) {
+    const shortSha = (branchDecision.identity.headSha ?? "").slice(0, 7);
+    const tagName = inputs.releaseLabel ? `${inputs.releaseLabel}${shortSha ? ` (${shortSha})` : ""}` : shortSha || `sync-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
+    try {
+      const tag = await dependencies.postman.tagSpecVersion(inputs.specId, tagName);
+      outputs["spec-version-tag"] = tag.name || tagName;
+      if (tag.id) {
+        outputs["spec-version-url"] = `https://web.postman.co/workspace/${encodeURIComponent(inputs.workspaceId)}/specification/${encodeURIComponent(inputs.specId)}?tagId=${encodeURIComponent(tag.id)}&versionLabel=${encodeURIComponent(tag.name || tagName)}`;
+      }
+      dependencies.core.info(`Tagged spec version at finalize: ${tag.name || tagName}`);
+    } catch (error) {
+      const status = error.status;
+      if (status === 409) {
+        const tags = await dependencies.postman.listSpecVersionTags?.(inputs.specId).catch(() => []) ?? [];
+        const latest = tags[0];
+        if (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 {
+          dependencies.core.warning("Latest changelog group already carries a hand-applied tag; leaving it in place.");
+        }
+      } else {
+        dependencies.core.warning(`Spec version tagging failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  if (inputs.branchStrategy !== "legacy" || process.env[BRANCH_DECISION_ENV]) {
+    const decision = decideBranchTier(inputs);
+    outputs["sync-status"] = "synced";
+    outputs["branch-decision"] = serializeBranchDecision(decision);
+  }
   for (const [name, value] of Object.entries(outputs)) {
     dependencies.core.setOutput(name, value);
   }
@@ -127314,7 +128041,19 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     listMonitors: gatewayAssets.listMonitors.bind(gatewayAssets),
     monitorExists: gatewayAssets.monitorExists.bind(gatewayAssets),
     findMonitorByCollection: gatewayAssets.findMonitorByCollection.bind(gatewayAssets),
-    runMonitor: gatewayAssets.runMonitor.bind(gatewayAssets)
+    runMonitor: gatewayAssets.runMonitor.bind(gatewayAssets),
+    listEnvironments: gatewayAssets.listEnvironments.bind(gatewayAssets),
+    // GC path (preview/channel retention machine — lib/repo/preview-gc.ts).
+    deleteEnvironment: gatewayAssets.deleteEnvironment.bind(gatewayAssets),
+    deleteMock: gatewayAssets.deleteMock.bind(gatewayAssets),
+    deleteMonitor: gatewayAssets.deleteMonitor.bind(gatewayAssets),
+    deleteCollection: gatewayAssets.deleteCollection.bind(gatewayAssets),
+    listSpecifications: gatewayAssets.listSpecifications.bind(gatewayAssets),
+    getSpecContent: gatewayAssets.getSpecContent.bind(gatewayAssets),
+    listSpecCollections: gatewayAssets.listSpecCollections.bind(gatewayAssets),
+    deleteSpec: gatewayAssets.deleteSpec.bind(gatewayAssets),
+    tagSpecVersion: gatewayAssets.tagSpecVersion.bind(gatewayAssets),
+    listSpecVersionTags: gatewayAssets.listSpecVersionTags.bind(gatewayAssets)
   };
   const repoMutation = repository && (inputs.repoWriteMode === "commit-only" || inputs.repoWriteMode === "commit-and-push") ? new RepoMutationService({
     provider: inputs.provider,
@@ -127351,6 +128090,400 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     repoMutation
   };
 }
+function decideBranchTier(inputs, env = process.env) {
+  return resolveEffectiveBranchDecision(
+    {
+      strategy: inputs.branchStrategy,
+      identity: resolveBranchIdentity(env, { defaultBranch: inputs.canonicalBranch }),
+      canonicalBranch: inputs.canonicalBranch,
+      channels: parseChannelRules(inputs.channels)
+    },
+    env
+  );
+}
+function runGatedSkip(inputs, decision, actionCore) {
+  actionCore.info(
+    `branch-aware sync: gated run (${decision.reason}) \u2014 repo-sync skipped, zero workspace writes`
+  );
+  const outputs = createOutputs(inputs);
+  outputs["sync-status"] = "skipped-branch-gate";
+  outputs["branch-decision"] = serializeBranchDecision(decision);
+  outputs["repo-sync-summary-json"] = JSON.stringify({
+    status: "skipped-branch-gate",
+    reason: decision.reason
+  });
+  for (const [name, value] of Object.entries(outputs)) {
+    actionCore.setOutput(name, value);
+  }
+  return outputs;
+}
+
+// src/lib/repo/preview-gc.ts
+function looksGenerated(name) {
+  return / @[A-Za-z0-9._-]+/.test(name) || /^\[[A-Z][A-Z0-9]*\] /.test(name);
+}
+function resolveMarker(candidate) {
+  return candidate.marker ?? parseAssetMarker(candidate.description);
+}
+function stampChannelRetirement(marker, reason, now, previewTtlDays) {
+  const deleteAfter = new Date(now.getTime() + previewTtlDays * 24 * 60 * 60 * 1e3);
+  return {
+    ...marker,
+    retirementDetectedAt: now.toISOString(),
+    retirementReason: reason,
+    deleteAfter: deleteAfter.toISOString()
+  };
+}
+function clearChannelRetirement(marker) {
+  const next = { ...marker };
+  delete next.retirementDetectedAt;
+  delete next.retirementReason;
+  delete next.deleteAfter;
+  return next;
+}
+function decideRetention(candidate, context) {
+  const marker = resolveMarker(candidate);
+  if (!marker) {
+    if (looksGenerated(candidate.name)) {
+      return { action: "orphan-audit", reason: "generated-looking name with missing or invalid marker" };
+    }
+    return { action: "stranger", reason: "no marker; not our asset" };
+  }
+  if (marker.repo !== context.repo) {
+    return { action: "stranger", reason: `marker repo ${marker.repo} does not match ${context.repo}` };
+  }
+  if (context.triggerGeneration && marker.createdAt) {
+    const created = new Date(marker.createdAt);
+    if (!Number.isNaN(created.getTime()) && created.getTime() > context.triggerGeneration.getTime()) {
+      return { action: "retain", reason: "marker generation is newer than the GC trigger (name reuse)" };
+    }
+  }
+  if (marker.role === "channel") {
+    if (marker.retirementReason && marker.deleteAfter) {
+      const existence3 = context.branchExists(marker.rawBranch);
+      const mapped = context.channelMapped?.(marker.rawBranch);
+      const restored = marker.retirementReason === "branch-deleted" ? existence3 === "exists" && mapped !== false : existence3 === "exists" && mapped === true;
+      if (restored) {
+        return { action: "restore", reason: "retired channel branch and mapping are active again", branchProbe: "exists" };
+      }
+      const deleteAfter = new Date(marker.deleteAfter);
+      if (!Number.isNaN(deleteAfter.getTime()) && context.now.getTime() >= deleteAfter.getTime()) {
+        return { action: "delete", reason: `retired channel set past deleteAfter (${marker.retirementReason})` };
+      }
+      return { action: "retain", reason: "retired channel set inside deleteAfter window" };
+    }
+    const existence2 = context.branchExists(marker.rawBranch);
+    if (existence2 === "deleted") {
+      return { action: "retire", reason: "channel branch deleted; start retirement window", branchProbe: "deleted", retirementReason: "branch-deleted" };
+    }
+    if (context.channelMapped?.(marker.rawBranch) === false) {
+      return { action: "retire", reason: "channel mapping removed; start retirement window", branchProbe: existence2, retirementReason: "mapping-removed" };
+    }
+    return { action: "retain", reason: "active channel set (channels are never TTL-swept)", branchProbe: existence2 };
+  }
+  if (context.onlyBranch !== void 0) {
+    if (marker.rawBranch !== context.onlyBranch && marker.sanitizedBranch !== context.onlyBranch) {
+      return { action: "retain", reason: "outside manual --branch scope" };
+    }
+    return { action: "delete", reason: `manual gc --branch ${context.onlyBranch}` };
+  }
+  if (context.allPreviews) {
+    return { action: "delete", reason: "manual gc --all-previews" };
+  }
+  const existence = context.branchExists(marker.rawBranch);
+  if (existence === "exists") {
+    return { action: "retain", reason: "branch still exists", branchProbe: "exists" };
+  }
+  if (existence === "deleted") {
+    return { action: "delete", reason: "branch deleted", branchProbe: "deleted" };
+  }
+  if (marker.expiresAt) {
+    const expires = new Date(marker.expiresAt);
+    if (!Number.isNaN(expires.getTime()) && context.now.getTime() >= expires.getTime()) {
+      return { action: "delete", reason: "sliding TTL expired", branchProbe: "skipped" };
+    }
+  }
+  return { action: "retain", reason: "branch existence unknown and TTL not expired", branchProbe: "skipped" };
+}
+async function runPreviewGc(options) {
+  const { context, candidates, deleters, dryRun } = options;
+  const log = options.log ?? (() => void 0);
+  const summary2 = {
+    repo: context.repo,
+    scannedAt: context.now.toISOString(),
+    degraded: Boolean(options.degraded),
+    counts: { delete: 0, retire: 0, restore: 0, retain: 0, stranger: 0, "orphan-audit": 0, errors: 0 },
+    entries: []
+  };
+  for (const candidate of candidates) {
+    const decision = decideRetention(candidate, context);
+    const entry = {
+      kind: candidate.kind,
+      uid: candidate.uid,
+      name: candidate.name,
+      action: decision.action,
+      reason: decision.reason
+    };
+    summary2.counts[decision.action] += 1;
+    if (decision.action === "retire" && !dryRun && candidate.kind === "environment") {
+      const retire = options.retirers?.environment;
+      if (!retire) {
+        entry.error = "no channel retirement writer wired for environment";
+        summary2.counts.errors += 1;
+      } else {
+        try {
+          await retire(candidate, decision.retirementReason ?? "branch-deleted");
+          log(`gc: retired channel ${candidate.name} (${candidate.uid}) \u2014 ${decision.reason}`);
+        } catch (error) {
+          entry.error = error instanceof Error ? error.message : String(error);
+          summary2.counts.errors += 1;
+        }
+      }
+    } else if (decision.action === "restore" && !dryRun && candidate.kind === "environment") {
+      const restore = options.retirers?.restoreEnvironment;
+      if (!restore) {
+        entry.error = "no channel retirement restore writer wired for environment";
+        summary2.counts.errors += 1;
+      } else {
+        try {
+          await restore(candidate);
+          log(`gc: restored channel ${candidate.name} (${candidate.uid})`);
+        } catch (error) {
+          entry.error = error instanceof Error ? error.message : String(error);
+          summary2.counts.errors += 1;
+        }
+      }
+    } else if (decision.action === "delete" && !dryRun) {
+      const remove = deleters[candidate.kind];
+      if (!remove) {
+        entry.error = `no deleter wired for kind ${candidate.kind}`;
+        summary2.counts.errors += 1;
+      } else {
+        try {
+          await remove(candidate.uid);
+          entry.deleted = true;
+          log(`gc: deleted ${candidate.kind} ${candidate.name} (${candidate.uid}) \u2014 ${decision.reason}`);
+        } catch (error) {
+          entry.error = error instanceof Error ? error.message : String(error);
+          summary2.counts.errors += 1;
+          log(`gc: FAILED deleting ${candidate.kind} ${candidate.name} (${candidate.uid}): ${entry.error}`);
+        }
+      }
+    } else if (decision.action === "delete" && dryRun) {
+      log(`gc (dry-run): would delete ${candidate.kind} ${candidate.name} (${candidate.uid}) \u2014 ${decision.reason}`);
+    }
+    summary2.entries.push(entry);
+  }
+  return summary2;
+}
+function renderGcSummary(summary2) {
+  const lines = [];
+  lines.push(`Preview GC summary for ${summary2.repo} at ${summary2.scannedAt}${summary2.degraded ? " (degraded: branch probes skipped)" : ""}`);
+  lines.push(
+    `  deleted=${summary2.counts.delete} retired=${summary2.counts.retire} restored=${summary2.counts.restore} retained=${summary2.counts.retain} strangers=${summary2.counts.stranger} orphans=${summary2.counts["orphan-audit"]} errors=${summary2.counts.errors}`
+  );
+  for (const entry of summary2.entries) {
+    if (entry.action === "retain" || entry.action === "stranger") continue;
+    const status = entry.error ? `ERROR: ${entry.error}` : entry.deleted ? "deleted" : entry.action;
+    lines.push(`  [${entry.kind}] ${entry.name} (${entry.uid}): ${status} \u2014 ${entry.reason}`);
+  }
+  return lines.join("\n");
+}
+
+// src/lib/repo/gc-runner.ts
+var GC_MARKER_ENV_KEY = "x-pm-onboarding";
+async function inventoryRemoteBranches(exec) {
+  try {
+    const result = await exec.getExecOutput("git", ["ls-remote", "--heads", "origin"], {
+      ignoreReturnCode: true
+    });
+    if (result.exitCode !== 0) {
+      return void 0;
+    }
+    const branches = /* @__PURE__ */ new Set();
+    for (const line of result.stdout.split("\n")) {
+      const match = line.match(/\trefs\/heads\/(.+)$/);
+      if (match) branches.add(match[1].trim());
+    }
+    return branches;
+  } catch {
+    return void 0;
+  }
+}
+function markerFromEnvironment(envelope) {
+  const record = envelope && typeof envelope === "object" ? envelope : null;
+  const data = record && typeof record.data === "object" && record.data !== null ? record.data : record;
+  const values = data && Array.isArray(data.values) ? data.values : [];
+  for (const value of values) {
+    if (String(value?.key ?? "") === GC_MARKER_ENV_KEY) {
+      return parseAssetMarker(`${GC_MARKER_ENV_KEY}: ${String(value?.value ?? "")}`);
+    }
+  }
+  return void 0;
+}
+function environmentValues(envelope) {
+  const record = envelope && typeof envelope === "object" ? envelope : null;
+  const data = record && typeof record.data === "object" && record.data !== null ? record.data : record;
+  const values = data && Array.isArray(data.values) ? data.values : [];
+  return values.map((raw) => {
+    const value = raw && typeof raw === "object" ? raw : {};
+    return {
+      key: String(value.key ?? ""),
+      value: String(value.value ?? ""),
+      enabled: value.enabled !== false,
+      type: String(value.type ?? "default")
+    };
+  });
+}
+function markerFromSpecContent(content) {
+  if (!content) return void 0;
+  try {
+    const parsed = load(content);
+    const marker = parsed?.["x-postman-onboarding"];
+    return marker && typeof marker === "object" ? parseAssetMarker(`${GC_MARKER_ENV_KEY}: ${JSON.stringify(marker)}`) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isGcCandidateName(name) {
+  return / @[A-Za-z0-9._-]+/.test(name) || /^\[[A-Z][A-Z0-9]*\] /.test(name);
+}
+async function collectGcCandidates(postman, workspaceId) {
+  const candidates = [];
+  const environments = await postman.listEnvironments(workspaceId);
+  for (const env of environments) {
+    if (!isGcCandidateName(env.name)) continue;
+    let marker;
+    try {
+      marker = markerFromEnvironment(await postman.getEnvironment(env.uid));
+    } catch {
+      marker = void 0;
+    }
+    candidates.push({ kind: "environment", uid: env.uid, name: env.name, marker });
+  }
+  const mocks = await postman.listMocks();
+  for (const mock of mocks) {
+    if (!isGcCandidateName(mock.name)) continue;
+    const envMatch = candidates.find(
+      (entry) => entry.kind === "environment" && entry.uid === mock.environment
+    );
+    candidates.push({ kind: "mock", uid: mock.uid, name: mock.name, marker: envMatch?.marker });
+  }
+  const monitors = await postman.listMonitors();
+  for (const monitor of monitors) {
+    if (!isGcCandidateName(monitor.name)) continue;
+    const envMatch = candidates.find(
+      (entry) => entry.kind === "environment" && entry.uid === monitor.environmentUid
+    );
+    candidates.push({ kind: "monitor", uid: monitor.uid, name: monitor.name, marker: envMatch?.marker });
+  }
+  const ownedCollections = /* @__PURE__ */ new Map();
+  for (const mock of mocks) {
+    const marker = candidates.find((entry) => entry.kind === "environment" && entry.uid === mock.environment)?.marker;
+    if (marker && mock.collection) ownedCollections.set(mock.collection, { name: `${mock.name} collection`, marker });
+  }
+  for (const monitor of monitors) {
+    const marker = candidates.find((entry) => entry.kind === "environment" && entry.uid === monitor.environmentUid)?.marker;
+    if (marker && monitor.collectionUid) ownedCollections.set(monitor.collectionUid, { name: `${monitor.name} collection`, marker });
+  }
+  for (const [uid, collection] of ownedCollections) {
+    candidates.push({ kind: "collection", uid, name: collection.name, marker: collection.marker });
+  }
+  const specifications = await postman.listSpecifications(workspaceId);
+  for (const spec of specifications) {
+    if (!isGcCandidateName(spec.name)) continue;
+    let marker;
+    try {
+      marker = markerFromSpecContent(await postman.getSpecContent(spec.uid));
+    } catch {
+      marker = void 0;
+    }
+    candidates.push({ kind: "spec", uid: spec.uid, name: spec.name, marker });
+    if (marker) {
+      try {
+        for (const collection of await postman.listSpecCollections(spec.uid)) {
+          if (!ownedCollections.has(collection.uid)) {
+            candidates.push({ kind: "collection", uid: collection.uid, name: collection.name || `${spec.name} collection`, marker });
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return candidates;
+}
+async function runGc(options) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const log = options.log ?? (() => void 0);
+  const remoteBranches = options.onlyBranch || options.allPreviews ? void 0 : await inventoryRemoteBranches(options.exec);
+  const degraded = remoteBranches === void 0 && !options.onlyBranch && !options.allPreviews;
+  if (degraded) {
+    log("gc: branch inventory unavailable (credential absent/denied?) \u2014 degraded sweep, TTL only");
+  }
+  const branchExists = (rawBranch) => {
+    if (!remoteBranches) return "unknown";
+    return remoteBranches.has(rawBranch) ? "exists" : "deleted";
+  };
+  const channelRules = options.channels === void 0 ? void 0 : parseChannelRules(options.channels);
+  const channelMapped = channelRules ? (rawBranch) => channelRules.some(
+    (rule) => rule.pattern.endsWith("*") ? rawBranch.startsWith(rule.pattern.slice(0, -1)) : rawBranch === rule.pattern
+  ) : void 0;
+  const candidates = await collectGcCandidates(options.postman, options.workspaceId);
+  const retiredChannels = candidates.filter((candidate) => candidate.kind === "environment" && candidate.marker?.role === "channel" && candidate.marker.retirementReason).map((candidate) => candidate.marker);
+  for (const candidate of candidates) {
+    const marker = candidate.marker;
+    if (!marker || marker.role !== "channel" || marker.retirementReason) continue;
+    const retired = retiredChannels.find((entry) => entry.repo === marker.repo && entry.rawBranch === marker.rawBranch);
+    if (retired) candidate.marker = retired;
+  }
+  return runPreviewGc({
+    context: {
+      repo: options.repo,
+      now,
+      branchExists,
+      channelMapped,
+      onlyBranch: options.onlyBranch,
+      allPreviews: options.allPreviews
+    },
+    candidates,
+    deleters: {
+      environment: (uid) => options.postman.deleteEnvironment(uid),
+      mock: (uid) => options.postman.deleteMock(uid),
+      monitor: (uid) => options.postman.deleteMonitor(uid),
+      collection: (uid) => options.postman.deleteCollection(uid),
+      spec: (uid) => options.postman.deleteSpec(uid)
+    },
+    retirers: {
+      environment: async (candidate, reason) => {
+        if (!candidate.marker) return;
+        const envelope = await options.postman.getEnvironment(candidate.uid);
+        const values = environmentValues(envelope);
+        const retired = stampChannelRetirement(
+          candidate.marker,
+          reason,
+          now,
+          options.previewTtlDays ?? 30
+        );
+        const markerValue = values.find((value) => value.key === GC_MARKER_ENV_KEY);
+        if (markerValue) markerValue.value = JSON.stringify(retired);
+        else values.push({ key: GC_MARKER_ENV_KEY, value: JSON.stringify(retired), enabled: true, type: "default" });
+        await options.postman.updateEnvironment(candidate.uid, candidate.name, values);
+      },
+      restoreEnvironment: async (candidate) => {
+        if (!candidate.marker) return;
+        const envelope = await options.postman.getEnvironment(candidate.uid);
+        const values = environmentValues(envelope);
+        const restored = clearChannelRetirement(candidate.marker);
+        const markerValue = values.find((value) => value.key === GC_MARKER_ENV_KEY);
+        if (markerValue) markerValue.value = JSON.stringify(restored);
+        await options.postman.updateEnvironment(candidate.uid, candidate.name, values);
+      }
+    },
+    degraded,
+    dryRun: options.dryRun,
+    log
+  });
+}
 
 // src/cli.ts
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
@@ -127399,15 +128532,25 @@ var CLI_INPUT_NAMES = [
   "ssl-client-passphrase",
   "ssl-extra-ca-certs",
   "spec-id",
+  "spec-content-changed",
   "spec-path",
   "team-id",
   "postman-region",
-  "postman-stack"
+  "postman-stack",
+  "branch-strategy",
+  "canonical-branch",
+  "channels",
+  "preview-ttl"
 ];
 var HELP_TEXT = `Usage: postman-repo-sync [options]
 
 Sync Postman artifacts into a git repository.
 
+Subcommands:
+  gc [--branch <name> | --all-previews] [--dry-run]
+                                 Garbage-collect preview/channel asset sets
+                                 (marker-guarded; strangers are never deleted)
+
 Options:
   --help                         Show this help and exit
   --version                      Show version and exit
@@ -127501,7 +128644,7 @@ function resolvePackageVersion() {
   candidates.push(import_node_path3.default.join(process.cwd(), "package.json"));
   for (const packageJsonPath of candidates) {
     try {
-      const packageJson = JSON.parse((0, import_node_fs4.readFileSync)(packageJsonPath, "utf8"));
+      const packageJson = JSON.parse((0, import_node_fs5.readFileSync)(packageJsonPath, "utf8"));
       if (packageJson.name === "@postman-cse/onboarding-repo-sync" && packageJson.version) {
         return String(packageJson.version).trim();
       }
@@ -127666,9 +128809,22 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
     return;
   }
   const env = runtime.env ?? process.env;
+  if (argv[0] === "gc") {
+    await runGcCommand(argv.slice(1), env, writeStdout);
+    return;
+  }
   const config = parseCliArgs(argv, env);
   const inputs = resolveInputs(config.inputEnv);
   const reporter = new ConsoleReporter();
+  const branchDecision = decideBranchTier(inputs, config.inputEnv);
+  if (branchDecision.tier === "gated") {
+    const result2 = runGatedSkip(inputs, branchDecision, reporter);
+    await writeOptionalFile(config.resultJsonPath, JSON.stringify(result2, null, 2));
+    await writeOptionalFile(config.dotenvPath, toDotenv(result2));
+    writeStdout(`${JSON.stringify(result2, null, 2)}
+`);
+    return;
+  }
   await mintAccessTokenIfNeeded(inputs, reporter);
   const initialMasker = createSecretMasker([
     inputs.postmanApiKey,
@@ -127719,6 +128875,80 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
   writeStdout(`${JSON.stringify(result, null, 2)}
 `);
 }
+async function runGcCommand(argv, env, writeStdout) {
+  let onlyBranch;
+  let allPreviews = false;
+  let dryRun = false;
+  const passthrough = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--branch") {
+      onlyBranch = argv[index + 1];
+      if (!onlyBranch || onlyBranch.startsWith("--")) {
+        throw new Error("Missing value for --branch");
+      }
+      index += 1;
+    } else if (arg === "--all-previews") {
+      allPreviews = true;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else {
+      passthrough.push(arg);
+    }
+  }
+  if (onlyBranch && allPreviews) {
+    throw new Error("Use either --branch <name> or --all-previews, not both");
+  }
+  const config = parseCliArgs(passthrough, env);
+  const inputs = resolveInputs(config.inputEnv);
+  if (!inputs.workspaceId) {
+    throw new Error("gc requires --workspace-id (the workspace holding the preview/channel sets)");
+  }
+  const repo = inputs.repoUrl || inputs.repository;
+  if (!repo) {
+    throw new Error("gc requires --repo-url or --repository to scope marker ownership");
+  }
+  const reporter = new ConsoleReporter();
+  await mintAccessTokenIfNeeded(inputs, reporter);
+  const initialMasker = createSecretMasker([
+    inputs.postmanApiKey,
+    inputs.postmanAccessToken,
+    inputs.githubToken,
+    inputs.ghFallbackToken
+  ]);
+  const resolved = await resolvePostmanApiKeyAndTeamId(
+    inputs,
+    reporter,
+    createCliExec(initialMasker),
+    initialMasker,
+    { persistGeneratedApiKeySecret: false, env }
+  );
+  const dependencies = createCliDependencies(inputs, resolved);
+  if (!dependencies.postman.deleteCollection || !dependencies.postman.listSpecifications || !dependencies.postman.getSpecContent || !dependencies.postman.listSpecCollections || !dependencies.postman.deleteSpec) {
+    throw new Error("gc requires the full branch-aware inventory client; this runtime is missing a spec or collection GC capability.");
+  }
+  const summary2 = await runGc({
+    workspaceId: inputs.workspaceId,
+    repo,
+    postman: {
+      ...dependencies.postman,
+      deleteCollection: dependencies.postman.deleteCollection,
+      listSpecifications: dependencies.postman.listSpecifications,
+      getSpecContent: dependencies.postman.getSpecContent,
+      listSpecCollections: dependencies.postman.listSpecCollections,
+      deleteSpec: dependencies.postman.deleteSpec
+    },
+    exec: createCliExec(initialMasker),
+    onlyBranch,
+    allPreviews,
+    dryRun,
+    previewTtlDays: inputs.previewTtlDays,
+    channels: inputs.channels,
+    log: (message) => reporter.info(message)
+  });
+  reporter.info(renderGcSummary(summary2));
+  writeStdout(JSON.stringify(summary2, null, 2) + "\n");
+}
 var currentModulePath = typeof __filename === "string" ? __filename : "";
 var entrypoint = process.argv[1];
 function isEntrypoint(currentPath, entrypointPath) {
@@ -127726,7 +128956,7 @@ function isEntrypoint(currentPath, entrypointPath) {
     return false;
   }
   try {
-    return (0, import_node_fs4.realpathSync)(currentPath) === (0, import_node_fs4.realpathSync)(entrypointPath);
+    return (0, import_node_fs5.realpathSync)(currentPath) === (0, import_node_fs5.realpathSync)(entrypointPath);
   } catch {
     return import_node_path3.default.resolve(currentPath) === import_node_path3.default.resolve(entrypointPath);
   }