From 67dc4d157d58b9c9d2f576e89752113415a536d1 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:43:07 +0000 Subject: [PATCH 1/7] Add repo-tuned Warden review skills Co-Authored-By: Amir Mujacic --- .agents/skills/unity-ci-review/SKILL.md | 70 +++++++++++++++++++ .../unity-ci-review/references/powershell.md | 28 ++++++++ .agents/skills/unity-sdk-review/SKILL.md | 70 +++++++++++++++++++ .../references/editor-build.md | 49 +++++++++++++ .../references/native-bridges.md | 43 ++++++++++++ warden.toml | 69 ++++++++++++++++++ 6 files changed, 329 insertions(+) create mode 100644 .agents/skills/unity-ci-review/SKILL.md create mode 100644 .agents/skills/unity-ci-review/references/powershell.md create mode 100644 .agents/skills/unity-sdk-review/SKILL.md create mode 100644 .agents/skills/unity-sdk-review/references/editor-build.md create mode 100644 .agents/skills/unity-sdk-review/references/native-bridges.md create mode 100644 warden.toml diff --git a/.agents/skills/unity-ci-review/SKILL.md b/.agents/skills/unity-ci-review/SKILL.md new file mode 100644 index 000000000..2cb5dff76 --- /dev/null +++ b/.agents/skills/unity-ci-review/SKILL.md @@ -0,0 +1,70 @@ +--- +name: unity-ci-review +description: Finds real breakage in the Sentry Unity SDK's GitHub Actions workflows, PowerShell and shell scripts, MSBuild targets, packaging, and integration-test harness. Use for changes under .github/, scripts/, build/, test/Scripts.*, sample build scripts, Directory.Build.*, csproj, and package metadata. Reports broken or falsely green CI, wrong artifacts, and broken local developer tooling. Excludes SDK runtime code, style, and AppSec. +allowed-tools: Read Grep Glob +--- + +You review the build, CI, packaging, and test-harness code of the Sentry Unity SDK. +Report only failures that you can prove from the code: a concrete trigger (event, matrix entry, runner image, platform, or local invocation), and a deterministic symptom: a broken job, a job that passes when it should fail, a wrong or missing artifact, or a developer script that cannot work. + +## Facts That Change Verdicts + +- `ci.yml` is the entry point. It calls reusable workflows (`sdk.yml`, `build.yml`, `test-create.yml`, `test-build-*.yml`, `test-run-*.yml`) and passes `create-unity-matrix.yml` outputs to them. +- Many jobs do **not** use `needs:` for their inputs. They poll for an artifact by name in the same run with `.github/actions/wait-for-artifact` (up to an hour). Removing or renaming a producer, a matrix entry, or an artifact name makes every consumer hang and then fail. Trace artifact names from the producer to each consumer. +- That action calls the artifacts API, so the calling job needs `actions: read`. When a job lists `permissions`, every scope it does not list is `none`. +- Unity versions: PRs run `2021.3` and the newest version; `main` runs the full list in `create-unity-matrix.yml`; `chore/unity-*` PRs run only their own version. Exact versions and changesets are in `scripts/unity-versions.json`. The package itself is built with Unity 2021.3. +- Runner images move. `macos-latest`, `macos-15`, `ubuntu-latest`, and `windows-latest` drop old Xcode versions, iOS simulator runtimes, and Android build tools. A pinned Xcode, simulator, or SDK version must exist on the image the job runs on. +- Scripts are mostly PowerShell 7 (`pwsh`). The harness (`scripts/run-tests.ps1`, `scripts/build-sample.ps1`, `scripts/unity-*.ps1`) drives either a running Editor through Unity Pipeline or headless `unity` CLI. The two paths must accept the same parameters and report results the same way. +- `test/Scripts.Tests/*.snapshot` lock package contents. `test/Scripts.Tests/test-plugin-platforms.ps1` checks plugin importer settings. Packaging changes that add, move, or drop shipped files must update both. +- `bootstrap.ps1` and the download scripts must be safe to re-run after a partial failure. + +## Load Only When Relevant + +| Read | When the hunk touches | +|------|-----------------------| +| `references/powershell.md` | Any `*.ps1`, or `shell: pwsh` steps | +| `docs/agent-guides/ci.md` | Workflow ownership, artifacts, or the Unity matrix | +| `docs/agent-guides/packaging.md` | `package/`, `scripts/pack.ps1`, `scripts/repack.ps1`, `.craft.yml`, snapshots | +| `docs/agent-guides/build.md` | `Directory.Build.*`, `build/*.targets`, native SDK build targets | + +## What To Report + +These patterns caused most of the fixed CI and build bugs in this repo: + +1. **Producer and consumer drift.** A matrix entry, job, artifact name, output, or reusable-workflow input changes on one side only. This includes x86, ARM64, or Mono jobs that hardcode one Unity version or artifact name while the matrix changes it. +2. **Unavailable toolchains.** Xcode, iOS simulator, Android build-tools or NDK, or Docker image versions that the selected runner image or container does not provide. Also simulator destinations or architectures that do not match the runner's CPU (Apple Silicon `macos-*`). +3. **False success.** A failing native command whose exit code is ignored, a status output taken from a step that did not run on this path (for example an emulator step vs a Redroid step), a wait loop that accepts a stale or previous result, or an assertion script that checks output that the CI path never writes. +4. **Permissions.** An explicit `permissions:` block that drops a scope that a step, action, or reusable workflow needs. +5. **Temporary edits left in.** Pinned matrices, commented-out steps, `if: false`, or "revert before merge" notes that would ship. +6. **Cache and skip logic.** Cache keys that omit an input script or version file. "Already exists, skip" checks that ignore version bumps or treat a partial download as complete. +7. **MSBuild path logic.** Property and item metadata changes that move a resolved path up or down a directory level (`UnityRoot`, `HubInstallDir`), or version parsing that only accepts one file format. +8. **Harness parity.** Pipeline and headless paths that interpret `-Filter`, result parsing, or failure output differently, or a dropped flag such as `--non-interactive` that lets a headless run block. + +## What Not To Report + +Maintainers rejected these as false positives: + +- Arguments that look unread but are forwarded: Unity CLI passes unknown arguments through to `-executeMethod` targets, and `SampleBuilder` reads them. +- Output checks on directories that the script creates before Unity runs, when Unity's own exit code is checked too. +- Hypothetical failures in pinned environments that already fail loudly, such as an Editor path probe for a pinned Unity version, or an internal Unity property lookup that throws when renamed. +- PowerShell semantics you have not confirmed. For example, `"WebGL" -in "WebGL"` is `$true`: a scalar right-hand side is a one-element collection, not a list of characters. +- Simulator architecture claims for Unity 2021.3 exports without evidence from the build settings in the repo. +- Version catalog formats or upstream file layouts in submodules (`modules/**`). They are not in the checkout. Code that intentionally supports one format and fails with a clear error is fine. +- Known follow-ups that the PR description or a comment names. +- Secrets, injection, and `pull_request_target` risks. `security-review` covers those. +- Style, naming, comments, duplicate CHANGELOG lines, and Markdown. + +## Severity + +| Level | Use for | +|-------|---------| +| high | CI broken for every PR or for `main`, a release or package artifact missing files or shipping stale ones, a required job that always passes, or bootstrap broken for a fresh clone. | +| medium | One platform, Unity version, or runner path broken or falsely green. A developer script that fails in a documented mode. A retry or re-run that cannot recover. | + +Report nothing below medium. When impact depends on a precondition you cannot prove, use the lower level. + +## Finding Format + +- Title: the exact breakage and its trigger, for example "x86 job waits for `test-2021.3` artifact on Unity-bump PRs". +- Description: one or two sentences with what breaks, on which path, and the fix. +- `verification`: two to five bullets of code facts tracing the trigger to the symptom: producer and consumer names, the step that did or did not run, and the line that hides the failure. diff --git a/.agents/skills/unity-ci-review/references/powershell.md b/.agents/skills/unity-ci-review/references/powershell.md new file mode 100644 index 000000000..37bbddf3c --- /dev/null +++ b/.agents/skills/unity-ci-review/references/powershell.md @@ -0,0 +1,28 @@ +# PowerShell Pitfalls + +Read this when a hunk changes a `*.ps1` file or a `shell: pwsh` step. The items come from fixed bugs and false-positive reports in this repo. + +## Error Handling + +- `$ErrorActionPreference = 'Stop'` does not stop on a failing native command (`dotnet`, `docker`, `gh`, `unity`, `xcodebuild`) unless `$PSNativeCommandUseErrorActionPreference = $true`. Several scripts set it. A block that sets it to `$false` must check `$LASTEXITCODE` itself. +- `try { ... } catch { }` around a polling loop that swallows every exception keeps retrying errors that will never clear (wrong path, rejected request) until the timeout. It should rethrow those. +- A retry helper used by some wait functions but not by a new one gives that one a single-failure path. +- `exit` inside a dot-sourced script (`. ./common.ps1`) ends the caller too. `return` from a script does not set an exit code. + +## Values And Strings + +- Inside double quotes, only the variable expands: `"$obj.Prop"` is the object's string form followed by the literal `.Prop`. Property access needs `$()`. So `"$_.exe"` is correct when `$_` is a string (`"Windows-x86_64.exe"`); do not report it. It is a bug only when the code meant a property of an object. +- `Sort-Object Name` on version folders (`30.0.3`, `34.0.0`, `9.0.0`) sorts as text. Use `Sort-Object { [version]$_.Name }`. +- Comparison operators are case-insensitive by default (`-eq`, `-like`, `-match`). Use `-ceq` and friends when case matters, for example Unity plugin folder names on Linux. +- An empty pipeline result is `$null`, and a single result is a scalar, not an array. Code that indexes or iterates the result must handle both. +- Member access on a collection enumerates its items (`$matches.Groups`, `$files.Name`). Do not report that as a missing property. + +## Paths And Working Directory + +- `$PSScriptRoot` is the script's directory. Relative paths passed to `dotnet`, `git`, or `unity` resolve against the caller's current directory. Scripts that can run from anywhere must build paths from `$PSScriptRoot` or `Push-Location` first. +- `Test-Path` on a directory the script created before the tool ran is always true. It proves nothing about the tool's output unless the tool's exit code is checked too. + +## Idempotency + +- A download or setup step that creates its target directory before it finishes must remove it on failure, or later runs must validate the contents. An "already exists, skip" check otherwise turns one failed run into a permanent failure. +- "Skip if present" checks must also compare the version (`sentry-cli.properties`, `scripts/unity-versions.json`) when the version can change. diff --git a/.agents/skills/unity-sdk-review/SKILL.md b/.agents/skills/unity-sdk-review/SKILL.md new file mode 100644 index 000000000..8fd96bcac --- /dev/null +++ b/.agents/skills/unity-sdk-review/SKILL.md @@ -0,0 +1,70 @@ +--- +name: unity-sdk-review +description: Finds real correctness bugs in Sentry Unity SDK runtime, Editor, and native bridge code. Use for C#, Objective-C, and C changes under src/, package-dev/, and test/. Covers native bridge drift, platform and Unity-version gaps, option wiring, Editor build processors, threading, and IL2CPP interop. Excludes CI, scripts, style, and AppSec. +allowed-tools: Read Grep Glob +--- + +You review changes to the Sentry Unity SDK, which wraps sentry-dotnet and ships the native SDKs (sentry-cocoa, sentry-java, sentry-native) to Unity players on many platforms. +Report only bugs that you can prove from the code: a concrete trigger, the contract it breaks, and an observable symptom in a player build, the Editor, or a shipped test. + +## Facts That Change Verdicts + +- `src/` is compiled once with `dotnet build` against Unity 2021.3 assemblies, then shipped to Unity 2021.3 through 6000.x. Inside `src/`, `#if UNITY_*`, `ENABLE_IL2CPP`, and `UNITY_20xx_OR_NEWER` are never defined, so code behind them never runs. Platform and version branching in `src/` happens at runtime (`Application.platform`, `ApplicationAdapter`, `SentryUnityVersion.IsNewerOrEqualThan`). Only the `SENTRY_NATIVE_*` defines from the chained `Csc` targets in `Sentry.Unity.Native.csproj` exist. +- Unity APIs or enum values newer than 2021.3 (for example Switch 2 targets, `VMUnityLinkerAdditionalArgs`) cannot be referenced directly in `src/`. The code compares names (`target.ToString()`) or uses reflection, behind a runtime version check. +- `package-dev/Runtime/*.cs` and `package-dev/Editor/*.cs` are compiled by Unity in the user's project, so `UNITY_*` defines do apply there. +- Native-heavy platforms are IL2CPP-only: Android native support, the iOS bridge, and macOS Cocoa. The experimental macOS sentry-native backend supports Mono too. +- iOS and macOS share `src/Sentry.Unity.iOS/` (`SentryCocoaBridgeProxy`, `SentryNativeCocoa`). An iOS-only option or flag applied there also changes macOS. +- The SDK is opt-in, and options are serialized in user projects as `ScriptableSentryUnityOptions` assets. Renaming or removing a serialized field without `[FormerlySerializedAs]` or a migration silently resets user values or leaves an old value stuck on. +- Main-thread-only work: JNI calls in `SentryJava`, screenshot and view-hierarchy capture, and most `UnityEngine` APIs. Background callers go through `MainThreadData.IsMainThread()` checks or `SentryMonoBehaviour` queues. +- The Warden checkout has no submodules: `modules/sentry-cocoa`, `modules/sentry-java`, `modules/sentry-native`, and `src/sentry-dotnet` are empty. + +## Load Only When Relevant + +| Read | When the hunk touches | +|------|-----------------------| +| `references/native-bridges.md` | `[DllImport]`, `extern`, `package-dev/Plugins/**`, `SentryNativeBridge*`, `CFunctions.cs`, JNI calls, marshalling | +| `references/editor-build.md` | `src/Sentry.Unity.Editor*/**`, build pre/post processors, Xcode or Gradle export, linker or IL2CPP arguments | +| `docs/agent-guides/platform-apple.md`, `platform-android.md`, `platform-native.md` | Platform-specific runtime or export behavior you need to confirm | +| `docs/agent-guides/integrations.md` | `src/Sentry.Unity/Integrations/**`, initialization order, screenshots, ANR | + +## What To Report + +These patterns caused most of the bugs that were fixed in this repo. Check each one the hunk can reach. + +1. **Native entry-point drift.** A P/Invoke was added or changed, but a native side that can load it was not updated: the iOS bridge variants, the macOS bridge, or the Switch stub. Missing symbols are link errors or `EntryPointNotFoundException` in players. See `references/native-bridges.md`. +2. **Platform branch gaps.** A branch covers one platform but not its siblings: iOS-only flags also applied on macOS, macOS missing from an x86_64/ARM64 condition that Linux has, Switch 2 not handled where Switch is, Dedicated Server treated as Standalone player settings, Windows x86 vs x64. +3. **Option wiring breaks.** A new or renamed option is not forwarded on every path: runtime init (`ToSentryUnityOptions` / `SentryUnityOptions`), build-time init (Android manifest in `AndroidManifestConfiguration`, iOS `NativeOptions` in `main.mm`), and the native bridge init. Also check `Experimental.*` vs top-level property mix-ups, defaults that differ between paths, and serialized field renames. +4. **Build state that outlives its build.** Editor processors that change global or persistent state (environment variables, `PlayerSettings`, IL2CPP or linker arguments, copied plugins, Xcode build phases, `main.mm`) without restoring it. Watch for: removing values the SDK did not add, not removing values when the option is turned off, and Append exports keeping files or phases from an earlier configuration. +5. **Null and early-return paths in init and shutdown.** Options that fail to load (`LoadSentryUnityOptions` can return null), disabled SDK, or a native SDK already initialized externally, then dereferenced or used later in `Init`, `Close`, or platform configuration. +6. **Wrong thread or wrong frame.** Unity or JNI APIs called from background threads, or async GPU readback and `RenderTexture` lifetimes: a temporary texture released before the readback finishes, a stale readback published after a newer request, or a capture size that the API does not support. +7. **Batch-mode and domain-reload assumptions.** Editor code that relies on `EditorApplication.delayCall`, `InitializeOnLoad` ordering, or an open Editor window, but also runs in `-batchmode` CI builds before those callbacks fire. +8. **Tests that hide a regression.** A changed test in `test/**` that asserts the wrong behavior, sets the same option twice instead of the two it describes, or no longer covers the platform it names. + +## What Not To Report + +Maintainers rejected these as false positives: + +- Claims that a sentry-cocoa, sentry-java, sentry-native, or sentry-dotnet API is missing, renamed, or has a different signature. Their sources are not in the checkout. Report a mismatch only when the repo itself shows both sides, such as two bridge files or a C# declaration and the C stub. +- Stale-file bugs in a fresh player build. Unity deletes and recreates the `.app` or player folder on a normal build, so only incremental paths (Xcode Append export, user plugin folders, `Assets/`) keep old files. +- Unity callback lifecycle claims you cannot show in the code. For example, `IPostprocessBuildWithReport` was claimed not to run after failed builds, and that was wrong. +- Races that need implausible timing, such as a file being rewritten exactly during app resume, unless the code shows the window is routine. +- Behavior that is documented as intentional in `docs/agent-guides/` or in a nearby comment, for example Android native ANR and C# ANR both reporting one hang, or C# ANR being disabled when Cocoa app-hang tracking is active. +- Experimental options (`Experimental.*`) whose limitations the PR or code states as known follow-ups. +- Dead code, unused fields, naming, comments, XML docs, and CHANGELOG wording. +- Generated or downloaded artifacts under `package-dev/` (`*.dll`, `*.meta`, native libraries) and submodule pointer bumps. +- Security issues. `security-review` runs separately. + +## Severity + +| Level | Use for | +|-------|---------| +| high | Crash, link failure, or build failure on a supported platform in the default configuration. Events, crashes, or symbols silently not reported. User options reset or ignored. | +| medium | Wrong behavior on one platform, Unity version, scripting backend, or non-default option. Duplicate reports. State that leaks into a later build in the same Editor session. | + +Report nothing below medium. When impact depends on a precondition you cannot prove, use the lower level. + +## Finding Format + +- Title: the exact bug and its trigger, for example "macOS gets iOS app-hang flag from shared Cocoa init". +- Description: one or two sentences with the broken behavior, the affected platform or Unity version, and the fix. +- `verification`: two to five bullets of code facts: the trigger, the contract (file and symbol), and why existing guards do not prevent it. diff --git a/.agents/skills/unity-sdk-review/references/editor-build.md b/.agents/skills/unity-sdk-review/references/editor-build.md new file mode 100644 index 000000000..7a0e487a3 --- /dev/null +++ b/.agents/skills/unity-sdk-review/references/editor-build.md @@ -0,0 +1,49 @@ +# Editor Build Pipeline + +Read this when a hunk touches `src/Sentry.Unity.Editor/**`, `src/Sentry.Unity.Editor.iOS/**`, or `package-dev/Editor/**`. + +## Processors And Order + +| Processor | Hook | Order | +|-----------|------|-------| +| `Native/{Switch,PS5,Xbox}NativePluginBuildPreProcess` | `IPreprocessBuildWithReport` | -100 | +| `Il2CppBuildPreProcess`, `MonoLinkerProcessor` | `IPreprocessBuildWithReport` | 0 | +| `WebGL/BuildPreProcess` | `IPreprocessBuildWithReport` | 1 | +| `Native/BuildPostProcess` (Windows, Linux, macOS, consoles) | `IPostprocessBuildWithReport` | 1 | +| `Android/AndroidManifestConfiguration` | `IPostGenerateGradleAndroidProject` | `PostGenerateGradleProjectCallbackOrder` | +| `Sentry.Unity.Editor.iOS/BuildPostProcess` | `[PostProcessBuild(1)]` | 1 | + +Options are loaded with `SentryScriptableObject.LoadOptions(isBuilding: true)`, which can return null. Every processor must handle null and a disabled SDK. + +## Build Targets + +- Use `NamedBuildTargets.FromBuildReport(report)` for player settings such as the scripting backend. `BuildTargetGroup.Standalone` covers Dedicated Server, which has its own `NamedBuildTarget.Server` settings. Reading the group alone gets the player's backend. +- `GetSubtarget()` throws on non-Standalone groups. Only call it after checking the group. +- Switch 2 exists only in newer Unity versions. Compare it through `SwitchBuildTargets.IsSwitch2()` and `IsSwitchFamily()`. A `BuildTarget.Switch` or `BuildTargetGroup.Switch` check alone misses Switch 2. +- Unity plugin CPU folder names are case sensitive: `x86_64` and `ARM64`, not `arm64`. +- Windows ships `x86/` and `x64/` folders. `BuildTarget.StandaloneWindows` is x86. +- `nameof(x)` returns the identifier `"x"`, not its value. That bug has shipped here before in plugin path lookups. + +## State That Must Not Leak + +The Editor process outlives each build, and exported projects can be built again with **Append**. Check: + +- **Global arguments**: `PlayerSettings.SetAdditionalIl2CppArgs`, the UnityLinker diagnostic switch (`VMUnityLinkerAdditionalArgs`, Unity 6.5+ only), and environment variables. The SDK may only add or remove its own flags (`--emit-source-mapping`, `--link-symbols`). It must leave user flags alone, and it must remove its flag when the controlling option (`Il2CppLineNumberSupportEnabled`) is off. +- **Xcode Append exports** (`SentryXcodeProject`, `NativeMain`, iOS `BuildPostProcess`): files copied once (`SentryNativeBridge*.m`, frameworks), build phases (symbol upload on `UnityFramework` vs the main target), and `main.mm` initialization stay from the previous export. When an option switch changes what the export needs, the code must either replace the old artifact or fail with a `BuildFailedException` that asks for a Replace export. That is the repo convention. +- **User plugin folders** (`Assets/Plugins/Sentry/...`): Switch stubs are copied there while the libraries are missing, and must be deleted once the libraries exist, so that a stub never links next to the real library. +- **Native backend switch** (`Sentry~` vs `SentryNative~`): stale handler artifacts from the other backend must be cleared. + +A fresh, non-Append player build recreates its output folder. Do not report stale files there. + +## Option Paths + +A user option can reach a player through several paths. A change to one path usually needs the others: + +1. Runtime: `ScriptableSentryUnityOptions` → `ToSentryUnityOptions` → `SentryUnityOptions` → platform `Configure*` → native bridge options. +2. Android build-time: `AndroidManifestConfiguration` writes `io.sentry.*` meta-data. Runtime init writes `io.sentry.auto-init=false`. +3. iOS build-time: `NativeOptions` generates the options dictionary in `main.mm`. +4. Editor UI: `ConfigurationWindow/*Tab.cs` edits serialized fields. Removing a toggle while the runtime still reads the field leaves old saved values stuck on. + +## Batch Mode + +CI and users build with `-batchmode -executeMethod`. `EditorApplication.delayCall`, `InitializeOnLoad` work scheduled for later, and window-driven setup may not run before the build starts. Preprocess steps must not depend on them. diff --git a/.agents/skills/unity-sdk-review/references/native-bridges.md b/.agents/skills/unity-sdk-review/references/native-bridges.md new file mode 100644 index 000000000..fc49e3672 --- /dev/null +++ b/.agents/skills/unity-sdk-review/references/native-bridges.md @@ -0,0 +1,43 @@ +# Native Bridges + +Read this when a hunk adds, removes, or changes a P/Invoke, a JNI call, or a native bridge source. + +## Where Each Entry Point Must Exist + +| C# declaration | Library name | Native sides that must match | +|----------------|--------------|------------------------------| +| `src/Sentry.Unity.iOS/SentryCocoaBridgeProxy.cs` (`EntryPoint = "SentryNativeBridge*"`) | `__Internal` | `package-dev/Plugins/iOS/SentryNativeBridge.m`, `SentryNativeBridgeNoOp.m`, `SentryNativeBridgeExternal.m`, and `package-dev/Plugins/macOS/SentryNativeBridge.m` | +| `src/Sentry.Unity.iOS/NativeContextWriter.cs` (`SentryNativeBridgeWriteScope`) | `__Internal` | Same four bridge files | +| `src/Sentry.Unity.Native/CFunctions.cs`, `SentryNativeBridge.cs` (`sentry_*`) | `SentryNativeLibrary.Name`: `sentry-native` on desktop, `sentry` on Android, PS5, and Xbox, `__Internal` on Switch | sentry-native exports (not in the checkout), and `package-dev/Plugins/Switch/SentryStub~/sentry_native_stubs.c` for every symbol the Switch build binds | +| `src/Sentry.Unity.Native/SentryNativeSwitch.cs` | `__Internal` | `sentry_native_stubs.c` | +| `src/Sentry.Unity.Android/SentryNative.cs`, `SentryJava.cs` | JNI / `sentry` | sentry-java and the NDK (not in the checkout) | + +Existing guards are incomplete: + +- `test/Sentry.Unity.Editor.iOS.Tests/SentryNativeBridgeTests.cs` checks only that each `SentryCocoaBridgeProxy` entry point **name** appears in the three iOS bridge files. It does not check the macOS bridge, `NativeContextWriter`, argument count, or argument types. +- `SwitchNativeStubTests.Stub_ContainsEverySwitchNativeBinding` checks that the Switch stub covers the Switch `__Internal` bindings. + +So report: + +- An entry point that is added or renamed in C# but missing from any bridge file in the table. On iOS this is a link error. On macOS it is `EntryPointNotFoundException` at init. +- A parameter that is added, removed, or reordered on one side only. The NoOp and External bridges are easy to miss. +- A P/Invoke that becomes reachable on Switch without a matching stub function in `sentry_native_stubs.c`. +- A bridge function that calls an Objective-C class that another bridge file has already migrated away from (for example `SentrySDK` vs `SentryObjCSDK`), when the repo shows the migration. +- In `SentryNativeBridgeExternal.m`: a selector called without a `respondsToSelector:` check. Unity builds without Objective-C exceptions, so an unknown selector crashes the host app. + +## Marshalling Under IL2CPP + +- `string[]` or other arrays passed to `const char **` need an explicit count parameter, and the native side must not read past it. Without `[MarshalAs(UnmanagedType.LPArray, SizeParamIndex = n)]` the layout depends on the default marshaller. Report a mismatch only when the native signature in the repo disagrees with the C# side. +- `bool` crossing to C defaults to a 4-byte `BOOL`. Objective-C `BOOL` is 1 byte (`signed char`). The repo uses `sbyte` or `int` with explicit conversion. A raw `bool` paired with a 1-byte native type is a bug. +- Delegates passed to native code must be `static` methods with `[MonoPInvokeCallback(typeof(...))]` and kept alive. Instance-method or lambda callbacks fail under IL2CPP. +- `va_list` handling in `SentryNativeBridge.cs`: on x86_64 System V and Linux AArch64, `va_list` is a struct passed by reference, and `UseLibC` selects `vsnprintf` from libc. A platform added to the native logger path needs the same treatment as its ABI siblings. +- `string` returned from native code is freed by the marshaller. Returning a pointer that the native side still owns (or that was not allocated with `malloc` or `strdup`) corrupts the heap. + +## Threading + +- `SentryJava` methods that touch JNI must run on the Unity main thread, or attach the thread with `AndroidJNI.AttachCurrentThread` and detach it afterwards. Existing methods check `MainThreadData.IsMainThread()` first. A new JNI call without either is a bug. +- Scope observers (`NativeScopeObserver`, `AndroidJavaScopeObserver`) can be called from any thread. + +## Do Not Report + +- Missing stubs for PS5 or Xbox. Their libraries are supplied by the user. diff --git a/warden.toml b/warden.toml new file mode 100644 index 000000000..dfcd77a0f --- /dev/null +++ b/warden.toml @@ -0,0 +1,69 @@ +# Warden configuration for sentry-unity. +# https://github.com/getsentry/warden +# +# The org workflow (getsentry/.github) layers this file on top of the org base +# config. The base runs `security-review`; do not redeclare it here, Warden +# ignores repo skills that share a base skill's name. +# +# Repo skills inherit the base model, effort, runtime, and incrementalApp. +# They do not inherit the base reportOn, failOn, or ignorePaths, so they use +# the action defaults: reportOn "medium", failOn "high", failCheck false. +# With failCheck false, findings are comments and never fail the check. + +version = 1 + +# Runtime, Editor, and native bridge code, plus the unit tests that cover it. +[[skills]] +name = "unity-sdk-review" +incremental = true +paths = [ + "src/**/*.cs", + "package-dev/**/*.cs", + "package-dev/Plugins/**/*.m", + "package-dev/Plugins/**/*.mm", + "package-dev/Plugins/**/*.c", + "package-dev/Plugins/**/*.cpp", + "package-dev/Plugins/**/*.h", + "package-dev/Plugins/**/*.pro", + "package*/**/*.asmdef", + "test/**/*.cs", +] +ignorePaths = [ + "src/sentry-dotnet/**", + "test/Scripts.Integration.Test/**", + "**/*.meta", +] + +[[skills.triggers]] +type = "pull_request" +actions = ["opened", "synchronize", "reopened"] + +# Workflows, scripts, MSBuild, packaging, and the integration-test harness. +[[skills]] +name = "unity-ci-review" +incremental = true +paths = [ + ".github/**", + "scripts/**", + "build/**", + "**/*.ps1", + "**/*.sh", + "**/Directory.Build.props", + "**/Directory.Build.targets", + "**/*.csproj", + "global.json", + ".craft.yml", + "package/package.json", + "package-dev/package.json", + "test/Scripts.Integration.Test/**", + "test/Scripts.Tests/**", + "samples/*/Assets/Editor/**/*.cs", +] +ignorePaths = [ + "**/*.md", + "**/*.meta", +] + +[[skills.triggers]] +type = "pull_request" +actions = ["opened", "synchronize", "reopened"] From 3551838bad92d932a72fcd21357f0cdeffcf6b92 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:55:31 +0000 Subject: [PATCH 2/7] Repeat org Warden report thresholds in repo config Co-Authored-By: Amir Mujacic --- .agents/skills/unity-ci-review/SKILL.md | 3 ++- .agents/skills/unity-sdk-review/SKILL.md | 3 ++- warden.toml | 12 +++++++++--- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.agents/skills/unity-ci-review/SKILL.md b/.agents/skills/unity-ci-review/SKILL.md index 2cb5dff76..61ffe043a 100644 --- a/.agents/skills/unity-ci-review/SKILL.md +++ b/.agents/skills/unity-ci-review/SKILL.md @@ -60,8 +60,9 @@ Maintainers rejected these as false positives: |-------|---------| | high | CI broken for every PR or for `main`, a release or package artifact missing files or shipping stale ones, a required job that always passes, or bootstrap broken for a fresh clone. | | medium | One platform, Unity version, or runner path broken or falsely green. A developer script that fails in a documented mode. A retry or re-run that cannot recover. | +| low | A real but narrow breakage, such as a cache key missing an input, wrong output in a failure summary, or a developer script that misbehaves only with uncommon arguments. | -Report nothing below medium. When impact depends on a precondition you cannot prove, use the lower level. +Do not report style, dead code, or suspicion as low. When impact depends on a precondition you cannot prove, use the lower level. ## Finding Format diff --git a/.agents/skills/unity-sdk-review/SKILL.md b/.agents/skills/unity-sdk-review/SKILL.md index 8fd96bcac..9d6465998 100644 --- a/.agents/skills/unity-sdk-review/SKILL.md +++ b/.agents/skills/unity-sdk-review/SKILL.md @@ -60,8 +60,9 @@ Maintainers rejected these as false positives: |-------|---------| | high | Crash, link failure, or build failure on a supported platform in the default configuration. Events, crashes, or symbols silently not reported. User options reset or ignored. | | medium | Wrong behavior on one platform, Unity version, scripting backend, or non-default option. Duplicate reports. State that leaks into a later build in the same Editor session. | +| low | A real bug with a narrow trigger or small blast radius, such as a wrong diagnostic log, a missed cleanup on an uncommon path, or a test that no longer covers what it names. | -Report nothing below medium. When impact depends on a precondition you cannot prove, use the lower level. +Do not report style, dead code, or suspicion as low. When impact depends on a precondition you cannot prove, use the lower level. ## Finding Format diff --git a/warden.toml b/warden.toml index dfcd77a0f..0c91ffef2 100644 --- a/warden.toml +++ b/warden.toml @@ -6,12 +6,18 @@ # ignores repo skills that share a base skill's name. # # Repo skills inherit the base model, effort, runtime, and incrementalApp. -# They do not inherit the base reportOn, failOn, or ignorePaths, so they use -# the action defaults: reportOn "medium", failOn "high", failCheck false. -# With failCheck false, findings are comments and never fail the check. +# They do not inherit the base reportOn, failOn, failCheck, requestChanges, or +# ignorePaths, so the org policy values are repeated below. Findings of every +# severity are posted as comments and never fail the check or request changes. version = 1 +[defaults] +reportOn = "low" +failOn = "off" +failCheck = false +requestChanges = false + # Runtime, Editor, and native bridge code, plus the unit tests that cover it. [[skills]] name = "unity-sdk-review" From d82e6799f2302e2e313a097ab5ad7b74d775a1c1 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 12:12:18 +0000 Subject: [PATCH 3/7] Skip draft PRs in Warden triggers Co-Authored-By: Amir Mujacic --- warden.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/warden.toml b/warden.toml index 0c91ffef2..7404450eb 100644 --- a/warden.toml +++ b/warden.toml @@ -43,6 +43,7 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" actions = ["opened", "synchronize", "reopened"] +draft = false # Workflows, scripts, MSBuild, packaging, and the integration-test harness. [[skills]] @@ -73,3 +74,4 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" actions = ["opened", "synchronize", "reopened"] +draft = false From 541f7e85f9af231d0d30e91546494874ab9aa943 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 12:16:15 +0000 Subject: [PATCH 4/7] Run Warden skills when a PR is marked ready Co-Authored-By: Amir Mujacic --- warden.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/warden.toml b/warden.toml index 7404450eb..f76bab540 100644 --- a/warden.toml +++ b/warden.toml @@ -42,7 +42,7 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" -actions = ["opened", "synchronize", "reopened"] +actions = ["opened", "synchronize", "reopened", "ready_for_review"] draft = false # Workflows, scripts, MSBuild, packaging, and the integration-test harness. @@ -73,5 +73,5 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" -actions = ["opened", "synchronize", "reopened"] +actions = ["opened", "synchronize", "reopened", "ready_for_review"] draft = false From f4049a0e807e8fd2ad61a52e885da2a2afe5c547 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 12:21:00 +0000 Subject: [PATCH 5/7] Drop unused ready_for_review trigger The org Warden workflow does not start on ready_for_review, so this action never matches. Co-Authored-By: Amir Mujacic --- warden.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/warden.toml b/warden.toml index f76bab540..7404450eb 100644 --- a/warden.toml +++ b/warden.toml @@ -42,7 +42,7 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" -actions = ["opened", "synchronize", "reopened", "ready_for_review"] +actions = ["opened", "synchronize", "reopened"] draft = false # Workflows, scripts, MSBuild, packaging, and the integration-test harness. @@ -73,5 +73,5 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" -actions = ["opened", "synchronize", "reopened", "ready_for_review"] +actions = ["opened", "synchronize", "reopened"] draft = false From 530dba4cc03e2f7e88d2a301c0bc220e97b2d1c7 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 12:22:49 +0000 Subject: [PATCH 6/7] Review draft PRs with Warden Match getsentry/sentry: drop draft = false so skills also run on draft PRs. Co-Authored-By: Amir Mujacic --- warden.toml | 2 -- 1 file changed, 2 deletions(-) diff --git a/warden.toml b/warden.toml index 7404450eb..0c91ffef2 100644 --- a/warden.toml +++ b/warden.toml @@ -43,7 +43,6 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" actions = ["opened", "synchronize", "reopened"] -draft = false # Workflows, scripts, MSBuild, packaging, and the integration-test harness. [[skills]] @@ -74,4 +73,3 @@ ignorePaths = [ [[skills.triggers]] type = "pull_request" actions = ["opened", "synchronize", "reopened"] -draft = false From ef3bd39a36955ff79c795c487061e08f0096d81c Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Mon, 16 Nov 2026 14:07:35 +0100 Subject: [PATCH 7/7] Tighten Warden skill rules that could hide real bugs --- .agents/skills/unity-ci-review/SKILL.md | 2 +- .agents/skills/unity-sdk-review/SKILL.md | 4 ++-- .agents/skills/unity-sdk-review/references/native-bridges.md | 1 + modules/sentry-java | 2 +- warden.toml | 2 +- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.agents/skills/unity-ci-review/SKILL.md b/.agents/skills/unity-ci-review/SKILL.md index 61ffe043a..31c2eda93 100644 --- a/.agents/skills/unity-ci-review/SKILL.md +++ b/.agents/skills/unity-ci-review/SKILL.md @@ -50,7 +50,7 @@ Maintainers rejected these as false positives: - PowerShell semantics you have not confirmed. For example, `"WebGL" -in "WebGL"` is `$true`: a scalar right-hand side is a one-element collection, not a list of characters. - Simulator architecture claims for Unity 2021.3 exports without evidence from the build settings in the repo. - Version catalog formats or upstream file layouts in submodules (`modules/**`). They are not in the checkout. Code that intentionally supports one format and fails with a clear error is fine. -- Known follow-ups that the PR description or a comment names. +- Known follow-ups that the PR description names, unless the code is itself a temporary edit that would ship (item 5 above). - Secrets, injection, and `pull_request_target` risks. `security-review` covers those. - Style, naming, comments, duplicate CHANGELOG lines, and Markdown. diff --git a/.agents/skills/unity-sdk-review/SKILL.md b/.agents/skills/unity-sdk-review/SKILL.md index 9d6465998..b3ceda70e 100644 --- a/.agents/skills/unity-sdk-review/SKILL.md +++ b/.agents/skills/unity-sdk-review/SKILL.md @@ -46,10 +46,10 @@ Maintainers rejected these as false positives: - Claims that a sentry-cocoa, sentry-java, sentry-native, or sentry-dotnet API is missing, renamed, or has a different signature. Their sources are not in the checkout. Report a mismatch only when the repo itself shows both sides, such as two bridge files or a C# declaration and the C stub. - Stale-file bugs in a fresh player build. Unity deletes and recreates the `.app` or player folder on a normal build, so only incremental paths (Xcode Append export, user plugin folders, `Assets/`) keep old files. -- Unity callback lifecycle claims you cannot show in the code. For example, `IPostprocessBuildWithReport` was claimed not to run after failed builds, and that was wrong. +- Claims about when or whether a Unity build callback runs (ordering, failed builds) that you cannot show in the code. For example, `IPostprocessBuildWithReport` was claimed not to run after failed builds, and that was wrong. This does not cover the Unity API behavior listed in `references/editor-build.md`. - Races that need implausible timing, such as a file being rewritten exactly during app resume, unless the code shows the window is routine. - Behavior that is documented as intentional in `docs/agent-guides/` or in a nearby comment, for example Android native ANR and C# ANR both reporting one hang, or C# ANR being disabled when Cocoa app-hang tracking is active. -- Experimental options (`Experimental.*`) whose limitations the PR or code states as known follow-ups. +- Experimental options (`Experimental.*`) whose limitations the PR or code states as known follow-ups. Reading a top-level option where `Experimental.*` is meant, or the reverse, is still a bug. - Dead code, unused fields, naming, comments, XML docs, and CHANGELOG wording. - Generated or downloaded artifacts under `package-dev/` (`*.dll`, `*.meta`, native libraries) and submodule pointer bumps. - Security issues. `security-review` runs separately. diff --git a/.agents/skills/unity-sdk-review/references/native-bridges.md b/.agents/skills/unity-sdk-review/references/native-bridges.md index fc49e3672..456c897a5 100644 --- a/.agents/skills/unity-sdk-review/references/native-bridges.md +++ b/.agents/skills/unity-sdk-review/references/native-bridges.md @@ -24,6 +24,7 @@ So report: - A P/Invoke that becomes reachable on Switch without a matching stub function in `sentry_native_stubs.c`. - A bridge function that calls an Objective-C class that another bridge file has already migrated away from (for example `SentrySDK` vs `SentryObjCSDK`), when the repo shows the migration. - In `SentryNativeBridgeExternal.m`: a selector called without a `respondsToSelector:` check. Unity builds without Objective-C exceptions, so an unknown selector crashes the host app. +- The macOS bridge (`package-dev/Plugins/macOS/SentryNativeBridge.m`) loads `Sentry.dylib` with `dlopen` and calls sentry-cocoa through `performSelector:` and `objc_msgSend`, so nothing checks its selectors at build time. When a hunk adds or changes a selector there, compare it with the same call in `package-dev/Plugins/iOS/SentryNativeBridge.m`, which compiles against the headers. A mismatch is a crash on macOS. ## Marshalling Under IL2CPP diff --git a/modules/sentry-java b/modules/sentry-java index 0f55e39da..683908daa 160000 --- a/modules/sentry-java +++ b/modules/sentry-java @@ -1 +1 @@ -Subproject commit 0f55e39daaba7f1fd155aeb79b0c87b58c38939e +Subproject commit 683908daaa63add97ca9a1710ab4a6898ada1c2b diff --git a/warden.toml b/warden.toml index 0c91ffef2..8f0703fb2 100644 --- a/warden.toml +++ b/warden.toml @@ -63,7 +63,7 @@ paths = [ "package-dev/package.json", "test/Scripts.Integration.Test/**", "test/Scripts.Tests/**", - "samples/*/Assets/Editor/**/*.cs", + "samples/*/Assets/**/Editor/**/*.cs", ] ignorePaths = [ "**/*.md",