core+agents: JIT bundle resolution stage 1 — R03 flips (#440)

Imageless JIT-compiled classes get their Bundle(for:) redirected to the
target's built framework wrapper. The hook lives in each agent binary
(BundleRedirect objc_library on macOS, AgentApp.swift mirror on iOS)
because bridge generations can be torn down while the swizzled IMP must
outlive them; the bridge calls previewsmcp_set_resource_wrapper via
dlsym before each render, installing once per process and refreshing
the path. The wrapper rides BuildContext.resourceWrapperPath from
CODESIGNING_FOLDER_PATH on both Xcode capture paths; SwiftPM and Bazel
stay nil so the hook never installs there.

The stage-opening diagnostic (probe preview through the real JIT)
decided the predicate: ORC-materialized classes report
class_getImageName == NULL with Bundle(for:) falling back to the
agent's main bundle, so the hook redirects exactly that combination.

Manual matrix: R03 flips on macOS and iOS (localized title, plist,
Core Data model, generated color); R02 stays Spanish with the hook code
present; B04's real-image framework class keeps its own wrapper. Unit
rows pin the hook decision table (BundleRedirectTests) and the
generator emission (BridgeGeneratorRedirectTests); the iOS agent
builder hash is re-pinned.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: obj-p

docs/jit-bundle-resolution.md

@@ -106,27 +106,43 @@ metaclass swizzle fires for Swift's `Bundle(for:)` on the Xcode 26.2 SDK,
 that Foundation's bundle-for-class cache sits below the swizzle (a
 late-installed hook is not bypassed by earlier lookups), and that
 `Bundle(path:)` on `CODESIGNING_FOLDER_PATH` serves resources for both the
-versioned and flat layouts. One measurement remains before the predicate is
-final: what `class_getImageName` returns for a **real ORC-materialized**
-class in the agent (the review's proxy used `objc_allocateClassPair`).
-Stage 1 opens with that diagnostic; if ORC stamps JIT classes with the
-agent's own executable path, the predicate degrades to
-`original == Bundle.main`, which accepts redirecting agent-image lookups
-as the documented cost.
+versioned and flat layouts. The predicate is decided (stage 1, 2026-07-21): a probe preview rendered
+through the real JIT showed the ORC-materialized class reports
+`class_getImageName == NULL` with `Bundle(for:)` falling back to the
+agent's main bundle — the clean discriminator holds, no degraded
+fallback needed. The hook combines both signals: redirect only when the
+original resolution is the main bundle **and** the class is imageless.
 
 - **Plumbing:** `BuildContext` gains the optional wrapper path (Xcode
   targets: `CODESIGNING_FOLDER_PATH`; SPM/Bazel: nil — SwiftPM's generated
   `Bundle.module` accessor already finds the built bundle beside the
-  products, proven by R02). The session passes it to the agent with the
-  render request, the same route the crash-notice and setup sidecars ride.
+  products, proven by R02). The generated bridge declares the agent's
+  setter via `@_silgen_name` (the `set_preview_vc` precedent) and calls it
+  before setup and before every render — **unconditionally**: a nil
+  wrapper emits a clearing `nil` call, so an agent that survives a
+  mid-session build-system identity flip (Xcode → SwiftPM re-detection on
+  a live session, where the agent process persists across the refresh)
+  cannot keep a stale path. The call precedes `previewSetUp`, so setup
+  plugins that load resources see the redirect too.
 - **Scope:** one target per session, so one wrapper per agent process at a
