@@ -50,12 +50,24 @@ jobs:
     outputs:
       archive_name: ${{ steps.package.outputs.archive_name }}
       checksum_name: ${{ steps.package.outputs.checksum_name }}
+      distribution_ready: ${{ steps.package.outputs.distribution_ready }}
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           persist-credentials: false
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install locked dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build the bundled dashboard
+        run: bun run build:gui
+
       - name: Package the macOS companion
         id: package
         env:
@@ -79,7 +91,10 @@ jobs:
   attach-macos:
     runs-on: ubuntu-latest
     needs: [publish, package-macos]
-    if: ${{ inputs.dry-run != true }}
+    # Development/ad-hoc ZIPs remain downloadable workflow artifacts, but are never
+    # attached to a public release. The packager marks an asset distribution-ready
+    # only after Developer ID signing, Gatekeeper assessment, and staple validation.
+    if: ${{ inputs.dry-run != true && needs.package-macos.outputs.distribution_ready == 'true' }}
     timeout-minutes: 10
     permissions:
       contents: write # attach assets to the release created by publish
 
@@ -16,6 +16,24 @@ public enum RestartOutcome: Equatable, Sendable {
 public enum ProxyControlOutcome: Equatable, Sendable {
     case running
     case stopped
+    /// The proxy is healthy, but long-lived Codex workers still hold an older roster.
+    case catalogUpdateReady(staleWorkerCount: Int?)
+    case failed(String)
+}
+
+public struct CodexCatalogApplySummary: Equatable, Sendable {
+    public let catalogUpdated: Bool
+    public let stoppedWorkerCount: Int
+
+    public init(catalogUpdated: Bool, stoppedWorkerCount: Int) {
+        self.catalogUpdated = catalogUpdated
+        self.stoppedWorkerCount = stoppedWorkerCount
+    }
+}
+
+public enum CodexCatalogApplyOutcome: Equatable, Sendable {
+    case applied(CodexCatalogApplySummary)
+    case incomplete(message: String, stoppedWorkerCount: Int, survivingWorkerCount: Int)
     case failed(String)
 }
 
@@ -65,6 +83,9 @@ public actor ActionCoordinator {
     ) async -> ProxyControlOutcome {
         do {
             let result = try await lifecycle.run(action)
+            if result.state == .running, result.codexRestartRequired == true {
+                return .catalogUpdateReady(staleWorkerCount: result.staleWorkerCount)
+            }
             guard result.ok, result.state == expected else {
                 return .failed(result.message)
             }
@@ -76,6 +97,42 @@ public actor ActionCoordinator {
         }
     }
 
+    /// Applies the current model catalog and restarts only Codex's catalog-caching
+    /// workers through the fixed lifecycle bridge. The OpenCodex proxy is untouched.
+    public func applyCodexCatalog() async -> CodexCatalogApplyOutcome {
+        do {
+            let result = try await lifecycle.run(.applyCodexCatalog)
+            let stopped = result.stoppedWorkerCount ?? 0
+            let surviving = result.survivingWorkerCount ?? 0
+            // A stale worker may coexist with a refused or failed catalog write. The
+            // write failure is authoritative: never describe that result as applied.
+            if !result.ok, result.errorCode == "SYNC_FAILED" {
+                return .failed(result.message)
+            }
+            if surviving > 0 || result.codexRestartRequired == true {
+                return .incomplete(
+                    message: result.message,
+                    stoppedWorkerCount: stopped,
+                    survivingWorkerCount: surviving
+                )
+            }
+            guard result.ok,
+                  result.state == .running || result.state == .stopped,
+                  let catalogUpdated = result.catalogUpdated
+            else {
+                return .failed(result.message)
+            }
+            return .applied(CodexCatalogApplySummary(
+                catalogUpdated: catalogUpdated,
+                stoppedWorkerCount: stopped
+            ))
+        } catch let error as LifecycleHelperError {
+            return .failed(error.userMessage)
+        } catch {
+            return .failed("OpenCodex could not apply the agent catalog update.")
+        }
+    }
+
     /// Requests the proxy's owned drain-and-restart path and waits for a replacement
     /// OpenCodex identity. A 202 only means accepted; success requires a newly
     /// identity-validated process (or a refused interval followed by a valid process
 
@@ -7,6 +7,7 @@ public enum LifecycleAction: String, Codable, Sendable {
     case start
     case stop
     case restart
+    case applyCodexCatalog
 }
 
 public enum LifecycleState: String, Codable, Sendable {
@@ -27,6 +28,13 @@ public struct LifecycleCommandResult: Codable, Equatable, Sendable {
     public let port: Int?
     public let message: String
     public let errorCode: String?
+    /// Catalog-action fields are additive so older lifecycle results remain decodable.
+    /// The app deliberately receives counts rather than process identifiers.
+    public let catalogUpdated: Bool?
+    public let codexRestartRequired: Bool?
+    public let staleWorkerCount: Int?
+    public let stoppedWorkerCount: Int?
+    public let survivingWorkerCount: Int?
 
     public init(
         schemaVersion: Int = 1,
@@ -37,7 +45,12 @@ public struct LifecycleCommandResult: Codable, Equatable, Sendable {
         pid: Int? = nil,
         port: Int? = nil,
         message: String,
-        errorCode: String? = nil
+        errorCode: String? = nil,
+        catalogUpdated: Bool? = nil,
+        codexRestartRequired: Bool? = nil,
+        staleWorkerCount: Int? = nil,
+        stoppedWorkerCount: Int? = nil,
+        survivingWorkerCount: Int? = nil
     ) {
         self.schemaVersion = schemaVersion
         self.action = action
@@ -48,6 +61,11 @@ public struct LifecycleCommandResult: Codable, Equatable, Sendable {
         self.port = port
         self.message = message
         self.errorCode = errorCode
+        self.catalogUpdated = catalogUpdated
+        self.codexRestartRequired = codexRestartRequired
+        self.staleWorkerCount = staleWorkerCount
+        self.stoppedWorkerCount = stoppedWorkerCount
+        self.survivingWorkerCount = survivingWorkerCount
     }
 }
 
@@ -92,10 +110,19 @@ public enum LifecycleHelperDiscovery {
         home: URL = FileManager.default.homeDirectoryForCurrentUser,
         fileManager: FileManager = .default
     ) -> LifecycleInvocation? {
+        // The repository build is deliberately live: while developing, edits in the
+        // checkout must take effect without rebuilding the copied Resources snapshot.
         if let source = sourceInvocation(bundleURL: bundleURL, fileManager: fileManager) {
             return source
         }
 
+        // A released companion carries the complete Bun + OpenCodex package under
+        // Contents/Resources/runtime. Resolve it before global installs so a copied app
+        // never accidentally controls a different checkout or npm installation.
+        if let bundled = bundledInvocation(bundleURL: bundleURL, fileManager: fileManager) {
+            return bundled
+        }
+
         // Release companions may be launched outside the source tree. Only inspect
         // fixed installation locations, then resolve an npm/bun symlink back to an
         // actual OpenCodex package root. PATH and version-directory scans would turn
@@ -125,6 +152,19 @@ public enum LifecycleHelperDiscovery {
         return nil
     }
 
+    private static func bundledInvocation(
+        bundleURL: URL,
+        fileManager: FileManager
+    ) -> LifecycleInvocation? {
+        let bundle = bundleURL.resolvingSymlinksInPath()
+        guard bundle.pathExtension == "app" else { return nil }
+        let runtime = bundle
+            .appendingPathComponent("Contents", isDirectory: true)
+            .appendingPathComponent("Resources", isDirectory: true)
+            .appendingPathComponent("runtime", isDirectory: true)
+        return repositoryInvocation(runtime, fileManager: fileManager)
+    }
+
     private static func sourceInvocation(
         bundleURL: URL,
         fileManager: FileManager
@@ -263,7 +303,7 @@ public actor LifecycleHelper: LifecycleCommandRunning {
                 process.arguments = invocation.prefixArguments + ["__macos-lifecycle", action.rawValue]
                 process.standardOutput = pipe
                 process.standardError = FileHandle.nullDevice
-                process.environment = Self.controlledEnvironment()
+                process.environment = Self.controlledEnvironment(for: invocation.executable)
                 pipe.fileHandleForReading.readabilityHandler = { handle in
                     output.append(handle.availableData)
                 }
@@ -313,6 +353,15 @@ public actor LifecycleHelper: LifecycleCommandRunning {
                       result.message.utf8.count <= 240,
                       result.pid.map({ $0 > 0 }) ?? true,
                       result.port.map({ (1...65_535).contains($0) }) ?? true,
+                      result.staleWorkerCount.map({ $0 >= 0 }) ?? true,
+                      result.stoppedWorkerCount.map({ $0 >= 0 }) ?? true,
+                      result.survivingWorkerCount.map({ $0 >= 0 }) ?? true,
+                      action != .applyCodexCatalog || !result.ok || (
+                          result.catalogUpdated != nil
+                              && result.codexRestartRequired != nil
+                              && result.stoppedWorkerCount != nil
+                              && result.survivingWorkerCount != nil
+                      ),
                       (process.terminationStatus == 0) == result.ok
                 else {
                     continuation.resume(throwing: LifecycleHelperError.invalidResponse)
@@ -325,9 +374,14 @@ public actor LifecycleHelper: LifecycleCommandRunning {
 
     /// Preserve OpenCodex/Codex configuration while removing runtime preloads and an
     /// attacker-controlled PATH from this privileged fixed-action bridge.
-    private nonisolated static func controlledEnvironment() -> [String: String] {
+    private nonisolated static func controlledEnvironment(for executable: URL) -> [String: String] {
         var environment = ProcessInfo.processInfo.environment
         environment["PATH"] = "/usr/bin:/bin:/usr/sbin:/sbin"
+        if executable.path.contains("/Contents/Resources/runtime/") {
+            // The app-owned runtime must never enter npm/source self-update paths.
+            // This marker is inherited by the Bun proxy process and its management API.
+            environment["OCX_APP_RUNTIME"] = "1"
+        }
         for key in [
             "BUN_OPTIONS", "BUN_INSPECT", "BUN_INSPECT_CONNECT_TO",
             "NODE_OPTIONS", "NODE_PATH", "LD_PRELOAD",
 
@@ -197,6 +197,135 @@ enum ActionSuite {
             )
         }
 
+        t.test("lifecycle: a live proxy with stale Codex workers becomes update-ready") {
+            let lifecycle = FakeLifecycleRunner(results: [
+                LifecycleCommandResult(
+                    action: .ensure, ok: false, state: .running,
+                    changed: true, pid: 41, port: 10100,
+                    message: "Restart ChatGPT to load the routed models.",
+                    errorCode: "CODEX_RESTART_REQUIRED",
+                    codexRestartRequired: true,
+                    staleWorkerCount: 2
+                ),
+            ])
+            let coordinator = ActionCoordinator(
+                client: FakeActionClient(liveness: []),
+                lifecycle: lifecycle
+            )
+            t.equal(
+                sync { await coordinator.ensure() },
+                .catalogUpdateReady(staleWorkerCount: 2)
+            )
+        }
+
+        t.test("lifecycle: restart-like error codes without the additive flag remain failures") {
+            let lifecycle = FakeLifecycleRunner(results: [
+                LifecycleCommandResult(
+                    action: .ensure, ok: false, state: .running,
+                    changed: false, pid: 41, port: 10100,
+                    message: "Legacy Codex restart required.",
+                    errorCode: "CODEX_RESTART_REQUIRED"
+                ),
+                LifecycleCommandResult(
+                    action: .ensure, ok: false, state: .running,
+                    changed: false, pid: 41, port: 10100,
+                    message: "Proxy restart required.",
+                    errorCode: "PROXY_RESTART_REQUIRED"
+                ),
+            ])
+            let coordinator = ActionCoordinator(
+                client: FakeActionClient(liveness: []),
+                lifecycle: lifecycle
+            )
+            t.equal(
+                sync { await coordinator.ensure() },
+                .failed("Legacy Codex restart required.")
+            )
+            t.equal(
+                sync { await coordinator.ensure() },
+                .failed("Proxy restart required.")
+            )
+        }
+
+        t.test("catalog apply: uses the fixed helper action and returns counts") {
+            let lifecycle = FakeLifecycleRunner(results: [
+                LifecycleCommandResult(
+                    action: .applyCodexCatalog, ok: true, state: .running,
+                    changed: true, pid: 41, port: 10100,
+                    message: "Agent catalog updated.",
+                    catalogUpdated: true,
+                    codexRestartRequired: false,
+                    stoppedWorkerCount: 2,
+                    survivingWorkerCount: 0
+                ),
+            ])
+            let coordinator = ActionCoordinator(
+                client: FakeActionClient(liveness: []),
+                lifecycle: lifecycle
+            )
+            t.equal(
+                sync { await coordinator.applyCodexCatalog() },
+                .applied(CodexCatalogApplySummary(
+                    catalogUpdated: true,
+                    stoppedWorkerCount: 2
+                ))
+            )
+            t.equal(
+                sync { await lifecycle.recordedActions() },
+                [.applyCodexCatalog]
+            )
+        }
+
+        t.test("catalog apply: surviving workers remain an incomplete update") {
+            let lifecycle = FakeLifecycleRunner(results: [
+                LifecycleCommandResult(
+                    action: .applyCodexCatalog, ok: false, state: .running,
+                    changed: true, pid: 41, port: 10100,
+                    message: "One Codex worker is still running.",
+                    catalogUpdated: true,
+                    codexRestartRequired: true,
+                    stoppedWorkerCount: 1,
+                    survivingWorkerCount: 1
+                ),
+            ])
+            let coordinator = ActionCoordinator(
+                client: FakeActionClient(liveness: []),
+                lifecycle: lifecycle
+            )
+            t.equal(
+                sync { await coordinator.applyCodexCatalog() },
+                .incomplete(
+                    message: "One Codex worker is still running.",
+                    stoppedWorkerCount: 1,
+                    survivingWorkerCount: 1
+                )
+            )
+        }
+
+        t.test("catalog apply: a sync failure wins over stale surviving workers") {
+            let lifecycle = FakeLifecycleRunner(results: [
+                LifecycleCommandResult(
+                    action: .applyCodexCatalog, ok: false, state: .running,
+                    changed: false, pid: 41, port: 10100,
+                    message: "Agent catalog update did not complete.",
+                    errorCode: "SYNC_FAILED",
+                    catalogUpdated: false,
+                    codexRestartRequired: true,
+                    staleWorkerCount: 2,
+                    stoppedWorkerCount: 0,
+                    survivingWorkerCount: 2
+                ),
+            ])
+            let coordinator = ActionCoordinator(
+                client: FakeActionClient(liveness: []),
+                lifecycle: lifecycle
+            )
+            t.equal(
+                sync { await coordinator.applyCodexCatalog() },
+                .failed("Agent catalog update did not complete.")
+            )
+        }
+
     }
 
     private static func sync<T>(_ operation: @escaping () async -> T) -> T {