peachsim 0.1.1619 → 0.1.1625

package/src/process-group.ts

@@ -1,5 +1,12 @@
 import { spawn, spawnSync, type ChildProcess } from 'node:child_process'
-import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  appendFileSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
@@ -7,6 +14,57 @@ import { setTimeout as sleep } from 'node:timers/promises'
 const GRACEFUL_TIMEOUT_MS = 3_000
 const FORCED_EXIT_TIMEOUT_MS = 1_000
 
+// keep this self-contained: the detached browser host embeds its source.
+export function listProcessChildren(parents: number[], timeoutMs = 3_000): number[] {
+  if (parents.some((pid) => !Number.isInteger(pid) || pid <= 1))
+    throw new Error('process inspection requires valid parent pids')
+  if (parents.length === 0) return []
+  const deadline = Date.now() + timeoutMs
+  let children: string
+  if (process.platform === 'linux') {
+    // pgrep scans unrelated host processes. every thread can own children.
+    const lists: string[] = []
+    for (const parent of parents) {
+      try {
+        const tasks = `/proc/${parent}/task`
+        for (const thread of readdirSync(tasks)) {
+          if (Date.now() >= deadline)
+            throw new Error('process descendant inspection exceeded its deadline')
+          try {
+            lists.push(readFileSync(`${tasks}/${thread}/children`, 'utf8'))
+          } catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+              throw error
+          }
+        }
+      } catch (error) {
+        // an exiting parent or thread has no remaining children to inspect.
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+          throw error
+      }
+    }
+    children = lists.join(' ')
+  } else {
+    const result = spawnSync('pgrep', ['-P', parents.join(',')], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: Math.max(1, timeoutMs),
+      killSignal: 'SIGKILL',
+    })
+    if (result.error || (result.status !== 0 && result.status !== 1)) {
+      throw new Error(
+        `could not inspect descendants of processes ${parents.join(',')}: ${
+          result.error?.message || result.stderr.trim() || `pgrep exited ${result.status}`
+        }`,
+      )
+    }
+    children = result.stdout
+  }
+  return [...new Set(children.trim().split(/\s+/).map(Number))].filter(
+    (pid) => Number.isInteger(pid) && pid > 1 && !parents.includes(pid),
+  )
+}
+
 // synchronous group-or-pid signal for `process.on('exit')` sweeps, where no
 // async wait is possible. never throws: a dead group reads as ESRCH.
 export function signalProcessGroup(child: ChildProcess, signal: NodeJS.Signals) {
@@ -93,63 +151,49 @@ async function protectProcessFreeze(rootPid: number) {
   }
 }
 