-  time; the hook re-arms per session start.
+  time; the hook re-arms per session start. Each session gets a fresh
+  agent process on both platforms (macOS spawns per session; iOS
+  pre-launch-terminates), so cross-session staleness cannot occur even
+  without the clearing call — the clearing call covers the within-session
+  refresh case.
 - **What it fixes:** `Bundle(for:)` on any class in JIT-compiled target
   code — which also fixes `String(localized:bundle:)` and Core Data
   `momd` lookups made against that bundle (R03's three misses).
 - **What it deliberately does not touch:** `Bundle.main` (the agent's own
   identity, used by the JIT runtime), `Bundle.module` in SPM targets
   (already correct), lookups from real dylib images.
+- **Known over-redirection (accepted):** runtime-generated imageless
+  classes that resolve to the main bundle — KVO's `NSKVONotifying_*`
+  dynamic subclasses, other `objc_allocateClassPair` products — match the
+  predicate and redirect to the wrapper. For a KVO subclass of a target
+  class that answer is arguably more correct than the main bundle; for
+  agent-class KVO subclasses it is a harmless miss into a valid bundle.
+  No crash path either way.
 - **Known limitation (documented, gated):** Xcode-managed SwiftPM package
   products are JIT-linked as archives (`swiftPMPackageProducts`,
   `XcodeBuildSystem.swift:907-963`), so a package's classes are imageless
@@ -166,6 +182,13 @@ re-verification flipping rows in VERIFICATION.md.
    the tests that pin the generated color rendering. Only after stage 1's
    flake record is clean; the rewrite is proven and the hook must earn
    the same trust first.
+3. **Automated R03 guard.** The redirect's load-bearing premise (real
+   ORC-materialized classes are imageless) is pinned only by
+   `BundleRedirectTests`' `objc_allocateClassPair` proxy and the manual
+   matrix pass — a regression in ORC class imaging would pass the suite
+   while R03 silently un-flips. Add R03's macOS half to `RegressGuardTests`
+   (an Xcode row like D08, asserting the three loaded rows in the render)
+   in the next guard tranche.
 
 ## Out of scope
 

examples/regress/VERIFICATION.md

@@ -52,7 +52,7 @@ not a nonzero command exit.
 | F01 | Guard passes | 2026-07-20 (phase/error stage 4): the iOS start returns the classified error `XCFramework 'BadSlice' has no iOS simulator slice (available: ios-arm64).` with a rebuild remediation — the enricher reads the declared binary target's `Info.plist` when a `no such module` names it, and any miss degrades to the plain build failure. Daemon stays responsive. |
 | R01 | Guard passes | 2026-07-20 (phase/error stage 4): the start returns a classified session error — `Rendering the preview failed: JIT link could not resolve 3 symbol(s): _SCNVector3Zero, _OBJC_CLASS_$_SCNScene, _OBJC_CLASS_$_LPLinkMetadata` — naming the autolink closure's actual symbols, with the bounded list and an autolink remediation. The daemon stays responsive; rendering the closure remains named future work (`LC_LINKER_OPTION` scan). |
 | R02 | Guard passes | 2026-07-21: the original blank/partial framebuffer no longer reproduces, and with the fixture's Spanish assertion corrected (see Fixture Corrections) every surface renders `Recursos cargados` — the macOS control, the iOS single-preview control, and iOS index 1 after a live switch — alongside the JSON and text rows. The re-verification first found all surfaces rendering the English title, but a native harness against the healthy built bundle proved that was the fixture's own mechanism: `String(localized:bundle:locale:)` does not select the `.lproj` (its `locale:` parameter affects interpolation formatting only), so the 2026-07-15 fixture variant could never display Spanish even against correct staging. Original 2026-07-14 observation, for history: index 1 and the Spanish control produced a blank or partial framebuffer on iOS while the native build passed with both locale directories staged. |
