Agent-session tracking: single source of truth (no title/mtime heuristics)

CLI/CMUXCLI+CodexFireAndForgetHooks.swift

@@ -1,4 +1,62 @@
+import Foundation
+
 extension CMUXCLI {
+    /// The per-invocation Codex hook events the wrapper injects, paired with the
+    /// cmux subcommand they call and the codex hook timeout (ms). Lifecycle
+    /// events are short; feed events (`PreToolUse`/`PermissionRequest`) are long
+    /// because the user may take time to approve. This is the single source of
+    /// truth for `cmux-codex-wrapper`'s injection, mirrored from the historic
+    /// hand-rolled `cmux_codex_add_hook` calls in the wrapper.
+    static let codexWrapperInjectionEvents: [(agentEvent: String, cmuxSubcommand: String, timeoutMs: Int)] = [
+        ("SessionStart", "session-start", 10000),
+        ("UserPromptSubmit", "prompt-submit", 10000),
+        ("Stop", "stop", 10000),
+        ("PreToolUse", "pre-tool-use", 120000),
+        ("PostToolUse", "post-tool-use", 10000),
+        ("PermissionRequest", "notification", 120000),
+    ]
+
+    /// Emit, NUL-separated to stdout, the exact codex arg list the wrapper must
+    /// splice ahead of the user's args to enable + inject cmux's fire-and-forget
+    /// hooks for one codex invocation. Returns the arg list:
+    ///   --enable\0hooks\0--dangerously-bypass-hook-trust\0
+    ///   -c\0hooks.SessionStart=[{hooks=[{type="command",command='''<ff>''',timeout=10000}]}]\0
+    ///   -c\0hooks.UserPromptSubmit=...\0 ... (one `-c` pair per event)
+    /// where `<ff>` is `codexFireAndForgetAgentHookShellCommand(...)` so each
+    /// hook returns `{}` to codex instantly and backgrounds the real cmux call.
+    /// Requires no live socket: pure string construction from the agent def.
+    func emitCodexWrapperInjectArgs() throws {
+        guard let codexDef = Self.agentDef(named: "codex") else {
+            throw CLIError(message: "Codex hook integration is unavailable.")
+        }
+        var args: [String] = ["--enable", "hooks", "--dangerously-bypass-hook-trust"]
+        for event in Self.codexWrapperInjectionEvents {
+            let ff = Self.codexFireAndForgetAgentHookShellCommand(
+                "cmux hooks codex \(event.cmuxSubcommand)", for: codexDef
+            )
+            // TOML multi-line literal string ('''...''') preserves bytes verbatim
+            // and may contain single quotes, so the embedded `echo '{}'` / `sh -c
+            // '...'` survive with no escaping. TOML forbids only a literal triple
+            // single quote inside; guard against it (the command never has one).
+            guard !ff.contains("'''") else {
+                throw CLIError(message: "Codex fire-and-forget hook command contains a triple single quote and cannot be TOML-encoded.")
+            }
+            let toml = "hooks.\(event.agentEvent)=[{hooks=[{type=\"command\",command='''\(ff)''',timeout=\(event.timeoutMs)}]}]"
+            args.append("-c")
+            args.append(toml)
+        }
+        // NUL-TERMINATE each arg (trailing NUL after the last too) so a bash
+        // `while IFS= read -r -d '' arg` loop captures every element including
+        // the final one — a separator-only stream drops the unterminated last
+        // arg at EOF.
+        var out = Data()
+        for arg in args {
+            out.append(Data(arg.utf8))
+            out.append(0)
+        }
+        FileHandle.standardOutput.write(out)
+    }
+
     static func codexFireAndForgetAgentHookShellCommand(_ command: String, for def: AgentHookDef) -> String {
         let routedArguments = command.hasPrefix("cmux ") ? String(command.dropFirst("cmux ".count)) : command
         let runner = "payload=\"$1\"; shift; \"$@\" <\"$payload\" >/dev/null 2>&1 & child=\"$!\"; ( sleep 30; kill \"$child\" 2>/dev/null || true ) & watchdog=\"$!\"; wait \"$child\" 2>/dev/null || true; kill \"$watchdog\" 2>/dev/null || true; rm -f \"$payload\""

CLI/cmux.swift

@@ -29587,14 +29587,15 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
                 client: client
             )
         }
