resume: hookless directory-scoped continue bindings for remote agents (#7989)

CLI/cmux.swift

@@ -4794,8 +4794,27 @@ struct CMUXCLI {
                     defaultValue: "[cmux] remote session was lost; starting a new shell."
                 )
                 cliWriteStderr(Data((notice + "\n").utf8))
+                var respawnArgs = stableAttachArgs.filter { $0 != "--require-existing" }
+                // Hookless remote resume (#7989): the app can synthesize a
+                // directory-scoped continue command from the daemon's
+                // foreground tombstone for the session that just died. Any
+                // failure degrades to the plain replacement shell.
+                if let resumeCommand = sessionLostResumeRemoteCommand(
+                    client: client,
+                    attachArgs: stableAttachArgs
+                ) {
+                    let resumeNotice = String(
+                        localized: "cli.sshPtyAttach.remoteSessionLostResume",
+                        defaultValue: "[cmux] resuming the agent that was running in the lost session."
+                    )
+                    cliWriteStderr(Data((resumeNotice + "\n").utf8))
+                    respawnArgs = replacingSSHPTYAttachCommandB64(
+                        in: respawnArgs,
+                        with: Data(resumeCommand.utf8).base64EncodedString()
+                    )
+                }
                 try runSSHPTYAttach(
-                    commandArgs: stableAttachArgs.filter { $0 != "--require-existing" },
+                    commandArgs: respawnArgs,
                     client: client,
                     explicitPassword: socketPasswordArg
                 )
@@ -12801,6 +12820,67 @@ struct CMUXCLI {
         return ["workspace_id": workspaceId]
     }
 
+    /// Asks the app for a hookless remote continue command (#7989) after the
+    /// wrapper confirmed the persistent session was lost. The daemon's
+    /// foreground tombstone supplies the facts; binding precedence,
+    /// auto-resume, and approval policy stay in the app. Every failure —
+    /// older app, no tombstone, policy says attach plain — returns nil so the
+    /// respawn degrades to the existing replacement-shell behavior.
+    private func sessionLostResumeRemoteCommand(
+        client: SocketClient,
+        attachArgs: [String]
+    ) -> String? {
+        let (workspaceOpt, _) = parseOption(attachArgs, name: "--workspace")
+        let (sessionIDOpt, _) = parseOption(attachArgs, name: "--session-id")
+        let (attachmentIDOpt, _) = parseOption(attachArgs, name: "--attachment-id")
+        let environmentSurfaceID = Self.normalizedEnvValue(
+            ProcessInfo.processInfo.environment["CMUX_SURFACE_ID"]
+        )
+        let surfaceID = environmentSurfaceID
+            ?? Self.normalizedEnvValue(attachmentIDOpt).flatMap { UUID(uuidString: $0) == nil ? nil : $0 }
+        guard let workspaceID = Self.normalizedEnvValue(workspaceOpt)
+            ?? Self.normalizedEnvValue(ProcessInfo.processInfo.environment["CMUX_WORKSPACE_ID"]),
+            let sessionID = Self.normalizedEnvValue(sessionIDOpt),
+            let surfaceID else {
+            return nil
+        }
+        // The app-side handler deliberately outwaits the coordinator's daemon
+        // bootstrap (bounded at 20s), so this call must outlast it.
+        guard let payload = try? client.sendV2(
+            method: "workspace.remote.pty_session_lost_resume",
+            params: [
+                "workspace_id": workspaceID,
+                "surface_id": surfaceID,
+                "session_id": sessionID,
+            ],
+            responseTimeout: 30
+        ) else {
+            return nil
+        }
+        guard let command = payload["command"] as? String,
+              !command.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return nil
+        }
+        return command
+    }
+
+    /// Returns `args` with any `--command-b64 <value>` pair replaced by the
+    /// synthesized resume payload.
+    private func replacingSSHPTYAttachCommandB64(in args: [String], with base64: String) -> [String] {
+        var result: [String] = []
+        var index = 0
+        while index < args.count {
+            if args[index] == "--command-b64", index + 1 < args.count {
+                index += 2
+                continue
+            }
+            result.append(args[index])
+            index += 1
+        }
+        result.append(contentsOf: ["--command-b64", base64])
+        return result
+    }
+
     private func runSSHPTYAttach(commandArgs: [String], client: SocketClient, explicitPassword: String?) throws {
         let (workspaceOpt, rem0) = parseOption(commandArgs, name: "--workspace")
         let (sessionIDOpt, rem1) = parseOption(rem0, name: "--session-id")

Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Wire/ControlCommandExecutionPolicy.swift

@@ -125,6 +125,14 @@ public enum ControlCommandExecutionPolicy: Sendable, Equatable {
         // lane like the other workspace reads below.
         "workspace.env",
         "workspace.remote.pty_sessions",
+        // `workspace.remote.pty_session_lost_resume` deliberately outwaits the
+        // workspace coordinator's daemon bootstrap (bounded, signal-driven) and
+        // then queries the daemon's ended-session tombstones over the tunnel
+        // (#7989), so it must never hold the main actor; policy and binding
+        // registration take one `v2MainSync` hop. Without this entry the
+        // policy routes it to the main-actor processV2Command switch, which
+        // lacks the case, and the control socket returns method_not_found.
+        "workspace.remote.pty_session_lost_resume",
         "workspace.remote.pty_close",
         "workspace.remote.pty_detach",
         "workspace.remote.pty_bridge",

Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandExecutionPolicyTests.swift

@@ -32,6 +32,9 @@ struct ControlCommandExecutionPolicyTests {
             "feed.push", "browser.download.wait", "system.top", "system.memory",
             "workspace.remote.pty_bridge", "workspace.env", "sidebar.custom.reload",
             "sidebar.custom.open",
+            // Tombstone-backed hookless resume outwaits daemon bootstrap and
+            // queries the tunnel; it must never hold the main actor (#7989).
+            "workspace.remote.pty_session_lost_resume",
             "debug.sidebar.simulate_drag", "debug.mobile.transport.disconnect",
             "debug.window.screenshot", "mobile.attach_ticket.create",
             "mobile.terminal.set_font", "mobile.task.models.list",

Packages/macOS/CmuxRemoteDaemon/Sources/CmuxRemoteDaemon/Client/RemoteDaemonRPCClient+RPC.swift

@@ -264,6 +264,15 @@ extension RemoteDaemonRPCClient {
         return result["sessions"] as? [[String: Any]] ?? []
     }
 
+    /// Lists ended persistent PTY sessions that retained a foreground-process
+    /// tombstone (`pty.list` → `ended_sessions`): the last agent command the
+    /// daemon sampled before the session died (#7989). Older daemons omit the
+    /// key; absence decodes as no tombstones.
+    public func listEndedPTY() throws -> [[String: Any]] {
+        let result = try call(method: "pty.list", params: [:], timeout: 8.0)
+        return result["ended_sessions"] as? [[String: Any]] ?? []
+    }
+
     /// Drops a local PTY subscription without telling the daemon.
     public func unregisterPTY(sessionID: String, attachmentID: String, attachmentToken: String? = nil) {
         let key = Self.ptySubscriptionKey(

Packages/macOS/CmuxRemoteSession/Sources/CmuxRemoteSession/Session/RemoteSessionCoordinator+PTYBridge.swift

@@ -23,6 +23,19 @@ extension RemoteSessionCoordinator {
         }
     }
 
+    /// Lists the daemon's ended-session foreground tombstones (#7989) as raw
+    /// wire dictionaries; same blocking contract as ``listPTYSessions(timeout:)``.
+    public func listEndedPTYSessions(timeout: TimeInterval = 8.0) throws -> [[String: Any]] {
+        try runOnControllerQueue(timeout: timeout) {
+            guard self.daemonReady, self.proxyLease != nil else {
+                throw NSError(domain: "cmux.remote.pty", code: 1, userInfo: [
+                    NSLocalizedDescriptionKey: "remote daemon is not ready",
+                ])
+            }
+            return try self.proxyBroker.listEndedPTY(configuration: self.configuration)
+        }
+    }
+
     /// Closes one persistent PTY session by ID; same blocking contract as
     /// ``listPTYSessions(timeout:)``.
     public func closePTYSession(sessionID: String, timeout: TimeInterval = 8.0) throws {

Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/Broker/RemoteProxyBroker.swift

@@ -115,6 +115,13 @@ public final class RemoteProxyBroker: @unchecked Sendable {
         }
     }
 
+    /// Lists ended-session foreground tombstones through the ready tunnel (#7989).
+    public func listEndedPTY(configuration: WorkspaceRemoteConfiguration) throws -> [[String: Any]] {
+        try withReadyTunnel(configuration: configuration) { tunnel in
+            try tunnel.listEndedPTY()
+        }
+    }
+
     /// Closes a persistent PTY session through the ready tunnel.
     ///
     /// The broker queue is used only to pin the tunnel; the potentially

Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/Broker/RemoteProxyBrokering.swift

@@ -30,6 +30,10 @@ public protocol RemoteProxyBrokering: AnyObject, Sendable {
     /// `configuration`; throws when no tunnel is ready.
     func listPTY(configuration: WorkspaceRemoteConfiguration) throws -> [[String: Any]]
 
+    /// Lists ended-session foreground tombstones through the ready tunnel for
+    /// `configuration` (#7989); throws when no tunnel is ready.
+    func listEndedPTY(configuration: WorkspaceRemoteConfiguration) throws -> [[String: Any]]
+
     /// Closes a persistent PTY session through the ready tunnel before `deadline`.
     ///
     /// - Parameters:
@@ -194,4 +198,9 @@ extension RemoteProxyBrokering {
             wasCurrent: wasCurrent
         )
     }
+
+    /// Foreground tombstones are an optional daemon capability; brokers that
+    /// predate it (and test fakes) report none. ``RemoteProxyBroker``
+    /// overrides this with the ready-tunnel query.
+    public func listEndedPTY(configuration: WorkspaceRemoteConfiguration) throws -> [[String: Any]] { [] }
 }

Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/Broker/RemoteProxyTunneling.swift

@@ -33,6 +33,10 @@ public protocol RemoteProxyTunneling: AnyObject {
     /// shape pinned).
     func listPTY() throws -> [[String: Any]]
 
+    /// Lists ended persistent PTY sessions whose foreground-process tombstone
+    /// the daemon retained (#7989). Raw JSON objects, wire shape pinned.
+    func listEndedPTY() throws -> [[String: Any]]
+
     /// Closes a persistent PTY session on the daemon before `deadline`.
     ///
     /// - Parameters:
@@ -66,3 +70,9 @@ public protocol RemoteProxyTunneling: AnyObject {
         onLifecycleEnded: @escaping @Sendable () -> Void
     ) throws -> RemotePTYBridgeServer.Endpoint
 }
+
+public extension RemoteProxyTunneling {
+    /// Foreground tombstones are an optional daemon capability; tunnels that
+    /// predate it (and test doubles) report none.
+    func listEndedPTY() throws -> [[String: Any]] { [] }
+}

Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/Tunnel/RemoteDaemonProxyTunnel.swift

@@ -163,6 +163,21 @@ public final class RemoteDaemonProxyTunnel: @unchecked Sendable {
         }
     }
 
+    /// Lists the daemon's ended-session foreground tombstones (#7989).
+    ///
+    /// Same wire-shape contract as ``listPTY()``; older daemons simply omit
+    /// the key and decode as empty.
+    public func listEndedPTY() throws -> [[String: Any]] {
+        try queue.sync {
+            guard let rpcClient, !isStopped else {
+                throw NSError(domain: "cmux.remote.pty", code: 30, userInfo: [
+                    NSLocalizedDescriptionKey: "remote daemon tunnel is not ready",
+                ])
+            }
+            return try rpcClient.listEndedPTY()
+        }
+    }
+
     /// Resizes a PTY attachment.
     public func resizePTY(sessionID: String, attachmentID: String, attachmentToken: String, cols: Int, rows: Int) throws {
         try queue.sync {

Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/Tunnel/RemotePTYLifecycleRPCClient.swift

@@ -4,7 +4,14 @@ internal import Foundation
 /// Testable PTY-only seam used by the tunnel's lifecycle and bridge operations.
 protocol RemotePTYLifecycleRPCClient: RemotePTYBridgeRPCClient {
     func listPTY() throws -> [[String: Any]]
+    func listEndedPTY() throws -> [[String: Any]]
     func closePTY(sessionID: String, timeout: TimeInterval) throws
     func resizePTY(sessionID: String, attachmentID: String, attachmentToken: String, cols: Int, rows: Int) throws
     func detachPTYChecked(sessionID: String, attachmentID: String, attachmentToken: String) throws
 }
+
+extension RemotePTYLifecycleRPCClient {
+    /// Foreground tombstones are an optional daemon capability; clients that
+    /// predate it (and test doubles) report none.
+    func listEndedPTY() throws -> [[String: Any]] { [] }
+}

Resources/Localizable.xcstrings

@@ -54821,6 +54821,23 @@
         }
       }
     },
+    "cli.sshPtyAttach.remoteSessionLostResume": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "[cmux] resuming the agent that was running in the lost session."
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "[cmux] 失われたセッションで実行されていたエージェントを再開します。"
+          }
+        }
+      }
+    },
     "cli.sshSessionList.remoteStateUnavailable": {
       "extractionState": "manual",
       "localizations": {

Sources/ControlSurfaceResumeTarget.swift

@@ -343,6 +343,11 @@ extension TerminalController {
         guard let binding else { return nil }
         let trimmedKind = binding.kind?.trimmingCharacters(in: .whitespacesAndNewlines)
         let normalizedKind = trimmedKind.flatMap { $0.isEmpty ? nil : $0 } ?? "command"
+        // Remote-synthesized bindings (#7989) intentionally map to `.direct`:
+        // they carry no session checkpoint, so `cmux surface resume show`
+        // presents the stored directory-level continue command verbatim under
+        // the agent kind instead of a typed `cmux restore <kind> <checkpoint>`
+        // selector.
         let mode: AgentRestoreRequestMode = binding.isAgentHookBinding
             ? .resumeAgent
             : .direct

Sources/RemoteAgentContinueSynthesizer.swift

@@ -0,0 +1,87 @@
+import Foundation
+
+/// Synthesizes a hookless, directory-scoped resume binding for a remote agent
+/// (issue #7989, Tier 1).
+///
+/// A remote host without cmux agent hooks never reports a session checkpoint,
+/// so the strongest honest restore signal is "agent `<kind>` was running in
+/// `<directory>`". This synthesizer turns that pair into a conservative
+/// `cd <dir> && <agent> --continue || <agent>` command bound to the panel's
+/// persistent-SSH PTY, mirroring how `TmuxResumeParser` turns a locally
+/// observed tmux client into a `process-detected` binding.
+///
+/// Known limitation (accepted for hookless remotes): a directory-scoped
+/// continue command resumes whatever conversation the agent considers most
+/// recent for that directory. When several sessions of the same agent share
+/// one working directory, the wrong conversation can be continued.
+enum RemoteAgentContinueSynthesizer {
+    /// `SurfaceResumeBindingSnapshot.source` value for synthesized bindings;
+    /// must match `SurfaceResumeBindingSnapshot.isRemoteSynthesized`.
+    static let source = "remote-synthesized"
+
+    /// Builds a directory-scoped continue binding, or nil when the agent kind
+    /// has no trustworthy sessionless continue invocation or the remote
+    /// working directory is unknown.
+    static func binding(
+        kind: RestorableAgentKind,
+        remoteWorkingDirectory: String?,
+        remoteContext: SurfaceResumeRemoteContext,
+        updatedAt: TimeInterval = Date().timeIntervalSince1970
+    ) -> SurfaceResumeBindingSnapshot? {
+        guard let workingDirectory = normalized(remoteWorkingDirectory),
+              let continueCommand = directoryScopedContinueCommand(for: kind) else {
+            return nil
+        }
+        // Same cd guard as every other startup command
+        // (`TerminalStartupWorkingDirectoryPrefix`): tolerate a deleted saved
+        // directory instead of failing before the agent launches. The command
+        // runs on the remote host, so the local claude/codex wrapper-resolver
+        // tokens are deliberately not used here — mirroring
+        // `SurfaceResumeBindingSnapshot.remoteStartupInput()`, which renders
+        // remote commands with `repairPortableAgentExecutable: false`.
+        let command = TerminalStartupWorkingDirectoryPrefix.prefix(
+            continueCommand,
+            workingDirectory: workingDirectory
+        )
+        return SurfaceResumeBindingSnapshot(
+            name: "\(kind.displayName) continue",
+            kind: kind.rawValue,
+            command: command,
+            cwd: workingDirectory,
+            source: source,
+            autoResume: true,
+            launchFlavor: .persistentSSH(remoteContext),
+            updatedAt: updatedAt
+        )
+    }
+
+    /// Sessionless continue templates. Deliberately conservative: only agents
+    /// with a documented directory-level continue invocation are covered; the
+    /// per-session commands in `docs/agent-hooks.md` all need a checkpoint id
+    /// that a hookless remote cannot provide. The `|| <agent>` fallback starts
+    /// a fresh session when the agent has nothing to continue in that
+    /// directory, so restore never dead-ends on a continue error.
+    private static func directoryScopedContinueCommand(
+        for kind: RestorableAgentKind
+    ) -> String? {
+        switch kind {
+        case .claude:
+            // Continues the most recent conversation recorded for the current
+            // working directory (claude's session store is cwd-keyed).
+            return "claude --continue || claude"
+        case .codex:
+            // Resumes the most recently used codex session.
+            return "codex resume --last || codex"
+        default:
+            return nil
+        }
+    }
+
+    private static func normalized(_ value: String?) -> String? {
+        guard let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !trimmed.isEmpty else {
+            return nil
+        }
+        return trimmed
+    }
+}

Sources/SessionPersistence.swift

@@ -363,6 +363,12 @@ struct SurfaceResumeBindingSnapshot: Codable, Equatable, Sendable {
         source == "cli"
     }
 
+    /// A directory-scoped continue binding synthesized by
+    /// `RemoteAgentContinueSynthesizer` for a hookless remote agent (#7989).
+    var isRemoteSynthesized: Bool {
+        source == "remote-synthesized"
+    }
+
     var allowsAutomaticResume: Bool {
         autoResume == true
     }