Distillation

Date: Sep 10, 2026

• 🟡 (11:46) Review tracking showed 3 ordered tasks: 1. Verify immutable base/head metadata, ancestry evidence, trees, changed paths, and diff cleanliness (in_progress, high priority); 2. Inspect the full diff and every changed source and test file against accepted upgrade contracts (pending, high priority); 3. Trace edge cases and produce a findings-first merge verdict with exact HEAD line evidence (pending, high priority).
• 🟡 (11:46) Immutable base metadata verified: commit ec83887a16f780f32fba4b7d710bad262dba3a22, tree 110d6530e57ca4fbfb2a3f98e52013d2668b5b5e, parent e7beceb6ba09b64dc277ae1732df04e65500062b, author sentry[bot] <39604003+sentry[bot]@users.noreply.github.com>, committer GitHub <noreply@github.com>, subject fix(event): Prevent immediate retry of rate-limited org in event view fallback (#1566).
• 🟡 (11:46) Immutable head metadata verified: commit 9525f72c70fabbb23ec21d13cf86add58f6287cc, tree 22f49363a13e32c36dcd9e1ca95916809c2dc271, parent a84012184c79c2566c7466aa6beda5f767199218, author/committer Burak Yigit Kaya <byk@sentry.io>, subject fix(cli): harden upgrade metadata validation.
• 🟡 (11:46) Base-to-head diff contained exactly 17 modified files: packages/cli/src/commands/cli/upgrade.ts, packages/cli/src/lib/binary.ts, packages/cli/src/lib/delta-upgrade.ts, packages/cli/src/lib/errors.ts, packages/cli/src/lib/ghcr.ts, packages/cli/src/lib/release-notes.ts, packages/cli/src/lib/upgrade.ts, packages/cli/src/lib/version-check.ts, packages/cli/test/commands/cli.test.ts, packages/cli/test/commands/cli/upgrade.test.ts, packages/cli/test/lib/binary.test.ts, packages/cli/test/lib/delta-upgrade.mocked.test.ts, packages/cli/test/lib/delta-upgrade.test.ts, packages/cli/test/lib/ghcr.test.ts, packages/cli/test/lib/release-notes.test.ts, packages/cli/test/lib/upgrade.test.ts, and packages/cli/test/lib/version-check.test.ts.
• 🟡 (11:46) Diff statistics were exactly 17 files changed, 3,299 insertions, and 433 deletions. Per-file changes: upgrade.ts command 180; binary.ts 191; delta-upgrade.ts 170; errors.ts 8; ghcr.ts 213; release-notes.ts 134; library upgrade.ts 520; version-check.ts 21; commands/cli.test.ts 40; commands/cli/upgrade.test.ts 494; binary.test.ts 188; delta-upgrade.mocked.test.ts 14; delta-upgrade.test.ts 220; ghcr.test.ts 235; release-notes.test.ts 221; upgrade.test.ts 758; version-check.test.ts 125.
• 🟡 (11:46) Diff cleanliness check produced no output.
• 🟡 (11:47) Ancestry inspection showed a linear 19-commit series from base ec83887a16f780f32fba4b7d710bad262dba3a22 to head, ordered oldest to newest: 1. 04867eaf9b412a62d4b1ea1c59c2b382c557bd0b feat(cli): add toolkit upgrade bridge; 2. 9c874298e3b57515ba36d35140627a668a46dc7b fix(cli): address toolkit bridge review; 3. 723375b6ce4e37884e760fa0f848e7e7e3effcc9 fix(cli): address upgrade review findings; 4. dbee7e9f2a4555e044f74dfebad002cccfa43a1f test(cli): update toolkit upgrade fixtures; 5. 5ffa5cd0fe02c0a5dc5bec9a8a099f4135c0b447 fix(cli): harden upgrade source resolution; 6. c8c815bbecf472061ec02ab96d1a31f23f078d01 fix(cli): validate GitHub release pagination; 7. b6484e0fb1eb0f8bce68272d538f5c3b26cd5bd5 fix(cli): validate resolved upgrade metadata; 8. c6030fbf4d0c190f037c86d832edb6680d3e54ab fix(cli): bind nightly manifests to versions; 9. 2f9b5d0d26124d445a916b8bfc584ad518720584 fix(cli): isolate pinned upgrade resolution; 10. 4a1d5bad105c006193c68459175f5eb3c7f78e08 test(cli): update pinned version fixture; 11. e565b1afb39a341605adc883de8812851de7d581 fix(cli): validate stable upgrade metadata; 12. f1c10a6cb1a753b8c4b8c613cd78735c3f12cba6 fix(cli): preserve pinned upgrade contracts; 13. dcf6719995800d28d6f88a8c709abe4aa3d0b6db test(cli): validate GitHub request origin; 14. e22f0eba66298a7228a988a4adcf1ec5be85227b fix(cli): preserve source and cancellation provenance; 15. 878459c490576dbb7abb76d3a3dc1b5d9fc62c1f fix(cli): fail closed on upgrade metadata; 16. 7d62ffa8317f9b98be0dc4afec0a927c1cabb0b7 fix(cli): preserve paginated request cancellation; 17. cea7b2afba91f11f1cdbb1785ea97ba61159520c fix(cli): validate release response shapes; 18. a84012184c79c2566c7466aa6beda5f767199218 fix(cli): validate upgrade response bodies; 19. 9525f72c70fabbb23ec21d13cf86add58f6287cc fix(cli): harden upgrade metadata validation.
• 🔴 (11:48) User stated package managers always need network access to fetch and install packages; therefore offline upgrade is supported only for curl-installed binaries, and validateMethod() throws UpgradeError("unsupported_operation", "Offline upgrade is only supported for curl-installed binaries.") when offline && method !== "curl".
• 🔴 (11:48) User stated nightly builds are GitHub-only and pinned nightly-version validation should always use curl (GitHub) lookup regardless of the current installation method.
• 🔴 (11:48) User specified the CLI usage meaning sentry cli upgrade nightly as “Switch to nightly channel and update.”
• 🟡 (11:48) In packages/cli/src/commands/cli/upgrade.ts, channel switching while offline is rejected when resolveOpts.channelChanged && !versionArg, because the cached version belongs to the old/current channel and could install the wrong binary type. The error instructs: Run 'sentry cli upgrade' with network access to switch channels.
• 🟡 (11:48) Offline target resolution reads the cached version before persistChannelFn() because setReleaseChannel clears the version cache on channel changes; it logs Offline mode: using cached target ${target} and returns { kind: "target", target, offline: "explicit" }.
• 🟡 (11:48) validateMethod() in packages/cli/src/commands/cli/upgrade.ts was changed to remove its channel: ReleaseChannel parameter and derive pinnedVersion as CHANNEL_VERSIONS.has(versionArg ?? "") ? undefined : versionArg?.replace(VERSION_PREFIX_REGEX, "").
• 🟡 (11:48) Homebrew validation now rejects a pinned version only when method === "brew" && pinnedVersion && !isNightlyVersion(pinnedVersion), preserving nightly-version handling while continuing to emit Homebrew does not support installing a specific version. Run 'brew upgrade getsentry/tools/sentry' to upgrade to the latest formula version. for unsupported stable pins.
• 🟡 (11:48) Upgrade resolution now compares CLI_VERSION with resolvedTarget rather than target; the up-to-date result reports targetVersion: resolvedTarget, and successful target resolution returns { kind: "target", target: resolvedTarget, source }.
• 🟡 (11:48) Upgrade execution now preserves source provenance by passing source into executeUpgrade(method, target, downloadTag, offline, setMessage, source).
• 🟡 (11:48) Nightly download-tag behavior remains: use rolling NIGHTLY_TAG only for latest-nightly upgrades where channel === "nightly" && !versionArg; a specific version argument uses its own tag so the correct release is downloaded.