-        func sendAgentFeedTelemetry(workspaceId: String? = nil) {
+        func sendAgentFeedTelemetry(workspaceId: String? = nil, surfaceId: String? = nil) {
             didSendFeedTelemetry = true
             sendFeedTelemetry(
                 client: client,
                 source: def.name,
                 subcommand: subcommand,
                 parsedInput: input,
                 workspaceId: workspaceId ?? workspaceArg(),
+                surfaceId: surfaceId,
                 socketPassword: socketPassword
             )
         }
@@ -29610,11 +29611,11 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
             }
             return def.feedHookEvents.contains(event)
         }
-        func sendAgentFeedTelemetryUnlessSuppressed(workspaceId: String? = nil) {
+        func sendAgentFeedTelemetryUnlessSuppressed(workspaceId: String? = nil, surfaceId: String? = nil) {
             if shouldSuppressGenericFeedTelemetry() {
                 didSendFeedTelemetry = true
             } else {
-                sendAgentFeedTelemetry(workspaceId: workspaceId)
+                sendAgentFeedTelemetry(workspaceId: workspaceId, surfaceId: surfaceId)
             }
         }
         func notificationDedupeFingerprint(status: AgentHookNotificationStatus?) -> String? {
@@ -29820,7 +29821,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
                 print("{}")
                 return
             }
-            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
             if !suppressVisibleMutations {
                 if codexSessionStartWentStaleAfterAccept() {
                     telemetry.breadcrumb("\(def.name)-hook.session-start.stale-after-turn")
@@ -30083,7 +30084,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
                 stopStaleCodexPromptSubmit()
                 return
             }
-            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
             if !sessionId.isEmpty, !suppressVisibleMutations {
                 let acceptedRunningUpdate: Bool
                 if def.name == "codex" {
@@ -30231,7 +30232,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
             }
             let workspaceId = target.workspaceId
             let surfaceId = target.surfaceId
-            sendAgentFeedTelemetry(workspaceId: workspaceId)
+            sendAgentFeedTelemetry(workspaceId: workspaceId, surfaceId: surfaceId)
             let pid = mapped?.pid ?? inferredPID
             let codexFailure: CodexHookFailureSummary?
             let codexSubagentSignals: CodexTranscriptSubagentSignals
@@ -30551,7 +30552,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
             }
             let workspaceId = target.workspaceId
             let surfaceId = target.surfaceId
-            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
             let pid = mapped?.pid ?? inferredPID
             let launchCommand = agentLaunchCommandFromEnvironment(
                 env,
@@ -30692,7 +30693,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
                     env: env
                 )
 #endif
-                sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+                sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
                 print("{}")
                 return
             }
@@ -30707,7 +30708,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
                     env: env
                 )
 #endif
-                sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+                sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
                 print("{}")
                 return
             }
@@ -30854,15 +30855,15 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
             case nil:
                 break
             }