-| R03 | Reproduced | macOS and iOS rendered the generated color symbol, while the localized key remained `resource.title` and plist/Core Data lookup reported missing. The cold iOS Xcode build also spent about 49 seconds in one progress step. Re-verified 2026-07-15 under Xcode compile capture: the generated-sources half renders identically; the remaining gap is runtime-resource staging (out of the resolver's scope). Re-verified 2026-07-21: macOS unchanged (the generated color renders; `resource.title`, plist, and Core Data model still miss). iOS had regressed to a deterministic agent SIGILL — the generic `iOS Simulator` destination builds every arch and the build-log capture could return the x86_64 swift-frontend invocation — fixed the same day (#438, host-arch capture preference plus the foreign-arch triple strip); after the fix iOS renders the macOS-identical partial baseline again. The remaining gap on both platforms: `Bundle(for:)` on a class compiled into the JIT resolves to the agent process image, and only `Generated*Symbols.swift` files are rewritten to the framework wrapper (`applyResourceBundleRewrites`), so user-code bundle lookups miss resources that are present on disk in the built framework. |
+| R03 | Guard passes | 2026-07-21 (jit-bundle-resolution stage 1): both platforms render `Xcode resources loaded`, `Plist loaded`, `Core Data model loaded`, and the generated color — the agent's `bundleForClass:` hook redirects imageless JIT-class lookups to the target's framework wrapper (`CODESIGNING_FOLDER_PATH` plumbed via `BuildContext.resourceWrapperPath`; hook installed once per agent process, path refreshed per render). Inertness verified in the same pass: R02 (SwiftPM, wrapper nil) still renders Spanish and B04's real-image framework class keeps resolving its own wrapper. History: `Bundle(for:)` on a class compiled into the JIT resolved to the agent image while only `Generated*Symbols.swift` got the #151 wrapper rewrite (why the color always rendered); the 2026-07-14 pass recorded that partial state, 2026-07-15 re-verified it under compile capture, and the same-day iOS SIGILL regression (fat-build x86_64 capture) was fixed in #438. |
 | W01 | Partial guard | Editing a dependency Swift file live changed `source version one` to `source version two` in a stable follow-up snapshot without restarting the session. The add/rename/remove variants are present in the fixture instructions but were not all exercised in this pass. Edit variant re-verified 2026-07-15 with the watcher fed by captured compile inputs; the fixture's Swift 6 language mode also forced two generated-source concurrency fixes (DesignTimeStore, window-state observer). |
 | W02 | Guard passes | 2026-07-16 (state-invalidation stage 4): a resource-only edit to `Resources/payload.json` fired the runtime-input tier — the daemon logged `Evidence change: re-running the native build` — and a stable follow-up snapshot rendered the new value; the revert refreshed back. Regression note on the original observation: on stage-3 code, neither an in-place nor an atomic-rename resource-only edit produces any watcher activity (the resource path cannot pass the exact-path filter), and a snapshot logs only clean MCP lines — the originally recorded "reload transition" therefore came from the operator's editor re-saving an open watched source file in the same burst, not from the resource edit. |
 | W03 | Guard passes | Both editor save styles reloaded on macOS: write-temp-then-rename-over and rename-away-then-recreate each updated the render to the new source value in a stable follow-up snapshot. |

previewsmcp/PreviewAgent/BUILD.bazel

@@ -1,4 +1,20 @@
 load("@rules_cc//cc:defs.bzl", "cc_binary")
+load("@rules_cc//cc:objc_library.bzl", "objc_library")
+load("@rules_swift//swift:swift.bzl", "swift_interop_hint")
+
+swift_interop_hint(
+    name = "BundleRedirect_swift_hint",
+    module_name = "BundleRedirect",
+)
+
+objc_library(
+    name = "BundleRedirect",
+    srcs = ["BundleRedirect.m"],
+    hdrs = ["BundleRedirect.h"],
+    aspect_hints = [":BundleRedirect_swift_hint"],
+    visibility = ["//visibility:public"],
+    alwayslink = True,
+)
 
 cc_binary(
     name = "PreviewAgent",
@@ -8,5 +24,8 @@ cc_binary(
         "-fno-rtti",
     ],
     visibility = ["//visibility:public"],
-    deps = ["//:llvm"],
+    deps = [
+        ":BundleRedirect",
+        "//:llvm",
+    ],
 )

previewsmcp/PreviewAgent/BundleRedirect.h

@@ -0,0 +1,10 @@
+#ifndef PREVIEWSMCP_BUNDLE_REDIRECT_H
+#define PREVIEWSMCP_BUNDLE_REDIRECT_H
+
+/// Installs the agent-process +[NSBundle bundleForClass:] hook on first call
+/// and stores (or replaces) the target framework wrapper path the hook
+/// redirects to. Passing NULL clears the path, disabling redirection while
+/// leaving the hook installed. See docs/jit-bundle-resolution.md.
+void previewsmcp_set_resource_wrapper(const char *path);
+
+#endif

previewsmcp/PreviewAgent/BundleRedirect.m

@@ -0,0 +1,58 @@
+#import "BundleRedirect.h"
+
+#import <Foundation/Foundation.h>
+#import <objc/runtime.h>
+#import <os/lock.h>
+
+// Keep in sync with the BundleRedirect enum in
+// previewsmcp/ios-host/agent/AgentApp.swift (the iOS agent's implementation
+// of the same contract).
+//
+// The JIT recompiles target sources into the agent process, so their classes
+// belong to no dyld image and +[NSBundle bundleForClass:] falls back to the
+// main bundle. The hook redirects exactly that combination — imageless class
+// resolved to the main bundle — to the target's on-disk framework wrapper.
+// It lives in the agent binary, never in JIT-generated code, because bridge
+// generations can be torn down while the swizzled IMP must stay valid for
+// the life of the process (docs/jit-bundle-resolution.md).
+
+static os_unfair_lock gWrapperLock = OS_UNFAIR_LOCK_INIT;
+static NSString *gWrapperPath;
+
+static NSString *currentWrapperPath(void) {
+  os_unfair_lock_lock(&gWrapperLock);
+  NSString *path = gWrapperPath;
+  os_unfair_lock_unlock(&gWrapperLock);
+  return path;
+}
+
+static NSBundle *(*gOriginalBundleForClass)(id, SEL, Class);
+
+static NSBundle *PreviewsMCPBundleForClass(id self, SEL _cmd, Class cls) {
+  NSBundle *original = gOriginalBundleForClass(self, _cmd, cls);
+  NSString *wrapper = currentWrapperPath();
+  if (wrapper == nil || cls == Nil) {
+    return original;
+  }
+  if (original != [NSBundle mainBundle] || class_getImageName(cls) != NULL) {
+    return original;
+  }
+  NSBundle *redirected = [NSBundle bundleWithPath:wrapper];
+  return redirected ?: original;
+}
+
+__attribute__((used)) void previewsmcp_set_resource_wrapper(const char *path) {
+  NSString *wrapper = path != NULL ? [NSString stringWithUTF8String:path] : nil;
+  os_unfair_lock_lock(&gWrapperLock);
+  gWrapperPath = wrapper;
+  os_unfair_lock_unlock(&gWrapperLock);
+
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    Method method =
+        class_getClassMethod([NSBundle class], @selector(bundleForClass:));
+    gOriginalBundleForClass =
+        (NSBundle * (*)(id, SEL, Class)) method_getImplementation(method);
+    method_setImplementation(method, (IMP)PreviewsMCPBundleForClass);
+  });
+}