-function runningPids(pids: number[]): number[] {
-  return pids.filter((pid) => {
+// reparented members remain in the group; detached descendants need their
+// recorded pids. both can leave zombies, which signal zero cannot distinguish
+// from running processes. inspect their states together before confirming exit.
+function processesHaveExited(pids: number[], pgid: number): boolean {
+  const mayExist = [-pgid, ...pids].some((target) => {
     try {
-      process.kill(pid, 0)
+      process.kill(target, 0)
       return true
     } catch (error) {
-      return error instanceof Error && 'code' in error && error.code === 'EPERM'
+      return !(error instanceof Error && 'code' in error && error.code === 'ESRCH')
     }
   })
-}
-
-// a descendant whose parent exited first is reparented to init, so `pgrep -P`
-// no longer finds it and it never enters the pid list. it stays in the leader's
-// process group though, and the group outlives its leader while any member is
-// left, so the group is the survivor check that still sees it.
-//
-// a signal cannot finish the answer. a zombie is an exit status its parent has
-// not collected: it runs nothing and holds nothing, and it is what a finished
-// tree leaves behind. macos reports one with EPERM, which otherwise means a
-// live member we may not signal, and linux reports one as signalable, so on
-// either platform a kill that does not fail reads a finished group as a live
-// one, which holds shutdown open for the whole graceful timeout and then
-// SIGKILLs something already dead. ps reports the state, so it settles which
-// it is, and it costs a process only when a survivor we never enumerated is
-// really there: this runs after the known pids are gone, and an empty group
-// fails the kill with ESRCH before reaching it.
-//
-// exported for its test: node reaps its own children, so a group left holding
-// only a zombie cannot be built through terminateProcessGroup from inside a
-// test, and this is the function that has to read one correctly.
-export function groupIsEmpty(pgid: number): boolean {
-  try {
-    process.kill(-pgid, 0)
-  } catch (error) {
-    if (!(error instanceof Error && 'code' in error && error.code === 'EPERM'))
-      return true
-  }
-  const result = spawnSync('ps', ['-A', '-o', 'pgid=,stat='], {
+  if (!mayExist) return true
+  const result = spawnSync('ps', ['-A', '-o', 'pid=,pgid=,stat='], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: FORCED_EXIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
   })
-  // an unreadable process table is not evidence of an empty group. keep waiting
-  // and let the caller escalate to SIGKILL the way it does for any live tree.
+  // an unreadable process table cannot confirm exit.
   if (result.error || result.status !== 0) return false
+  const knownPids = new Set(pids)
   return !result.stdout.split('\n').some((line) => {
-    const [group, state] = line.trim().split(/\s+/)
-    return Number(group) === pgid && state !== undefined && !state.startsWith('Z')
+    const [pid, group, state] = line.trim().split(/\s+/)
+    return (
+      (Number(group) === pgid || knownPids.has(Number(pid))) &&
+      state !== undefined &&
+      !state.startsWith('Z')
+    )
   })
 }
 
+export function groupIsEmpty(pgid: number): boolean {
+  return processesHaveExited([], pgid)
+}
+
 async function waitForExit(
   pids: number[],
   pgid: number,
   timeoutMs: number,
 ): Promise<boolean> {
   const deadline = Date.now() + timeoutMs
-  const gone = () => runningPids(pids).length === 0 && groupIsEmpty(pgid)
+  const gone = () => processesHaveExited(pids, pgid)
   while (Date.now() < deadline) {
     if (gone()) return true
     await sleep(50)
@@ -197,30 +241,16 @@ export async function terminateProcessGroup(
         inspectionError = new Error('process descendant inspection exceeded its deadline')
         break
       }
-      const result = spawnSync('pgrep', ['-P', parents.join(',')], {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: remaining,
-        killSignal: 'SIGKILL',
-      })
-      if (result.error || (result.status !== 0 && result.status !== 1)) {
-        inspectionError = new Error(
-          `could not inspect descendants of processes ${parents.join(',')}: ${
-            result.error?.message ||
-            result.stderr.trim() ||
-            `pgrep exited ${result.status}`
-          }`,
-        )
+      let children: number[]
+      try {
+        children = listProcessChildren(parents, remaining)
+      } catch (error) {
+        inspectionError = new Error(`could not inspect descendants: ${String(error)}`)
         break
       }
       const next: number[] = []
-      for (const line of result.stdout.split('\n')) {
-        const descendantPid = Number(line.trim())
-        if (
-          Number.isInteger(descendantPid) &&
-          descendantPid > 1 &&
-          !descendants.has(descendantPid)
-        ) {
+      for (const descendantPid of children) {
+        if (!descendants.has(descendantPid)) {
           freeze.record(descendantPid)
           descendants.add(descendantPid)
           next.push(descendantPid)

package/src/process-output.ts

@@ -1,12 +1,3 @@
-// a consumer such as head may close its pipe before the command finishes.
-// exit directly: reporting this through stderr can fail on the same pipe.
-for (const stream of [process.stdout, process.stderr]) {
-  stream.on('error', (error: NodeJS.ErrnoException) => {
-    if (error.code === 'EPIPE') process.exit(1)
-    throw error
-  })
-}
-
 // wait for both pipes before forcing an exit with live handles.
 // console writers must use these streams rather than a separate runtime sink.
 export async function exitWithFlushedOutput(code: number): Promise<never> {

package/src/public-brand.ts

@@ -6,6 +6,7 @@ export const peachPublicBrand = Object.freeze({
   commandName: 'peach',
   domain: 'peachsim.com',
   origin: 'https://peachsim.com',
+  boxOrigin: 'https://rnx-box.contrast.dev',
 })
 
 export const rnxPublicBrand = peachPublicBrand

package/src/react-native-host-modules.ts

@@ -6,6 +6,9 @@
  * preserves upstream platform, style, event-emitter, and TurboModule behavior.
  */
 export const REACT_NATIVE_PASSTHROUGH_SPECIFIERS: readonly string[] = [
+  // one's native bootstrap runs the upstream environment entry.
+  'react-native/setup-env',
+  'react-native/src/setup-env',
   // sdk 58 reads these upstream getters and wraps the original metro logger.
   'react-native/unstable-internals-do-not-use',
   'react-native/src/unstable-internals-do-not-use',

package/src/sim-client.ts

@@ -48,6 +48,10 @@ import {
   type WaitForSootsimIdleResult,
 } from '../cli/commands/inspect/settling'
 import { openAppUrl } from './app-url'
+import {
+  LAUNCH_METADATA_KEYS,
+  LAUNCH_METADATA_QUERY_PARAM,
+} from './launchMetadataContract'
 import { sleep } from './sleep'
 import type { BridgeClaimResult, BridgeSimInfo, WsBridge } from '../cli/ws-bridge'
 import type {
@@ -187,10 +191,8 @@ const TARGET_SEARCH_PARAMS = [
   'open',
   'port',
   'inspectOpen',
-  'appFonts',
-  'appManifest',
-  'appSplash',
-  'appCatalog',
+  ...LAUNCH_METADATA_KEYS,
+  LAUNCH_METADATA_QUERY_PARAM,
 ]
 
 export function buildSimOpenUrl(currentUrl: string, target: number | string): string {

package/src/swift-compile.ts

@@ -16,6 +16,7 @@ import {
 import os from 'node:os'
 import path from 'node:path'
 import { admittedMacBuilderSlot } from './admitted-mac-build'
+import { rnxHomeDir } from './home-paths'
 import { terminateProcessGroup } from './process-group'
 import { designTimeDiagnostic, designTimeSource } from './swift-design-time'
 import {
@@ -719,6 +720,9 @@ export function swiftArtifactHash(
   moduleRoot: string,
 ): string {
   const hash = createHash('sha256')
+  // v49: NSObject metatype initialization reaches its explicit runtime boundary
+  // v48: top-level classes rooted in an Apple framework class stay out of C++
+  // v47: target ownership honors exclusions before lowering manifest-named files
   // v46: view builder literals compile as design-time lookups
   // v45: the link runs no wasm-opt pass, whatever the compiling machine has
   // v44: fixed-signature optional type methods retain metatype dispatch
@@ -765,7 +769,7 @@ export function swiftArtifactHash(
   // v6: app and scene delegate classes compile final
   // (v5: a target declaring resources gets SwiftPM's Bundle.module accessor;
   // v4: sources compile through swiftSourceAsIOS)
-  hash.update(`swift-compile/v46\n${release}\n`)
+  hash.update(`swift-compile/v49\n${release}\n`)
   if (input.oneModule) hash.update('one-module\n')
   hash.update(swiftModuleDigest(moduleRoot))
   for (const file of Object.keys(input.files).sort()) {
@@ -1565,9 +1569,14 @@ function compiledSwiftSources(
   const orderedTargets = [...targets].sort((a, b) => b.path.length - a.path.length)
   for (const [file, contents] of Object.entries(files)) {
     if (!file.endsWith('.swift')) continue
-    const owner = orderedTargets.find(
-      (candidate) => candidate.path === '.' || file.startsWith(`${candidate.path}/`),
-    )
+    const owner = orderedTargets.find((candidate) => {
+      const prefix = candidate.path === '.' ? '' : `${candidate.path}/`
+      if (!file.startsWith(prefix)) return false
+      const relative = file.slice(prefix.length)
+      return !candidate.exclude?.some(
+        (excluded) => relative === excluded || relative.startsWith(`${excluded}/`),
+      )
+    })
     if (
       /(?:^|\/)Package(?:@swift-[\d.]+)?\.swift$/.test(file) &&
       (!owner || /^Package(?:@swift-[\d.]+)?\.swift$/.test(file))
@@ -1600,12 +1609,73 @@ function compiledSwiftSources(
     const sources = lifted.map(([, contents]) => contents)
     const extensions = objcExtensionMemberIndex(sources)
     const objc = objcIndex(sources)
+    const rooted = objcRootedClasses(sources)
     for (const [file, contents] of lifted)
-      compiled.set(file, swiftSourceAsIOS(contents, extensions, objc))
+      compiled.set(
+        file,
+        hideObjCClassesFromCxx(swiftSourceAsIOS(contents, extensions, objc), rooted),
+      )
   }
   return compiled
 }
 
+// an Apple framework protocol a class may list first, which is no superclass
+const APPLE_PROTOCOL =
+  /^NS(?:Mutable)?Copying$|^NS(?:Secure)?Coding$|^NSLocking$|^NSFastEnumeration$|^NSObjectProtocol$|(?:Delegate|DataSource)$/
+
+// the module's classes whose superclass chain, through the classes `sources`
+// declare, reaches an Apple framework class: Objective-C classes on iOS
+function objcRootedClasses(sources: string[]): Set<string> {
+  const bases = new Map<string, string>()
+  for (const source of sources)
+    for (const match of swiftCodeMask(source).matchAll(
+      /\bclass\s+(?!(?:func|var|let|subscript)\b)([A-Za-z_]\w*)\s*(?:<[^>{]*>)?\s*:\s*(?:[A-Za-z_]\w*\.)*([A-Za-z_]\w*)/g,
+    ))
+      bases.set(match[1]!, match[2]!)
+  const rooted = new Set<string>()
+  for (const name of bases.keys()) {
+    const seen = new Set([name])
+    let base = bases.get(name)!
+    while (bases.has(base) && !seen.has(base)) {
+      seen.add(base)
+      base = bases.get(base)!
+    }
+    if (
+      !bases.has(base) &&
+      APPLE_CLASS.test(base) &&
+      !APPLE_PROTOCOL.test(base) &&
+      !(base in SDK_OBJC_OPTIONAL)
+    )
+      rooted.add(name)
+  }
+  return rooted
+}
+
+// the header swift emits on iOS keeps an Objective-C class out of its C++
+// section. here its root is a swift class from a module with no C++ header,
+// so C++ that includes the header fails on the undeclared base. a top-level
+// class in `rooted` gains @_expose(!Cxx) in front of its declaration,
+// shifting that one line's columns. swift rejects the attribute in a local
+// scope, so a nested class keeps its exposure.
+function hideObjCClassesFromCxx(source: string, rooted: Set<string>): string {
+  if (rooted.size === 0) return source
+  const code = swiftCodeMask(source)
+  const starts: number[] = []
+  let depth = 0
+  for (const match of code.matchAll(
+    /[{}]|\bclass\s+(?!(?:func|var|let|subscript)\b)([A-Za-z_]\w*)/g,
+  )) {
+    if (match[0] === '{') depth++
+    else if (match[0] === '}') depth--
+    else if (depth === 0 && rooted.has(match[1]!))
+      starts.push(declarationStart(code, match.index, 0))
+  }
+  let out = source
+  for (const at of starts.reverse())
+    out = `${out.slice(0, at)}@_expose(!Cxx) ${out.slice(at)}`
+  return out
+}
+
 // wasm Swift has no ObjC runtime, so a member read on AnyObject never
 // resolves: `value of type 'AnyObject' has no member 'doubleValue'`. native
 // code that bridges dictionary values through AnyObject to reach NSNumber's
@@ -3596,6 +3666,8 @@ export type ObjCIndex = {
   // each @objc type method's selector to its result type, null when two
   // declarations disagree
   typeMethods: Map<string, string | null>
+  // NSObject and protocols constrained to it without a Swift init requirement
+  nsObjectTypes: Set<string>
 }
 
 // the @objc type methods `source` declares, by selector, into `found`
@@ -3733,15 +3805,43 @@ export function objcIndex(sources: string[]): ObjCIndex {
         /\b(?:var|let)\s+([A-Za-z_]\w*)/g,
       ))
         variables.add(declared[1]!)
-  const parents = requirements.size
-    ? inheritedTypes(sources)
-    : new Map<string, Set<string>>()
+  const parents = inheritedTypes(sources)
   for (const [protocol, inherited] of sdkParents)
     parents.set(protocol, new Set([...(parents.get(protocol) ?? []), ...inherited]))
   const conformers = requirements.size
     ? conformingTypes(parents, new Set(requirements.keys()))
     : new Map<string, Set<string>>()
-  return { requirements, conformers, callable, variables, aliases, typeMethods }
+  const protocols = new Set<string>()
+  const initializers = new Set<string>()
+  for (const source of sources) {
+    if (!/\bprotocol\b/.test(source)) continue
+    const code = swiftCodeMask(source)
+    const braces = [...code.matchAll(/[{}]/g)].map((match) => match.index)
+    for (const protocol of code.matchAll(/\bprotocol\s+([A-Za-z_]\w*)[^{}]*\{/g)) {
+      const name = protocol[1]!
+      protocols.add(name)
+      const open = protocol.index + protocol[0].length - 1
+      if (
+        /\binit\s*[?!]?\s*\(/.test(code.slice(open + 1, closingBrace(code, braces, open)))
+      )
+        initializers.add(name)
+    }
+  }
+  const rooted = conformingTypes(parents, new Set(['NSObject']))
+  const initialized = conformingTypes(parents, initializers)
+  const nsObjectTypes = new Set([
+    'NSObject',
+    ...[...protocols].filter((name) => rooted.has(name) && !initialized.has(name)),
+  ])
+  return {
+    requirements,
+    conformers,
+    callable,
+    variables,
+    aliases,
+    typeMethods,
+    nsObjectTypes,
+  }
 }
 
 // the non-generic file-scope typealiases `sources` declare, each resolved
@@ -4111,7 +4211,7 @@ const IMP_CONVENTION = /@convention\(c\)(?=\s*\(\s*AnyObject\s*,\s*Selector\b)/g
 
 function lowerObjCRuntimeCalls(source: string, index: ObjCIndex): string {
   const casts = source.includes('@convention(c)')
-  const classes = /\b(?:AnyClass|AnyObject)\b/.test(source)
+  const classes = /\b(?:AnyClass|AnyObject)\b|\.\s*init\s*\(/.test(source)
   if (!casts && !classes) return source
   const code = swiftCodeMask(source)
   const edits: [number, number, string][] = []
@@ -4142,15 +4242,33 @@ function lowerObjCRuntimeCalls(source: string, index: ObjCIndex): string {
     }
   }
   if (classes) {
-    // every declaration of a name, typed or not; a receiver is an AnyClass
-    // or AnyObject only where its innermost declaration in scope says so
+    // every declaration of a name, typed or not; a receiver's innermost
+    // declaration in scope determines its runtime operation
     const declarations = new Map<string, { at: number; type: string }[]>()
     for (const declared of code.matchAll(
-      /(?:\b(?:let|var)\s+|[(,]\s*(?:[A-Za-z_]\w*\s+)?)([A-Za-z_]\w*)\s*:\s*(?:([A-Z]\w*(?:\.\w+)*)\s*([?!])?|[[(])|\b(?:let|var|for)\s+([A-Za-z_]\w*)\b(?!\s*:)|[{,]\s*([A-Za-z_]\w*)\s+in\b/g,
+      /(?:\b(?:let|var)\s+|[(,]\s*(?:[A-Za-z_]\w*\s+)?)([A-Za-z_]\w*)\s*:\s*(?:(?:any\s+)?([A-Z]\w*(?:\.\w+)*)\s*([?!])?|[[(])|\b(?:let|var|for)\s+([A-Za-z_]\w*)\b(?!\s*:)|[{,]\s*([A-Za-z_]\w*)\s+in\b/g,
     )) {
       const name = declared[1] ?? declared[4] ?? declared[5]!
       const list = declarations.get(name) ?? []
-      list.push({ at: declared.index, type: declared[3] ? '' : (declared[2] ?? '') })
+      let type = declared[3] ? '' : (declared[2] ?? '')
+      if (!type && declared[4]) {
+        // NSClassFromString's checked cast establishes the metatype of a
+        // successful conditional binding, including a guard's remaining body.
+        const lookup = /^\s*=\s*NSClassFromString\s*\(/.exec(
+          code.slice(declared.index + declared[0].length),
+        )
+        if (lookup) {
+          const open = declared.index + declared[0].length + lookup[0].length - 1
+          type =
+            /^\s*as\?\s*([A-Za-z_]\w*(?:\.\w+)*\.Type)\b/.exec(
+              code.slice(closingParen(code, open) + 1),
+            )?.[1] ?? ''
+        }
+      }
+      const resolved = type.endsWith('.Type')
+        ? `${resolveAliases(type.slice(0, -5), index.aliases)}.Type`
+        : resolveAliases(type, index.aliases)
+      list.push({ at: declared.index, type: resolved })
       declarations.set(name, list)
     }
     // a tuple or enum pattern (`let (a, b)`, `case let .some(a)`) binds
@@ -4168,7 +4286,7 @@ function lowerObjCRuntimeCalls(source: string, index: ObjCIndex): string {
     }
     for (const list of declarations.values()) list.sort((a, b) => a.at - b.at)
     const braces = [...code.matchAll(/[{}]/g)].map((match) => match.index)
-    const receives = (name: string, at: number, type: string): boolean => {
+    const receiverType = (name: string, at: number): string | undefined => {
       let innermost: { from: number; type: string } | undefined
       for (const declared of declarations.get(name) ?? []) {
         if (declared.at > at) break
@@ -4176,22 +4294,40 @@ function lowerObjCRuntimeCalls(source: string, index: ObjCIndex): string {
         if (at > from && at < to && (!innermost || from >= innermost.from))
           innermost = { from, type: declared.type }
       }
-      return innermost?.type === type
+      return innermost?.type
     }
     let reached = -1
     for (const call of code.matchAll(
       /(?<![\w.])((?:type\s*\(\s*of\s*:\s*([A-Za-z_]\w*)\s*\))|[A-Za-z_]\w*)\s*\.\s*([A-Za-z_]\w*)\s*\(/g,
     )) {
-      if (
-        call.index < reached ||
-        !(call[2]
-          ? receives(call[2], call.index, 'AnyObject')
-          : receives(call[1]!, call.index, 'AnyClass'))
-      )
-        continue
+      if (call.index < reached) continue
+      const type = receiverType(call[2] ?? call[1]!, call.index)
+      const constructed = call[2] ? type : type?.replace(/\.Type$/, '')
+      const constructs =
+        call[3] === 'init' &&
+        constructed &&
+        (call[2] || type?.endsWith('.Type')) &&
+        index.nsObjectTypes.has(constructed.replace(/^Foundation\./, ''))
+      if (!constructs && type !== (call[2] ? 'AnyObject' : 'AnyClass')) continue
       const open = call.index + call[0].length - 1
       const shut = closingParen(code, open)
       const passed = callArguments(source, code, open, shut)
+      if (constructs && passed.length === 0) {
+        // a class-constrained protocol metatype otherwise erases a generic
+        // initializer result to NSObject, losing its protocol requirements.
+        const result =
+          constructed.replace(/^Foundation\./, '') === 'NSObject'
+            ? constructed
+            : `any ${constructed}`
+        edits.push([
+          call.index,
+          shut + 1 - call.index,
+          `_objcNSObjectDefaultInit(${call[1]}, returning: (${result}).self)`,
+        ])
+        reached = shut + 1
+        continue
+      }
+      if (type !== (call[2] ? 'AnyObject' : 'AnyClass')) continue
       const selector = objcSelectorName(
         call[3]!,
         passed.map(({ label }) => label),
@@ -5213,18 +5349,29 @@ export function compileSwiftProjectUnit(
     multi: compileTargets(input).length > 0,
   }
   const hash = swiftArtifactHash(input, options.release, moduleRoot)
+  const sharedRoot = path.join(rnxHomeDir(), 'cache', 'swift-projects', hash)
+  const report = (message: string) =>
+    console.error(`[swift-project ${hash.slice(0, 16)}] ${message}`)
+  report('checking verified artifacts')
   return serialize(
     root,
     async () => {
       // reuse one verified result across server restarts before admission or
       // swiftpm. the address covers sources, framework inputs and toolchain.
       const retained = retainedArtifacts.get(root)?.find((old) => old.hash === hash)
-      if (retained) return retain(root, retained)
-      const cached = readCompiledArtifact(path.join(root, 'artifact'), hash)
-      if (cached) return retain(root, cached)
-      // an admitted mac slot already holds the build lock and the pinned
-      // toolchain, so it compiles here. a bare CONTRAST_REMOTE_BUILD value is
-      // only an inherited marker and still dispatches through admission.
+      if (retained) {
+        report('reusing memory artifact')
+        return retain(root, retained)
+      }
+      const cached = readCompiledArtifact(path.join(sharedRoot, 'artifact'), hash)
+      const previous = cached ?? readCompiledArtifact(path.join(root, 'artifact'), hash)
+      if (previous) {
+        if (!cached) saveCompiledArtifact(sharedRoot, previous)
+        report('reusing verified disk artifact')
+        return retain(root, previous)
+      }
+      // a mac builder with a live destination grant compiles here. inherited
+      // transport markers alone still dispatch through admission.
       if (
         process.platform === 'darwin' &&
         process.env.TM_SESSION &&
@@ -5248,6 +5395,7 @@ export function compileSwiftProjectUnit(
         )
         try {
           const repo = path.resolve(moduleRoot, '../..')
+          report('requesting builder admission or cached result')
           await runCompiler(
             'bun',
             [
@@ -5276,6 +5424,8 @@ export function compileSwiftProjectUnit(
             )
           }
           saveCompiledArtifact(root, artifact)
+          saveCompiledArtifact(sharedRoot, artifact)
+          report('builder artifact verified')
           return retain(root, artifact)
         } finally {
           rmSync(requestRoot, { recursive: true, force: true })
@@ -5288,6 +5438,7 @@ export function compileSwiftProjectUnit(
           `swift-compile: no swift.org toolchain at ${options.toolchainBin}; install ${options.release} and its matching wasm sdk`,
         )
       }
+      report('preparing compiler plugins')
       const macroPlugins = await ensureMacroPlugins(
         moduleRoot,
         options.toolchainBin,
@@ -5343,8 +5494,9 @@ export function compileSwiftProjectUnit(
         timeout: options.timeoutMs,
         signal: options.signal,
       }
+      report('compiling and linking Swift modules')
       try {
-        await runCompiler(swift, buildArgs, buildOptions)
+        await runCompiler(swift, buildArgs, buildOptions, true)
       } catch (error) {
         const output = outputOf(error)
         const moduleCache = path.join(
@@ -5360,7 +5512,7 @@ export function compileSwiftProjectUnit(
         ) {
           rmSync(moduleCache, { recursive: true, force: true })
           try {
-            await runCompiler(swift, buildArgs, buildOptions)
+            await runCompiler(swift, buildArgs, buildOptions, true)
           } catch (retryError) {
             throw new Error(
               projectDiagnostic(outputOf(retryError), layout, input.files),
@@ -5381,6 +5533,8 @@ export function compileSwiftProjectUnit(
         icu: await icu,
       }
       saveCompiledArtifact(root, artifact)
+      saveCompiledArtifact(sharedRoot, artifact)
+      report('compiled artifact verified')
       return retain(root, artifact)
     },
     options.signal,