-            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId)
+            sendAgentFeedTelemetryUnlessSuppressed(workspaceId: workspaceId, surfaceId: surfaceId)
 
         case .sessionEnd:
             if def.name == "codex", !sessionId.isEmpty {
                 retireCodexMonitorLeases(sessionId: sessionId, turnId: nil, env: env)
             }
             if def.sessionEndIsTurnBoundary {
                 if let mapped = sessionId.isEmpty ? nil : (try? store.lookup(sessionId: sessionId)) {
-                    sendAgentFeedTelemetry(workspaceId: mapped.workspaceId)
+                    sendAgentFeedTelemetry(workspaceId: mapped.workspaceId, surfaceId: mapped.surfaceId)
                     _ = try? store.recordPromptStop(
                         sessionId: sessionId,
                         workspaceId: mapped.workspaceId,
@@ -30932,6 +30933,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
         subcommand: String,
         parsedInput: ClaudeHookParsedInput,
         workspaceId: String? = nil,
+        surfaceId: String? = nil,
         socketPassword: String? = nil
     ) {
         let hookEventName = Self.feedEventName(forClaudeSubcommand: subcommand)
@@ -30955,6 +30957,12 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
         if let workspaceId = feedWorkspaceId(rawObject: parsedInput.object, fallback: workspaceId) {
             event["workspace_id"] = workspaceId
         }
+        if let surfaceId, !surfaceId.isEmpty {
+            event["surface_id"] = surfaceId
+        }
+        if let transcriptPath = parsedInput.transcriptPath, !transcriptPath.isEmpty {
+            event["transcript_path"] = transcriptPath
+        }
         if let cwd = parsedInput.cwd { event["cwd"] = cwd }
         let toolName = parsedInput.object?["tool_name"] as? String
         if let toolName, !toolName.isEmpty {
@@ -33538,6 +33546,12 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
             }
             let actionArgs = Array(rest.dropFirst())
             switch action {
+            case "inject-args" where def.name == "codex":
+                // Hidden: emit the NUL-separated codex arg list the wrapper
+                // (Resources/bin/cmux-codex-wrapper) splices to inject cmux's
+                // fire-and-forget hooks for one invocation. No socket required.
+                try emitCodexWrapperInjectArgs()
+                return true
             case "install":
                 try installHooksForAgent(def, arguments: actionArgs)
                 return true

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Model/ChatSessionDescriptor.swift

@@ -38,6 +38,13 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
     /// Timestamp of the most recent transcript or hook activity.
     public let lastActivityAt: Date?
 
+    /// Monotonic per-session revision, bumped by the host on every change to
+    /// this session. The client reconciles best-effort pushes against
+    /// authoritative pulls by this number: apply a push only when its version
+    /// is strictly greater than the last applied, and replace wholesale from a
+    /// snapshot pull. A missed or duplicated push self-heals on the next pull.
+    public var version: Int = 0
+
     /// Creates a session descriptor.
     ///
     /// - Parameters:
@@ -86,7 +93,8 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
         terminalID: String? = nil,
         workingDirectory: String? = nil,
         state: ChatAgentState = .idle,
-        lastActivityAt: Date? = nil
+        lastActivityAt: Date? = nil,
+        version: Int = 0
     ) {
         self.id = id
         self.agentKind = agentKind
@@ -97,6 +105,7 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
         self.workingDirectory = workingDirectory
         self.state = state
         self.lastActivityAt = lastActivityAt
+        self.version = version
     }
 
     /// A copy with a new live state, leaving identity and bindings intact.
@@ -115,7 +124,8 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
             terminalID: terminalID,
             workingDirectory: workingDirectory,
             state: newState,
-            lastActivityAt: lastActivityAt
+            lastActivityAt: lastActivityAt,
+            version: version
         )
     }
 
@@ -129,6 +139,7 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
         case workingDirectory = "cwd"
         case state
         case lastActivityAt = "last_activity_at"
+        case version
     }
 
     // Custom Codable so `kind` decodes with a `.agent` default when absent
@@ -145,6 +156,7 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
         workingDirectory = try container.decodeIfPresent(String.self, forKey: .workingDirectory)
         state = try container.decode(ChatAgentState.self, forKey: .state)
         lastActivityAt = try container.decodeIfPresent(Date.self, forKey: .lastActivityAt)
+        version = try container.decodeIfPresent(Int.self, forKey: .version) ?? 0
     }
 
     public func encode(to encoder: any Encoder) throws {
@@ -158,5 +170,6 @@ public struct ChatSessionDescriptor: Identifiable, Sendable, Equatable, Codable
         try container.encodeIfPresent(workingDirectory, forKey: .workingDirectory)
         try container.encode(state, forKey: .state)
         try container.encodeIfPresent(lastActivityAt, forKey: .lastActivityAt)
+        try container.encode(version, forKey: .version)
     }
 }

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Store/ChatSessionListReducer.swift

