fastlane-plugin-bugsee 1.0.4 → 1.1.0

data/BugseeAgent

@@ -27,9 +27,2454 @@ import re
 import json
 import hashlib
 import shutil
+import gzip
+import plistlib
+import socket
+import time
+import math
+import platform
+import struct
+import uuid
 from optparse import OptionParser
 import fnmatch
 
+
+# ──────────────────────────────────────────────────────────────────
+# bugsee-cli resolver
+#
+# Symbol upload (dSYM) is handled by the bugsee-cli Rust binary —
+# the same one the Android Gradle plugin uses. This agent shells out
+# to it instead of hand-rolling zip + curl. The binary is
+# auto-downloaded from download.bugsee.com on first use, SHA-256
+# verified, and cached under ~/.bugsee/cli/<version>/<triple>/.
+# Override via --cli-path (developer-local binary) or --cli-version
+# (test a newer release). Environment fallbacks: BUGSEE_CLI_PATH,
+# BUGSEE_CLI_VERSION.
+#
+# Build-info / dependency collection (the rest of this file below)
+# is still done in Python here. That migration is deferred to the
+# cross-platform build-info contributor SPI.
+# ──────────────────────────────────────────────────────────────────
+
+# Download FLOOR: the CLI version this agent installs on first use.
+# After downloading it, the agent runs `bugsee-cli update --max-age 12h`
+# (see `_maybe_self_update`), letting the CLI bump itself in place to
+# the latest same-major release. Must be >= 0.6.0 — the first release that
+# ships the `update` self-update command this agent relies on.
+BUGSEE_CLI_DEFAULT_VERSION = "0.6.0"
+BUGSEE_CLI_DOWNLOAD_BASE = "https://download.bugsee.com/cli"
+# Strict version-string shape: SemVer-ish `<major>.<minor>.<patch>`
+# optionally followed by `-<prerelease>`. This regex gates any value
+# that flows into the download URL or the on-disk cache directory
+# path, so a malicious BUGSEE_CLI_VERSION env var cannot inject `/` or
+# `..` segments to escape the cache root or redirect downloads.
+_BUGSEE_CLI_VERSION_RE = re.compile(r'^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$')
+
+# ──────────────────────────────────────────────────────────────────
+# CLI self-update (delegated to the CLI — shared contract across the
+# fastlane / SDK / gradle / iOS producers)
+#
+# Version discovery is no longer hand-rolled here. After the agent has
+# DOWNLOADED a binary it manages, it runs once per process:
+#
+#   bugsee-cli update --max-age 12h
+#
+# The CLI owns everything: discovering the newest same-major
+# (non-breaking) release, downloading + SHA-256-verifying it, and
+# self-replacing the binary IN PLACE. `--max-age 12h` makes it throttle
+# internally (a last-check timestamp next to the binary; no-op/no-network
+# when fresh) and best-effort (any failure → exit 0). We only self-update
+# a binary we MANAGE (one we auto-downloaded into ~/.bugsee/cli/...),
+# never a PATH / explicit BUGSEE_CLI_PATH one — those may be read-only or
+# shared and must not be mutated. Disable via BUGSEE_CLI_AUTO_UPDATE.
+# ──────────────────────────────────────────────────────────────────
+
+# `--max-age` value handed to `bugsee-cli update`; the CLI throttles its
+# own network check to this freshness window.
+_BUGSEE_CLI_SELF_UPDATE_MAX_AGE = "12h"
+# Generous cap for the self-update subprocess. The CLI is best-effort, so
+# a hang past this is swallowed (TimeoutExpired) and the build proceeds.
+_BUGSEE_CLI_SELF_UPDATE_TIMEOUT_SECONDS = 120
+
+# Process-wide guard so the self-update runs at most once per build phase.
+_self_update_done = False
+
+
+def _bugsee_cli_auto_update_enabled():
+    """Auto-update is ON unless BUGSEE_CLI_AUTO_UPDATE is an explicit
+    off token (`0` / `false` / `no` / `off`, case-insensitive)."""
+    raw = (os.environ.get("BUGSEE_CLI_AUTO_UPDATE") or "").strip().lower()
+    return raw not in ("0", "false", "no", "off")
+
+
+def _maybe_self_update(cli_path):
+    """Run `bugsee-cli update --max-age 12h` BEST-EFFORT on a binary the
+    agent MANAGES (i.e. one it auto-downloaded into ~/.bugsee/cli/...).
+
+    The CLI owns version discovery (newest same-major release), download
+    + SHA-256 verify, in-place self-replace, and its own ~12h throttle
+    (a last-check timestamp next to the binary; no-op/no-network when
+    fresh). This call therefore just fires the command and forgets: it
+    swallows EVERYTHING (timeout, non-zero exit, exec failure), NEVER
+    raises, and never prints to stdout. Memoized to run at most once per
+    process. Skipped when BUGSEE_CLI_AUTO_UPDATE is disabled."""
+    global _self_update_done
+    if _self_update_done:
+        return
+    _self_update_done = True
+    if not cli_path or not _bugsee_cli_auto_update_enabled():
+        return
+    try:
+        subprocess.run(
+            [cli_path, "update", "--max-age",
+             _BUGSEE_CLI_SELF_UPDATE_MAX_AGE],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            timeout=_BUGSEE_CLI_SELF_UPDATE_TIMEOUT_SECONDS, check=False,
+        )
+    except Exception:
+        # Best-effort: a hung / failing / missing CLI must never break or
+        # slow the build. Ignore the return code and any exception
+        # (TimeoutExpired included).
+        pass
+
+
+# Exception tuple every CLI-shelling helper catches. Pinned in one
+# place so all of `_resolve_*_via_cli` / `_collect_*_via_cli` /
+# `_parse_*_via_cli` follow the same fallback policy:
+#   - OSError: subprocess exec failure, pipe close, broken file handle
+#   - ValueError: malformed JSON from CLI stdout
+#   - TypeError: defensive — subprocess.run mocked in tests can return
+#     MagicMock objects that explode in json.loads (this is the
+#     bite the dsym helper hit during TestParseDSYM hardening)
+#   - subprocess.CalledProcessError: a side_effect in test mocks that
+#     raise rather than return a fake CompletedProcess
+_CLI_CATCHALL_EXCEPTIONS = (
+    OSError,
+    ValueError,
+    TypeError,
+    subprocess.CalledProcessError,
+    # TimeoutExpired: the CLI hung past its `subprocess.run(timeout=...)`
+    # cap. Treat as a soft failure so the fallback (in-process Python)
+    # path runs — a deadlocked CLI, SIGSTOP'd process, NFS-mounted
+    # binary stalling on first run, or an OS sandbox prompt waiting
+    # for user interaction would otherwise crash the build.
+    subprocess.TimeoutExpired,
+)
+
+
+def detectHostTriple():
+    """Map current OS+arch to a Rust target triple the CLI is published for.
+    Returns None for unsupported combinations (Linux musl, Windows ARM64, etc.).
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    is_arm64 = machine in ("arm64", "aarch64")
+    is_amd64 = machine in ("x86_64", "amd64")
+    if system == "darwin":
+        if is_arm64:
+            return "aarch64-apple-darwin"
+        if is_amd64:
+            return "x86_64-apple-darwin"
+    elif system == "linux":
+        if is_arm64:
+            return "aarch64-unknown-linux-gnu"
+        if is_amd64:
+            return "x86_64-unknown-linux-gnu"
+    elif system.startswith("win") or system == "windows":
+        if is_amd64:
+            return "x86_64-pc-windows-msvc"
+    return None
+
+
+_resolveCli_cache = {}
+
+
+def resolveCli(cliPath=None, cliVersion=None):
+    """Return path to a usable bugsee-cli binary, or None.
+    Precedence: explicit cliPath > BUGSEE_CLI_PATH env > auto-download.
+    Returning None is a soft failure — caller should fall back / skip.
+
+    Result is memoized by `(cliPath, cliVersion, BUGSEE_CLI_PATH env,
+    BUGSEE_CLI_VERSION env)` for the lifetime of the process. The
+    plugin invokes this once per CLI helper (8+ times per build) and
+    the resolve path includes filesystem walks (cache hit check,
+    network-side artefact-existence check) — caching the first
+    success/failure avoids the per-call cost. The env vars are part
+    of the key because a CI step could (in principle) flip them mid-
+    run; the cliPath/cliVersion args ARE typically constant per call
+    site but vary across helpers, so include them too.
+    """
+    cache_key = (
+        cliPath,
+        cliVersion,
+        os.environ.get("BUGSEE_CLI_PATH"),
+        os.environ.get("BUGSEE_CLI_VERSION"),
+    )
+    if cache_key in _resolveCli_cache:
+        return _resolveCli_cache[cache_key]
+    result = _resolveCli_uncached(cliPath, cliVersion)
+    # ONLY cache successful resolutions. A None result means the
+    # network was down, the SHA mismatched, or the host was unsupported
+    # on THIS call — but a subsequent call (after network comes up,
+    # after a retry, after the user installs the binary manually mid-
+    # build) may succeed. Caching the None would short-circuit every
+    # subsequent helper to the in-process fallback for the rest of
+    # the process lifetime.
+    if result is not None:
+        _resolveCli_cache[cache_key] = result
+    return result
+
+
+def _resolveCli_uncached(cliPath=None, cliVersion=None):
+    explicit = cliPath or os.environ.get("BUGSEE_CLI_PATH")
+    if explicit:
+        if os.path.isfile(explicit) and os.access(explicit, os.X_OK):
+            return explicit
+        print("Bugsee: --cli-path %s is not an executable file; trying auto-download" % explicit)
+
+    # An explicit version (arg or env) is honoured EXACTLY. Otherwise we
+    # download the pinned floor; version discovery (bumping to the latest
+    # same-major release) is delegated to the CLI's own `update` command
+    # via `_maybe_self_update` after the download succeeds — the agent no
+    # longer hand-rolls it.
+    explicit_version = cliVersion or os.environ.get("BUGSEE_CLI_VERSION")
+    version = explicit_version or BUGSEE_CLI_DEFAULT_VERSION
+    # Strict version-string validation BEFORE the value flows into the
+    # download URL and the on-disk cache path. Without this, anyone who
+    # can set BUGSEE_CLI_VERSION (a malicious CI step, a poisoned .env,
+    # a Gemfile post_install) could land the cached binary at e.g.
+    # `~/.bugsee/cli/../../malicious_dir/<triple>/bugsee-cli` (path
+    # traversal) or redirect the download to a sibling release URL
+    # via injected path segments.
+    if not _BUGSEE_CLI_VERSION_RE.fullmatch(version):
+        print("Bugsee: rejecting BUGSEE_CLI_VERSION=%r — must match X.Y.Z[-prerelease]" % version)
+        return None
+    triple = detectHostTriple()
+    if triple is None:
+        print("Bugsee: no published bugsee-cli for host %s/%s; skipping CLI upload" % (
+            platform.system(), platform.machine()))
+        return None
+
+    cache_root = os.path.expanduser(os.path.join("~/.bugsee/cli", version, triple))
+    binary_name = "bugsee-cli.exe" if "windows" in triple else "bugsee-cli"
+    cached = os.path.join(cache_root, binary_name)
+
+    # Cache hit — the binary was auto-downloaded on a prior run and is one
+    # we manage, so it's eligible for self-update.
+    if os.path.isfile(cached) and os.access(cached, os.X_OK):
+        _maybe_self_update(cached)
+        return cached
+
+    try:
+        os.makedirs(cache_root, exist_ok=True)
+        _downloadCli(version, triple, cache_root)
+    except Exception as e:
+        print("Bugsee: failed to download bugsee-cli v%s for %s: %s" % (version, triple, e))
+        return None
+
+    if os.path.isfile(cached) and os.access(cached, os.X_OK):
+        # Freshly downloaded → a binary we manage; let the CLI bump it in
+        # place to the latest same-major release (best-effort, once per
+        # process). Never run on a PATH / BUGSEE_CLI_PATH binary.
+        _maybe_self_update(cached)
+        return cached
+    return None
+
+
+def _downloadCli(version, triple, cacheDir):
+    """Fetch tarball + SHA-256 sidecar, verify, extract via system tar."""
+    is_windows = "windows" in triple
+    ext = "zip" if is_windows else "tar.xz"
+    artifact = "bugsee-cli-%s.%s" % (triple, ext)
+    url = "%s/v%s/%s" % (BUGSEE_CLI_DOWNLOAD_BASE, version, artifact)
+    sha_url = url + ".sha256"
+
+    # Defence-in-depth: refuse to fetch from anywhere but the literal
+    # https://download.bugsee.com host. BUGSEE_CLI_DOWNLOAD_BASE is a
+    # module global an importer can shadow, and the URL composition
+    # accepts any string before the version segment. Pin both the
+    # scheme and the host before either urlopen so neither a hostile
+    # import nor a typo on the base const can redirect downloads to
+    # an attacker-controlled origin. The sidecar verifies tarball
+    # integrity, not origin authenticity — those are independent
+    # protections that must both hold.
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme != "https" or parsed.hostname != "download.bugsee.com":
+        raise ValueError(
+            "Refusing to download bugsee-cli from non-canonical origin %s "
+            "(scheme=%s host=%s); set BUGSEE_CLI_DOWNLOAD_BASE back to "
+            "https://download.bugsee.com/cli to restore."
+            % (url, parsed.scheme, parsed.hostname)
+        )
+
+    print("Bugsee: downloading bugsee-cli v%s for %s from %s" % (version, triple, url))
+
+    # SHA-256 sidecar format: `<hex>  <filename>` or `<hex> *<filename>` or just `<hex>`.
+    with urllib.request.urlopen(sha_url) as resp:
+        expected_sha = resp.read().decode("utf-8").strip().split()[0]
+
+    tarball_path = os.path.join(cacheDir, artifact)
+    with urllib.request.urlopen(url) as resp:
+        with open(tarball_path, "wb") as f:
+            shutil.copyfileobj(resp, f)
+
+    h = hashlib.sha256()
+    with open(tarball_path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    actual_sha = h.hexdigest()
+    if expected_sha.lower() != actual_sha.lower():
+        os.unlink(tarball_path)
+        raise IOError("SHA-256 mismatch for %s: expected %s, got %s" % (
+            artifact, expected_sha, actual_sha))
+
+    # System `tar` handles tar.xz on macOS/Linux and zip on Windows 10+ (bsdtar).
+    # `--strip-components=1` peels the `bugsee-cli-<triple>/` wrapper dir.
+    result = subprocess.run(
+        ["tar", "-xf", tarball_path, "-C", cacheDir, "--strip-components=1"],
+        capture_output=True, text=True)
+    if result.returncode != 0:
+        raise IOError("tar -xf %s failed (exit %d): %s" % (
+            artifact, result.returncode, result.stderr.strip()))
+
+    os.unlink(tarball_path)
+    binary_name = "bugsee-cli.exe" if is_windows else "bugsee-cli"
+    binary_path = os.path.join(cacheDir, binary_name)
+    if not os.path.isfile(binary_path):
+        raise IOError("extraction did not produce %s in %s" % (binary_name, cacheDir))
+    os.chmod(binary_path, 0o755)
+    print("Bugsee: bugsee-cli v%s installed at %s" % (version, binary_path))
+
+
+def uploadDsymViaCli(cliBinary, dsymPath, appToken, endpoint, version, build):
+    """Exec bugsee-cli to upload one .dSYM bundle. Returns True on success."""
+    cmd = [
+        cliBinary,
+        "--endpoint", endpoint,
+        "--app-token", appToken,
+        "debug-files", "upload",
+        "--type", "dsym",
+        "--version", version or "",
+        "--build", build or "",
+        dsymPath,
+    ]
+    # Stream stderr/stdout straight through so the user sees CLI progress
+    # in the same terminal / Xcode log they'd see BugseeAgent output in.
+    try:
+        result = subprocess.run(cmd, check=False)
+        return result.returncode == 0
+    except Exception as e:
+        print("Bugsee: failed to exec bugsee-cli at %s: %s" % (cliBinary, e))
+        return False
+
+
+def uploadMappingViaCli(cliBinary, mappingPath, appToken, endpoint,
+                        version, build, uuid, iconPath=None):
+    """Exec bugsee-cli to upload one ProGuard / R8 mapping.txt for
+    Android. The fastlane-plugin-bugsee `upload_mapping_to_bugsee`
+    action resolves the UUID Ruby-side (either from the Bugsee Gradle
+    plugin's BugseeBuildIdResolveTask output, or by Ruby-side
+    synthesis matching the SDK's runtime fallback formula) and
+    passes it via `uuid`. The CLI's local UUID compute is bypassed.
+
+    Returns True on success.
+    """
+    cmd = [
+        cliBinary,
+        "--endpoint", endpoint,
+        "--app-token", appToken,
+        "debug-files", "upload",
+        "--type", "proguard",
+        "--version", version or "",
+        "--build", build or "",
+        "--uuid", uuid or "",
+    ]
+    if iconPath:
+        cmd.extend(["--icon", iconPath])
+    cmd.append(mappingPath)
+    try:
+        result = subprocess.run(cmd, check=False)
+        return result.returncode == 0
+    except Exception as e:
+        print("Bugsee: failed to exec bugsee-cli at %s: %s" % (cliBinary, e))
+        return False
+
+
+# ──────────────────────────────────────────────────────────────────
+# Build dependencies collection (parallel to the Android Gradle
+# plugin's `DependencyCollector` — wire format must stay in lockstep
+# with `BugseeBuildDependenciesPipelineRecipe` consumed by the
+# Bugsee worker / appserver / viewer stack).
+#
+# Sources scanned, in order:
+#   1. CocoaPods         — Podfile.lock (full resolved tree with
+#                          parent → child edges)
+#   2. Swift Package Mgr — Package.resolved (flat list, no graph)
+#   3. Carthage          — Cartfile.resolved (flat list, no graph)
+#   4. Vendored frames   — `otool -L` on the linked product binary,
+#                          filtered to @rpath / @executable_path
+#                          entries (system frameworks excluded)
+#
+# Output: same shape the Android plugin emits — a JSON dictionary
+# carrying `schema_version: 1` and a `dependencies` array of
+# objects with keys: `id`, `group`, `name`, `version`, `direct`,
+# `scope`, `type`, `parents`. iOS-specific mapping notes:
+#
+#   - `group` is the empty string for every source iOS deps come
+#     from (Pods / SPM packages / Carthage / vendored frameworks
+#     don't carry the Maven group:name:version triple).
+#   - `id` is `"<type>:<group>:<name>"` — three colons total for
+#     iOS rows because `group` is empty, matching the format the
+#     viewer's identityOf and the worker's _identity functions
+#     produce. Subspecs (e.g. "Braintree/Card") keep the slash
+#     in `name`.
+#   - `type` is one of `library` (Pods + SPM + Carthage) or
+#     `file` (vendored frameworks discovered via otool). No
+#     `project` rows from iOS for now — local SPM packages are
+#     emitted as library-type with the package name; the path
+#     distinction isn't surfaced.
+#   - `scope` is left unset by default. CocoaPods has a
+#     `:configuration` qualifier on `pod` directives but that's a
+#     Podfile-time concept the lockfile doesn't surface.
+# ──────────────────────────────────────────────────────────────────
+
+# Wire-format schema version. Must equal the Android plugin's
+# `DependencyPayloadSerializer.SCHEMA_VERSION` and be in the worker's
+# `_SUPPORTED_SCHEMA_VERSIONS` set; any bump on either side requires
+# a parallel bump here.
+DEPENDENCIES_SCHEMA_VERSION = 1
+
+# Maximum number of entries we keep before truncating — same cap
+# the Android plugin uses (5000). The summary's `truncated` flag
+# surfaces when the cap kicks in, and the worker uses it to gate
+# diffability (truncated builds can't be diffed against each
+# other since the lists aren't apples-to-apples).
+DEPENDENCIES_MAX_COUNT = 5000
+
+
+def _make_dep_id(dep_type, group, name):
+    """Canonical identity string `"<type>:<group>:<name>"`. The
+    triple must stay byte-for-byte identical with the Android
+    plugin's `DependencyEntry.makeId` and the worker's
+    `_make_identity` so cross-platform diff matching works."""
+    return "%s:%s:%s" % (dep_type, group, name)
+
+
+def _strip_pod_version_paren(s):
+    """Strip the ` (version)` or ` (~> constraint)` suffix from a
+    CocoaPods reference. Returns just the bare name, e.g.
+    `"Braintree/Card (= 5.26.0)"` -> `"Braintree/Card"`.
+    Used for both DEPENDENCIES section entries and child references
+    inside the PODS section — both wear the same version-paren
+    suffix and we always want the underlying name as the lookup key.
+    """
+    paren_pos = s.find('(')
+    if paren_pos == -1:
+        return s.strip()
+    return s[:paren_pos].strip()
+
+
+def _parse_podfile_lock(path):
+    """Parse a CocoaPods `Podfile.lock` and return a list of dep
+    entries with parent edges.
+
+    Strategy:
+      1. Walk the PODS: section line-by-line tracking indent depth.
+         A 2-space-indent line is a top-level pod declaration of
+         shape `- Name (Version):` (the trailing colon is optional —
+         pods with no transitive children skip the colon).
+         A 4-space-indent line is a child of the last top-level pod
+         seen, of shape `- Name [(constraint)]`.
+      2. Walk the DEPENDENCIES: section in the same indent style,
+         collecting the bare name (no constraint) of every entry
+         the user declared directly in their Podfile.
+      3. Emit one entry per top-level pod. `direct` is true iff
+         the pod (or a subspec whose base name matches) appears in
+         the DEPENDENCIES set. `parents` is the list of `id`s of
+         pods that referenced this one as a child — built by
+         reverse-walking the children map.
+
+    The format is YAML-ish but we don't pull in PyYAML — single-file
+    distribution constraint, and the lockfile shape is rigid enough
+    that a hand-rolled parser is robust.
+    """
+    if not path or not os.path.isfile(path):
+        return []
+
+    with open(path, 'r', encoding='utf-8') as f:
+        lines = f.read().splitlines()
+
+    # Split into sections by the top-level uppercase headers
+    # `PODS:`, `DEPENDENCIES:`, `SPEC REPOS:`, etc. Section start is
+    # a line at column 0 ending in ':' (we ignore everything past
+    # the PODS / DEPENDENCIES sections — SPEC CHECKSUMS, etc.).
+    pods_lines = []
+    deps_lines = []
+    current = None
+    for line in lines:
+        if re.match(r'^[A-Z][A-Z _]+:\s*$', line):
+            header = line.rstrip(': ').strip()
+            if header == 'PODS':
+                current = pods_lines
+            elif header == 'DEPENDENCIES':
+                current = deps_lines
+            else:
+                current = None
+            continue
+        if current is not None:
+            current.append(line)
+
+    # PODS section parse: top-level pods and their immediate
+    # children. We don't recurse — CocoaPods's lockfile is flat
+    # past depth 2 (children are pod refs, not nested declarations).
+    pods = {}          # name -> {"version": str, "children": [str]}
+    current_pod = None
+    pod_line_re = re.compile(r'^  - (.+?)(?::?)$')
+    child_line_re = re.compile(r'^    - (.+?)$')
+    name_version_re = re.compile(r'^(.+?)\s+\(([^)]+)\)\s*$')
+    for line in pods_lines:
+        if not line.strip():
+            continue
+        m = child_line_re.match(line)
+        if m and current_pod is not None:
+            child_ref = _strip_pod_version_paren(m.group(1))
+            pods[current_pod]["children"].append(child_ref)
+            continue
+        m = pod_line_re.match(line)
+        if m:
+            body = m.group(1)
+            nv = name_version_re.match(body)
+            if nv:
+                name = nv.group(1).strip()
+                version = nv.group(2).strip()
+            else:
+                # Pod with no version paren — defensive; shouldn't
+                # happen in a well-formed lockfile but we don't
+                # crash on it.
+                name = body.strip()
+                version = None
+            pods[name] = {"version": version, "children": []}
+            current_pod = name
+
+    # DEPENDENCIES section parse: just the bare names of pods the
+    # user declared directly in their Podfile.
+    direct_names = set()
+    dep_line_re = re.compile(r'^  - (.+?)$')
+    for line in deps_lines:
+        if not line.strip():
+            continue
+        m = dep_line_re.match(line)
+        if m:
+            direct_names.add(_strip_pod_version_paren(m.group(1)))
+
+    # Reverse-walk the children map to build the parents lookup:
+    # for each child reference, the owning top-level pod is a
+    # parent. A child reference can include a subspec slash (e.g.
+    # `Braintree/Card`) — we record the parent against the exact
+    # referenced name, so subspecs end up with parents pointing at
+    # the pods that pulled them in (typically the parent pod and
+    # any cross-pod users).
+    parents_by_name = {}
+    for owner_name, info in pods.items():
+        owner_id = _make_dep_id("library", "", owner_name)
+        for child_ref in info["children"]:
+            parents_by_name.setdefault(child_ref, []).append(owner_id)
+
+    # Emit one entry per top-level pod. A pod is "direct" iff its
+    # EXACT name appears in DEPENDENCIES. CocoaPods writes subspecs
+    # into DEPENDENCIES verbatim when the user named them
+    # explicitly (`pod 'Foo', :subspecs => ['Bar']` → `Foo/Bar`
+    # appears in DEPENDENCIES). When the user writes `pod 'Foo'`
+    # against an umbrella pod, only `Foo` is in DEPENDENCIES —
+    # subspecs are pulled in transitively as children of the
+    # umbrella, which is exactly how the user intended.
+    entries = []
+    for name, info in pods.items():
+        is_direct = name in direct_names
+        entries.append({
+            "id":      _make_dep_id("library", "", name),
+            "group":   "",
+            "name":    name,
+            "version": info["version"],
+            "direct":  is_direct,
+            "scope":   None,
+            "type":    "library",
+            "parents": list(parents_by_name.get(name, [])),
+        })
+
+    return entries
+
+
+def _parse_package_resolved(path):
+    """Parse Swift Package Manager's `Package.resolved` (JSON).
+
+    Two formats exist in the wild:
+      - Xcode-managed: `{"object": {"pins": [...]}, "version": 1|2}`
+      - SPM CLI v2:    `{"pins": [...], "version": 2}` (Xcode 14+
+        and `swift package` write this at the project root)
+
+    Both carry the same per-pin information: a package identity
+    (kind/location/name) plus a resolved version pin. The resolved
+    file does NOT carry the dependency graph — only the locked
+    list — so every entry comes out as `direct=true` with no
+    parents. Tree-view rendering on the viewer reduces to a flat
+    list for SPM-only builds, which is correct: we don't have the
+    information to do better.
+    """
+    if not path or not os.path.isfile(path):
+        return []
+
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return []
+
+    pins = None
+    if isinstance(data, dict):
+        if isinstance(data.get('pins'), list):
+            pins = data['pins']
+        elif isinstance(data.get('object'), dict) \
+                and isinstance(data['object'].get('pins'), list):
+            pins = data['object']['pins']
+    if not pins:
+        return []
+
+    entries = []
+    for pin in pins:
+        if not isinstance(pin, dict):
+            continue
+        # Identity field name differs by format:
+        #   - new format uses `identity` (lowercase package name)
+        #   - legacy format uses `package` (capitalised display name)
+        # Prefer `identity` when present so the id is stable across
+        # Xcode versions writing the same package set.
+        name = pin.get('identity') or pin.get('package')
+        if not name:
+            continue
+        version = None
+        state = pin.get('state') or {}
+        if isinstance(state, dict):
+            # `version` for tagged pins; `branch` for branch
+            # tracking; `revision` for revision-locked pins. Prefer
+            # the most specific human-readable value.
+            version = state.get('version') or state.get('branch') or state.get('revision')
+        # SPM URL — `location` is the v2/v3 key, `repositoryURL`
+        # the v1 key. Load-bearing for OSV vuln lookups (OSV's
+        # SwiftURL ecosystem keys off this URL). The Rust CLI
+        # emits this field too (bugsee-cli/src/cli/ios_deps.rs's
+        # `parse_package_resolved`); the in-process Python
+        # fallback must match or the wire-shape silently diverges
+        # depending on which path produced the payload.
+        url = pin.get('location') or pin.get('repositoryURL')
+        entry = {
+            "id":      _make_dep_id("library", "", name),
+            "group":   "",
+            "name":    name,
+            "version": version,
+            "direct":  True,
+            "scope":   None,
+            "type":    "library",
+            "parents": [],
+        }
+        if url:
+            entry["url"] = url
+        entries.append(entry)
+    return entries
+
+
+def _parse_cartfile_resolved(path):
+    """Parse a Carthage `Cartfile.resolved`. Each line has the
+    shape: `<source> "<repo>" "<version>"`. Examples:
+
+      github "ReactiveCocoa/ReactiveCocoa" "v2.3.1"
+      git "https://example.com/private.git" "1.0.0"
+      binary "https://example.com/MyBin.json" "1.0.0"
+
+    Emit one library entry per line. No graph info, so direct=true
+    and parents=[]. The repo path (e.g. `ReactiveCocoa/ReactiveCocoa`)
+    becomes the name verbatim — surfacing the slash keeps the
+    namespacing visible in the dashboard.
+    """
+    if not path or not os.path.isfile(path):
+        return []
+
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.read().splitlines()
+    except OSError:
+        return []
+
+    entries = []
+    # `<source> "repo" "version"` — tolerate single-quoted values
+    # too (Carthage's parser does).
+    line_re = re.compile(r'^\s*(\S+)\s+["\']([^"\']+)["\']\s+["\']([^"\']+)["\']\s*$')
+    for line in lines:
+        if not line.strip() or line.strip().startswith('#'):
+            continue
+        m = line_re.match(line)
+        if not m:
+            continue
+        name = m.group(2)
+        version = m.group(3)
+        entries.append({
+            "id":      _make_dep_id("library", "", name),
+            "group":   "",
+            "name":    name,
+            "version": version,
+            "direct":  True,
+            "scope":   None,
+            "type":    "library",
+            "parents": [],
+        })
+    return entries
+
+
+# Mach-O load paths emitted by `otool -L` that point at OS-owned
+# frameworks. Stripped from the vendored-framework scan since they
+# aren't user dependencies and would just bloat the list.
+_SYSTEM_DYLIB_PREFIXES = (
+    '/usr/lib/',
+    '/System/Library/',
+    '/Library/Frameworks/',
+)
+
+
+def _parse_vendored_frameworks(binary_path):
+    """Run `otool -L` on the linked product binary and return a
+    list of dep entries for embedded / vendored frameworks. Lines
+    whose load path starts with `@rpath/`, `@executable_path/`, or
+    `@loader_path/` are the embedded frameworks shipped inside
+    the .app bundle; everything else is either the OS or a Swift
+    toolchain dylib — neither is a user dependency.
+
+    Each entry is `type="file"`, direct=true, no parents. The
+    `name` is the framework's basename (e.g. `Bugsee.framework`)
+    rather than the full @rpath path — the user-recognisable form.
+    """
+    if not binary_path or not os.path.isfile(binary_path):
+        return []
+
+    try:
+        out = subprocess.run(
+            ['/usr/bin/otool', '-L', binary_path],
+            capture_output=True, text=True, check=True,
+        ).stdout
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return []
+
+    seen = set()
+    entries = []
+    # Sample line: `\t@rpath/Bugsee.framework/Bugsee (compatibility version 1.0.0, current version 1.0.0)`
+    line_re = re.compile(r'^\s*([^\s]+)\s+\(compatibility version')
+    for raw in out.splitlines():
+        m = line_re.match(raw)
+        if not m:
+            continue
+        load_path = m.group(1)
+        if load_path.startswith(_SYSTEM_DYLIB_PREFIXES):
+            continue
+        if not (load_path.startswith('@rpath/')
+                or load_path.startswith('@executable_path/')
+                or load_path.startswith('@loader_path/')):
+            continue
+        # Extract the framework name: the `.framework/X` suffix
+        # carries Mach-O's binary slice name; the directory above
+        # it is the user-facing framework. Falls back to the
+        # basename if the path doesn't carry a `.framework/` token.
+        framework_match = re.search(r'/([^/]+\.framework)/', load_path)
+        if framework_match:
+            name = framework_match.group(1)
+        else:
+            name = os.path.basename(load_path)
+        if name in seen:
+            continue
+        seen.add(name)
+        entries.append({
+            "id":      _make_dep_id("file", "", name),
+            "group":   "",
+            "name":    name,
+            "version": None,
+            "direct":  True,
+            "scope":   None,
+            "type":    "file",
+            "parents": [],
+        })
+    return entries
+
+
+def _merge_dep_entries(*sources):
+    """Combine multiple dep-entry lists into one. Deduplication
+    is field-wise — first-seen entry survives, but later sources
+    can graft on missing `url` / `version` / `parents` and OR-merge
+    the `direct` flag.
+
+    Why field-wise instead of pure first-source-wins: the parsers
+    populate these fields asymmetrically. CocoaPods walks the PODS
+    graph and emits `direct: false` + `parents: ["<umbrella>"]`
+    for transitive subspecs; SPM emits `direct: true` +
+    `parents: []` because `Package.resolved` only records resolved
+    pins, not the dependency graph; SPM ALSO carries the upstream
+    `url` (load-bearing for OSV vuln lookups). Wholesale-replacing
+    the existing record on url-preference would wipe the CocoaPods
+    graph evidence; ignoring url-bearing later sources would lose
+    the upstream URL. Mirrors the Rust CLI's `merge_dep_entries`
+    in `bugsee-cli/src/cli/ios_deps.rs`.
+
+    Returns a `(entries, truncated)` pair, capped at
+    [DEPENDENCIES_MAX_COUNT]. The truncated flag drives the
+    summary's same-name field and ultimately the worker's
+    compatibility check (truncated lists aren't diff-comparable).
+    """
+    by_id = {}
+    insertion_order = []
+    for source in sources:
+        for entry in source:
+            eid = entry["id"]
+            if eid not in by_id:
+                # Defensive copy so later same-id mutations don't
+                # bleed back into the caller's source list.
+                by_id[eid] = dict(entry)
+                insertion_order.append(eid)
+                continue
+            prev = by_id[eid]
+            # url: copy from incoming when previous has none.
+            if not prev.get("url") and entry.get("url"):
+                prev["url"] = entry["url"]
+            # direct: OR-merge — any source reaching the package
+            # directly is authoritative.
+            if entry.get("direct"):
+                prev["direct"] = True
+            # version: fill in when previous has none.
+            if prev.get("version") in (None, "") and entry.get("version"):
+                prev["version"] = entry["version"]
+            # parents: backfill when previous is empty. The first
+            # non-empty parents list wins so a follow-on source
+            # with `parents: []` can't wipe the graph evidence.
+            if not prev.get("parents") and entry.get("parents"):
+                prev["parents"] = list(entry["parents"])
+
+    deduped = [by_id[i] for i in insertion_order]
+    truncated = False
+    if len(deduped) > DEPENDENCIES_MAX_COUNT:
+        truncated = True
+        # Direct-prefer truncation: keep direct entries first.
+        # Stable sort preserves insertion order within each group.
+        deduped.sort(key=lambda e: 0 if e.get("direct") else 1)
+        deduped = deduped[:DEPENDENCIES_MAX_COUNT]
+
+    # Self-consistency pass: filter parents pointing at IDs that
+    # didn't make it into the emitted set (truncation eviction
+    # OR a malformed source listing a phantom parent). Same posture
+    # as the Android plugin's post-truncation cleanup.
+    kept = {e["id"] for e in deduped}
+    for e in deduped:
+        if e.get("parents"):
+            e["parents"] = [p for p in e["parents"] if p in kept]
+    return deduped, truncated
+
+
+def _build_dependencies_payload(entries, truncated, scope_label,
+                                include_selected_reason=False,
+                                max_count=DEPENDENCIES_MAX_COUNT,
+                                clock=None):
+    """Build the JSON-serialisable summary + blob pair. Shape
+    mirrors what the Android plugin produces (see
+    `DependencyPayloadSerializer.summaryJson` / `entriesJson`).
+
+    Returns a tuple `(summary_dict, blob_dict)`:
+      - `summary_dict` is the scalar summary sent inline on the
+        build registration POST body (under
+        `dependencies_summary`).
+      - `blob_dict` is the per-entry list serialised as JSON and
+        gzipped before PUT.
+    """
+    clock = clock or (lambda: int(time.time() * 1000))
+    total = len(entries)
+    direct = sum(1 for e in entries if e["direct"])
+    transitive = total - direct
+    by_type = {"library": 0, "project": 0, "file": 0}
+    for e in entries:
+        t = e["type"]
+        if t in by_type:
+            by_type[t] += 1
+
+    # ISO-8601 UTC with the trailing `Z` form — matches the
+    # Android plugin's `isoUtc` helper so the appserver's
+    # `new Date(collected_at)` parses identically.
+    epoch_ms = clock()
+    iso_utc = time.strftime('%Y-%m-%dT%H:%M:%SZ',
+                            time.gmtime(epoch_ms / 1000))
+
+    summary = {
+        "total":      total,
+        "direct":     direct,
+        "transitive": transitive,
+        "by_type":    by_type,
+        "truncated":  truncated,
+        "collected_at": iso_utc,
+        "collection_config": {
+            "scope":                   scope_label,
+            "include_selected_reason": include_selected_reason,
+            "max_count":               max_count,
+        },
+    }
+
+    # Per-entry blob. Omit `version` / `scope` when None, omit
+    # empty `parents` lists — same wire posture the Android
+    # serializer takes. Keeps the gzipped payload small for the
+    # common case (most pods don't have transitive children).
+    serialised = []
+    for e in entries:
+        item = {
+            "id":     e["id"],
+            "group":  e["group"],
+            "name":   e["name"],
+            "direct": e["direct"],
+            "type":   e["type"],
+        }
+        if e.get("version"):
+            item["version"] = e["version"]
+        if e.get("scope"):
+            item["scope"] = e["scope"]
+        if e.get("parents"):
+            item["parents"] = list(e["parents"])
+        # SPM `url` (load-bearing for OSV's SwiftURL vuln lookups).
+        # Mirrors the Rust `DepEntry::url` field's
+        # `#[serde(skip_serializing_if = "Option::is_none")]`. Without
+        # this, fastlane Python-fallback uploads would emit
+        # url-less blobs even when the CLI populated url, silently
+        # degrading vuln-scan coverage vs the SDK-side blob shape.
+        if e.get("url"):
+            item["url"] = e["url"]
+        serialised.append(item)
+
+    blob = {
+        "schema_version": DEPENDENCIES_SCHEMA_VERSION,
+        "dependencies":   serialised,
+    }
+    return summary, blob
+
+
+def _gzip_json_bytes(obj):
+    """Serialise `obj` to compact JSON and return gzipped bytes.
+    The blob is uploaded to a presigned S3 URL with
+    `Content-Encoding: gzip` on the worker side; the producer
+    PUT carries `application/octet-stream` (matching the Android
+    plugin's signing posture)."""
+    raw = json.dumps(obj, separators=(',', ':')).encode('utf-8')
+    return gzip.compress(raw, compresslevel=9)
+
+
+# ──────────────────────────────────────────────────────────────────
+# Build environment metadata (machine label, VCS, Xcode version)
+#
+# Ported from the SDK's tools.bundle/BugseeAgent. The wire shape
+# matches the Android Gradle plugin's `BuildMachineResolver` and
+# `VcsMetadataResolver` so a single build record can compare iOS
+# and Android runs from the same CI runner.
+#
+# The appserver's `sanitizeVcs` / `sanitizeBuildMetadata`
+# (appserver/code/components/app/builds/modules/build.vcs-helper.js)
+# accepts these fields verbatim; the dashboard's build view reads
+# `vcs.branch` / `vcs.commit_sha` / `vcs.pr_number` directly.
+# ──────────────────────────────────────────────────────────────────
+
+def _env_truthy(value):
+    """True when an env-var-style value is a conventional "on" token.
+    Matches the set used by the Android Gradle plugin (`"1"`, `"true"`,
+    `"yes"`, `"on"`, case-insensitive) so one CI config snippet
+    can enable a feature on both platforms."""
+    return (value or '').strip().lower() in ('1', 'true', 'yes', 'on')
+
+
+def _set_if_present(out, key, value):
+    """Only write `key` to `out` when `value` is a non-empty string.
+    Keeps the JSON payload clean — the back-end distinguishes
+    "unknown" from "known empty" by field presence."""
+    if value and str(value).strip():
+        out[key] = str(value).strip()
+
+
+def _local_hostname():
+    """Short hostname or None. `socket.gethostname()` is the standard
+    cross-platform lookup; it may throw on sandboxed hosts, hence
+    the broad except."""
+    try:
+        host = socket.gethostname()
+        return host if host else None
+    except Exception:
+        return None
+
+
+def _resolve_machine_label_via_cli():
+    """Shell to `bugsee-cli build-env machine-label` and return the
+    trimmed stdout. Option-C target."""
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if not cli:
+        return None
+    try:
+        result = subprocess.run(
+            [cli, "build-env", "machine-label"],
+            capture_output=True, text=True, timeout=10, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        return out if out else None
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
+def resolve_machine_label():
+    """Returns a `<provider>[:<detail>]` label describing where the
+    build ran — mirrors the cascade in the Android plugin's
+    `BuildMachineResolver` so the front-end can group iOS + Android
+    builds from the same CI runner.
+
+    Prefers `bugsee-cli build-env machine-label` (single cross-
+    language source of truth). Falls back to the in-process
+    Python implementation below — pure env-based detection; no
+    shelling out.
+
+    First positive provider signal wins. Falls back to the local
+    hostname when nothing matches AND hostname lookup succeeds.
+    Returns None as last resort (sandboxed / networkless hosts).
+    """
+    via_cli = _resolve_machine_label_via_cli()
+    if via_cli is not None:
+        return via_cli
+
+    env = os.environ
+
+    def with_detail(prefix, detail):
+        detail = (detail or '').strip()
+        return '%s:%s' % (prefix, detail) if detail else prefix
+
+    if _env_truthy(env.get('GITHUB_ACTIONS')):
+        return with_detail('github-actions', env.get('RUNNER_NAME'))
+    if _env_truthy(env.get('GITLAB_CI')):
+        detail = ((env.get('CI_RUNNER_DESCRIPTION') or '').strip()
+                  or (env.get('CI_RUNNER_ID') or '').strip())
+        return with_detail('gitlab-ci', detail)
+    if (env.get('JENKINS_URL') or '').strip():
+        return with_detail('jenkins', env.get('NODE_NAME'))
+    if _env_truthy(env.get('CIRCLECI')):
+        return with_detail('circleci', env.get('CIRCLE_NODE_INDEX'))
+    if _env_truthy(env.get('BITRISE_IO')):
+        return with_detail('bitrise', env.get('BITRISE_APP_SLUG'))
+    if (env.get('TEAMCITY_VERSION') or '').strip():
+        agent_name = ((env.get('AGENT_NAME') or '').strip()
+                      or (env.get('agent.name') or '').strip())
+        return with_detail('teamcity', agent_name)
+    # Xcode Cloud — Apple's own CI. `CI_WORKFLOW` is the canonical
+    # presence signal; `CI_XCODEBUILD_ACTION` adds action context
+    # (build / archive / test) when available.
+    if ((env.get('CI_WORKFLOW') or '').strip()
+            or _env_truthy(env.get('CI_XCODE_CLOUD'))):
+        detail = ((env.get('CI_WORKFLOW') or '').strip()
+                  or (env.get('CI_XCODEBUILD_ACTION') or '').strip())
+        return with_detail('xcode-cloud', detail)
+    if _env_truthy(env.get('CI')):
+        host = ((env.get('HOSTNAME') or '').strip()
+                or _local_hostname() or '')
+        return with_detail('ci', host)
+
+    return _local_hostname()
+
+
+def _run_git(working_dir, git_args):
+    try:
+        result = subprocess.run(
+            ['/usr/bin/env', 'git'] + list(git_args),
+            cwd=working_dir,
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+        return (result.stdout or '').strip() or None
+    except Exception:
+        return None
+
+
+def _resolve_git_fallback(working_dir):
+    """Shell out to `git` for the basics. Returns {} if not a git
+    working tree, or if `git` isn't on PATH (rare on dev macs, but
+    possible in stripped-down CI containers)."""
+    if not working_dir or not os.path.isdir(working_dir):
+        return {}
+    out = {}
+    commit = _run_git(working_dir, ['rev-parse', 'HEAD'])
+    if commit:
+        out['commit_sha'] = commit
+    branch = _run_git(working_dir, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    # Detached HEADs show up as "HEAD" — not a meaningful branch name.
+    if branch and branch != 'HEAD':
+        out['branch'] = branch
+    return out
+
+
+def _resolve_vcs_metadata_via_cli(cli_binary, working_dir):
+    """Shell to `bugsee-cli vcs-metadata` and parse its JSON output.
+
+    Part of the Option-C migration that moved VCS resolution to the
+    Rust CLI as the single canonical implementation. The Python
+    fallback below is preserved for the case where the CLI isn't
+    available (older CLI versions that don't have the subcommand,
+    a stripped-down env without auto-download, etc.).
+
+    Returns the parsed dict on success, or None on any failure
+    (subprocess error, non-zero exit, malformed JSON). The caller
+    falls back to the Python implementation on None.
+    """
+    if not cli_binary:
+        return None
+    try:
+        result = subprocess.run(
+            [cli_binary, "vcs-metadata", "--working-dir", working_dir or "."],
+            capture_output=True, text=True, timeout=10, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        if not out:
+            return None
+        return json.loads(out)
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
+def resolve_vcs_metadata(working_dir):
+    """Returns a dict shaped for the upload JSON's nested `vcs`
+    sub-object. Matches what the Android Gradle plugin emits so the
+    back-end persists both identically. Keys (any / all may be
+    absent):
+
+        commit_sha, base_sha, branch, base_branch, pr_number,
+        provider, repo
+
+    Resolution order — first provider with a positive signal wins:
+      1. GitHub Actions env (push + pull_request events).
+      2. GitLab CI env (push + merge_request events).
+      3. Bitbucket Pipelines env.
+      4. Git fallback — shell out to `git` in `working_dir` when
+         none of the CI providers matched. Lets local dev archives
+         still carry `commit_sha` / `branch` without needing CI
+         context.
+
+    Implementation: prefers the Rust `bugsee-cli vcs-metadata`
+    subcommand (the single cross-language source of truth, ported
+    from this Python function — see
+    `bugsee-cli/src/cli/vcs_metadata.rs`). Falls back to the
+    in-process Python implementation below when the CLI isn't
+    available so cold-start environments without the CLI cache
+    still produce a usable result.
+    """
+    # Try the Rust CLI first — same algorithm, in the canonical
+    # cross-language implementation. `options` is set by main() in
+    # production but unset at import time (tests load the agent as
+    # a module without ever invoking main()); the NameError catch
+    # lets the resolver still invoke resolveCli with defaults so
+    # the mock-based unit tests can exercise the CLI path.
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if cli:
+        via_cli = _resolve_vcs_metadata_via_cli(cli, working_dir)
+        if via_cli is not None:
+            return via_cli
+
+    env = os.environ
+
+    # GitHub Actions ----------------------------------------------
+    if _env_truthy(env.get('GITHUB_ACTIONS')):
+        out = {'provider': 'github'}
+        _set_if_present(out, 'commit_sha', env.get('GITHUB_SHA'))
+        _set_if_present(out, 'repo',       env.get('GITHUB_REPOSITORY'))
+        if (env.get('GITHUB_EVENT_NAME') or '') == 'pull_request':
+            _set_if_present(out, 'branch',      env.get('GITHUB_HEAD_REF'))
+            _set_if_present(out, 'base_branch', env.get('GITHUB_BASE_REF'))
+            m = re.search(r'refs/pull/(\d+)/', env.get('GITHUB_REF') or '')
+            if m:
+                out['pr_number'] = int(m.group(1))
+        else:
+            # Push event: GITHUB_REF carries `refs/heads/<branch>` for
+            # a branch push, `refs/tags/<tag>` for a tag push. Only
+            # emit `branch` when the ref is actually a head ref. The
+            # historical `.replace('refs/heads/', '', 1)` returned the
+            # raw `refs/tags/v1.0.0` ref on tag pushes, which then
+            # landed in the dashboard's branch column verbatim. Match
+            # the Android Gradle plugin's canonical Kotlin resolver
+            # (`removePrefix.takeIf { it != ref }`) and the Rust CLI
+            # (bugsee-cli@cf1325f).
+            ref = (env.get('GITHUB_REF') or '')
+            if ref.startswith('refs/heads/'):
+                _set_if_present(out, 'branch', ref[len('refs/heads/'):])
+        return out
+
+    # GitLab CI ---------------------------------------------------
+    if _env_truthy(env.get('GITLAB_CI')):
+        out = {'provider': 'gitlab'}
+        _set_if_present(out, 'commit_sha', env.get('CI_COMMIT_SHA'))
+        _set_if_present(out, 'repo',       env.get('CI_PROJECT_PATH'))
+        # Merge-request pipelines expose different branch variables
+        # than push pipelines. `CI_MERGE_REQUEST_IID` is the MR
+        # number (the `_ID` variant is a global DB id and unusable
+        # as a PR reference).
+        if (env.get('CI_MERGE_REQUEST_IID') or '').strip():
+            _set_if_present(out, 'branch',
+                            env.get('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'))
+            _set_if_present(out, 'base_branch',
+                            env.get('CI_MERGE_REQUEST_TARGET_BRANCH_NAME'))
+            try:
+                out['pr_number'] = int(env.get('CI_MERGE_REQUEST_IID'))
+            except (TypeError, ValueError):
+                pass
+        else:
+            # Branch vs tag pipeline distinction. GitLab CI sets:
+            #   - CI_COMMIT_BRANCH on branch pipelines (not tag).
+            #   - CI_COMMIT_TAG on tag pipelines (not branch).
+            #   - CI_COMMIT_REF_NAME is ALWAYS set; on a tag pipeline
+            #     it equals the tag name. Without the gate, tag
+            #     pipelines leaked the tag into the branch column.
+            # Prefer CI_COMMIT_BRANCH; if absent and CI_COMMIT_TAG is
+            # set, leave branch absent. Fall back to CI_COMMIT_REF_NAME
+            # only for legacy GitLab (pre-12.6) that lacked the
+            # specific markers.
+            if (env.get('CI_COMMIT_BRANCH') or '').strip():
+                _set_if_present(out, 'branch', env.get('CI_COMMIT_BRANCH'))
+            elif (env.get('CI_COMMIT_TAG') or '').strip():
+                pass  # tag pipeline — branch stays absent
+            else:
+                _set_if_present(out, 'branch', env.get('CI_COMMIT_REF_NAME'))
+        return out
+
+    # Bitbucket Pipelines -----------------------------------------
+    if (env.get('BITBUCKET_BUILD_NUMBER') or '').strip():
+        out = {'provider': 'bitbucket'}
+        _set_if_present(out, 'commit_sha', env.get('BITBUCKET_COMMIT'))
+        _set_if_present(out, 'repo',
+                        env.get('BITBUCKET_REPO_FULL_NAME')
+                        or env.get('BITBUCKET_REPO_SLUG'))
+        _set_if_present(out, 'branch',     env.get('BITBUCKET_BRANCH'))
+        if (env.get('BITBUCKET_PR_ID') or '').strip():
+            _set_if_present(out, 'base_branch',
+                            env.get('BITBUCKET_PR_DESTINATION_BRANCH'))
+            try:
+                out['pr_number'] = int(env.get('BITBUCKET_PR_ID'))
+            except (TypeError, ValueError):
+                pass
+        return out
+
+    # Git fallback ------------------------------------------------
+    # Covers local archives + any CI provider we don't specifically
+    # recognise. Missing `provider` / `repo` is fine — the server
+    # accepts partial payloads.
+    return _resolve_git_fallback(working_dir)
+
+
+def _resolve_xcode_version_via_cli():
+    """Shell to `bugsee-cli build-env xcode-version` and return the
+    trimmed stdout. Option-C migration target — the Rust CLI owns
+    the canonical resolver. Returns None on CLI absence /
+    non-zero exit / empty output (the Python fallback below
+    handles those cases)."""
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if not cli:
+        return None
+    try:
+        result = subprocess.run(
+            [cli, "build-env", "xcode-version"],
+            capture_output=True, text=True, timeout=15, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        return out if out else None
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
+def resolve_xcode_version():
+    """Returns the short Xcode version (e.g. `"16.2"`) or None. Tries
+    `$XCODE_VERSION_ACTUAL` first (set in every Run Script env —
+    numeric like `1620`, needs reformatting), then falls back to
+    `xcodebuild -version` which is slow but ground-truth.
+
+    Prefers `bugsee-cli build-env xcode-version` when available
+    (single cross-language source of truth, ported from this
+    Python implementation — see `bugsee-cli/src/cli/build_env.rs`).
+    Falls back to the in-process Python below when the CLI isn't
+    installed."""
+    via_cli = _resolve_xcode_version_via_cli()
+    if via_cli is not None:
+        return via_cli
+
+    actual = os.environ.get('XCODE_VERSION_ACTUAL')
+    if actual and actual.isdigit():
+        # "1620" → "16.2.0" ; "1543" → "15.4.3"
+        parts = [actual[0:-2] or '0', actual[-2:-1] or '0',
+                 actual[-1:] or '0']
+        return '.'.join(p.lstrip('0') or '0' for p in parts)
+
+    try:
+        result = subprocess.run(
+            ['/usr/bin/xcodebuild', '-version'],
+            capture_output=True, text=True, timeout=10,
+        )
+        if result.returncode != 0:
+            return None
+        first_line = ((result.stdout or '').splitlines()[0].strip()
+                      if result.stdout else '')
+        m = re.match(r'^Xcode\s+(\S+)', first_line)
+        return m.group(1) if m else None
+    except Exception:
+        return None
+
+
+# ──────────────────────────────────────────────────────────────────
+# Xcode env + Info.plist helpers
+# ──────────────────────────────────────────────────────────────────
+
+def _read_info_plist_via_cli(plist_path):
+    """Shell to `bugsee-cli build-env read-plist <path>` and parse
+    the JSON. Option-C migration target."""
+    if not plist_path:
+        return None
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if not cli:
+        return None
+    try:
+        result = subprocess.run(
+            [cli, "build-env", "read-plist", plist_path],
+            capture_output=True, text=True, timeout=10, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        if not out:
+            return None
+        return json.loads(out)
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
+def _read_info_plist(plist_path):
+    """Read the binary or XML Info.plist at the given path. Returns
+    a dict on success or `{}` on any error — the caller treats
+    missing fields as best-effort and falls back to env vars.
+
+    Prefers `bugsee-cli build-env read-plist` when available
+    (single cross-language source of truth). Falls back to the
+    in-process `plistlib.load` below.
+
+    Choke-point dict-coercion: every caller (`_collect_build_metadata`,
+    `resolve_bundle_info_from_app`, `_extract_uuid_from_app`, …)
+    indexes the return value as a dict. The CLI's `read-plist`
+    returns whatever `json.loads(stdout)` produces with no shape
+    validation, so a future CLI bug, version-skew, or exotic plist
+    could surface as a list/string/number and crash every call site
+    with `AttributeError`. Coerce non-dict returns to `{}` HERE so
+    no caller needs its own isinstance guard."""
+    via_cli = _read_info_plist_via_cli(plist_path)
+    if via_cli is not None:
+        return via_cli if isinstance(via_cli, dict) else {}
+
+    if not plist_path or not os.path.isfile(plist_path):
+        return {}
+    try:
+        with open(plist_path, 'rb') as f:
+            data = plistlib.load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def resolve_bundle_info_from_app(app_path):
+    """Read the Info.plist inside a `.app` bundle and return
+    `(bundle_id, version, build)`. Any field may be None when the
+    plist lacks it or can't be read.
+
+    Mirrors the SDK BugseeAgent's
+    `tools.bundle/BugseeAgent::resolve_bundle_info_from_app` so the
+    fastlane artefact-upload flow ships the SAME baseline-lookup
+    keys (`package_id`, `version`, `build`) the SDK does. Without
+    matching keys the back-end's `/builds/baseline` lookup never
+    finds a previous build for the same package, and the dashboard's
+    size-trend chart silently shows no delta.
+    """
+    if not app_path or not os.path.isdir(app_path):
+        return (None, None, None)
+    plist_path = os.path.join(app_path, 'Info.plist')
+    # `_read_info_plist` coerces non-dict CLI returns to `{}` at the
+    # choke point, so an unguarded `.get()` is safe here.
+    info = _read_info_plist(plist_path)
+    return (
+        info.get('CFBundleIdentifier'),
+        info.get('CFBundleShortVersionString'),
+        info.get('CFBundleVersion'),
+    )
+
+
+# Arch preference order for fat-binary LC_UUID selection. arm64 wins
+# because it's the slice the runtime SDK reports on actual device
+# crashes; arm64e is M-series Macs; x86_64 covers Intel macs; the
+# simulator variants come last (only useful for simulator-only Debug
+# Build configs). Matches the SDK BugseeAgent's
+# `tools.bundle/BugseeAgent::_PREFERRED_MACHO_ARCHS` ordering exactly
+# so the fastlane and SDK producers emit the SAME uuid for the same
+# fat-binary build.
+_PREFERRED_MACHO_ARCHS = ('arm64', 'arm64e', 'x86_64',
+                         'arm64-simulator', 'x86_64-simulator')
+
+
+def _load_macho_slices_via_cli(binary_path):
+    """Shell to `bugsee-cli dsym slices <binary>` and return a
+    `{arch: uuid}` dict, or None when the CLI is unavailable / its
+    output can't be parsed.
+
+    Mirrors the SDK BugseeAgent's `_load_macho_slices_via_cli` so
+    `_extract_uuid_from_app` can pick the preferred arch's UUID on
+    fat binaries — same posture as the SDK side, which means the two
+    producers emit byte-identical uuids for the same artefact."""
+    if not binary_path:
+        return None
+    cli = shutil.which("bugsee-cli")
+    if not cli:
+        return None
+    try:
+        result = subprocess.run(
+            [cli, "dsym", "slices", binary_path],
+            capture_output=True, text=True, timeout=30, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        if not out:
+            return None
+        data = json.loads(out)
+        if not isinstance(data, list):
+            return None
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+    slices = {}
+    for entry in data:
+        if not isinstance(entry, dict):
+            continue
+        uuid_str = entry.get('uuid')
+        arch = entry.get('arch')
+        if not isinstance(uuid_str, str) or not isinstance(arch, str):
+            continue
+        # First-seen wins for duplicate arch entries — matches the
+        # SDK side's behaviour (rare exotic case).
+        if arch not in slices:
+            slices[arch] = uuid_str
+    return slices
+
+
+def _extract_uuid_from_app(app_path):
+    """Extract the main executable's Mach-O `LC_UUID` from `app_path`
+    and format it the way the iOS SDK reports it at runtime — 32
+    lowercase hex chars, no dashes. Returns None on any failure
+    (missing CFBundleExecutable, binary absent, CLI missing).
+
+    Prefers the arch-aware `bugsee-cli dsym slices <main_binary>`
+    subcommand and picks the preferred-arch UUID via the cascade
+    `arm64 → arm64e → x86_64 → arm64-simulator → x86_64-simulator →
+    first reported`. Falls back to the flat `dsym uuid` subcommand
+    only when slices returns None (older bugsee-cli versions that
+    predate the slices subcommand, or when the CLI isn't on PATH).
+
+    Mirrors the SDK BugseeAgent's `get_main_executable_uuid` posture
+    exactly so the fastlane producer path and the SDK producer path
+    emit the SAME uuid for the same fat-binary build — without this
+    cross-source consistency the back-end's `crash.uuid → build`
+    join would only match on whichever producer happened to upload
+    the build record.
+
+    The format matches `BGSCrashReport.m`'s LC_UUID reporting so
+    the back-end can join `crash.uuid → build.uuid` deterministically.
+    """
+    if not app_path or not os.path.isdir(app_path):
+        return None
+    plist_path = os.path.join(app_path, 'Info.plist')
+    # `_read_info_plist` returns `{}` for non-dict CLI output, so
+    # `.get()` is safe without an isinstance guard.
+    info = _read_info_plist(plist_path)
+    executable_name = info.get('CFBundleExecutable')
+    if not executable_name:
+        return None
+    binary_path = os.path.join(app_path, executable_name)
+    if not os.path.isfile(binary_path):
+        return None
+    # Prefer the arch-aware `dsym slices` subcommand so a fat binary's
+    # arm64 slice (the one the iOS runtime SDK reports at crash time)
+    # wins over x86_64/simulator slices that may appear first in the
+    # archive's load-command order. Mirrors the SDK BugseeAgent's
+    # `get_main_executable_uuid` posture exactly — without this, the
+    # fastlane producer path and the SDK producer path could emit
+    # different uuids for the same fat-binary build.
+    slices = _load_macho_slices_via_cli(binary_path)
+    candidate_uuid = None
+    if slices:
+        for arch in _PREFERRED_MACHO_ARCHS:
+            if arch in slices:
+                candidate_uuid = slices[arch]
+                break
+        if candidate_uuid is None:
+            # Exotic arch — take the first reported. Deterministic
+            # because the dict preserved insertion order from the CLI
+            # output (Python 3.7+).
+            candidate_uuid = next(iter(slices.values()))
+
+    # Fallback to the flat `dsym uuid` subcommand (for older bugsee-cli
+    # versions or when slices returned None — e.g. CLI not on PATH and
+    # the helper short-circuited).
+    if candidate_uuid is None:
+        uuids = _parse_dsym_via_cli(binary_path)
+        if uuids:
+            candidate_uuid = uuids[0]
+
+    # Funnel through the shared choke-point helper so the canonical
+    # shape contract (32 lowercase hex chars, no dashes, whitespace-
+    # only → None) lives in one place. Makes a regression that flipped
+    # the normalisation rule trivially visible — every caller flows
+    # through `_normalise_build_uuid`.
+    return _normalise_build_uuid(candidate_uuid)
+
+
+def _collect_build_metadata():
+    """Read Xcode environment + Info.plist into the build-registration
+    POST body shape. Mirrors the Android plugin's metadata block —
+    the appserver / viewer consume the same field names regardless
+    of platform.
+
+    Returns a tuple of `(body_dict, dwarf_uuid_or_none)`. The
+    body's `uuid` carries the Mach-O image UUID extracted from the
+    dSYM via dwarfdump; the value is also returned so the caller
+    can pass it to the symbols-upload step without re-running
+    dwarfdump.
+    """
+    build_dir = os.environ.get('TARGET_BUILD_DIR') or options.build_dir or ''
+    info_path_rel = os.environ.get('INFOPLIST_PATH', '')
+    info_path = os.path.join(build_dir, info_path_rel) if info_path_rel else ''
+    info = _read_info_plist(info_path)
+
+    version = info.get('CFBundleShortVersionString') \
+        or os.environ.get('MARKETING_VERSION') \
+        or (options.version if options.version else None)
+    build_number = info.get('CFBundleVersion') \
+        or os.environ.get('CURRENT_PROJECT_VERSION') \
+        or (options.build if options.build else None)
+    bundle_id = info.get('CFBundleIdentifier') \
+        or os.environ.get('PRODUCT_BUNDLE_IDENTIFIER')
+
+    body = {
+        # Mach-O UUID is filled in by the caller (after dwarfdump).
+        "uuid": None,
+        "package_id":          bundle_id,
+        "version":             str(version) if version is not None else None,
+        "build":               str(build_number) if build_number is not None else None,
+        "build_configuration": os.environ.get('CONFIGURATION'),
+        # iOS deploy format. The appserver's ALLOWED_BUILD_FORMATS
+        # set includes 'ipa' alongside 'apk' / 'aab'.
+        "format":              "ipa",
+        "has_mapping":         False,  # no Java-style ProGuard mapping on iOS
+        "build_metadata": {
+            "machine": {
+                # `host` is the CI-provider-aware label (e.g.
+                # `github-actions:Linux-X64`); falls back to
+                # platform.node() for local-archive runs where no
+                # provider env var is set. The richer label lets the
+                # dashboard cluster runs by runner across platforms.
+                "host": resolve_machine_label() or platform.node(),
+                "os":   platform.platform(),
+                "arch": platform.machine(),
+            },
+            "build_system": {
+                "type":    "xcode",
+                # `XCODE_VERSION_ACTUAL` is the numeric form Xcode
+                # exports (`"1620"` for 16.2.0); the resolver
+                # normalises to the dotted form the dashboard
+                # displays. Falls back to `xcodebuild -version`.
+                "version": resolve_xcode_version(),
+            },
+            "agent": {
+                "name":    "BugseeAgent",
+                # Resolved relative to the script — keeps the value
+                # honest even when the SDK ships multiple agent
+                # versions in different distributions.
+                "script":  os.path.basename(__file__),
+            },
+        },
+    }
+
+    # VCS metadata. Sibling field to `build_metadata` — matches the
+    # Android Gradle plugin's wire shape and the appserver's
+    # `sanitizeVcs` accept-list. Omit the field entirely when no
+    # provider was detected AND the git fallback didn't surface a
+    # commit (e.g. /tmp archive without a .git dir) — empty `vcs: {}`
+    # records would still pass `sanitizeVcs` but pollute the dashboard.
+    vcs = resolve_vcs_metadata(
+        os.environ.get('SRCROOT')
+        or os.environ.get('PROJECT_DIR')
+        or os.getcwd()
+    )
+    if vcs:
+        body["vcs"] = vcs
+
+    return body
+
+
+# -----------------------------------------------------------------
+# Artifact packaging (synthetic .ipa from `.app`)
+# -----------------------------------------------------------------
+
+# File extensions that are already compressed; storing them with
+# DEFLATE wastes CPU without saving bytes. Mirrors the SDK
+# BugseeAgent's (`tools.bundle/BugseeAgent::_IPA_STORE_EXTENSIONS`)
+# and the Android Gradle plugin's `BundleZipNormalizer` set. Keep in
+# sync — divergence would make the byte-deterministic IPA dedup that
+# the back-end relies on break across producers.
+_IPA_STORE_EXTENSIONS = (
+    # Image / video / audio
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tiff", ".webp", ".heic",
+    ".mp4", ".mov", ".m4v", ".avi", ".webm",
+    ".mp3", ".m4a", ".aac", ".ogg", ".flac", ".wav",
+    # Archive / asset-catalog / package formats
+    ".zip", ".gz", ".bz2", ".xz", ".7z",
+    ".car",  # Asset catalog
+    ".pdf",
+    # Compiled fonts + binary glyph caches
+    ".woff", ".woff2", ".otf", ".ttf",
+)
+
+# MS-DOS date/time epoch is 1980-01-01; picking a fixed value gives
+# the zip a stable mtime across rebuilds so two archives of identical
+# bits produce byte-identical synthetic IPAs. Mirrors the SDK side
+# (`tools.bundle/BugseeAgent::_IPA_FIXED_MTIME`) and the Android
+# Gradle plugin's `DOS_EPOCH_LOCAL`.
+_IPA_FIXED_MTIME = (1980, 1, 1, 0, 0, 0)
+
+
+def package_app_as_ipa(app_path, output_ipa_path):
+    """Zip `<App>.app` as `Payload/<App>.app/...` into an .ipa.
+
+    Byte-deterministic — entries sorted by name, mtimes pinned. Two
+    runs over the same source tree produce hash-identical output, so
+    the back-end can dedupe re-uploads by content sha. Compression
+    method per-entry: STORE (no recompression) for already-compressed
+    formats (PNG/JPG/MP4/.car/...), DEFLATE for plists / strings /
+    Mach-O / etc. Same posture as the SDK BugseeAgent's
+    `package_app_as_ipa` so artefacts produced by either producer
+    are interchangeable on the back-end.
+
+    DOES NOT add iTunesMetadata.plist or code signing — neither is
+    needed for size analysis (the back-end's `_analyze_bundle` walks
+    `Payload/*.app` and runs the categorisation heuristics off the
+    Mach-O + resource tree only).
+    """
+    with zipfile.ZipFile(output_ipa_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+        for root, dirs, files in os.walk(app_path):
+            # Sort in place so `os.walk` traverses in a deterministic
+            # order — filesystem enumeration is otherwise non-
+            # deterministic (and differs between APFS / HFS+ / NFS).
+            dirs.sort()
+            files.sort()
+            for f in files:
+                src = os.path.join(root, f)
+                if os.path.islink(src):
+                    # Real IPAs don't carry symlinks; zipfile can't
+                    # encode them; skip.
+                    continue
+                rel = os.path.relpath(src, os.path.dirname(app_path))
+                arcname = os.path.join('Payload', rel)
+                method = (
+                    zipfile.ZIP_STORED
+                    if f.lower().endswith(_IPA_STORE_EXTENSIONS)
+                    else zipfile.ZIP_DEFLATED
+                )
+                info = zipfile.ZipInfo(filename=arcname, date_time=_IPA_FIXED_MTIME)
+                info.compress_type = method
+                # Preserve POSIX exec bits on the embedded Mach-O —
+                # otherwise the archive encodes as plain data and the
+                # back-end's executable-detection heuristics (e.g.
+                # "is this the main binary?") lose a signal.
+                try:
+                    st_mode = os.stat(src).st_mode
+                    info.external_attr = (st_mode & 0xFFFF) << 16
+                except OSError:
+                    pass
+                # Stream each file into the archive instead of
+                # `zf.writestr(info, fp.read())` — the latter slurps
+                # the entire source file into a transient bytes
+                # buffer, doubling RSS for every embedded Mach-O. A
+                # 300 MB main binary + 100 MB Swift stdlib + asset
+                # catalogs would peak well over 1 GB on a CI runner
+                # with 4 GB total. `zf.open(info, 'w')` returns a
+                # stream-capable target; copy in 64 KB chunks.
+                # `compress_type` MUST be set on the ZipInfo BEFORE
+                # `zf.open` consumes it (already done above).
+                with open(src, 'rb') as fp, zf.open(info, 'w') as dst:
+                    shutil.copyfileobj(fp, dst, length=65536)
+    return output_ipa_path
+
+
+def _normalise_build_uuid(raw):
+    """Coerce a Mach-O LC_UUID string to the canonical wire format
+    the back-end uses for `crash.uuid → build.uuid` join: 32
+    lowercase hex chars, no dashes, no whitespace. Matches the iOS
+    runtime SDK's `BGSCrashReport.m` shape verbatim. Returns None on
+    empty/whitespace-only input so callers never write a meaningless
+    uuid into the registration payload.
+
+    Used at every uuid-cascade exit point — `_extract_uuid_from_app`
+    (Mach-O), `_extract_first_dwarf_uuid` (dSYM scan via dwarfdump),
+    and the random-fallback in run_artifact_upload_flow (uuid4) —
+    so all three steps produce a single canonical shape regardless
+    of which fallback hit."""
+    if not raw:
+        return None
+    candidate = str(raw).replace('-', '').strip().lower()
+    return candidate or None
+
+
+def _extract_first_dwarf_uuid():
+    """Scan the dSYM folder for the FIRST Mach-O UUID we can find
+    via dwarfdump. The Android plugin sends a single per-build
+    UUID; we mirror that posture by surfacing the main binary's
+    first arch slice UUID (typically arm64). Returns None on any
+    error or if no dSYMs are present.
+
+    Returns the value already normalised through
+    `_normalise_build_uuid` so callers don't need to know whether
+    `parseDSYM`'s underlying tool (bugsee-cli OR dwarfdump fallback)
+    emitted uppercase-hyphenated, lowercase-hyphenated, or
+    lowercase-no-dashes — they all converge here."""
+    folder = options.dsym_folder
+    if not folder or not os.path.isdir(folder):
+        return None
+    for root, dirs, files in os.walk(folder):
+        if not root.endswith('dSYM/Contents/Resources/DWARF'):
+            continue
+        for f in files:
+            full = os.path.join(root, f)
+            if os.path.islink(full) or os.stat(full).st_size == 0:
+                continue
+            uuids = parseDSYM(full)
+            if uuids:
+                return _normalise_build_uuid(uuids[0])
+    return None
+
+
+def _resolve_product_binary_path():
+    """Resolve the path to the linked product binary for the
+    vendored-framework scan. Uses Xcode env vars
+    `EXECUTABLE_PATH` and `TARGET_BUILD_DIR` which together name
+    the exact Mach-O the linker emitted for this build. Returns
+    None when run outside Xcode."""
+    build_dir = os.environ.get('TARGET_BUILD_DIR') or options.build_dir
+    exe_path = os.environ.get('EXECUTABLE_PATH')
+    if not build_dir or not exe_path:
+        return None
+    candidate = os.path.join(build_dir, exe_path)
+    return candidate if os.path.isfile(candidate) else None
+
+
+# ──────────────────────────────────────────────────────────────────
+# Dependency-source discovery
+# ──────────────────────────────────────────────────────────────────
+
+def _find_first_above(start_dir, filename, max_levels=6):
+    """Walk up from `start_dir` looking for `filename`. CocoaPods
+    / SPM / Carthage lockfiles all sit at the project root, which
+    is somewhere ABOVE the Xcode build directory at runtime — the
+    walk-up locates them without the caller having to know the
+    exact relative depth.
+
+    `max_levels` caps the climb so a misconfigured environment
+    can't send us all the way to `/`. Returns the absolute path on
+    hit or None on miss.
+    """
+    if not start_dir:
+        return None
+    current = os.path.abspath(start_dir)
+    for _ in range(max_levels):
+        candidate = os.path.join(current, filename)
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+    return None
+
+
+def _collect_all_dependencies_via_cli(cli_binary, project_root,
+                                       product_binary):
+    """Shell to `bugsee-cli ios-deps collect` and parse the JSON.
+
+    Part of the Option-C migration that moved iOS dep parsing to
+    the Rust CLI as the single canonical implementation. The
+    in-process Python parsers below are preserved as a cold-start
+    fallback when the CLI isn't available.
+
+    Returns `(entries, scope_label, truncated)` on success or
+    `None` on any failure (subprocess error, malformed JSON,
+    non-zero exit). The caller falls back to the Python
+    implementation on None.
+    """
+    if not cli_binary or not project_root:
+        return None
+    cmd = [cli_binary, "ios-deps", "collect",
+           "--project-root", project_root]
+    if product_binary:
+        cmd.extend(["--product-binary", product_binary])
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True,
+            timeout=30, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        if not out:
+            return None
+        data = json.loads(out)
+        # Shape validation (parity with the SDK side and the dsym
+        # helper). A future CLI shape change — accidental `"entry"`
+        # rename, list-instead-of-dict, non-string ids — must
+        # surface as "fall back to Python parsers" rather than
+        # crashing in `_build_dependencies_payload` further down
+        # the pipeline.
+        if not isinstance(data, dict):
+            return None
+        raw_entries = data.get("entries")
+        if not isinstance(raw_entries, list):
+            return None
+        entries = [e for e in raw_entries if isinstance(e, dict)
+                                            and isinstance(e.get("id"), str)]
+        return (
+            entries,
+            data.get("scope_label") or "all",
+            bool(data.get("truncated")),
+        )
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
+def _collect_all_dependencies(project_root):
+    """Run every parser against the project root and return the
+    merged entry list plus the `(scope_label, truncated)` tuple
+    the payload builder needs.
+
+    `project_root` is the directory we walk up from to find each
+    source lockfile. In an Xcode build that's `SRCROOT` (or
+    `$PROJECT_DIR`); outside Xcode (CLI testing) the caller passes
+    the project root explicitly.
+
+    Implementation: prefers `bugsee-cli ios-deps collect` (the
+    single cross-language source of truth, ported from these
+    Python parsers — see `bugsee-cli/src/cli/ios_deps.rs`). Falls
+    back to the in-process Python parsers below when the CLI
+    isn't available. Same migration pattern the VCS resolver
+    landed first.
+    """
+    # Resolve binary path up-front — needed for both CLI invocation
+    # (`--product-binary <path>`) and the Python fallback.
+    binary = _resolve_product_binary_path()
+
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if cli:
+        via_cli = _collect_all_dependencies_via_cli(cli, project_root, binary)
+        if via_cli is not None:
+            return via_cli
+
+    podfile = _find_first_above(project_root, 'Podfile.lock')
+    package_resolved = (
+        _find_first_above(project_root, 'Package.resolved')
+        # SPM CLI writes Package.resolved at the package root, but
+        # Xcode-managed projects keep one under
+        # `*.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/`.
+        # Search for that variant too if the top-level miss.
+        or _find_first_above(project_root,
+                             os.path.join('xcshareddata', 'swiftpm',
+                                          'Package.resolved'))
+    )
+    cartfile = _find_first_above(project_root, 'Cartfile.resolved')
+
+    pods_entries = _parse_podfile_lock(podfile) if podfile else []
+    spm_entries  = _parse_package_resolved(package_resolved) if package_resolved else []
+    cart_entries = _parse_cartfile_resolved(cartfile) if cartfile else []
+    vendored_entries = _parse_vendored_frameworks(binary) if binary else []
+
+    merged, truncated = _merge_dep_entries(
+        pods_entries, spm_entries, cart_entries, vendored_entries,
+    )
+    # `scope` here describes the COLLECTION scope (Android plugin
+    # uses 'runtime' / 'runtime_direct_only'). iOS doesn't have
+    # that distinction; surface 'all' so the worker's
+    # compatibility check still has a stable token to compare
+    # against across builds.
+    return merged, "all", truncated
+
+
+# ──────────────────────────────────────────────────────────────────
+# Bugsee API client (build registration + presigned upload)
+# ──────────────────────────────────────────────────────────────────
+
+def _request_build_registration(app_token, endpoint, body_json):
+    """POST the build registration body to /v2/apps/{token}/builds
+    and return the unwrapped result payload (the inner `result`
+    object the appserver wraps every v2 response in). Returns None
+    on any error — callers fall back to skipping the deps upload
+    step.
+
+    Response shape from the appserver:
+      success: {"ok": true, "result": { <payload> }}
+      failure: {"ok": false, "error": { "type": ..., "message": ... }}
+
+    The Android plugin's `ApiEndpoint.unwrapResult` performs the
+    same unwrap; we mirror its posture so the caller sees a flat
+    payload regardless of platform.
+    """
+    url = endpoint.rstrip('/') + '/v2/apps/' + urllib.parse.quote(app_token) + '/builds'
+    try:
+        req = urllib.request.Request(
+            url, data=body_json.encode('utf-8'),
+            headers={'Content-Type': 'application/json'},
+            method='POST',
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            raw = json.loads(resp.read().decode('utf-8'))
+    except (urllib.error.URLError, urllib.error.HTTPError,
+            ValueError, OSError) as e:
+        print("Bugsee: build registration failed: %s" % e)
+        return None
+
+    # Unwrap `{ok, result}` envelope. `ok: false` is surfaced as a
+    # logged error and None return so the caller can short-circuit.
+    if not isinstance(raw, dict):
+        print("Bugsee: build registration: unexpected response type %s"
+              % type(raw).__name__)
+        return None
+    if raw.get('ok') is False:
+        err = raw.get('error') or {}
+        if isinstance(err, dict):
+            print("Bugsee: build registration rejected: %s (%s)"
+                  % (err.get('message', '(no message)'), err.get('type', '?')))
+        else:
+            print("Bugsee: build registration rejected (no error detail).")
+        return None
+    result = raw.get('result')
+    if isinstance(result, dict):
+        return result
+    # Some appserver routes return a flat payload without the
+    # `{ok, result}` envelope (legacy endpoints). Return the raw
+    # dict in that case so we don't lose information.
+    return raw
+
+
+def _put_dependencies_blob(endpoint_url, gz_bytes):
+    """PUT the gzipped deps JSON to the presigned URL the appserver
+    returned. Matches the Android plugin's signing posture:
+    `Content-Type: application/octet-stream`, no Content-Encoding
+    header on the producer PUT (the worker sets it when moving
+    bytes to the store bucket). Returns True on success.
+    """
+    try:
+        req = urllib.request.Request(
+            endpoint_url, data=gz_bytes,
+            headers={
+                'Content-Type': 'application/octet-stream',
+                # Precise Content-Length so urllib doesn't fall back
+                # to chunked transfer-encoding (which S3 presigned
+                # PUT signatures don't accept — the worker would see
+                # the body but the signature check 403s). The sibling
+                # `_put_timings_blob` and `_put_artifact_blob` both
+                # set this explicitly; this helper used to rely on
+                # urllib's auto-derive which works on most paths but
+                # was inconsistent with the documented S3 signing
+                # posture.
+                'Content-Length': str(len(gz_bytes)),
+            },
+            method='PUT',
+        )
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            status = getattr(resp, 'status', 200)
+            return 200 <= status < 300
+    except (urllib.error.URLError, urllib.error.HTTPError, OSError) as e:
+        print("Bugsee: dependencies upload failed: %s" % e)
+        return False
+
+
+def _put_timings_blob(url, gz_bytes, debug=False):
+    """Best-effort PUT of the gzipped per-task timeline DETAIL blob to
+    the presigned `timings_upload_endpoint` the metadata POST returned.
+
+    Mirrors `_put_dependencies_blob` exactly — independent of the
+    artefact upload, runs on the build-info-only path too, never
+    raises (a failed PUT degrades to "no Gantt chart for this build"
+    and must not break the user's archive flow). Returns True on a
+    2xx, False otherwise.
+
+    `Content-Type` is hard-set to `application/octet-stream` because
+    the back-end signs the presigned URL over exactly that value —
+    S3 403s the PUT on any Content-Type mismatch.
+    """
+    if not url or not gz_bytes:
+        return False
+    try:
+        put_req = urllib.request.Request(url, data=gz_bytes, method='PUT')
+        # Precise Content-Length so the signed request body-length
+        # matches; chunked transfer-encoding breaks S3 presigned PUTs.
+        put_req.add_header('Content-Length', str(len(gz_bytes)))
+        put_req.add_header('Content-Type', 'application/octet-stream')
+        with urllib.request.urlopen(put_req, timeout=120) as resp:
+            status = resp.status
+    except urllib.error.HTTPError as e:
+        print("Bugsee: timings PUT failed (HTTP %d)" % e.code)
+        return False
+    except Exception as e:
+        print("Bugsee: timings PUT network error: %s" % e)
+        return False
+
+    if 200 <= status < 300:
+        if debug:
+            print("Bugsee: timings blob uploaded (%d bytes, HTTP %d)"
+                  % (len(gz_bytes), status))
+        return True
+    print("Bugsee: timings PUT unexpected status: %d" % status)
+    return False
+
+
+def _put_artifact_blob(url, ipa_path, debug=False):
+    """Best-effort PUT of the .ipa bytes to the presigned
+    `endpoint` the metadata POST returned.
+
+    Streams from disk instead of slurping into memory — modern iOS
+    apps can exceed 300 MB once extensions + assets are included,
+    and macOS CI runners have modest memory budgets.
+
+    `Content-Type` is hard-set to `application/octet-stream`
+    (matches the SDK BugseeAgent's upload_build posture; the
+    back-end signs the presigned URL over exactly that content
+    type, so S3 403s on any mismatch). `Content-Length` is
+    pre-computed because urllib's default chunked transfer-encoding
+    breaks S3 presigned PUT signatures.
+    """
+    if not url or not ipa_path:
+        return False
+    try:
+        ipa_size = os.path.getsize(ipa_path)
+    except OSError as e:
+        print("Bugsee: could not stat artefact for upload: %s" % e)
+        return False
+    try:
+        with open(ipa_path, 'rb') as fp:
+            put_req = urllib.request.Request(url, data=fp, method='PUT')
+            put_req.add_header('Content-Length', str(ipa_size))
+            put_req.add_header('Content-Type', 'application/octet-stream')
+            with urllib.request.urlopen(put_req, timeout=600) as resp:
+                status = resp.status
+    except urllib.error.HTTPError as e:
+        print("Bugsee: artefact PUT failed (HTTP %d)" % e.code)
+        return False
+    except Exception as e:
+        print("Bugsee: artefact PUT network error: %s" % e)
+        return False
+
+    if 200 <= status < 300:
+        if debug:
+            print("Bugsee: artefact uploaded (%d bytes, HTTP %d)"
+                  % (ipa_size, status))
+        return True
+    print("Bugsee: artefact PUT unexpected status: %d" % status)
+    return False
+
+
+def run_artifact_upload_flow(app_token, endpoint, app_path,
+                             version=None, build_number=None,
+                             request_artifact_upload=True,
+                             debug=False):
+    """Package an `.app` into a synthetic `.ipa` and upload it to
+    Bugsee for size analysis. Mirrors the SDK BugseeAgent's
+    `run_size_analysis_flow` minus the chunked-upload opt-in and
+    the in-build size-check evaluation (those can land in a
+    follow-up).
+
+    Returns True on overall success (build registered AND, when
+    requested, artefact bytes shipped); False on any failure.
+
+    `request_artifact_upload=False` flips this into a build-info-
+    only registration that records the artefact_size on the
+    server WITHOUT shipping the bytes — useful for firewalled CI
+    or privacy-sensitive setups where the dashboard's size-trend
+    chart is enough.
+    """
+    if not app_path or not os.path.isdir(app_path):
+        print("Bugsee: --app-path is required and must be a directory; got %r"
+              % app_path)
+        return False
+    if not app_path.endswith('.app'):
+        print("Bugsee: --app-path must end in .app; got %r" % app_path)
+        return False
+
+    temp_dir = tempfile.mkdtemp(prefix='bugsee-artifact-')
+    try:
+        # Resolve Info.plist provenance BEFORE packaging — we want
+        # `package_id` + `version` + `build` on the registration
+        # payload so the back-end's /builds/baseline lookup keys on
+        # the same triple the SDK side uses. Otherwise every fastlane-
+        # registered build lives in its own bucket and the size-trend
+        # chart never finds a delta.
+        bundle_id, plist_version, plist_build = resolve_bundle_info_from_app(app_path)
+        # Caller-supplied args override the plist (a CI step may want
+        # to label a build differently from what Xcode wrote in).
+        effective_version = version or plist_version
+        effective_build = build_number or plist_build
+
+        # Sanitise the .ipa filename stem against path-traversal — the
+        # bundle id / app name flow from Info.plist values we read but
+        # don't fully validate.
+        stem = bundle_id or os.path.basename(app_path)[:-4] or 'build'
+        safe_stem = re.sub(r'[^A-Za-z0-9._-]', '_', os.path.basename(stem))
+        ipa_path = os.path.join(temp_dir, '%s.ipa' % (safe_stem or 'build'))
+        print("Bugsee: packaging %s → %s"
+              % (os.path.basename(app_path), ipa_path))
+        package_app_as_ipa(app_path, ipa_path)
+
+        try:
+            artifact_size = os.path.getsize(ipa_path)
+        except OSError:
+            artifact_size = 0
+
+        # Build the registration payload. Mirrors the SDK's
+        # `run_size_analysis_flow` payload shape so the back-end's
+        # `_register_build` route treats both producers identically.
+        payload = {
+            'format': 'ipa',
+            'request_artifact_upload': bool(request_artifact_upload),
+        }
+        if bundle_id:
+            # `package_id` is one of the back-end's baseline lookup
+            # keys. Without it the dashboard size-trend chart never
+            # finds a baseline for this build's family.
+            payload['package_id'] = bundle_id
+        if effective_version:
+            payload['version'] = effective_version
+        if effective_build:
+            payload['build'] = effective_build
+        if artifact_size > 0:
+            payload['artifact_size'] = artifact_size
+        # $CONFIGURATION is set by Xcode in build phases and by
+        # `xcodebuild` invocations; the second baseline-lookup key
+        # the back-end consumes. Optional — when absent, the back-end
+        # treats it as the implicit "Release" bucket.
+        config = (os.environ.get('CONFIGURATION') or '').strip()
+        if config:
+            payload['build_configuration'] = config
+
+        # `uuid` is the build identifier the back-end uses to join
+        # crashes to this build (`crash.uuid → build`). Resolution
+        # cascade matches the SDK's posture:
+        #   1. Main executable's Mach-O LC_UUID (deterministic per
+        #      linker invocation; the same value the runtime reports).
+        #   2. First dwarf UUID from the legacy dSYM scan (when the
+        #      fastlane lane runs the dSYM upload action in the same
+        #      invocation, options.dsym_folder is set).
+        #   3. uuid.uuid4() — pure random fallback. The build record
+        #      is still useful for the size-trend chart but crash-
+        #      to-build join is best-effort in this case.
+        # All cascade exits funnel through `_normalise_build_uuid`
+        # so the registration payload's `uuid` is always the canonical
+        # 32-char lowercase-no-dash shape the back-end joins on.
+        # `_extract_uuid_from_app` and `_extract_first_dwarf_uuid`
+        # both already normalise on their way out (#2/#4/#11 fix);
+        # the random fallback also goes through the helper for the
+        # same reason.
+        build_uuid = _extract_uuid_from_app(app_path)
+        if not build_uuid:
+            try:
+                build_uuid = _extract_first_dwarf_uuid()
+            except NameError:
+                build_uuid = None
+        if not build_uuid:
+            build_uuid = _normalise_build_uuid(str(uuid.uuid4()))
+        payload['uuid'] = build_uuid
+
+        # VCS metadata (best-effort). Resolves via bugsee-cli when on
+        # PATH, falls back to in-process Python otherwise. Guard
+        # against the same `options`-NameError window as the dSYM
+        # UUID extraction above (resolve_vcs_metadata's CLI path may
+        # consult `options.cli_path` / `options.cli_version`).
+        try:
+            vcs = resolve_vcs_metadata(os.getcwd())
+        except NameError:
+            vcs = None
+        if vcs:
+            payload['vcs'] = vcs
+
+        if debug:
+            print("Bugsee: artefact registration payload = %s"
+                  % json.dumps(payload))
+
+        result = _request_build_registration(
+            app_token, endpoint, json.dumps(payload))
+        if result is None:
+            return False
+
+        if not request_artifact_upload:
+            # Build-info-only path: nothing more to ship. The server
+            # recorded artifact_size for the size-trend chart.
+            if debug:
+                print("Bugsee: build-info-only registration complete")
+            return True
+
+        presigned = result.get('endpoint') if isinstance(result, dict) else None
+        if not presigned:
+            print("Bugsee: build registration returned no presigned endpoint")
+            return False
+
+        return _put_artifact_blob(presigned, ipa_path, debug=debug)
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def _upload_build_info_bundle(upload_url, deps_gz, timings_gz):
+    """Ship the build-info components as ONE zstd bundle via
+    `bugsee-cli upload build-info --upload-url <url>` (pre-signed mode:
+    the plugin already registered the build, so the CLI just PUTs).
+
+    `deps_gz` / `timings_gz` are the gzipped per-blob payloads; they're
+    gunzipped here because the bundle's `dependencies.json` /
+    `timings.json` entries carry RAW JSON (the CLI does the zstd packing
+    and the worker re-gzips on store, so the stored bytes match the legacy
+    per-blob path). At least one must be non-None.
+
+    Returns True on success. Returns False on ANY failure — including no
+    resolvable CLI — so the caller falls back to the legacy per-blob gzip
+    PUTs, which target independent presigned URLs (an independent upload
+    mechanism, so retrying them is worthwhile even on a substantive
+    bundle failure).
+    """
+    cli = resolveCli(getattr(options, 'cli_path', None),
+                     getattr(options, 'cli_version', None))
+    if not cli:
+        return False
+    tmpdir = tempfile.mkdtemp(prefix='bugsee-build-info-')
+    try:
+        argv = [cli, "upload", "build-info", "--upload-url", upload_url]
+        if deps_gz is not None:
+            deps_path = os.path.join(tmpdir, "dependencies.json")
+            with open(deps_path, 'wb') as fp:
+                fp.write(gzip.decompress(deps_gz))
+            argv += ["--deps", deps_path]
+        if timings_gz is not None:
+            timings_path = os.path.join(tmpdir, "timings.json")
+            with open(timings_path, 'wb') as fp:
+                fp.write(gzip.decompress(timings_gz))
+            argv += ["--timings", timings_path]
+        result = subprocess.run(
+            argv, capture_output=True, text=True, timeout=120, check=False)
+        stderr = (result.stderr or '').strip()
+        if stderr:
+            print("Bugsee: bugsee-cli output:\n%s" % stderr)
+        return result.returncode == 0
+    except _CLI_CATCHALL_EXCEPTIONS as e:
+        print("Bugsee: build-info bundle CLI invocation failed: %s" % e)
+        return False
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def _run_dependencies_pipeline(app_token, project_root):
+    """Top-level driver wired into [main] when --deps is enabled.
+
+    Collects + uploads the project's dependency graph AND the
+    build's xcactivitylog-derived timings (when available) in ONE
+    build-registration round-trip. Both pieces of data are
+    optional — if neither produced useful output the function
+    short-circuits before the network call. Otherwise the
+    registration POST carries:
+
+      - `build_metadata.timings`  — inline summary (total_ms,
+        category sums, top tasks); always present when the
+        xcactivitylog was found.
+      - `dependencies_summary`   — total/direct/transitive counts,
+        collection_config; present when at least one lockfile
+        parsed.
+
+    The server responds with up to two presigned PUT endpoints:
+
+      - `dependencies_upload_endpoint` — for the full deps blob.
+      - `timings_upload_endpoint`      — for the full per-task
+        Gantt-detail blob.
+
+    Each PUT is best-effort and independent: a failed deps PUT
+    does NOT skip the timings PUT, and vice versa. The function
+    returns True only when registration succeeded AND every
+    attempted PUT succeeded; partial failures return False but
+    don't raise.
+
+    Failures here MUST NOT block the existing symbols-upload
+    step — both pipelines are independent.
+    """
+    # Per-feature gating. Each side of the cross-producer
+    # handshake decides independently whether THIS agent should
+    # contribute deps / timings — see the --no-deps / --no-timings
+    # OptionParser entries. The fastlane Ruby action sets these
+    # flags based on the manifest the iOS SDK's BugseeAgent build
+    # phase emitted (or didn't) for this build.
+    collect_deps    = getattr(options, 'collect_deps',    True)
+    collect_timings = getattr(options, 'collect_timings', True)
+
+    if collect_deps:
+        entries, scope_label, truncated = _collect_all_dependencies(project_root)
+    else:
+        entries, scope_label, truncated = [], 'all', False
+
+    if collect_timings:
+        timings_summary, timings_gz = resolve_build_timings(os.environ)
+    else:
+        timings_summary, timings_gz = None, None
+
+    have_deps    = bool(entries)
+    have_timings = timings_summary is not None
+
+    if not have_deps and not have_timings:
+        print("Bugsee: no dependency sources found and no build timings "
+              "available; skipping build-info upload.")
+        return False
+
+    body = _collect_build_metadata()
+    # Guard against writing `"uuid": null` into the POST body when the
+    # dSYM scan yields nothing (e.g. a lane that ships build-info-only
+    # with no dSYMs alongside). The historic assignment unconditionally
+    # set the value, leaking the None into the JSON.
+    #
+    # `_extract_first_dwarf_uuid` now normalises through
+    # `_normalise_build_uuid` on its way out (lifted from the per-
+    # callsite normalisation that used to live only in
+    # run_artifact_upload_flow), so `dwarf_uuid` here is already the
+    # canonical 32-char lowercase-no-dash shape the back-end joins on.
+    dwarf_uuid = _extract_first_dwarf_uuid()
+    if dwarf_uuid:
+        body["uuid"] = dwarf_uuid
+    body["request_artifact_upload"]      = False
+    body["request_dependencies_upload"]  = have_deps
+    body["request_timings_upload"]       = timings_gz is not None
+    # Opt into the converged build-info bundle (Phase D). The server only
+    # signs a build_info_upload_endpoint when the org's
+    # BUGSEE_FEATURE_BUILD_INFO_BUNDLE_ENABLED flag is on; the deps/timings
+    # flags above stay set so the legacy path remains available for
+    # fallback (and for non-flagged orgs) during the soak.
+    body["request_build_info_upload"]    = have_deps or have_timings
+
+    deps_blob_gz = None
+    if have_deps:
+        deps_summary, deps_blob = _build_dependencies_payload(
+            entries, truncated, scope_label,
+            include_selected_reason=False,
+            max_count=DEPENDENCIES_MAX_COUNT,
+        )
+        body["dependencies_summary"] = deps_summary
+        deps_blob_gz = _gzip_json_bytes(deps_blob)
+
+    if have_timings:
+        # Inline timings summary lives under build_metadata so the
+        # server-side rollup (total_ms, top tasks, category sums)
+        # is available without fetching the detail blob. The blob
+        # itself is uploaded separately via the presigned URL.
+        body.setdefault("build_metadata", {})["timings"] = timings_summary
+
+    response = _request_build_registration(
+        app_token, options.endpoint, json.dumps(body))
+    if not response:
+        return False
+
+    # Build-info bundle (Phase D): when the server signed a
+    # build_info_upload_endpoint (the org is flagged on), the escape hatch
+    # is off, and a CLI resolves, ship deps+timings as ONE zstd bundle via
+    # `bugsee-cli upload build-info` instead of the two legacy gzip PUTs.
+    # Fails closed — any miss/failure falls through to the legacy PUTs.
+    build_info_endpoint = response.get('build_info_upload_endpoint')
+    if (build_info_endpoint
+            and not _env_truthy(os.environ.get('BUGSEE_LEGACY_BUILDINFO_GZIP'))
+            and (have_deps or have_timings)):
+        if _upload_build_info_bundle(
+                build_info_endpoint, deps_blob_gz, timings_gz):
+            print("Bugsee: build-info bundle uploaded via bugsee-cli.")
+            return True
+        print("Bugsee: build-info bundle unavailable/failed; falling back "
+              "to legacy per-blob upload.")
+
+    overall_ok = True
+
+    if have_deps and deps_blob_gz is not None:
+        deps_endpoint = response.get('dependencies_upload_endpoint')
+        if not deps_endpoint:
+            print("Bugsee: server did not return a dependencies upload "
+                  "endpoint — skipping deps PUT.")
+            overall_ok = False
+        else:
+            print("Bugsee: uploading dependencies blob (%d entries, "
+                  "%d bytes gzipped)"
+                  % (len(entries), len(deps_blob_gz)))
+            if not _put_dependencies_blob(deps_endpoint, deps_blob_gz):
+                overall_ok = False
+
+    if timings_gz is not None:
+        timings_endpoint = response.get('timings_upload_endpoint')
+        if not timings_endpoint:
+            # Older appservers may not surface the timings endpoint
+            # yet — the inline summary still landed via the POST,
+            # so this isn't a hard failure.
+            print("Bugsee: server did not return a timings upload "
+                  "endpoint — inline summary kept; per-task detail "
+                  "blob skipped.")
+        else:
+            print("Bugsee: uploading build timings blob (%d bytes gzipped)"
+                  % len(timings_gz))
+            if not _put_timings_blob(timings_endpoint, timings_gz):
+                overall_ok = False
+
+    return overall_ok
+
+
 def isInUploadedList(images, imageList):
     for image in images:
         if (image in imageList):
@@ -49,7 +2494,55 @@ def loadUploadedList():
     except Exception as error:
         return []
 
+def _parse_dsym_via_cli(fullPath):
+    """Shell to `bugsee-cli dsym uuid <path>` for the UUID list.
+    Returns a list of UUID strings on success, or None on any
+    failure. Part of the Option-C migration that moved dSYM UUID
+    extraction to the Rust CLI (which keys off
+    `symbolic-debuginfo`'s Mach-O parser — no `/usr/bin/dwarfdump`
+    dependency)."""
+    if not fullPath:
+        return None
+    cli_path_opt = None
+    cli_version_opt = None
+    try:
+        cli_path_opt = getattr(options, 'cli_path', None)
+        cli_version_opt = getattr(options, 'cli_version', None)
+    except NameError:
+        pass
+    cli = resolveCli(cli_path_opt, cli_version_opt)
+    if not cli:
+        return None
+    try:
+        result = subprocess.run(
+            [cli, "dsym", "uuid", fullPath],
+            capture_output=True, text=True, timeout=30, check=False,
+        )
+        if result.returncode != 0:
+            return None
+        out = (result.stdout or "").strip()
+        if not out:
+            return None
+        data = json.loads(out)
+        if not isinstance(data, list):
+            return None
+        # Each entry must be a UUID string.
+        return [str(u) for u in data if isinstance(u, str)]
+    except _CLI_CATCHALL_EXCEPTIONS:
+        return None
+
+
 def parseDSYM(fullPath):
+    """Extract Mach-O UUIDs from a dSYM bundle or Mach-O binary.
+
+    Prefers `bugsee-cli dsym uuid` (canonical Rust implementation;
+    no /usr/bin/dwarfdump dependency). Falls back to the in-
+    process dwarfdump shell-out below when the CLI isn't
+    available."""
+    via_cli = _parse_dsym_via_cli(fullPath)
+    if via_cli is not None:
+        return via_cli
+
     images = []
     try:
         out = subprocess.run(['/usr/bin/dwarfdump', '-u', fullPath], check=True, capture_output=True, text=True).stdout
@@ -73,43 +2566,29 @@ def deobfuscateDSYM(fullPath, mapsPath):
         return
     return
 
-def getIcon():
-    if not options.from_xcode:
-        # No icon extraction when run outside of XCode
-        # TODO: Get it from fastlane if we run after build?
-        return None
-    try:
-        info_file_path = os.path.join(options.build_dir, os.environ['INFOPLIST_PATH'])
-        info_file_dir = os.path.dirname(info_file_path)
-        # p = subprocess.Popen('/usr/libexec/PlistBuddy -c "Print :CFBundleIcons:CFBundlePrimaryIcon:CFBundleIconFiles" %s' % info_file_path,
-        #                  stdout=subprocess.PIPE, shell=True)
-
-        # stdout, stderr = p.communicate()
-        # icons = stdout.split()
-        # if len(icons) > 4:
-        #     return icons[2:-1]
-        icons = [   
-                    '114x114',
-                    '120x120', 'AppIcon60x60@2x', 'AppIcon40x40@3x',
-                    '144x144',
-                    '180x180', 'AppIcon60x60@3x',
-                    '87x87', 'AppIcon29x29@3x',
-                    '80x80', 'AppIcon40x40@2x',
-                    '72x72',
-                    '58x58', 'AppIcon29x29@2x',
-                    '57x57',
-                    '29x29'
-                ]
-
-        for icon in icons:
-            path = os.path.join(info_file_dir, icon + '.png')
-            if os.path.isfile(path):
-                return path
-
-    except Exception as error:
-        return None
+# Note on app icon attachment (removed in 1.1.0):
+#
+# The legacy upload pipeline shipped the Xcode-uncrushed launcher
+# PNG inside the dSYM zip; the worker's symbols job extracted
+# `icon.png` from the bundle root and called `icons.store_icon(...,
+# 'build', ...)` (see worker/jobs/symbols.py). Two helpers — getIcon
+# and uncrushIcon (running `xcrun pngcrush -revert-iphone-
+# optimizations`) — produced that PNG.
+#
+# bugsee-cli's --type dsym path takes no --icon (the CLI rejects it
+# at parse-time; see bugsee-cli/src/cli/debug_files.rs), so the
+# build-extraction code path is dead. The dashboard falls back to
+# the worker's appstore fetch (icon.source='appstore') for any app
+# that's published on the App Store, but enterprise / TestFlight /
+# internal builds now render without an icon until icon attachment
+# is re-wired into the build registration body
+# (`_request_build_registration` would be the place).
+#
+# The legacy helpers are removed here rather than left as comments
+# because git history preserves them — searching for getIcon /
+# uncrushIcon in the log of this file surfaces the exact 1.0.4
+# implementation if someone needs to re-introduce it.
 
-    return None
 
 def getVersionAndBuild(zipFile):
     version = None
@@ -122,8 +2601,20 @@ def getVersionAndBuild(zipFile):
     else:
         try:
             info_file_path = os.path.join(options.build_dir, os.environ['INFOPLIST_PATH'])
-            cmd = '/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" -c "Print :CFBundleVersion" "' + info_file_path + '"'
-            p = subprocess.Popen([cmd], stdout=subprocess.PIPE, shell=True)
+            # Argv list — never shell=True. The PlistBuddy invocation
+            # used to be `subprocess.Popen([cmd], shell=True)` with the
+            # info_file_path concatenated into the command string,
+            # which broke quoting on any project path containing a
+            # quote/apostrophe AND opened a shell-injection sink if
+            # INFOPLIST_PATH or build_dir came from an attacker-
+            # controlled env var. The list form bypasses the shell
+            # entirely; quoting is no longer the script's problem.
+            p = subprocess.Popen([
+                '/usr/libexec/PlistBuddy',
+                '-c', 'Print :CFBundleShortVersionString',
+                '-c', 'Print :CFBundleVersion',
+                info_file_path,
+            ], stdout=subprocess.PIPE)
             stdout, stderr = p.communicate()
             version, build = stdout.decode().split()
         except Exception as error:
@@ -131,19 +2622,6 @@ def getVersionAndBuild(zipFile):
 
     return (version, build)
 
-def uncrushIcon(icon, tempDir):
-    try:
-        dest = os.path.join(tempDir, 'icon.png')
-        print("Uncrushing Icon PNG file to %s" % dest)
-        cmd = '/usr/bin/xcrun pngcrush -revert-iphone-optimizations "'+ icon + '" "' + dest + '"'
-        p = subprocess.Popen([cmd], stdout=subprocess.PIPE, shell=True)
-
-        stdout, stderr = p.communicate()
-    except Exception as error:
-        return None
-
-    return dest
-
 def requestEndPoint(version, build):
     encoded_data = json.dumps({
         'version': version,
@@ -159,16 +2637,21 @@ def requestEndPoint(version, build):
     return json.loads(text.decode())
 
 def uploadBundle(endpoint, filePath):
-    # TODO: Change it to urllib2 as well
-    cmd = 'curl -v -T "' + filePath + '" "' + endpoint + '"' + ' --write-out %{http_code} --silent --output /dev/null'
-    p = subprocess.Popen([cmd], 
-                         stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=True)
-    stdout, stderr = p.communicate()
-    code = stdout.decode()
-    if code == '200':
-        return True
-
-    return False
+    # PUT the file via urllib instead of shelling to curl. The
+    # original `curl -v -T "<filePath>" "<endpoint>"` was constructed
+    # by string concatenation and passed to `subprocess.Popen([cmd],
+    # shell=True)` — broken on any filePath/endpoint containing
+    # quotes and a shell-injection sink for the server-returned
+    # endpoint URL. urllib was already imported for adjacent
+    # uploadStatus/requestEndPoint calls; reuse it.
+    try:
+        with open(filePath, 'rb') as f:
+            data = f.read()
+        req = urllib.request.Request(endpoint, data=data, method='PUT')
+        with urllib.request.urlopen(req) as resp:
+            return 200 <= resp.status < 300
+    except Exception:
+        return False
 
 def updateStatus(symbolId):
     encoded_data = json.dumps({
@@ -206,13 +2689,848 @@ def uploadZipFile(zipFileLocation):
 
     return False
 
+# ──────────────────────────────────────────────────────────────────
+# Build timings via xcactivitylog (ported from SDK BugseeAgent)
+#
+# Parses Xcode's .xcactivitylog (SLF0-compressed binary format) to
+# extract per-task durations + category rollups for the build
+# registration's `build_metadata.timings` sub-object. Same schema
+# the Android Gradle plugin's BuildTimingService emits, so the
+# back-end renders iOS and Android timings from one wire shape.
+# ──────────────────────────────────────────────────────────────────
+
+_SLF_SECTION_CLASS = 'IDEActivityLogSection'
+_SLF_COMMAND_CLASS = 'IDEActivityLogCommandInvocationSection'
+_SLF_SECTION_CLASSES = frozenset((_SLF_SECTION_CLASS, _SLF_COMMAND_CLASS))
+
+# SLF token delimiters. The three LENGTH-PREFIXED forms (`"` string,
+# `%` className-def, `*` JSON/data blob) carry a DECIMAL length whose
+# raw bytes follow; the rest are SIMPLE (`#` hex int, `^` hex double,
+# `@` hex classRef, `(` array/object element count, `-` null).
+_SLF_LEN_PREFIXED = b'"%*'
+_SLF_SIMPLE = b'#^@(-'
+_SLF_DELIMS = frozenset(_SLF_LEN_PREFIXED + _SLF_SIMPLE)
+_SLF_LEN_PREFIXED_SET = frozenset(_SLF_LEN_PREFIXED)
+
+
+# Per-category title classifier for iOS build events. Wire shape is
+# the same as the Android Gradle plugin's (`managed_code_ms` /
+# `native_ms` / `resources_ms` / `packaging_ms` / `other_ms`) so
+# back-end + front-end render both platforms from a single schema.
+# Semantic mapping for iOS:
+#
+#   managed_code_ms → never emitted on iOS. Reserved for JVM-
+#                     bytecode pipelines (kotlinc / javac / R8 /
+#                     desugar) on Android. Everything iOS compiles
+#                     is native code — Swift, Obj-C, C and C++ all
+#                     flow through clang/swiftc into the Mach-O.
+#   native_ms       → Swift + Obj-C + C/C++ compile units, Swift
+#                     module planning / emission / clang module
+#                     building. Dominates almost every iOS build.
+#                     Matches the Android semantic (JNI/C++ compile
+#                     via CMake / NDK lands in `native_ms` there).
+#   resources_ms    → asset catalogs, storyboards, xibs, strings,
+#                     plist processing, resource copies.
+#   packaging_ms    → linking, code signing, framework embedding,
+#                     strip, touch, dSYM generation, Swift stdlib
+#                     embedding (conceptually "get the runtime into
+#                     the bundle").
+#   other_ms        → build-graph dependency computation, tool
+#                     version discovery, auxiliary file generation,
+#                     Swift Package Manager resolution steps — the
+#                     scaffolding that isn't otherwise classified.
+#                     Typically <1% on a simple app build; SPM-heavy
+#                     projects can push this higher as `Computing
+#                     package information` / `Copying Package.resolved`
+#                     / `Resolve Package Graph` all land in this
+#                     bucket.
+#
+# Wrapper prefixes filter FIRST so container sections contribute to
+# no category; within the remaining rules, precedence is native →
+# resources → packaging (each list is checked in order and the
+# first match wins).
+_XCACTIVITYLOG_CATEGORY_NATIVE_PATTERNS = (
+    # Per-source compile events: "Compile Foo.swift (arm64)", etc.
+    re.compile(r'^Compile \S+\.(swift|m|mm|c|cpp|cxx|cc)\b', re.IGNORECASE),
+    re.compile(r'^CompileSwiftSources\b'),
+    re.compile(r'^CompileC\b'),
+    re.compile(r'^CompileSwift\b'),
+    # Swift toolchain phases — planning / driver / module emission.
+    re.compile(r'^Planning Swift module\b'),
+    re.compile(r'^SwiftDriver\b'),
+    re.compile(r'^Emit(?:ting)? [Ss]wift [Mm]odule\b'),
+    re.compile(r'^Emitting module for\b'),
+    re.compile(r'^SwiftMergeGeneratedHeaders\b'),
+    re.compile(r'^SwiftVerifyEmittedModuleInterface\b'),
+    re.compile(r'^Generate Swift Constant Values\b'),
+    # Explicit module / Clang module builds pulled into Swift.
+    # NOTE: `^Compiling Clang module` is also special-cased in
+    # `_classify_section_title` ahead of the wrapper check — the
+    # `Compiling ` wrapper prefix would otherwise intercept it.
+    re.compile(r'^Compiling Clang module\b'),
+    re.compile(r'^Precompile module\b'),
+    re.compile(r'^Explicitly Built\b'),
+    re.compile(r'^Discovering version info for swiftc\b'),
+    re.compile(r'^Extract app intents metadata\b', re.IGNORECASE),
+)
+_XCACTIVITYLOG_CATEGORY_RESOURCES_PATTERNS = (
+    re.compile(r'^Compile asset catalog', re.IGNORECASE),
+    re.compile(r'^CompileAssetCatalog\b'),
+    re.compile(r'^CompileStoryboard\b'),
+    re.compile(r'^CompileXIB\b'),
+    re.compile(r'^CompileXCStrings\b'),
+    # `LinkStoryboards` must be caught here, before the packaging
+    # tuple's generic `^Link\b` rule claims it. The native →
+    # resources → packaging precedence in `_classify_section_title`
+    # is what keeps this working — do not reorder.
+    re.compile(r'^LinkStoryboards\b'),
+    re.compile(r'^CompileStrings\b'),
+    re.compile(r'^ProcessInfoPlistFile\b'),
+    re.compile(r'^CpResource\b'),
+    re.compile(r'^CopyPlistFile\b'),
+    re.compile(r'^CopyStringsFile\b'),
+    re.compile(r'^CopyTiffFile\b'),
+    re.compile(r'^CopyPNGFile\b'),
+    re.compile(r'^GenerateAssetSymbols\b'),
+)
+_XCACTIVITYLOG_CATEGORY_PACKAGING_PATTERNS = (
+    re.compile(r'^Link\b'),
+    re.compile(r'^Ld\b'),
+    re.compile(r'^CodeSign\b'),
+    re.compile(r'^Sign \b'),
+    re.compile(r'^SignManifestFile\b'),
+    re.compile(r'^Strip\b'),
+    re.compile(r'^Touch\b'),
+    re.compile(r'^Embed\b'),
+    re.compile(r'^ProcessProductPackaging\b'),
+    re.compile(r'^RegisterExecutionPolicyException\b'),
+    re.compile(r'^Validate\b'),
+    re.compile(r'^GenerateDSYMFile\b'),
+    re.compile(r'^CreateUniversalBinary\b'),
+    # Swift stdlib embedding — `swift-stdlib-tool` copies the Swift
+    # runtime dylibs into the app bundle. Conceptually packaging,
+    # not compilation.
+    re.compile(r'^Copy Swift standard libraries\b'),
+)
+
+
+def _find_derived_data_root(obj_root):
+    """Walk up from `$OBJROOT` looking for the first ancestor that has
+    a `Logs/Build/` subdirectory — that's Xcode's per-project
+    DerivedData root. Returns the path, or None when not found.
+
+    `$OBJROOT` during `archive` typically resolves to
+    `<DerivedData>/Build/Intermediates.noindex/ArchiveIntermediates/
+    <SchemeName>/IntermediateBuildFilesPath`, so the ancestor walk
+    usually crosses four or five directory levels before hitting the
+    logs folder. Bounded by an explicit step cap so a malformed
+    `$OBJROOT` never sends us walking to `/`.
+    """
+    if not obj_root:
+        return None
+    current = os.path.normpath(obj_root)
+    for _ in range(10):
+        candidate = os.path.join(current, 'Logs', 'Build')
+        if os.path.isdir(candidate):
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+    return None
+
+
+def _find_latest_xcactivitylog(obj_root):
+    """Return the path to the newest `.xcactivitylog` Xcode wrote for
+    this project, or None if the log directory can't be located.
+
+    "Newest" is resolved by mtime — Xcode writes one log file per
+    build/archive, so the most-recently-modified one in `Logs/Build/`
+    corresponds to the archive we're currently running under.
+
+    TODO(timings): Multi-arch archives (Mac Catalyst, iOS + macOS
+    targets in one workspace) can place the relevant log in a sibling
+    `Logs/Build/` directory we don't search. The current
+    newest-mtime-in-the-discovered-dir strategy is deterministic but
+    may pick the wrong arch's log on such projects. Cross-directory
+    search deferred.
+
+    TODO(timings): Stale-log detection — if the newest `.xcactivitylog`
+    was written before the current build started, we'd report
+    pre-build numbers as if they were this build's. No retry / warning
+    is emitted today; consider checking the file's mtime against
+    `os.environ.get('BUILD_TIMESTAMP')` or similar before parsing.
+    """
+    dd_root = _find_derived_data_root(obj_root)
+    if not dd_root:
+        return None
+    log_dir = os.path.join(dd_root, 'Logs', 'Build')
+    try:
+        entries = [
+            os.path.join(log_dir, f)
+            for f in os.listdir(log_dir)
+            if f.endswith('.xcactivitylog')
+        ]
+    except OSError:
+        return None
+    if not entries:
+        return None
+    # Tie-break by filename so sibling logs with the same
+    # second-granularity mtime (HFS+ filesystems, rsync-preserving-
+    # mtime CI caches) don't shuffle non-deterministically. Xcode
+    # encodes a monotonic timestamp at the start of each log's
+    # UUID-based filename, so descending-by-name pairs well with
+    # descending-by-mtime.
+    entries.sort(
+        key=lambda p: (os.path.getmtime(p), os.path.basename(p)),
+        reverse=True,
+    )
+    return entries[0]
+
+
+def _tokenize_slf(data):
+    """Tokenize an `SLF0` byte stream into a flat `[(type, value), …]`
+    list. `data` is the DECOMPRESSED stream (the leading 4-byte `SLF0`
+    header is skipped here).
+
+    Each token is `<ascii-payload><1-byte-delimiter>`:
+      - `"` / `%` / `*` are LENGTH-PREFIXED: the payload is a DECIMAL
+        length, then that many raw bytes follow and become the token's
+        value (decoded as UTF-8, replacement on error). The single
+        nastiest bug here is that the length is DECIMAL, NOT hex, and
+        that `*` (JSON/data blob) MUST consume its length in bytes or
+        the whole stream desyncs.
+      - `^` is a double: 16 hex chars, little-endian IEEE-754. Value is
+        the float, or None if malformed.
+      - `#` / `@` are ints: HEX payload. `#` is a plain int, `@` is a
+        1-based class-table reference. Value is the parsed int.
+      - `(` is an array/object header: HEX payload is the element
+        count. Value is that int.
+      - `-` is null. Value is None.
+
+    Returns `(tokens, desync_count)`. `desync_count` is the number of
+    malformed length/number payloads encountered — non-zero hints the
+    grammar drifted, but parsing continues best-effort.
+    """
+    tokens = []
+    desync = 0
+    i = 4  # skip the 4-byte 'SLF0' header
+    n = len(data)
+    payload = bytearray()
+    while i < n:
+        b = data[i]
+        if b in _SLF_DELIMS:
+            t = chr(b)
+            p = payload.decode('ascii', 'replace')
+            payload = bytearray()
+            i += 1
+            if b in _SLF_LEN_PREFIXED_SET:
+                # DECIMAL length, then that many raw bytes.
+                try:
+                    ln = int(p, 10) if p else 0
+                except ValueError:
+                    ln = 0
+                    desync += 1
+                tokens.append((t, data[i:i + ln].decode('utf-8', 'replace')))
+                i += ln
+            elif t == '^':
+                if len(p) == 16:
+                    try:
+                        tokens.append((t, struct.unpack('<d', bytes.fromhex(p))[0]))
+                    except Exception:
+                        tokens.append((t, None))
+                        desync += 1
+                else:
+                    tokens.append((t, None))
+            else:
+                # '#', '@', '(' carry a HEX payload; '-' carries none.
+                try:
+                    tokens.append((t, int(p, 16) if p else 0))
+                except ValueError:
+                    tokens.append((t, None))
+                    desync += 1
+        else:
+            payload.append(b)
+            i += 1
+    return tokens, desync
+
+
+def _extract_slf_sections(tokens):
+    """Walk a tokenized SLF stream and extract every section instance
+    as a `(cls, title, start_cf, end_cf)` tuple.
+
+    The class table is every `%` className-def in stream order, 1-based;
+    an `@N` token references the N-th def. A section instance starts at
+    an `@`-ref to one of the two section classes, immediately followed
+    by tokens of types `# " " " ^ ^` (sectionType, domainType, title,
+    signature, timeStarted, timeStopped) and then a subSections field
+    that is `(` (array) or `-` (none). We read:
+      - `cls`      — the referenced class name.
+      - `title`    — the 3rd string (index +3).
+      - `start_cf` — the 1st double (index +5), CFAbsoluteTime seconds.
+      - `end_cf`   — the 2nd double (index +6), CFAbsoluteTime seconds.
+
+    Sections with a missing / non-finite / inverted timestamp pair are
+    dropped (they can't contribute to span, occupancy, or the Gantt).
+
+    No tree reconstruction is attempted: containment is resolved later
+    by interval math, which is robust to the subSection-count drift
+    that an explicit child-count stack walk is prone to on real logs.
+    """
+    class_table = [v for (t, v) in tokens if t == '%']
+    ntok = len(tokens)
+
+    def class_of(idx):
+        if isinstance(idx, int) and 1 <= idx <= len(class_table):
+            return class_table[idx - 1]
+        return None
+
+    sections = []
+    for k in range(ntok - 7):
+        t, v = tokens[k]
+        if t != '@':
+            continue
+        cls = class_of(v)
+        if cls not in _SLF_SECTION_CLASSES:
+            continue
+        # Shape check: # " " " ^ ^ then ( or - .
+        if (tokens[k + 1][0] != '#' or tokens[k + 2][0] != '"'
+                or tokens[k + 3][0] != '"' or tokens[k + 4][0] != '"'
+                or tokens[k + 5][0] != '^' or tokens[k + 6][0] != '^'
+                or tokens[k + 7][0] not in ('(', '-')):
+            continue
+        title = tokens[k + 3][1]
+        start_cf = tokens[k + 5][1]
+        end_cf = tokens[k + 6][1]
+        if start_cf is None or end_cf is None:
+            continue
+        if not (math.isfinite(start_cf) and math.isfinite(end_cf)):
+            continue
+        if end_cf < start_cf:
+            continue
+        sections.append((cls, title, start_cf, end_cf))
+    return sections
+
+
+def _interval_union_seconds(intervals):
+    """Total length (seconds) of the UNION of `[start, end]` intervals
+    — the OCCUPANCY metric. Overlapping windows are merged, so the
+    result can never exceed wall-clock. This is the fix for the flat
+    code's per-category SUM, which double-counted Swift batch windows
+    replicated onto every file's command section.
+
+    `intervals` is an iterable of `(start, end)` float pairs (any
+    order). Returns 0.0 for an empty input.
+    """
+    ordered = sorted(intervals)
+    total = 0.0
+    cur_start = cur_end = None
+    for s, e in ordered:
+        if cur_start is None:
+            cur_start, cur_end = s, e
+        elif s <= cur_end:
+            if e > cur_end:
+                cur_end = e
+        else:
+            total += cur_end - cur_start
+            cur_start, cur_end = s, e
+    if cur_start is not None:
+        total += cur_end - cur_start
+    return total
+
+
+def _classify_section_title(title):
+    """Map a command-invocation section title to one of the cross-
+    platform category buckets: `'native'`, `'resources'`,
+    `'packaging'`, `'other'`. (iOS never emits `'managed_code'` — see
+    the mapping docstring above the pattern tuples.) Returns `None`
+    only for an empty title. Precedence-ordered regex scan — first
+    match wins.
+
+    Callers pass COMMAND-invocation titles (`IDEActivityLogCommand-
+    InvocationSection`), never the grouping wrappers, so there is no
+    longer a wrapper-title escape hatch here: the SLF section-tree
+    walk already separates the two classes, and per-category OCCUPANCY
+    (interval union over command sections) is what feeds the chips,
+    so a parallel build's occupancy can never exceed wall-clock
+    `total_ms`. The dominant-category logic in `_build_timeline_blob`
+    reuses this same classifier on the commands contained within each
+    target window.
+    """
+    if not title:
+        return None
+    # `Compiling Clang module <name>` is a real native compile event
+    # (explicit module build); list it ahead of the generic patterns
+    # so it lands in `native` rather than `other`.
+    if title.startswith('Compiling Clang module'):
+        return 'native'
+    for p in _XCACTIVITYLOG_CATEGORY_NATIVE_PATTERNS:
+        if p.match(title):
+            return 'native'
+    for p in _XCACTIVITYLOG_CATEGORY_RESOURCES_PATTERNS:
+        if p.match(title):
+            return 'resources'
+    for p in _XCACTIVITYLOG_CATEGORY_PACKAGING_PATTERNS:
+        if p.match(title):
+            return 'packaging'
+    return 'other'
+
+
+# `/Users/<name>` matches the username token regardless of what
+# follows. Earlier we anchored on `(?=/|$)` so the lookahead would
+# require either a path separator or end-of-string — but Xcode
+# occasionally embeds bare user-home references in the middle of
+# titles (e.g. `"warning at /Users/alice and exit"`), and the
+# anchored form let the username slip past, where the catch-all
+# `_ABSOLUTE_PATH_RE` then reduced `/Users/alice` to basename
+# `alice` — emitting the bare username as a standalone word.
+#
+# Username character class is restricted to `[A-Za-z0-9._\-]+` (the
+# realistic Unix-username surface) rather than `[^/\s]+`. The broader
+# negation would also consume trailing punctuation (`,`, `)`, `:`,
+# `;`, `.`) when the username appears mid-title, producing slightly
+# mangled surrounding text in the emitted name. The narrower class
+# stops at the first non-username character so the surrounding
+# sentence preserves its shape (`"see /Users/alice)"` →
+# `"see <home>)"`, not `"see <home>"`).
+_PATH_USER_HOME_RE = re.compile(r'/Users/[A-Za-z0-9._\-]+')
+_PATH_PRIVATE_VAR_FOLDERS_RE = re.compile(
+    r'/private/var/folders/[^\s]+'
+)
+_ABSOLUTE_PATH_RE = re.compile(r'(?<!\S)(/[^\s]+)')
+
+
+def _sanitize_section_title_for_emission(title):
+    """Strip PII (username, machine-local paths) out of an xcactivitylog
+    section title before it ships in `top_tasks`.
+
+    Xcode often embeds absolute paths in section titles (e.g.
+    `Compile /Users/alice/Projects/MyApp/Sources/Foo.swift`). We:
+      - replace `/Users/<name>/` with `<home>/` (drops the username),
+      - collapse `/private/var/folders/...` paths to their basename
+        (TemporaryItems / DerivedData scratch paths leak machine UUIDs),
+      - reduce any other absolute path token to its basename.
+    Non-path tokens pass through unchanged so titles like
+    `Compile Foo.swift (arm64)` are emitted verbatim.
+    """
+    if not title:
+        return title
+
+    def _replace_user_home(m):
+        return '<home>'
+
+    def _replace_private_var(m):
+        return os.path.basename(m.group(0))
+
+    def _replace_absolute(m):
+        path = m.group(1)
+        if path.startswith('<home>'):
+            return path
+        return os.path.basename(path) or path
+
+    sanitized = _PATH_USER_HOME_RE.sub(_replace_user_home, title)
+    sanitized = _PATH_PRIVATE_VAR_FOLDERS_RE.sub(_replace_private_var, sanitized)
+    sanitized = _ABSOLUTE_PATH_RE.sub(_replace_absolute, sanitized)
+    return sanitized
+
+
+def _dominant_category_for_window(commands, win_start, win_end):
+    """Return the DOMINANT category for a target window — the category
+    with the greatest command-OCCUPANCY (interval union, not sum) among
+    the command-invocations whose `[start, end]` is CONTAINED within
+    `[win_start, win_end]`.
+
+    Containment (rather than overlap) keeps each command attributed to
+    exactly the target it belongs to; a command that straddles a target
+    boundary (rare, and usually a build-system bookkeeping section) is
+    simply not counted toward that target's category.
+
+    `commands` is a list of `(category, start_cf, end_cf)` tuples for
+    every classified command-invocation in the build. Returns `'native'`
+    when the window contains no classifiable command (a target made up
+    of only build-graph bookkeeping still renders as a native bar rather
+    than vanishing).
+    """
+    by_cat = {}
+    for cat, s, e in commands:
+        if s >= win_start and e <= win_end:
+            by_cat.setdefault(cat, []).append((s, e))
+    if not by_cat:
+        return 'native'
+    best_cat = 'native'
+    best_occ = -1.0
+    for cat, intervals in by_cat.items():
+        occ = _interval_union_seconds(intervals)
+        if occ > best_occ:
+            best_occ = occ
+            best_cat = cat
+    return best_cat
+
+
+def _build_timeline_blob(targets, build_start_cf):
+    """Build the Gantt-chart DETAIL blob from the per-target grouping
+    records. `targets` is a list of `(path, category, start_cf, end_cf)`
+    tuples — one per `Build target ` grouping, with `category` already
+    resolved to the target's DOMINANT command-category — and
+    `build_start_cf` is the build's earliest section start in
+    CFAbsoluteTime.
+
+    Wire shape (unchanged from the flat implementation, and mirroring
+    the Android Gradle plugin's `TimingsPayloadSerializer` so back-end
+    + front-end render both platforms from one schema):
+
+      { "schema_version": 1,
+        "build_started_at_ms": <epoch ms of build start>,
+        "wall_clock_ms": <max end − min start over targets, ms>,
+        "tasks": [ {"path", "category", "start_ms", "end_ms"}, … ] }
+
+    Rules:
+      - `start_ms`/`end_ms` are OFFSETS from `build_started_at_ms`
+        (not absolute), in ms.
+      - tasks sorted by `start_ms` ascending.
+      - capped at `_TIMELINE_MAX_TASKS`; when truncating we keep the
+        SLOWEST targets, then re-sort the kept slice by start.
+
+    Unlike the old code, the rows are the per-target GROUPINGS — NOT
+    per-file leaf sections — so the Gantt shows ~one bar per target
+    (low-double-digit peak concurrency) rather than 300+ phantom
+    parallel bars. The mega-wrappers (root build / `Prepare build` /
+    `Run post-actions` / `Prepare packages`) were already filtered out
+    by the caller.
+
+    Returns the blob dict, or None when there are no target groupings —
+    callers then PUT nothing.
+    """
+    if not targets:
+        return None
+
+    # `build_started_at_ms` is anchored to the WHOLE build's start (the
+    # earliest section of any class), so per-target offsets are relative
+    # to t0 of the build, not to the earliest target.
+    build_started_at_ms = int(round(
+        (build_start_cf + _CF_ABSOLUTE_TIME_EPOCH_OFFSET) * 1000))
+    latest_end_cf = max(e for _p, _c, _s, e in targets)
+    wall_clock_ms = max(0, int(round((latest_end_cf - build_start_cf) * 1000)))
+
+    # Truncation keeps the SLOWEST targets (sort by duration desc,
+    # slice), then re-sorts the kept slice chronologically so the array
+    # reads start-ordered for the front-end's greedy-lane Gantt packer.
+    if len(targets) > _TIMELINE_MAX_TASKS:
+        print(
+            "Bugsee: build-timings detail blob truncated "
+            "(%d targets -> %d slowest kept)"
+            % (len(targets), _TIMELINE_MAX_TASKS)
+        )
+        kept = sorted(
+            targets, key=lambda t: t[3] - t[2], reverse=True
+        )[:_TIMELINE_MAX_TASKS]
+    else:
+        kept = targets
+
+    tasks = [
+        {
+            'path': _sanitize_section_title_for_emission(path)[:255],
+            'category': category,
+            'start_ms': int(round((start_cf - build_start_cf) * 1000)),
+            'end_ms': int(round((end_cf - build_start_cf) * 1000)),
+        }
+        for path, category, start_cf, end_cf in sorted(kept, key=lambda t: t[2])
+    ]
+
+    return {
+        'schema_version': _TIMELINE_SCHEMA_VERSION,
+        'build_started_at_ms': build_started_at_ms,
+        'wall_clock_ms': wall_clock_ms,
+        'tasks': tasks,
+    }
+
+
+def _timeline_blob_gz(blob):
+    """Gzip the compact JSON timeline blob, mirroring `_deps_blob_gz`
+    (compact separators, `gzip.compress`). Shape matches the Android
+    Gradle plugin's `TimingsPayloadSerializer.gzipBytes`."""
+    raw = json.dumps(blob, separators=(',', ':')).encode('utf-8')
+    return gzip.compress(raw)
+
+
+def _parse_xcactivitylog(log_path):
+    """Extract the build's wall-clock span, per-category OCCUPANCY, a
+    top-N slowest-targets list, AND a per-target Gantt timeline from an
+    `.xcactivitylog`, using a proper SLF section-tree decode.
+
+    Pipeline:
+      1. Decompress + `_tokenize_slf` the `SLF0` stream.
+      2. `_extract_slf_sections` → every `(cls, title, start, end)`
+         section instance, split into the two section classes.
+      3. `total_ms`      = wall-clock SPAN (`max(end) − min(start)`)
+                           over ALL sections.
+      4. `category_sums` = per-category OCCUPANCY (interval union) over
+                           the COMMAND-invocation sections, classified
+                           by title. Occupancy can never exceed
+                           wall-clock — the fix for the flat code's
+                           batch-inflated SUMs.
+      5. targets         = the `IDEActivityLogSection` groupings whose
+                           title starts with `Build target ` (the
+                           mega-wrappers are excluded). Each target's
+                           DOMINANT category is the category with the
+                           greatest command-occupancy among commands
+                           contained within its window.
+      6. `top_tasks`     = the slowest targets (name + duration_ms),
+                           capped at `_XCACTIVITYLOG_TOP_N`.
+      7. `timeline`      = the Gantt blob (one row per target).
+
+    Returns a dict with `total_ms` / `top_tasks` / `category_sums` /
+    `timeline`, or None when the log can't be opened / decompressed /
+    tokenized into any section at all.
+    """
+    try:
+        with gzip.open(log_path, 'rb') as g:
+            data = g.read(_XCACTIVITYLOG_MAX_DECOMPRESSED + 1)
+    except Exception:
+        return None
+
+    if len(data) > _XCACTIVITYLOG_MAX_DECOMPRESSED:
+        # Truncated to cap memory; a truncated tail loses late sections
+        # anyway. Work with what we have — the class table and the root
+        # section live at the head of the stream.
+        data = data[:_XCACTIVITYLOG_MAX_DECOMPRESSED]
+
+    tokens, _desync = _tokenize_slf(data)
+    sections = _extract_slf_sections(tokens)
+    if not sections:
+        return None
+
+    # total_ms = wall-clock SPAN over ALL sections. CFAbsoluteTime is
+    # seconds since 2001; the span is offset-independent so no epoch
+    # shift is needed here.
+    build_start_cf = min(s for _c, _t, s, _e in sections)
+    build_end_cf = max(e for _c, _t, _s, e in sections)
+    total_ms = max(0, int(round((build_end_cf - build_start_cf) * 1000)))
+
+    # Classify each COMMAND-invocation once; reused for both the
+    # category-occupancy chips and the per-target dominant category.
+    commands = []
+    for cls, title, s, e in sections:
+        if cls != _SLF_COMMAND_CLASS:
+            continue
+        bucket = _classify_section_title(title)
+        if bucket is None:
+            continue
+        commands.append((bucket, s, e))
+
+    # Per-category OCCUPANCY (interval union per bucket), in ms.
+    # `managed_code` is a cross-platform bucket iOS never fills (Swift /
+    # Obj-C / C/C++ all land in `native`); kept pre-seeded to zero for
+    # parity with Android, and the emission loop drops zero buckets.
+    by_cat_intervals = {}
+    for bucket, s, e in commands:
+        by_cat_intervals.setdefault(bucket, []).append((s, e))
+    category_sums = {
+        'managed_code': 0,
+        'native': 0,
+        'resources': 0,
+        'packaging': 0,
+        'other': 0,
+    }
+    for bucket, intervals in by_cat_intervals.items():
+        category_sums[bucket] = int(round(
+            _interval_union_seconds(intervals) * 1000))
+
+    # `Build target ` groupings → the Gantt rows + top_tasks. The four
+    # mega-wrappers (root build, `Prepare build`, `Prepare packages`,
+    # `Run post-actions`) are `IDEActivityLogSection` too but DON'T
+    # carry the `Build target ` prefix, so they're excluded — they span
+    # the whole build and would draw a single full-width bar.
+    targets = []
+    for cls, title, s, e in sections:
+        if cls != _SLF_SECTION_CLASS:
+            continue
+        if not title or not title.startswith(_XCACTIVITYLOG_TARGET_PREFIX):
+            continue
+        category = _dominant_category_for_window(commands, s, e)
+        # Strip the `Build target ` prefix for the emitted path.
+        path = title[len(_XCACTIVITYLOG_TARGET_PREFIX):] or title
+        targets.append((path, category, s, e))
+
+    # top_tasks = slowest target groupings, longest first, capped at
+    # TOP_N. Durations here are the target wall-clock windows (NOT
+    # batch-inflated per-file sums).
+    top_sorted = sorted(
+        targets, key=lambda t: t[3] - t[2], reverse=True)
+    top_tasks = []
+    for path, _category, s, e in top_sorted[:_XCACTIVITYLOG_TOP_N]:
+        dur = int(round((e - s) * 1000))
+        if dur < 1:  # sub-millisecond targets are noise
+            continue
+        top_tasks.append({
+            'name': _sanitize_section_title_for_emission(path)[:255],
+            'duration_ms': dur,
+        })
+
+    # Per-target Gantt blob. Offsets are relative to the WHOLE build's
+    # start so the bars line up with the absolute timeline.
+    timeline = _build_timeline_blob(targets, build_start_cf)
+
+    return {
+        'total_ms': total_ms,
+        'top_tasks': top_tasks,
+        'category_sums': category_sums,
+        'timeline': timeline,
+    }
+
+
+def resolve_build_timings(env):
+    """Produce the build's timing data for the current build.
+
+    Returns a `(timings, timeline_gz)` tuple:
+      - `timings`: the inline `build_metadata.timings` sub-object —
+        `total_ms` (wall-clock SPAN), a `top_tasks` list of the
+        slowest `Build target ` groupings, and a per-category rollup
+        (`native_ms` / `resources_ms` / `packaging_ms` / `other_ms`)
+        whose values are command-invocation OCCUPANCY (interval union,
+        so they never exceed `total_ms`). iOS never emits
+        `managed_code_ms` — Swift / Obj-C / C / C++ all compile into
+        the Mach-O and land in `native_ms`. The server schema shares
+        the field names with Android, which keeps `managed_code_ms`
+        populated (JVM-bytecode compilation: kotlinc / javac / R8 /
+        desugar).
+      - `timeline_gz`: the gzipped per-target Gantt DETAIL blob PUT to
+        the presigned `timings_upload_endpoint` for Gantt-chart parity
+        with Android's `timings.json`, or None when there's no
+        `Build target ` grouping to chart.
+
+    Either element may be None independently. `(None, None)` means no
+    timing source was available at all.
+
+    Wraps the entire pipeline in a broad except so any future parser
+    bug (e.g. an `inf`/`nan` slipping past the section filters and
+    overflowing duration arithmetic, or a malformed SLF stream
+    causing struct/unicode decode errors that weren't anticipated)
+    degrades gracefully to "no timings" instead of escaping into the
+    outer build-publish wrapper. The outer wrapper aborts the entire
+    build-info upload — losing timings is acceptable; losing the
+    build record is not.
+    """
+    try:
+        return _resolve_build_timings_impl(env)
+    except Exception as e:
+        print(
+            "Bugsee: build-timings extraction failed (%s) — "
+            "omitting timings from build_metadata" % str(e)
+        )
+        return None, None
+
+
+def _resolve_build_timings_impl(env):
+    obj_root = env.get('OBJROOT')
+    log_path = _find_latest_xcactivitylog(obj_root)
+    if not log_path:
+        return None, None
+    parsed = _parse_xcactivitylog(log_path)
+    if not parsed:
+        return None, None
+
+    # Server sanitizer drops fields that are falsy / None, but being
+    # explicit about omissions keeps the wire payload tidy. Emit
+    # zero-valued category sums as positive zeros so "no data" stays
+    # distinguishable from "genuinely zero time in this category" on
+    # the server — the sanitizer preserves zero-valued ints.
+    timings = {}
+    if parsed.get('total_ms'):
+        timings['total_ms'] = parsed['total_ms']
+    if parsed.get('top_tasks'):
+        timings['top_tasks'] = parsed['top_tasks']
+    for bucket, value in (parsed.get('category_sums') or {}).items():
+        if value > 0:
+            timings['%s_ms' % bucket] = value
+
+    # Per-task timeline DETAIL blob — gzipped only when it carries at
+    # least one task, so the caller never sets `request_timings_upload`
+    # nor PUTs an empty blob. Mirrors the deps-blob "summary + blob"
+    # split exactly.
+    timeline = parsed.get('timeline')
+    timeline_gz = None
+    if timeline and timeline.get('tasks'):
+        timeline_gz = _timeline_blob_gz(timeline)
+
+    return (timings or None), timeline_gz
+
+
+# -----------------------------------------------------------------
+# Build-publish flow + gate
+# -----------------------------------------------------------------
+#
+# The flow has two layers:
+#
+#   - **build-info** (default ON, release-only): every Release archive
+#     posts a build record to the Bugsee back-end carrying version,
+#     build, package_id, VCS, build-machine, plugin / Xcode / SDK
+#     versions, timings, and the artefact's file size. The record
+#     unlocks crash-context enrichment (commit lookup) and serves as
+#     the in-build size-check baseline. Disable via
+#     `BUGSEE_BUILD_INFO_ENABLED=0` for firewalled CI / privacy-
+#     sensitive builds.
+#
+#   - **size-analysis** (default OFF, sub-feature of build-info):
+#     when enabled, the build-info POST also asks the server for a
+#     presigned PUT URL and ships the artefact bytes for server-side
+#     tree analysis. Requires build-info to be enabled — the flow
+#     warns and skips both if size-analysis is on while build-info
+#     is off.
+
+
+def _env_truthy_default_true(value):
+    """`True` for missing / unset / empty values (treated as "default
+    on") AND for conventional truthy tokens. Used by the build-info
+    gate where the default is ON.
+
+    Empty string is treated as missing: many GUIs (Xcode's "Add
+    Environment Variable", some CI dashboards) emit `BUGSEE_…=""`
+    when the user leaves the value field blank. Treating `""` as
+    "off" would silently flip a user who *thought* they were
+    accepting the default into the disabled path — confusing and
+    invisible."""
+    if value is None:
+        return True
+    if not value.strip():
+        return True
+    return _env_truthy(value)
+
+
+
+
 def main():
+    # Symbols-pipeline entry. The deps pipeline is now invoked
+    # separately from the post-daemonization slot at module level
+    # (see the `if __name__ == "__main__":` block) so it runs
+    # regardless of whether the build has dSYM symbols to upload.
+    #
+    # As of the bugsee-cli migration, the actual dSYM upload is
+    # performed by the bugsee-cli Rust binary, one invocation per
+    # `.dSYM` bundle. This loop's role is:
+    #   - discover .dSYM bundles under options.dsym_folder
+    #   - extract Mach-O UUIDs (via dwarfdump) to short-circuit
+    #     dSYMs whose UUIDs are already in ~/.bugseeUploadList
+    #   - apply BCSymbolMap deobfuscation in place when --maps is set
+    #   - hand each surviving .dSYM directory to the CLI
+    # The CLI itself re-extracts UUIDs internally via
+    # `symbolic-debuginfo` and POSTs `{version, build}` to
+    # /apps/<token>/symbols — the server then walks the uploaded
+    # tarball and stores `images[]` per arch slice. Dashboard
+    # outcome is one symbol record per .dSYM (finer granularity
+    # than the legacy one-record-per-build zip).
     tempDir = tempfile.mkdtemp()
     print("Processing in " + tempDir)
-    zipFileLocation = os.path.join(tempDir, 'symbols.zip')
-    dwarfs = []
+    # List of (dsym_bundle_dir, uuids_discovered) — one entry per
+    # .dSYM the CLI needs to upload.
+    dsymUploads = []
     uploadedImages = loadUploadedList()
 
+    # Track the first .dSYM zip filename (--list mode) so the legacy
+    # `-{version}-{build}.dSYM.zip` pattern can supply the version/build
+    # fallback. Used only when neither --version/--build nor Info.plist
+    # produced values.
+    firstDsymZipForFallback = None
     if options.dsym_list:
         options.dsym_folder = tempDir
         for f in args[1:]:
@@ -220,48 +3538,93 @@ def main():
                 continue
             if (os.stat(f).st_size == 0):
                 continue
+            if firstDsymZipForFallback is None:
+                firstDsymZipForFallback = f
             with zipfile.ZipFile(f, 'r') as zipf:
-                zipf.extractall(tempDir) 
+                zipf.extractall(tempDir)
+
+    # Resolve version + build with the legacy fallback chain. Order:
+    #   1. --version / --build CLI flags (or BUGSEE_APP_{VERSION,BUILD} env)
+    #   2. --list mode: `-{version}-{build}.dSYM.zip` filename pattern
+    #   3. Otherwise: CFBundleShortVersionString + CFBundleVersion from
+    #      $INFOPLIST_PATH (the Xcode build-phase default — users rarely
+    #      pass -v/-b in that context).
+    # Without resolved values the bugsee-cli exec would error out, since
+    # `--version` and `--build` are required positional args on the CLI.
+    resolvedVersion = options.version
+    resolvedBuild = options.build
+    if not (resolvedVersion and resolvedBuild):
+        fallbackVersion, fallbackBuild = getVersionAndBuild(firstDsymZipForFallback or "")
+        if not resolvedVersion:
+            resolvedVersion = fallbackVersion
+        if not resolvedBuild:
+            resolvedBuild = fallbackBuild
 
     os.chdir(options.dsym_folder)
     for root, dirs, files in os.walk(options.dsym_folder):
         if not root.endswith('dSYM/Contents/Resources/DWARF'):
             continue
 
+        # The .dSYM directory is three components up from
+        # `<bundle>.dSYM/Contents/Resources/DWARF`.
+        dsymDir = os.path.dirname(os.path.dirname(os.path.dirname(root)))
         print(root)
+
+        newImagesInDsym = []
         for f in files:
-            if (os.path.islink(os.path.join(root, f))):
+            filePath = os.path.join(root, f)
+            if os.path.islink(filePath):
                 continue
-            if (os.stat(os.path.join(root, f)).st_size == 0):
+            if os.stat(filePath).st_size == 0:
                 continue
-            images = parseDSYM(os.path.join(root, f))
-            if (len(images) == 0):
+            images = parseDSYM(filePath)
+            if len(images) == 0:
                 continue
             if isInUploadedList(images, uploadedImages):
                 print("Already uploaded %s, skipping" % f)
                 continue
             if options.symbol_maps:
-                deobfuscateDSYM(os.path.join(root, f), options.symbol_maps)
-            dwarfs.append(os.path.join(root, f))
-            uploadedImages.extend(images)
-
-    if len(dwarfs) > 0:
-        with zipfile.ZipFile(zipFileLocation, 'w', zipfile.ZIP_DEFLATED) as zipf:
-            for dwarf in dwarfs:
-                zipf.write(dwarf, os.path.relpath(dwarf, options.dsym_folder), zipfile.ZIP_DEFLATED)
+                deobfuscateDSYM(filePath, options.symbol_maps)
+            newImagesInDsym.extend(images)
 
-            icon = getIcon()
-            if icon:
-                icon = uncrushIcon(icon, tempDir)
-            if icon and os.path.isfile(icon):
-                zipf.write(icon, 'icon.png', zipfile.ZIP_DEFLATED)
-
-            zipf.close()
-
-        result = uploadZipFile(zipFileLocation)
-        if result:
-            saveUploadedList(uploadedImages)
+        if newImagesInDsym:
+            dsymUploads.append((dsymDir, newImagesInDsym))
 
+    if len(dsymUploads) > 0:
+        if not (resolvedVersion and resolvedBuild):
+            # CLI requires both. Bailing here avoids burning N CLI execs
+            # only to have each fail the same way at argv parsing.
+            print("Bugsee: could not determine version/build (none of "
+                  "--version/--build, --list-mode filename pattern, or "
+                  "$INFOPLIST_PATH produced values); %d dSYM(s) not "
+                  "uploaded" % len(dsymUploads))
+        else:
+            cliBinary = resolveCli(
+                cliPath=options.cli_path,
+                cliVersion=options.cli_version)
+            if cliBinary is None:
+                # resolveCli already explained why on stderr/stdout. Skip
+                # uploads; do NOT mark UUIDs as uploaded — next run will
+                # retry once a usable binary is available.
+                print("Bugsee: no bugsee-cli available; %d dSYM(s) not uploaded" % len(dsymUploads))
+            else:
+                successCount = 0
+                for dsymDir, images in dsymUploads:
+                    ok = uploadDsymViaCli(
+                        cliBinary,
+                        dsymDir,
+                        APP_TOKEN,
+                        options.endpoint,
+                        resolvedVersion,
+                        resolvedBuild,
+                    )
+                    if ok:
+                        successCount += 1
+                        uploadedImages.extend(images)
+                if successCount > 0:
+                    saveUploadedList(uploadedImages)
+                print("Bugsee: uploaded %d/%d dSYM(s) via bugsee-cli" % (
+                    successCount, len(dsymUploads)))
 
     # cleanup
     shutil.rmtree(tempDir, ignore_errors=True)
@@ -286,34 +3649,248 @@ if __name__ == "__main__":
                   help="Set the version of the application dSYM corresponds to")
     parser.add_option("-d", "--build_dir", dest="build_dir",
                   help="Use for custom TARGET_BUILD_DIR", default=os.environ.get('TARGET_BUILD_DIR'))
+    # Dependencies-collection toggle. On by default — registers
+    # the build with Bugsee and uploads a per-build deps blob
+    # parsed from Podfile.lock / Package.resolved / Cartfile.resolved
+    # / linked vendored frameworks. Disable with --no-deps if the
+    # consumer wants the legacy symbols-only flow OR if the Bugsee
+    # iOS SDK's tools.bundle/BugseeAgent build phase already
+    # handled deps collection for this build (the fastlane Ruby
+    # action checks the cross-producer handshake and passes
+    # --no-deps when it detects the other producer did the work).
+    parser.add_option("--no-deps", dest="collect_deps", action="store_false",
+                  default=True,
+                  help="Skip the dependencies collection + upload step. "
+                       "Symbols + timings uploads still run unless "
+                       "disabled separately.")
+    # Timings-collection toggle. On by default. Independent of
+    # --no-deps so the cross-producer handshake can disable each
+    # action individually. When the Bugsee iOS SDK's
+    # tools.bundle/BugseeAgent build phase already collected the
+    # xcactivitylog-derived build timings for this build, the
+    # fastlane Ruby action passes --no-timings here and the
+    # build-info pipeline emits no `build_metadata.timings`
+    # sub-object and skips the timings PUT.
+    parser.add_option("--no-timings", dest="collect_timings",
+                  action="store_false", default=True,
+                  help="Skip the xcactivitylog-derived build timings "
+                       "collection + upload step. Symbols + deps "
+                       "uploads still run unless disabled separately.")
+    # bugsee-cli override knobs. See the resolver block near the top of
+    # this file for the full precedence rules.
+    parser.add_option("--cli-path", dest="cli_path",
+                  default=os.environ.get("BUGSEE_CLI_PATH"),
+                  help="Path to a local bugsee-cli binary. When set and the file "
+                       "is executable, this binary is used for symbol upload "
+                       "instead of the auto-downloaded one. Lets developers test "
+                       "a locally-built CLI without touching the on-disk cache.")
+    parser.add_option("--cli-version", dest="cli_version",
+                  default=os.environ.get("BUGSEE_CLI_VERSION"),
+                  help="bugsee-cli version to auto-download when --cli-path is "
+                       "unset. Defaults to BUGSEE_CLI_DEFAULT_VERSION (pinned to "
+                       "the version this agent was shipped against).")
+    parser.add_option("--project-root", dest="project_root",
+                  default=os.environ.get('SRCROOT') or os.environ.get('PROJECT_DIR'),
+                  help="Root of the iOS project — where lockfiles "
+                       "(Podfile.lock / Package.resolved / Cartfile.resolved) "
+                       "are searched for. Defaults to $SRCROOT then "
+                       "$PROJECT_DIR when run from Xcode.")
+    # ──────────────────────────────────────────────
+    # Android mapping upload mode (off by default)
+    # ──────────────────────────────────────────────
+    # When --upload-mapping is passed, BugseeAgent skips ALL the
+    # iOS-side flows (dSYM upload, dependencies pipeline,
+    # daemonization, dSYM-folder scanning) and runs ONE step:
+    # resolve bugsee-cli, upload the mapping.txt at --mapping-path
+    # via `debug-files upload --type proguard --uuid <pre-resolved>`.
+    # The fastlane plugin's upload_mapping_to_bugsee Ruby action
+    # resolves the UUID upstream (from explicit override, the Bugsee
+    # Gradle plugin's build-uuid.txt, or synthesis matching the
+    # SDK's runtime fallback formula) and passes the pre-resolved
+    # value via --mapping-uuid.
+    parser.add_option("--upload-mapping", dest="upload_mapping",
+                  action="store_true", default=False,
+                  help="Run in Android mapping upload mode. Skips "
+                       "iOS dSYM / deps flows entirely. Requires "
+                       "--mapping-path, --mapping-uuid, --version, "
+                       "--build, and the positional app token.")
+    parser.add_option("--mapping-path", dest="mapping_path",
+                  default=None,
+                  help="Path to the Android mapping.txt to upload. "
+                       "Only used with --upload-mapping.")
+    parser.add_option("--mapping-uuid", dest="mapping_uuid",
+                  default=None,
+                  help="Pre-resolved BUILD_UUID for the mapping. "
+                       "The fastlane action computes this Ruby-side "
+                       "(from the Gradle plugin's build-uuid.txt or "
+                       "by synthesis matching the SDK's runtime "
+                       "fallback formula) so the SDK can match the "
+                       "uploaded mapping against runtime crashes.")
+    parser.add_option("--icon", dest="icon_path",
+                  default=None,
+                  help="Optional launcher-icon PNG path. Forwarded "
+                       "to bugsee-cli's --icon flag for "
+                       "--type proguard uploads.")
+    parser.add_option("--upload-artifact", dest="upload_artifact",
+                  action="store_true", default=False,
+                  help="iOS artifact-upload flow. Packages the .app "
+                       "at --app-path into a synthetic .ipa and "
+                       "uploads it to the back-end for size analysis. "
+                       "Short-circuits the dSYM / deps / timings "
+                       "pipeline. Used by the upload_artifact_to_bugsee "
+                       "fastlane action.")
+    parser.add_option("--app-path", dest="app_path",
+                  default=None,
+                  help="Path to the built `.app` directory. Required "
+                       "by --upload-artifact. Typically resolved by "
+                       "the fastlane action from xcarchive_path + "
+                       "Products/Applications/<App>.app or from "
+                       "TARGET_BUILD_DIR/WRAPPER_NAME.")
+    parser.add_option("--request-artifact-upload", dest="request_artifact_upload",
+                  action="store_true", default=False,
+                  help="Set the build registration payload's "
+                       "`request_artifact_upload` field to true. "
+                       "Implied by --upload-artifact; expose "
+                       "separately so a future build-info-only "
+                       "caller can request size analysis without "
+                       "actually shipping the artefact bytes.")
+    parser.add_option("--build-info-only", dest="build_info_only",
+                  action="store_true", default=False,
+                  help="Inverse of --request-artifact-upload. With "
+                       "--upload-artifact, this flips the flow into "
+                       "register-only mode: the registration POST "
+                       "still records `artifact_size` on the server "
+                       "(so the dashboard's size-trend chart works) "
+                       "but the .ipa bytes never leave the build "
+                       "host. Useful for firewalled CI and privacy-"
+                       "sensitive setups.")
     (options, args) = parser.parse_args()
 
+    # ──────────────────────────────────────────────
+    # App-token check (BEFORE daemonization)
+    # ──────────────────────────────────────────────
+    # Pulled in front of the fork so a missing-token error reaches
+    # the user's terminal / Xcode build log instead of being
+    # swallowed by the daemonized child's redirected stdout.
+    if (len(args) < 1):
+        print("Bugsee:  Not initialized with app token. Must be passed as a parameter")
+        exit(1)
+    APP_TOKEN = args[0]
+
+    # ──────────────────────────────────────────────
+    # Android mapping upload — short-circuit path
+    # ──────────────────────────────────────────────
+    # Runs BEFORE the from_xcode daemonization fork so the
+    # mapping upload is fully synchronous from the caller's
+    # perspective (the Ruby action's Actions.sh shells to us and
+    # blocks on completion). Skips:
+    #   - the iOS dSYM upload flow (--type dsym is wrong for Android)
+    #   - the iOS deps pipeline (Podfile.lock / Package.resolved /
+    #     Cartfile.resolved scanning — irrelevant for an Android
+    #     build's mapping.txt)
+    #   - the daemonization double-fork (the iOS-specific Xcode-
+    #     post-action runs out-of-process so it can't block the
+    #     build; the fastlane Android lane WANTS to block).
+    # The fastlane action's Ruby side handles UUID resolution and
+    # input validation; here we just exec the CLI.
+    if options.upload_mapping:
+        if not options.mapping_path:
+            print("Bugsee: --upload-mapping requires --mapping-path")
+            exit(1)
+        if not options.mapping_uuid:
+            print("Bugsee: --upload-mapping requires --mapping-uuid "
+                  "(fastlane-resolved BUILD_UUID for SDK matching)")
+            exit(1)
+        if not os.path.isfile(options.mapping_path):
+            print("Bugsee: mapping file does not exist: %s"
+                  % options.mapping_path)
+            exit(1)
+        if options.icon_path and not os.path.isfile(options.icon_path):
+            print("Bugsee: --icon path does not exist: %s "
+                  "(continuing without icon)" % options.icon_path)
+            options.icon_path = None
+        cliBinary = resolveCli(options.cli_path, options.cli_version)
+        if not cliBinary:
+            print("Bugsee: bugsee-cli unavailable; mapping upload skipped")
+            exit(1)
+        ok = uploadMappingViaCli(
+            cliBinary, options.mapping_path, APP_TOKEN,
+            options.endpoint, options.version, options.build,
+            options.mapping_uuid, options.icon_path,
+        )
+        if ok:
+            print("Bugsee: mapping uploaded successfully")
+            exit(0)
+        else:
+            print("Bugsee: mapping upload failed")
+            exit(1)
+
+    # ──────────────────────────────────────────────
+    # iOS artefact upload — short-circuit path
+    # ──────────────────────────────────────────────
+    # Runs BEFORE the from_xcode daemonization fork so the artefact
+    # upload is fully synchronous from the caller's perspective (the
+    # Ruby action's Actions.sh blocks on completion). Skips:
+    #   - the iOS dSYM upload flow (orthogonal, has its own action)
+    #   - the deps/timings pipeline (those have their own
+    #     handshake-gated entry path)
+    #   - the daemonization double-fork (the fastlane lane wants to
+    #     block on the upload — the post-action daemon is an iOS
+    #     SDK BugseeAgent-only concern)
+    if options.upload_artifact:
+        if not options.app_path:
+            print("Bugsee: --upload-artifact requires --app-path")
+            exit(1)
+        if not os.path.isdir(options.app_path):
+            print("Bugsee: --app-path does not exist or is not a "
+                  "directory: %s" % options.app_path)
+            exit(1)
+        if not options.app_path.endswith('.app'):
+            print("Bugsee: --app-path must end in .app: %s"
+                  % options.app_path)
+            exit(1)
+        # `--build-info-only` flips the flow into register-only
+        # mode (records artifact_size, ships no bytes). The agent's
+        # default is byte-shipping (request_artifact_upload=True).
+        ok = run_artifact_upload_flow(
+            APP_TOKEN, options.endpoint, options.app_path,
+            version=options.version,
+            build_number=options.build,
+            request_artifact_upload=not options.build_info_only,
+        )
+        if ok:
+            print("Bugsee: artefact uploaded successfully")
+            exit(0)
+        else:
+            print("Bugsee: artefact upload failed")
+            exit(1)
+
     if options.from_xcode:
         # do the UNIX double-fork magic, see Stevens' "Advanced
         # Programming in the UNIX Environment" for details (ISBN 0201563177)
-        try: 
-            pid = os.fork() 
+        try:
+            pid = os.fork()
             if pid > 0:
                 # exit first parent
-                sys.exit(0) 
-        except OSError as e: 
-            print("fork #1 failed: %d (%s)" % (e.errno, e.strerror), file=sys.stderr) 
+                sys.exit(0)
+        except OSError as e:
+            print("fork #1 failed: %d (%s)" % (e.errno, e.strerror), file=sys.stderr)
             sys.exit(1)
 
         # decouple from parent environment
-        os.chdir("/") 
-        os.setsid() 
-        os.umask(0) 
+        os.chdir("/")
+        os.setsid()
+        os.umask(0)
 
         # do second fork
-        try: 
-            pid = os.fork() 
+        try:
+            pid = os.fork()
             if pid > 0:
                 # exit from second parent, print eventual PID before
-                print("Daemon PID %d" % pid) 
-                sys.exit(0) 
-        except OSError as e: 
-            print("fork #2 failed: %d (%s)" % (e.errno, e.strerror), file=sys.stderr) 
+                print("Daemon PID %d" % pid)
+                sys.exit(0)
+        except OSError as e:
+            print("fork #2 failed: %d (%s)" % (e.errno, e.strerror), file=sys.stderr)
             sys.exit(1)
 
         # redirect standard file descriptors
@@ -329,6 +3906,36 @@ if __name__ == "__main__":
         os.dup2(so.fileno(), sys.stdout.fileno())
         os.dup2(se.fileno(), sys.stderr.fileno())
 
+    # ──────────────────────────────────────────────
+    # Dependencies pipeline (runs in the daemonized child)
+    # ──────────────────────────────────────────────
+    #
+    # Hoisted ABOVE the dSYM / simulator gates that follow because
+    # the deps pipeline is independent of symbolication:
+    #
+    #   - Debug builds with `DEBUG_INFORMATION_FORMAT != dwarf-with-dsym`
+    #     still ship their lockfile-derived dep list.
+    #   - Simulator builds skip symbols but still get deps.
+    #
+    # Errors are caught and logged so a deps failure (parser bug,
+    # network blip, ngrok tunnel down) cannot prevent the symbols
+    # pipeline from running afterward — the two are independent.
+    if options.collect_deps:
+        try:
+            _run_dependencies_pipeline(APP_TOKEN, options.project_root)
+        except Exception as e:
+            print("Bugsee: dependencies pipeline failed: %s — "
+                  "continuing with symbols upload." % e)
+
+    # ──────────────────────────────────────────────
+    # Symbols-pipeline gates
+    # ──────────────────────────────────────────────
+    # Each gate exits the (already-daemonized) process cleanly so
+    # the user's build log doesn't spam errors about dSYMs that
+    # aren't supposed to exist on Debug / simulator builds. Deps
+    # already ran above — these gates only short-circuit the
+    # symbols half.
+    if options.from_xcode:
         if os.environ.get('DEBUG_INFORMATION_FORMAT') != 'dwarf-with-dsym':
             print("Bugsee:  DEBUG_INFORMATION_FORMAT is not set. Have you enabled debug symbols in your build? See: https://docs.bugsee.com/sdk/ios/symbolication/")
             exit(0)
@@ -337,13 +3944,6 @@ if __name__ == "__main__":
             print("Bugsee:  Bugsee is not supoorted in iOS simulator. Will not upload debug symbols for i386!")
             exit(0)
 
-
-    if (len(args) < 1):
-        print("Bugsee:  Not initialized with app token. Must be passed as a parameter")
-        exit(1)
-
-    APP_TOKEN = args[0]
-
     if not options.build_dir:
         print('Target build directory was not specified. Either provide it with the "-d" option or set "TARGET_BUILD_DIR" environment variable')
         exit(1)
@@ -358,5 +3958,5 @@ if __name__ == "__main__":
             print("Bugsee:  Can not find dSYM folder (expecting either a -f option or DWARF_DSYM_FOLDER_PATH)")
             exit(1)
 
-    # start the daemon main loop
-    main() 
+    # start the daemon main loop (symbols pipeline only)
+    main()