previewsmcp/PreviewsCore/BridgeGenerator.swift

@@ -57,7 +57,8 @@ public enum BridgeGenerator {
         stableModuleImport: String? = nil,
         renderWindow: JITRenderWindow? = nil,
         frameSidecarPath: String? = nil,
-        setupErrorSidecarPath: String? = nil
+        setupErrorSidecarPath: String? = nil,
+        resourceWrapperPath: String? = nil
     ) -> (source: String, literals: [LiteralEntry]) {
         // Transform source to replace literals with DesignTimeStore lookups
         let thunkResult = ThunkGenerator.transform(source: originalSource)
@@ -74,7 +75,10 @@ public enum BridgeGenerator {
         let hasSetup = isUsableSetup(module: setupModule, type: setupType)
         let setupImport = hasSetup ? "import \(setupModule!)\nimport PreviewsSetupKit\n" : ""
         let setUpEntry = hasSetup
-            ? setUpEntryPoint(setupType: setupType!, errorSidecarPath: setupErrorSidecarPath)
+            ? setUpEntryPoint(
+                setupType: setupType!, errorSidecarPath: setupErrorSidecarPath,
+                resourceWrapperPath: resourceWrapperPath
+            )
             : ""
         let viewCode =
             hasSetup
@@ -93,24 +97,30 @@ public enum BridgeGenerator {
                 case .macOS:
                     return renderToFileEntryPoint(
                         viewCode: viewCode, path: path, valuesPath: designTimeValuesPath,
-                        window: renderWindow, frameSidecarPath: frameSidecarPath
+                        window: renderWindow, frameSidecarPath: frameSidecarPath,
+                        resourceWrapperPath: resourceWrapperPath
                     )
                 case .iOS:
-                    return iosRenderEntryPoint(viewCode: viewCode, valuesPath: designTimeValuesPath)
+                    return iosRenderEntryPoint(
+                        viewCode: viewCode, valuesPath: designTimeValuesPath,
+                        resourceWrapperPath: resourceWrapperPath
+                    )
                 }
             } ?? ""
         let bridgeCode = switch platform {
         case .macOS:
             """
             import AppKit
             \(setupImport)
+            \(resourceWrapperDeclaration)
             \(setUpEntry)
             \(renderEntry)
             """
         case .iOS:
             """
             import UIKit
             \(setupImport)
+            \(resourceWrapperDeclaration)
             \(setUpEntry)
             \(renderEntry)
             """
@@ -208,6 +218,25 @@ public enum BridgeGenerator {
         } ?? ""
     }
 
+    /// The set call runs before setup and before each view construction so
+    /// target-code bundle lookups already resolve to the framework wrapper —
+    /// and a nil wrapper still emits a clearing call, so an agent that
+    /// survives a mid-session build-system identity change cannot keep a
+    /// stale path. Resolved via `@_silgen_name` like `set_preview_vc`; the
+    /// hook implementation lives in the agent binary, never here — bridge
+    /// generations can be torn down while the swizzled IMP must outlive
+    /// them.
+    static let resourceWrapperDeclaration = """
+    @_silgen_name("previewsmcp_set_resource_wrapper")
+    func __previewsmcp_set_resource_wrapper(_ path: UnsafePointer<CChar>?)
+    """
+
+    private static func resourceWrapperCall(_ wrapperPath: String?) -> String {
+        wrapperPath.map {
+            "__previewsmcp_set_resource_wrapper(\"\(escapedForSwiftStringLiteral($0))\")"
+        } ?? "__previewsmcp_set_resource_wrapper(nil)"
+    }
+
     /// Generate the `@_cdecl("renderPreviewToFile")` entry point (macOS, model-A JIT path).
     /// Builds the same preview view as `createPreviewView`, hosts it in a borderless
     /// `NSWindow` positioned off-screen via `NSHostingView` (AppKit-backed views like
@@ -222,7 +251,7 @@ public enum BridgeGenerator {
     /// AppKit state is shared across JITDylib generations; the entry's own globals are not.
     private static func renderToFileEntryPoint(
         viewCode: String, path: String, valuesPath: String?, window: JITRenderWindow?,
-        frameSidecarPath: String?
+        frameSidecarPath: String?, resourceWrapperPath: String?
     ) -> String {
         let seed = designTimeSeed(valuesPath)
         let createWindow: String
@@ -308,6 +337,7 @@ public enum BridgeGenerator {
         public func renderPreviewToFile() -> Int32 {
             MainActor.assumeIsolated {
                 \(seed)
+                \(resourceWrapperCall(resourceWrapperPath))
                 let view = \(viewCode)
                 let identifier = NSUserInterfaceItemIdentifier("previewsmcp-preview")
                 var isNewWindow = false
@@ -461,7 +491,9 @@ public enum BridgeGenerator {
     /// macOS entry it does not raster a PNG: the daemon captures the simulator screen via
     /// `simctl`, so the baked render path is unused here. Nullary and run over the agent's
     /// `runOnMain` surface; re-running it after a literal edit re-seeds DesignTimeStore.
-    private static func iosRenderEntryPoint(viewCode: String, valuesPath: String?) -> String {
+    private static func iosRenderEntryPoint(
+        viewCode: String, valuesPath: String?, resourceWrapperPath: String?
+    ) -> String {
         let seed = designTimeSeed(valuesPath)
         return """
         @_silgen_name("previewsmcp_set_preview_vc")
@@ -471,6 +503,7 @@ public enum BridgeGenerator {
         public func renderPreviewToFile() -> Int32 {
             MainActor.assumeIsolated {
                 \(seed)
+                \(resourceWrapperCall(resourceWrapperPath))
                 let view = \(viewCode)
                 let hosting = UIHostingController(rootView: view)
                 _previewsmcp_set_preview_vc(Unmanaged.passRetained(hosting).toOpaque())
@@ -515,7 +548,9 @@ public enum BridgeGenerator {
     /// skipping `wrap`), written to the error sidecar for the daemon to
     /// read, and reported as a nonzero status — never silently dropped
     /// (docs/phase-error-protocol.md, setup integrity; T01).
-    private static func setUpEntryPoint(setupType: String, errorSidecarPath: String?) -> String {
+    private static func setUpEntryPoint(
+        setupType: String, errorSidecarPath: String?, resourceWrapperPath: String?
+    ) -> String {
         let recordError = errorSidecarPath.map { path -> String in
             """
             try? ((error as? any LocalizedError)?.errorDescription ?? String(describing: error)).write(
@@ -525,6 +560,7 @@ public enum BridgeGenerator {
         return """
         @_cdecl("previewSetUp")
         public func previewSetUp() -> Int32 {
+            \(resourceWrapperCall(resourceWrapperPath))
             let semaphore = DispatchSemaphore(value: 0)
             Task {
                 do {