@@ -38,6 +38,19 @@ public struct ChatSessionListReducer: Sendable {
             }
             var updated = sessions
             if let index = updated.firstIndex(where: { $0.id == descriptor.id }) {
+                // Version-gated upsert: best-effort pushes can arrive out of
+                // order, be duplicated, or race an authoritative pull. The host
+                // stamps a strictly increasing `version` on every change, so a
+                // descriptor whose version is LOWER than the one already
+                // applied is stale (or out of order) and must not clobber newer
+                // state the client got from a later push or a snapshot pull.
+                // Equal version is allowed through (a no-op in practice: the
+                // monotonic counter guarantees equal version == identical
+                // content), which also keeps unversioned (version 0) payloads
+                // upserting as before.
+                guard descriptor.version >= updated[index].version else {
+                    return sessions
+                }
                 updated[index] = descriptor
             } else {
                 updated.append(descriptor)

Packages/Shared/CmuxAgentChat/Tests/CmuxAgentChatTests/ChatSessionListReducerTests.swift

@@ -100,4 +100,28 @@ struct ChatSessionListReducerTests {
         )
         #expect(reducer.applying(frame, to: seed).count == 1)
     }
+
+    @Test("a lower-version descriptorChanged is dropped; a higher one applies")
+    func versionGatedUpsert() {
+        let reducer = ChatSessionListReducer(workspaceID: "ws-1")
+        func desc(_ state: ChatAgentState, _ version: Int) -> ChatSessionDescriptor {
+            ChatSessionDescriptor(
+                id: "s1", agentKind: .claude, workspaceID: "ws-1",
+                terminalID: "s1", state: state, version: version
+            )
+        }
+        // Seed at version 5 (working).
+        let seed = [desc(Self.working, 5)]
+        // A stale push (version 3, idle) arrives out of order and is dropped:
+        // the newer working state the client already holds must survive.
+        let stale = ChatSessionEventFrame(sessionID: "s1", event: .descriptorChanged(desc(.idle, 3)))
+        let afterStale = reducer.applying(stale, to: seed)
+        #expect(afterStale.first?.state == Self.working)
+        #expect(afterStale.first?.version == 5)
+        // A newer push (version 6, ended) applies.
+        let newer = ChatSessionEventFrame(sessionID: "s1", event: .descriptorChanged(desc(.ended, 6)))
+        let afterNewer = reducer.applying(newer, to: afterStale)
+        #expect(afterNewer.first?.state == .ended)
+        #expect(afterNewer.first?.version == 6)
+    }
 }

Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileChatEventSource.swift

@@ -38,6 +38,29 @@ public actor MobileChatEventSource: ChatEventSource {
         return try coding.decode(MobileChatSessionsResponse.self, from: result).sessions
     }
 
+    /// Pulls the authoritative snapshot of one session by id.
+    ///
+    /// The client's reconcile path: on (re)connect, foreground, a detected
+    /// version gap, or manual refresh, the host fetches the current descriptor
+    /// and folds it through the same version-gated upsert as a push, so a pull
+    /// that races a newer push converges. Pull is authoritative; push is a
+    /// best-effort hint, so a missed or out-of-order push self-heals here.
+    ///
+    /// Not part of ``CmuxAgentChat/ChatEventSource`` (which is scoped to one
+    /// conversation). Throws when the host no longer knows the session (treat
+    /// as gone) or the request fails.
+    ///
+    /// - Parameter sessionID: The session to snapshot.
+    /// - Returns: The session's current descriptor, with its `version`.
+    public func session(sessionID: String) async throws -> ChatSessionDescriptor {
+        let request = try MobileCoreRPCClient.requestData(
+            method: "mobile.chat.session",
+            params: ["session_id": sessionID]
+        )
+        let result = try await client.sendRequest(request)
+        return try coding.decode(MobileChatSessionResponse.self, from: result).session
+    }
+
     /// Opens the live stream of session-list events for every session the
     /// Mac knows about (not scoped to one conversation).
     ///

Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileChatSessionResponse.swift

@@ -0,0 +1,19 @@
+public import CmuxAgentChat
+
+/// Result payload of `mobile.chat.session` (single-session snapshot pull).
+public struct MobileChatSessionResponse: Sendable, Equatable, Codable {
+    /// The authoritative current descriptor for the requested session,
+    /// carrying the host's monotonic `version` for reconciliation.
+    public let session: ChatSessionDescriptor
+
+    /// Creates a response.
+    ///
+    /// - Parameter session: The session descriptor.
+    public init(session: ChatSessionDescriptor) {
+        self.session = session
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case session
+    }
+}