feat: Worktree project root, terminal filter, installer fixes

Engine now sets PU_PROJECT_ROOT when spawning agents so CLI commands
resolve the correct project root from worktrees. Terminal output filter
strips DEC 2026 sync sequences and clamps cursor-up overshoots to work
around SwiftTerm rendering bugs. CLIInstaller moves plugin registration
off the main thread and adds os.log diagnostics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2witstudios

apps/purepoint-macos/purepoint-macos/Services/CLIInstaller.swift

@@ -1,4 +1,7 @@
 import Foundation
+import os.log
+
+private let logger = Logger(subsystem: "com.purepoint.macos", category: "CLIInstaller")
 
 enum CLIInstaller {
     private static let home = FileManager.default.homeDirectoryForCurrentUser
@@ -16,7 +19,9 @@ enum CLIInstaller {
         installBinary(from: macosDir)
         let pluginUpdated = installPlugin(from: macosDir)
         if pluginUpdated {
-            registerWithClaudeCode()
+            DispatchQueue.global().async {
+                registerWithClaudeCode()
+            }
         }
     }
 
@@ -39,7 +44,6 @@ enum CLIInstaller {
 
     /// Copy bundled plugin into the local marketplace at ~/.pu/marketplace/plugins/pu/
     /// and write the marketplace manifest. Returns true if files were updated.
-    @discardableResult
     private static func installPlugin(from macosDir: URL) -> Bool {
         let bundledPlugin =
             macosDir
@@ -113,14 +117,21 @@ enum CLIInstaller {
 
     /// Register the local marketplace and install the plugin via `claude` CLI.
     private static func registerWithClaudeCode() {
-        guard let claudePath = findClaude() else { return }
+        guard let claudePath = findClaude() else {
+            logger.warning("Claude Code CLI not found — skipping plugin registration")
+            return
+        }
         let mktPath = marketplaceDir.path
 
         // Add marketplace (idempotent — re-adding an existing one is fine)
-        run(claudePath, "plugins", "marketplace", "add", mktPath)
+        if !run(claudePath, "plugins", "marketplace", "add", mktPath) {
+            logger.error("Failed to add marketplace at \(mktPath)")
+        }
 
         // Install the plugin (idempotent — installing an already-installed plugin is fine)
-        run(claudePath, "plugins", "install", "pu@purepoint")
+        if !run(claudePath, "plugins", "install", "pu@purepoint") {
+            logger.error("Failed to install pu@purepoint plugin")
+        }
     }
 
     private static func findClaude() -> String? {

apps/purepoint-macos/purepoint-macos/Services/DaemonAttachSession.swift

@@ -142,10 +142,19 @@ actor DaemonAttachSession {
                     lastFullRefreshAtNanos = now
                 }
                 let bytes = [UInt8](data)
+                let termRows = await MainActor.run { tv?.getTerminal().rows ?? 24 }
+                let filtered = Self.filterTerminalOutput(bytes, maxRows: termRows)
                 await MainActor.run {
-                    tv?.feed(byteArray: ArraySlice(bytes))
-                    if shouldForceFullRefresh {
-                        tv?.getTerminal().updateFullScreen()
+                    tv?.feed(byteArray: ArraySlice(filtered))
+                    // DEBUG: Log terminal buffer state to find desync
+                    if let term = tv?.getTerminal() {
+                        let buf = term.buffer
+                        if buf.y == 0 && buf.yDisp > 0 {
+                            // swiftlint:disable:next line_length
+                            print(
+                                "[TermDBG] CURSOR AT TOP: y=\(buf.y) x=\(buf.x) yDisp=\(buf.yDisp) scrollTop=\(buf.scrollTop) scrollBottom=\(buf.scrollBottom) rows=\(term.rows) cols=\(term.cols)"
+                            )
+                        }
                     }
                     tv?.needsDisplay = true
                 }
@@ -159,6 +168,56 @@ actor DaemonAttachSession {
             }
         }
     }
+
+    // MARK: - Terminal Output Filter
+
+    /// Filter terminal output to work around SwiftTerm rendering issues:
+    /// 1. Strip DEC 2026 synchronized output sequences (SwiftTerm#203 — sync buffer
+    ///    snapshot mistracking causes cursor/scroll desync).
+    /// 2. Clamp CSI n A (cursor-up) sequences so n never exceeds viewport rows.
+    ///    Ink's eraseLines() emits cursor-up counts that can exceed viewport height,
+    ///    causing the cursor to overshoot row 0 and desync the buffer.
+    private static func filterTerminalOutput(_ bytes: [UInt8], maxRows: Int) -> [UInt8] {
+        let syncBegin: [UInt8] = [0x1b, 0x5b, 0x3f, 0x32, 0x30, 0x32, 0x36, 0x68]
+        let syncEnd: [UInt8] = [0x1b, 0x5b, 0x3f, 0x32, 0x30, 0x32, 0x36, 0x6c]
+        let maxUp = max(maxRows - 1, 1)
+
+        var result: [UInt8] = []
+        result.reserveCapacity(bytes.count)
+        var i = 0
+        while i < bytes.count {
+            // Strip DEC 2026 begin/end (8 bytes each)
+            if i + 8 <= bytes.count {
+                let slice = Array(bytes[i..<i + 8])
+                if slice == syncBegin || slice == syncEnd {
+                    i += 8
+                    continue
+                }
+            }
+            // Clamp CSI n A (cursor up): \x1b [ <digits> A
+            if bytes[i] == 0x1b, i + 2 < bytes.count, bytes[i + 1] == 0x5b {
+                var j = i + 2
+                var digits = 0
+                var hasDigits = false
+                while j < bytes.count, bytes[j] >= 0x30, bytes[j] <= 0x39 {
+                    digits = digits * 10 + Int(bytes[j] - 0x30)
+                    hasDigits = true
+                    j += 1
+                }
+                if j < bytes.count, bytes[j] == 0x41, hasDigits {
+                    // It's CSI <n> A — clamp n
+                    let clamped = min(digits, maxUp)
+                    let replacement = Array("\u{1b}[\(clamped)A".utf8)
+                    result.append(contentsOf: replacement)
+                    i = j + 1
+                    continue
+                }
+            }
+            result.append(bytes[i])
+            i += 1
+        }
+        return result
+    }
 }
 
 enum DaemonAttachError: Error, LocalizedError {

crates/pu-cli/src/commands/agent_def.rs

@@ -21,7 +21,7 @@ fn parse_tags(tags: &str) -> Vec<String> {
 
 pub async fn run_list(socket: &Path, json: bool) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
-    let project_root = commands::cwd_string()?;
+    let project_root = commands::project_root_string()?;
     let resp = client::send_request(socket, &Request::ListAgentDefs { project_root }).await?;
     let resp = output::check_response(resp, json)?;
     output::print_response(&resp, json)?;
@@ -41,7 +41,7 @@ pub async fn run_create(
     json: bool,
 ) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
-    let project_root = commands::cwd_string()?;
+    let project_root = commands::project_root_string()?;
     let tags_vec = parse_tags(tags);
     let resp = client::send_request(
         socket,
@@ -66,7 +66,7 @@ pub async fn run_create(
 
 pub async fn run_show(socket: &Path, name: &str, json: bool) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
-    let project_root = commands::cwd_string()?;
+    let project_root = commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::GetAgentDef {
@@ -87,7 +87,7 @@ pub async fn run_delete(
     json: bool,
 ) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
-    let project_root = commands::cwd_string()?;
+    let project_root = commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::DeleteAgentDef {

crates/pu-cli/src/commands/bench.rs

@@ -35,7 +35,7 @@ pub async fn run_bench(
 
     daemon_ctrl::ensure_daemon(socket).await?;
 
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::Suspend {
@@ -65,7 +65,7 @@ pub async fn run_bench(
 pub async fn run_play(socket: &Path, agent_id: &str, json: bool) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
 
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::Resume {

crates/pu-cli/src/commands/clean.rs

@@ -18,7 +18,7 @@ pub async fn run(
     }
 
     daemon_ctrl::ensure_daemon(socket).await?;
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
 
     if all {
         // Get status to find all worktree IDs

crates/pu-cli/src/commands/diff.rs

@@ -13,7 +13,7 @@ pub async fn run(
 ) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
 
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::Diff {

crates/pu-cli/src/commands/gate.rs

@@ -10,7 +10,7 @@ pub async fn run(socket: &Path, event: &str, project_root: Option<String>) -> Re
     daemon_ctrl::ensure_daemon(socket).await?;
     let project_root = match project_root {
         Some(pr) => pr,
-        None => commands::cwd_string()?,
+        None => commands::project_root_string()?,
     };
 
     // Git hooks run inside the worktree directory (cwd), while project_root points to

crates/pu-cli/src/commands/grid.rs

@@ -11,7 +11,7 @@ use crate::output;
 pub async fn run(socket: &Path, action: GridAction) -> Result<(), CliError> {
     daemon_ctrl::ensure_daemon(socket).await?;
 
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
 
     match action {
         GridAction::Show { json } => {

crates/pu-cli/src/commands/kill.rs

@@ -45,7 +45,7 @@ pub async fn run(
 
     daemon_ctrl::ensure_daemon(socket).await?;
 
-    let project_root = crate::commands::cwd_string()?;
+    let project_root = crate::commands::project_root_string()?;
     let resp = client::send_request(
         socket,
         &Request::Kill {

crates/pu-cli/src/commands/mod.rs

@@ -27,6 +27,18 @@ pub fn cwd_string() -> Result<String, CliError> {
     Ok(std::env::current_dir()?.to_string_lossy().to_string())
 }
 
+/// Resolve the project root directory.
+/// Checks `PU_PROJECT_ROOT` env var first (set by the engine for worktree agents),
+/// falls back to the current working directory.
+pub fn project_root_string() -> Result<String, CliError> {
+    if let Ok(root) = std::env::var("PU_PROJECT_ROOT") {
+        if !root.is_empty() {
+            return Ok(root);
+        }
+    }
+    cwd_string()
+}
+
 /// Parse --var KEY=VALUE pairs into a HashMap.
 pub fn parse_vars(vars: &[String]) -> Result<HashMap<String, String>, CliError> {
     let mut map = HashMap::new();