Resolve terminal relative paths from surface context

Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/PathResolution/String+TerminalPathTokens.swift

@@ -156,6 +156,40 @@ extension String {
         return candidates
     }
 
+    /// Candidate path references derived from a single normalized spelling.
+    ///
+    /// The literal spelling is first so a real file whose name ends in
+    /// `:number` wins. A trailing `:line` or `:line:column` interpretation is
+    /// second and is only observable when its stripped path exists.
+    func terminalPathReferenceCandidates() -> [(path: String, line: Int?, column: Int?)] {
+        var candidates = [(path: self, line: Optional<Int>.none, column: Optional<Int>.none)]
+        let components = split(separator: ":", omittingEmptySubsequences: false)
+        guard components.count >= 2,
+              let trailingNumber = components.last.flatMap({ Int($0) }),
+              trailingNumber > 0 else {
+            return candidates
+        }
+
+        let path: String
+        let line: Int
+        let column: Int?
+        if components.count >= 3,
+           let lineNumber = Int(components[components.count - 2]),
+           lineNumber > 0 {
+            path = components.dropLast(2).joined(separator: ":")
+            line = lineNumber
+            column = trailingNumber
+        } else {
+            path = components.dropLast().joined(separator: ":")
+            line = trailingNumber
+            column = nil
+        }
+
+        guard !path.isEmpty else { return candidates }
+        candidates.append((path: path, line: line, column: column))
+        return candidates
+    }
+
     /// Path-token candidates around a column of a visible terminal line: the
     /// raw whitespace-delimited segment first, then the shell-escape-aware
     /// token.

Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/PathResolution/TerminalCommandClickFallbackPolicy.swift

@@ -0,0 +1,30 @@
+/// Decides whether cmux should run its visible-line command-click fallback.
+///
+/// Ghostty may consume a mouse release without dispatching a usable link, so
+/// snapshot resolution remains a fallback for consumed releases. When the
+/// synchronous open-URL callback already owned the same source reference, the
+/// fallback is suppressed to prevent opening it twice.
+public nonisolated struct TerminalCommandClickFallbackPolicy: Sendable {
+    /// Creates the command-click fallback policy.
+    public init() {}
+
+    /// Returns whether the resolved visible-line reference should be opened.
+    ///
+    /// - Parameters:
+    ///   - ghosttyConsumed: Whether Ghostty consumed the mouse release.
+    ///   - isSnapshotResolution: Whether the fallback is anchored to the clicked
+    ///     visible-line snapshot rather than Ghostty's cached QuickLook target.
+    ///   - resolvedReference: The source reference resolved under the pointer.
+    ///   - handledOpenURLReference: The source reference already handled by the
+    ///     synchronous open-URL callback for this mouse release, if any.
+    /// - Returns: `true` when cmux should open `resolvedReference` as a fallback.
+    public func shouldOpenFallback(
+        ghosttyConsumed: Bool,
+        isSnapshotResolution: Bool,
+        resolvedReference: TerminalPathResolution,
+        handledOpenURLReference: TerminalPathResolution?
+    ) -> Bool {
+        guard handledOpenURLReference != resolvedReference else { return false }
+        return !ghosttyConsumed || isSnapshotResolution
+    }
+}

Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/PathResolution/TerminalPathResolution.swift

@@ -0,0 +1,24 @@
+/// An existing terminal path together with an optional source location.
+public nonisolated struct TerminalPathResolution: Equatable, Sendable {
+    /// The standardized absolute path that passed the existence probe.
+    public let path: String
+
+    /// The one-based line parsed from a `:line` suffix, when present.
+    public let line: Int?
+
+    /// The one-based column parsed from a `:line:column` suffix, when present.
+    public let column: Int?
+
+    /// Creates a resolved path reference.
+    ///
+    /// - Parameters:
+    ///   - path: A standardized absolute path. Resolver-produced values are
+    ///     guaranteed to exist at resolution time.
+    ///   - line: An optional one-based line.
+    ///   - column: An optional one-based column.
+    public init(path: String, line: Int?, column: Int?) {
+        self.path = path
+        self.line = line
+        self.column = column
+    }
+}

Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/PathResolution/TerminalPathResolutionContext.swift

@@ -0,0 +1,21 @@
+/// Ordered directories used to resolve a relative path emitted by a terminal.
+public nonisolated struct TerminalPathResolutionContext: Equatable, Sendable {
+    /// The clicked surface's current working directory.
+    public let workingDirectory: String?
+
+    /// Lower-priority roots, such as the enclosing repository and workspace.
+    public let fallbackDirectories: [String]
+
+    /// Creates a path-resolution context.
+    ///
+    /// - Parameters:
+    ///   - workingDirectory: The clicked surface's current working directory.
+    ///   - fallbackDirectories: Roots to try after the working directory.
+    public init(
+        workingDirectory: String?,
+        fallbackDirectories: [String] = []
+    ) {
+        self.workingDirectory = workingDirectory
+        self.fallbackDirectories = fallbackDirectories
+    }
+}