@holon-run/agentinbox 0.5.0 → 0.7.0

package/dist/src/runtime_gate.js

@@ -10,9 +10,11 @@ const node_util_1 = require("node:util");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+const logging_1 = require("./logging");
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
-const DEFAULT_ITERM2_SAMPLE_DELAY_MS = 250;
-const DEFAULT_TMUX_SAMPLE_DELAY_MS = 250;
+const DEFAULT_ITERM2_SAMPLE_DELAY_MS = 900;
+const DEFAULT_TMUX_SAMPLE_DELAY_MS = 900;
+const NORMALIZED_BUFFER_TAIL_LINES = 20;
 const ACTIVE_BUFFER_MARKERS = [
     "esc to interrupt",
     "Working (",
@@ -25,22 +27,36 @@ const TYPING_PROMPT_PREFIXES = [
 class DefaultActivationGate {
     runtimeProbes;
     terminalProbes;
-    constructor(runtimeProbes = [
-        new CodexRuntimePresenceProbe(),
-        new ClaudeCodeRuntimePresenceProbe(),
-    ], terminalProbes = [
-        new CodexTerminalStateProbe(),
-        new Iterm2TerminalStateProbe(),
-        new ClaudeCodeTerminalStateProbe(),
-        new TmuxTerminalStateProbe(),
-    ]) {
-        this.runtimeProbes = runtimeProbes;
-        this.terminalProbes = terminalProbes;
+    logger;
+    constructor(runtimeProbes, terminalProbes, logger = new logging_1.NoopLogger()) {
+        this.logger = logger.child("activation_gate");
+        this.runtimeProbes = runtimeProbes ?? [
+            new CodexRuntimePresenceProbe(undefined, undefined, this.logger.child("codex_runtime")),
+            new ClaudeCodeRuntimePresenceProbe(undefined, undefined, this.logger.child("claude_runtime")),
+        ];
+        this.terminalProbes = terminalProbes ?? [
+            new CodexTerminalStateProbe(undefined, undefined, undefined, undefined, undefined, this.logger.child("codex_terminal")),
+            new Iterm2TerminalStateProbe(undefined, {}, this.logger.child("iterm2_terminal")),
+            new ClaudeCodeTerminalStateProbe(undefined, undefined, undefined, this.logger.child("claude_terminal")),
+            new TmuxTerminalStateProbe(undefined, {}, this.logger.child("tmux_terminal")),
+        ];
     }
     async evaluate(target) {
         const runtimeProbe = this.runtimeProbes.find((probe) => probe.supports(target));
         const runtimePresence = runtimeProbe ? await runtimeProbe.check(target) : "unknown";
         if (runtimePresence === "gone") {
+            this.logger.debug("gate_decision", {
+                targetId: target.targetId,
+                runtimeKind: target.runtimeKind,
+                backend: target.backend,
+                runtimeProbe: runtimeProbe?.constructor?.name ?? null,
+                runtimePresence,
+                terminalProbe: null,
+                terminalPresence: null,
+                terminalBusy: null,
+                outcome: "offline",
+                reason: "runtime_gone",
+            });
             return { outcome: "offline", reason: "runtime_gone" };
         }
         const terminalProbe = this.terminalProbes.find((probe) => probe.supports(target));
@@ -48,14 +64,62 @@ class DefaultActivationGate {
             ? await terminalProbe.check(target)
             : { presence: "unknown", busy: "unknown" };
         if (terminalState.presence === "gone") {
+            this.logger.debug("gate_decision", {
+                targetId: target.targetId,
+                runtimeKind: target.runtimeKind,
+                backend: target.backend,
+                runtimeProbe: runtimeProbe?.constructor?.name ?? null,
+                runtimePresence,
+                terminalProbe: terminalProbe?.constructor?.name ?? null,
+                terminalPresence: terminalState.presence,
+                terminalBusy: terminalState.busy,
+                outcome: "offline",
+                reason: "terminal_gone",
+            });
             return { outcome: "offline", reason: "terminal_gone" };
         }
         if (terminalState.busy === "busy") {
+            this.logger.debug("gate_decision", {
+                targetId: target.targetId,
+                runtimeKind: target.runtimeKind,
+                backend: target.backend,
+                runtimeProbe: runtimeProbe?.constructor?.name ?? null,
+                runtimePresence,
+                terminalProbe: terminalProbe?.constructor?.name ?? null,
+                terminalPresence: terminalState.presence,
+                terminalBusy: terminalState.busy,
+                outcome: "defer",
+                reason: "terminal_busy",
+            });
             return { outcome: "defer", reason: "terminal_busy" };
         }
         if (target.runtimeKind === "codex" && terminalState.busy === "idle") {
+            this.logger.debug("gate_decision", {
+                targetId: target.targetId,
+                runtimeKind: target.runtimeKind,
+                backend: target.backend,
+                runtimeProbe: runtimeProbe?.constructor?.name ?? null,
+                runtimePresence,
+                terminalProbe: terminalProbe?.constructor?.name ?? null,
+                terminalPresence: terminalState.presence,
+                terminalBusy: terminalState.busy,
+                outcome: "defer",
+                reason: "terminal_recently_active",
+            });
             return { outcome: "defer", reason: "terminal_recently_active" };
         }
+        this.logger.debug("gate_decision", {
+            targetId: target.targetId,
+            runtimeKind: target.runtimeKind,
+            backend: target.backend,
+            runtimeProbe: runtimeProbe?.constructor?.name ?? null,
+            runtimePresence,
+            terminalProbe: terminalProbe?.constructor?.name ?? null,
+            terminalPresence: terminalState.presence,
+            terminalBusy: terminalState.busy,
+            outcome: "inject",
+            reason: "gate_unknown_or_idle",
+        });
         return { outcome: "inject", reason: "gate_unknown_or_idle" };
     }
 }
@@ -63,36 +127,45 @@ exports.DefaultActivationGate = DefaultActivationGate;
 class CodexRuntimePresenceProbe {
     killFn;
     sessionFileReader;
-    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader) {
+    logger;
+    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader, logger = new logging_1.NoopLogger()) {
         this.killFn = killFn;
         this.sessionFileReader = sessionFileReader;
+        this.logger = logger;
     }
     supports(target) {
         return target.runtimeKind === "codex" && Number.isInteger(target.runtimePid);
     }
     async check(target) {
         if (!Number.isInteger(target.runtimePid)) {
+            this.logger.trace("probe_result", { targetId: target.targetId, result: "unknown", reason: "missing_runtime_pid" });
             return "unknown";
         }
         try {
             this.killFn(target.runtimePid, 0);
             if (!target.runtimeSessionId) {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "unknown", reason: "missing_runtime_session_id" });
                 return "unknown";
             }
             const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
             if (sessionInfo === "unknown") {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "unknown", reason: "session_file_unknown" });
                 return "unknown";
             }
             if (!sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "gone", reason: "session_file_mismatch" });
                 return "gone";
             }
+            this.logger.trace("probe_result", { targetId: target.targetId, result: "alive" });
             return "alive";
         }
         catch (error) {
             const code = error instanceof Error && "code" in error ? String(error.code ?? "") : "";
             if (code === "ESRCH") {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "gone", reason: "process_missing" });
                 return "gone";
             }
+            this.logger.debug("probe_error", { targetId: target.targetId, error, result: "unknown" });
             return "unknown";
         }
     }
@@ -104,12 +177,14 @@ class CodexTerminalStateProbe {
     sessionFileReader;
     statReader;
     nowFn;
-    constructor(iTermProbe = new Iterm2TerminalStateProbe(), tmuxProbe = new TmuxTerminalStateProbe(), sessionFileReader, statReader, nowFn = () => Date.now()) {
+    logger;
+    constructor(iTermProbe = new Iterm2TerminalStateProbe(), tmuxProbe = new TmuxTerminalStateProbe(), sessionFileReader, statReader, nowFn = () => Date.now(), logger = new logging_1.NoopLogger()) {
         this.iTermProbe = iTermProbe;
         this.tmuxProbe = tmuxProbe;
         this.sessionFileReader = sessionFileReader;
         this.statReader = statReader;
         this.nowFn = nowFn;
+        this.logger = logger;
     }
     supports(target) {
         return target.runtimeKind === "codex";
@@ -117,26 +192,66 @@ class CodexTerminalStateProbe {
     async check(target) {
         const terminalState = await this.readTerminalState(target);
         if (!target.runtimeSessionId) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: terminalState,
+                reason: "missing_runtime_session_id",
+            });
             return terminalState;
         }
         const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
         if (sessionInfo === "unknown" || !sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: terminalState,
+                reason: "session_file_unavailable",
+            });
             return terminalState;
         }
         const stat = await (this.statReader ?? defaultFileStatReader)(sessionInfo.filePath);
         if (!stat) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: terminalState,
+                reason: "session_file_stat_missing",
+            });
             return terminalState;
         }
         if (terminalState.busy === "busy" || terminalState.presence === "gone") {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: terminalState,
+                reason: "terminal_probe_decisive",
+            });
             return terminalState;
         }
         const ageMs = this.nowFn() - stat.mtimeMs;
         if (ageMs < 5000) {
-            return { presence: terminalState.presence, busy: "busy" };
+            const result = { presence: terminalState.presence, busy: "busy" };
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result,
+                reason: "session_file_recent_activity",
+                ageMs,
+            });
+            return result;
         }
         if (ageMs < 30000) {
-            return { presence: terminalState.presence, busy: "idle" };
-        }
+            const result = { presence: terminalState.presence, busy: "idle" };
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result,
+                reason: "session_file_recently_active",
+                ageMs,
+            });
+            return result;
+        }
+        this.logger.trace("probe_result", {
+            targetId: target.targetId,
+            result: terminalState,
+            reason: "session_file_stale",
+            ageMs,
+        });
         return terminalState;
     }
     async readTerminalState(target) {
@@ -153,9 +268,11 @@ exports.CodexTerminalStateProbe = CodexTerminalStateProbe;
 class Iterm2TerminalStateProbe {
     execAsync;
     options;
-    constructor(execAsync = execFileAsync, options = {}) {
+    logger;
+    constructor(execAsync = execFileAsync, options = {}, logger = new logging_1.NoopLogger()) {
         this.execAsync = execAsync;
         this.options = options;
+        this.logger = logger;
     }
     supports(target) {
         // Only support iTerm2 targets that are NOT Claude Code
@@ -168,13 +285,203 @@ class Iterm2TerminalStateProbe {
     async check(target) {
         const sessionId = target.itermSessionId?.trim();
         if (!sessionId) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: { presence: "unknown", busy: "unknown" },
+                reason: "missing_iterm_session_id",
+            });
             return { presence: "unknown", busy: "unknown" };
         }
+        // Try Python API probe first (if enabled)
+        if (this.options.enablePythonProbe !== false) {
+            const pythonResult = await this.tryPythonApiProbe(sessionId, target.runtimeKind);
+            if (pythonResult && pythonResult.presence !== "unknown") {
+                this.logger.debug("probe_result", {
+                    targetId: target.targetId,
+                    path: "python",
+                    result: pythonResult,
+                });
+                return pythonResult;
+            }
+            this.logger.trace("probe_fallback", {
+                targetId: target.targetId,
+                from: "python",
+                to: "cli",
+                reason: pythonResult ? "python_presence_unknown" : "python_probe_unavailable",
+            });
+        }
+        // Fallback to command-line tools
+        const result = await this.checkWithCommandLineTools(sessionId, target.targetId);
+        this.logger.debug("probe_result", {
+            targetId: target.targetId,
+            path: "cli",
+            result,
+        });
+        return result;
+    }
+    async tryPythonApiProbe(sessionId, runtimeKind) {
+        try {
+            const scriptPath = this.options.pythonScriptPath ?? resolvePythonProbeScript();
+            const result = await this.execAsync("python3", [scriptPath, sessionId], {
+                env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+            });
+            const data = JSON.parse(result.stdout);
+            if (data.status === "gone") {
+                this.logger.trace("probe_python_result", {
+                    sessionId,
+                    result: { presence: "gone", busy: "unknown" },
+                    reason: "session_gone",
+                });
+                return { presence: "gone", busy: "unknown" };
+            }
+            if (data.status === "available") {
+                // If we have cursor and lines data, use cursor-aware detection
+                if (data.cursor && Array.isArray(data.lines)) {
+                    const bufferTail = normalizeProbeTailFromLines(data.lines);
+                    if (!bufferTail) {
+                        this.logger.trace("probe_python_result", {
+                            sessionId,
+                            result: { presence: "available", busy: "unknown" },
+                            reason: "empty_normalized_buffer",
+                        });
+                        return { presence: "available", busy: "unknown" };
+                    }
+                    const cursorPosition = { x: data.cursor.x, y: data.cursor.y };
+                    const screenHeight = data.screen_height;
+                    const startLine = data.start_line ?? 0;
+                    // Perform cursor-aware typing detection
+                    const busyStatus = evaluatePythonCursorAwareTypingPrompt(bufferTail, cursorPosition, screenHeight, startLine, runtimeKind);
+                    // If cursor-aware detection indicates busy, return immediately
+                    if (busyStatus === "busy") {
+                        this.logger.trace("probe_python_result", {
+                            sessionId,
+                            result: { presence: "available", busy: "busy" },
+                            reason: "cursor_aware_busy",
+                        });
+                        return { presence: "available", busy: "busy" };
+                    }
+                    // If cursor-aware detection is certain it's not busy, don't apply prompt heuristics
+                    if (busyStatus === "not_busy") {
+                        // Still check for buffer changes and active markers
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_ITERM2_SAMPLE_DELAY_MS);
+                        const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
+                            env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+                        });
+                        const secondData = JSON.parse(secondResult.stdout);
+                        if (secondData.status === "available" && Array.isArray(secondData.lines)) {
+                            const secondBufferTail = normalizeProbeTailFromLines(secondData.lines);
+                            if (secondBufferTail && bufferTail !== secondBufferTail) {
+                                this.logger.trace("probe_python_result", {
+                                    sessionId,
+                                    result: { presence: "available", busy: "busy" },
+                                    reason: "buffer_changed",
+                                });
+                                return { presence: "available", busy: "busy" };
+                            }
+                        }
+                        // Check for active buffer markers
+                        if (containsActiveBufferMarker(bufferTail)) {
+                            this.logger.trace("probe_python_result", {
+                                sessionId,
+                                result: { presence: "available", busy: "busy" },
+                                reason: "active_buffer_marker",
+                            });
+                            return { presence: "available", busy: "busy" };
+                        }
+                        this.logger.trace("probe_python_result", {
+                            sessionId,
+                            result: { presence: "available", busy: "unknown" },
+                            reason: "cursor_aware_not_busy",
+                        });
+                        return { presence: "available", busy: "unknown" };
+                    }
+                    // If cursor-aware detection is uncertain, fall back to buffer change detection only
+                    // Do NOT use generic typing prompts to avoid false positives (see #116)
+                    if (busyStatus === "unknown") {
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_ITERM2_SAMPLE_DELAY_MS);
+                        const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
+                            env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+                        });
+                        const secondData = JSON.parse(secondResult.stdout);
+                        if (secondData.status === "available" && Array.isArray(secondData.lines)) {
+                            const secondBufferTail = normalizeProbeTailFromLines(secondData.lines);
+                            if (secondBufferTail && bufferTail !== secondBufferTail) {
+                                this.logger.trace("probe_python_result", {
+                                    sessionId,
+                                    result: { presence: "available", busy: "busy" },
+                                    reason: "buffer_changed_after_unknown_cursor_state",
+                                });
+                                return { presence: "available", busy: "busy" };
+                            }
+                        }
+                        // Check for active buffer markers
+                        if (containsActiveBufferMarker(bufferTail)) {
+                            this.logger.trace("probe_python_result", {
+                                sessionId,
+                                result: { presence: "available", busy: "busy" },
+                                reason: "active_buffer_marker_after_unknown_cursor_state",
+                            });
+                            return { presence: "available", busy: "busy" };
+                        }
+                        // Return unknown when cursor-aware detection is uncertain
+                        // Do NOT fall back to generic typing prompts to avoid false positives
+                        this.logger.trace("probe_python_result", {
+                            sessionId,
+                            result: { presence: "available", busy: "unknown" },
+                            reason: "cursor_aware_unknown",
+                        });
+                        return { presence: "available", busy: "unknown" };
+                    }
+                    // This should never be reached as all cases are handled above
+                    this.logger.trace("probe_python_result", {
+                        sessionId,
+                        result: { presence: "available", busy: "unknown" },
+                        reason: "cursor_probe_fell_through",
+                    });
+                    return { presence: "available", busy: "unknown" };
+                }
+                // If we don't have cursor data, return unknown to trigger fallback
+                this.logger.trace("probe_python_result", {
+                    sessionId,
+                    result: null,
+                    reason: "missing_cursor_data",
+                });
+                return null;
+            }
+            // Any other status means we should fall back
+            this.logger.trace("probe_python_result", {
+                sessionId,
+                result: null,
+                reason: "unexpected_python_status",
+                status: data.status,
+            });
+            return null;
+        }
+        catch (error) {
+            // Python API probe failed, fall back to command-line tools
+            this.logger.trace("probe_fallback", {
+                sessionId,
+                from: "python",
+                to: "cli",
+                reason: "python_probe_error",
+                error,
+            });
+            return null;
+        }
+    }
+    async checkWithCommandLineTools(sessionId, targetId) {
         let it2api;
         try {
             it2api = resolveIterm2ApiPath(this.options.iterm2ApiPath);
         }
-        catch {
+        catch (error) {
+            this.logger.trace("probe_fallback", {
+                targetId,
+                from: "cli",
+                to: null,
+                reason: "it2api_unavailable",
+                error,
+            });
             return { presence: "unknown", busy: "unknown" };
         }
         const presence = await this.checkSessionPresence(it2api, sessionId);
@@ -192,14 +499,27 @@ class Iterm2TerminalStateProbe {
             return { presence: "available", busy: "unknown" };
         }
         if (first !== second) {
+            this.logger.trace("probe_cli_result", {
+                sessionId,
+                result: { presence: "available", busy: "busy" },
+                reason: "buffer_changed",
+            });
             return { presence: "available", busy: "busy" };
         }
         if (containsActiveBufferMarker(second)) {
+            this.logger.trace("probe_cli_result", {
+                sessionId,
+                result: { presence: "available", busy: "busy" },
+                reason: "active_buffer_marker",
+            });
             return { presence: "available", busy: "busy" };
         }
-        if (hasVisibleTypingPrompt(second)) {
-            return { presence: "available", busy: "busy" };
-        }
+        // Do NOT use generic typing prompts to avoid false positives (see #116)
+        this.logger.trace("probe_cli_result", {
+            sessionId,
+            result: { presence: "available", busy: "unknown" },
+            reason: "stable_quiet_buffer",
+        });
         return { presence: "available", busy: "unknown" };
     }
     async checkSessionPresence(it2api, sessionId) {
@@ -208,7 +528,13 @@ class Iterm2TerminalStateProbe {
             const sessionIds = parseIterm2SessionIds(result.stdout);
             return sessionIds.includes(sessionId) ? "available" : "gone";
         }
-        catch {
+        catch (error) {
+            this.logger.trace("probe_error", {
+                sessionId,
+                step: "list_sessions",
+                error,
+                result: "unknown",
+            });
             return "unknown";
         }
     }
@@ -234,9 +560,11 @@ exports.Iterm2TerminalStateProbe = Iterm2TerminalStateProbe;
 class TmuxTerminalStateProbe {
     execAsync;
     options;
-    constructor(execAsync = execFileAsync, options = {}) {
+    logger;
+    constructor(execAsync = execFileAsync, options = {}, logger = new logging_1.NoopLogger()) {
         this.execAsync = execAsync;
         this.options = options;
+        this.logger = logger;
     }
     supports(target) {
         return target.backend === "tmux" && typeof target.tmuxPaneId === "string" && target.tmuxPaneId.trim().length > 0;
@@ -244,16 +572,39 @@ class TmuxTerminalStateProbe {
     async check(target) {
         const paneId = target.tmuxPaneId?.trim();
         if (!paneId) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: { presence: "unknown", busy: "unknown" },
+                reason: "missing_tmux_pane_id",
+            });
             return { presence: "unknown", busy: "unknown" };
         }
         const paneState = await this.readPaneState(paneId);
         if (paneState === "missing") {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "gone", busy: "unknown" },
+                reason: "pane_missing",
+            });
             return { presence: "gone", busy: "unknown" };
         }
         if (paneState === "unknown") {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "unknown", busy: "unknown" },
+                reason: "pane_state_unknown",
+            });
             return { presence: "unknown", busy: "unknown" };
         }
         if (paneState.dead) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "gone", busy: "unknown" },
+                reason: "pane_dead",
+            });
             return { presence: "gone", busy: "unknown" };
         }
         const first = await this.readBufferTail(paneId);
@@ -266,26 +617,62 @@ class TmuxTerminalStateProbe {
             return { presence: "available", busy: "unknown" };
         }
         if (first !== second) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "available", busy: "busy" },
+                reason: "buffer_changed",
+            });
             return { presence: "available", busy: "busy" };
         }
         if (containsActiveBufferMarker(second)) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "available", busy: "busy" },
+                reason: "active_buffer_marker",
+            });
             return { presence: "available", busy: "busy" };
         }
-        if (paneState.active && hasVisibleTypingPrompt(second)) {
+        // Use cursor-aware detection when available
+        const cursorHint = evaluateCursorAwareTypingPrompt(target, paneState, second);
+        if (cursorHint === "busy") {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "available", busy: "busy" },
+                reason: "cursor_aware_busy",
+            });
             return { presence: "available", busy: "busy" };
         }
+        // Do NOT fall back to generic typing prompts when cursorHint is unknown to avoid false positives (see #116)
+        this.logger.trace("probe_result", {
+            targetId: target.targetId,
+            paneId,
+            result: { presence: "available", busy: "unknown" },
+            reason: cursorHint === "not_busy" ? "cursor_aware_not_busy" : "cursor_aware_unknown",
+        });
         return { presence: "available", busy: "unknown" };
     }
     async readPaneState(paneId) {
         try {
-            const result = await this.execAsync("tmux", ["display-message", "-p", "-t", paneId, "#{pane_active} #{pane_dead}"]);
-            const [active, dead] = result.stdout.trim().split(/\s+/, 2);
+            const result = await this.execAsync("tmux", [
+                "display-message",
+                "-p",
+                "-t",
+                paneId,
+                "#{pane_active} #{pane_dead} #{cursor_x} #{cursor_y} #{pane_height}",
+            ]);
+            const [active, dead, cursorX, cursorY, height] = result.stdout.trim().split(/\s+/, 5);
             if (!active || !dead) {
                 return "unknown";
             }
             return {
                 active: active === "1",
                 dead: dead === "1",
+                cursorX: parseOptionalInt(cursorX),
+                cursorY: parseOptionalInt(cursorY),
+                height: parseOptionalInt(height),
             };
         }
         catch (error) {
@@ -297,7 +684,7 @@ class TmuxTerminalStateProbe {
     }
     async readBufferTail(paneId) {
         try {
-            const result = await this.execAsync("tmux", ["capture-pane", "-p", "-t", paneId, "-S", "-20"]);
+            const result = await this.execAsync("tmux", ["capture-pane", "-p", "-t", paneId, "-S", `-${NORMALIZED_BUFFER_TAIL_LINES}`]);
             return normalizeBufferTail(result.stdout);
         }
         catch {
@@ -309,7 +696,7 @@ exports.TmuxTerminalStateProbe = TmuxTerminalStateProbe;
 function containsActiveBufferMarker(bufferTail) {
     return ACTIVE_BUFFER_MARKERS.some((marker) => bufferTail.includes(marker));
 }
-function hasVisibleTypingPrompt(bufferTail) {
+function hasVisibleTypingPrompt(bufferTail, prefixes = TYPING_PROMPT_PREFIXES) {
     const lines = bufferTail
         .split("\n")
         .map((line) => line.trimEnd())
@@ -318,23 +705,77 @@ function hasVisibleTypingPrompt(bufferTail) {
     if (!lastLine) {
         return false;
     }
-    for (const prefix of TYPING_PROMPT_PREFIXES) {
+    for (const prefix of prefixes) {
         if (lastLine.startsWith(prefix) && lastLine.slice(prefix.length).trim().length > 0) {
             return true;
         }
     }
     return false;
 }
+function evaluateCursorAwareTypingPrompt(target, paneState, bufferTail) {
+    const prefix = runtimeTypingPromptPrefix(target.runtimeKind);
+    if (!prefix) {
+        return "unknown";
+    }
+    if (paneState.cursorX == null || paneState.cursorY == null || paneState.height == null) {
+        return "unknown";
+    }
+    const lines = bufferTail
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.trimEnd());
+    if (lines.length === 0) {
+        return "unknown";
+    }
+    const captureStartRow = Math.max(0, paneState.height - lines.length);
+    const lineIndex = paneState.cursorY - captureStartRow;
+    if (lineIndex < 0 || lineIndex >= lines.length) {
+        return "unknown";
+    }
+    const line = lines[lineIndex] ?? "";
+    if (!line.startsWith(prefix)) {
+        return "not_busy";
+    }
+    return paneState.cursorX > prefix.length ? "busy" : "not_busy";
+}
+function runtimeTypingPromptPrefix(runtimeKind) {
+    if (runtimeKind === "codex") {
+        return "› ";
+    }
+    if (runtimeKind === "claude_code") {
+        return "❯ ";
+    }
+    return null;
+}
+function typingPromptPrefixesForRuntime(runtimeKind) {
+    if (runtimeKind === "codex") {
+        return ["› "];
+    }
+    if (runtimeKind === "claude_code") {
+        return ["❯ ", "› "];
+    }
+    return TYPING_PROMPT_PREFIXES;
+}
+function parseOptionalInt(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
 function normalizeBufferTail(buffer) {
     const normalized = buffer
         .replace(/\r/g, "")
         .split("\n")
         .map((line) => line.trimEnd())
-        .slice(-20)
+        .slice(-NORMALIZED_BUFFER_TAIL_LINES)
         .join("\n")
         .trim();
     return normalized.length > 0 ? normalized : null;
 }
+function normalizeProbeTailFromLines(lines) {
+    return normalizeBufferTail(lines.join("\n"));
+}
 function resolveIterm2ApiPath(override) {
     if (override) {
         return override;
@@ -471,15 +912,18 @@ function isTmuxMissingPaneError(error) {
 class ClaudeCodeRuntimePresenceProbe {
     killFn;
     sessionFileReader;
-    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader) {
+    logger;
+    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader, logger = new logging_1.NoopLogger()) {
         this.killFn = killFn;
         this.sessionFileReader = sessionFileReader;
+        this.logger = logger;
     }
     supports(target) {
         return target.runtimeKind === "claude_code" && Number.isInteger(target.runtimePid);
     }
     async check(target) {
         if (!Number.isInteger(target.runtimePid)) {
+            this.logger.trace("probe_result", { targetId: target.targetId, result: "unknown", reason: "missing_runtime_pid" });
             return "unknown";
         }
         try {
@@ -488,19 +932,24 @@ class ClaudeCodeRuntimePresenceProbe {
             // 2. Verify session file exists and is valid
             const sessionInfo = await (this.sessionFileReader ?? this.defaultSessionFileReader)(target.runtimePid);
             if (!sessionInfo) {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "gone", reason: "session_file_missing" });
                 return "gone"; // Process exists but session file is invalid/missing
             }
             // 3. Verify session ID matches (prevent PID reuse)
             if (target.runtimeSessionId && sessionInfo.sessionId !== target.runtimeSessionId) {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "gone", reason: "session_id_mismatch" });
                 return "gone";
             }
+            this.logger.trace("probe_result", { targetId: target.targetId, result: "alive" });
             return "alive";
         }
         catch (error) {
             const code = error instanceof Error && "code" in error ? String(error.code ?? "") : "";
             if (code === "ESRCH") {
+                this.logger.trace("probe_result", { targetId: target.targetId, result: "gone", reason: "process_missing" });
                 return "gone"; // Process doesn't exist
             }
+            this.logger.debug("probe_error", { targetId: target.targetId, error, result: "unknown" });
             return "unknown";
         }
     }
@@ -527,26 +976,43 @@ class ClaudeCodeTerminalStateProbe {
     sessionFileReader;
     logFileStatReader;
     sleepFn;
-    constructor(sessionFileReader, logFileStatReader, sleepFn = sleep) {
+    logger;
+    constructor(sessionFileReader, logFileStatReader, sleepFn = sleep, logger = new logging_1.NoopLogger()) {
         this.sessionFileReader = sessionFileReader;
         this.logFileStatReader = logFileStatReader;
         this.sleepFn = sleepFn;
+        this.logger = logger;
     }
     supports(target) {
         return target.runtimeKind === "claude_code";
     }
     async check(target) {
         if (!target.runtimePid || !target.runtimeSessionId) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: { presence: "unknown", busy: "unknown" },
+                reason: "missing_runtime_identity",
+            });
             return { presence: "unknown", busy: "unknown" };
         }
         try {
             // 1. Read session file to get cwd
             const sessionData = await (this.sessionFileReader ?? this.defaultSessionFileReader)(target.runtimePid);
             if (!sessionData) {
+                this.logger.trace("probe_result", {
+                    targetId: target.targetId,
+                    result: { presence: "gone", busy: "unknown" },
+                    reason: "session_file_missing",
+                });
                 return { presence: "gone", busy: "unknown" };
             }
             // 2. Verify session ID matches
             if (sessionData.sessionId !== target.runtimeSessionId) {
+                this.logger.trace("probe_result", {
+                    targetId: target.targetId,
+                    result: { presence: "gone", busy: "unknown" },
+                    reason: "session_id_mismatch",
+                });
                 return { presence: "gone", busy: "unknown" };
             }
             // 3. Construct log file path using Claude Code's encoding rules
@@ -558,10 +1024,18 @@ class ClaudeCodeTerminalStateProbe {
             const presence = target.backend === "iterm2" && target.itermSessionId
                 ? await this.checkIterm2Presence(target.itermSessionId)
                 : "available";
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                result: { presence, busy },
+            });
             return { presence, busy };
         }
         catch (error) {
-            console.warn('Claude Code state check failed:', error);
+            this.logger.debug("probe_error", {
+                targetId: target.targetId,
+                error,
+                result: { presence: "unknown", busy: "unknown" },
+            });
             return { presence: "unknown", busy: "unknown" };
         }
     }
@@ -643,3 +1117,79 @@ function parseIterm2SessionIds(stdout) {
     })
         .filter((id) => id !== null);
 }
+function resolvePythonProbeScript(override) {
+    if (override) {
+        return override;
+    }
+    const scriptRelativePath = node_path_1.default.join("scripts", "iterm2_cursor_probe.py");
+    const seen = new Set();
+    const candidates = [];
+    const addCandidate = (candidate) => {
+        const normalized = node_path_1.default.normalize(candidate);
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            candidates.push(normalized);
+        }
+    };
+    // Search upward from the current module's directory
+    let currentDir = __dirname;
+    for (let i = 0; i < 5; i++) { // Limit upward search depth
+        addCandidate(node_path_1.default.join(currentDir, scriptRelativePath));
+        addCandidate(node_path_1.default.join(currentDir, "dist", scriptRelativePath));
+        addCandidate(node_path_1.default.join(currentDir, "dist", "src", scriptRelativePath));
+        const parentDir = node_path_1.default.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    // Check process working directory and its dist paths
+    addCandidate(node_path_1.default.join(process.cwd(), scriptRelativePath));
+    addCandidate(node_path_1.default.join(process.cwd(), "dist", scriptRelativePath));
+    addCandidate(node_path_1.default.join(process.cwd(), "dist", "src", scriptRelativePath));
+    // Check all candidates
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`Unable to locate iterm2_cursor_probe.py. Checked: ${candidates.join(", ")}. ` +
+        "Ensure scripts/iterm2_cursor_probe.py is shipped with the package or copied into dist/ during build.");
+}
+function evaluatePythonCursorAwareTypingPrompt(bufferTail, cursorPosition, screenHeight, startLine, runtimeKind) {
+    const lines = bufferTail.split("\n");
+    const lastLineIndex = lines.length - 1;
+    // Cursor coordinates are in full-screen rows, while bufferTail only contains
+    // the lines from startLine to end of screen. First ensure the cursor is on the
+    // terminal's last visible row, then map that row into the captured window.
+    if (cursorPosition.y !== screenHeight - 1) {
+        return "not_busy";
+    }
+    // Map the cursor position into the captured buffer window using startLine
+    const cursorRowInBuffer = cursorPosition.y - startLine;
+    // If the last visible screen row is not represented by the captured tail,
+    // or does not map to the last captured line, we cannot evaluate reliably.
+    if (cursorRowInBuffer < 0 || cursorRowInBuffer > lastLineIndex) {
+        return "unknown";
+    }
+    if (cursorRowInBuffer !== lastLineIndex) {
+        return "not_busy";
+    }
+    const lastLine = lines[lastLineIndex] || "";
+    const promptPrefix = runtimeTypingPromptPrefix(runtimeKind);
+    if (!promptPrefix) {
+        return "unknown";
+    }
+    // Check if the last line starts with the runtime-specific prompt prefix
+    if (lastLine.startsWith(promptPrefix)) {
+        // Check if cursor is after the prompt prefix
+        if (cursorPosition.x > promptPrefix.length) {
+            const afterPrompt = lastLine.slice(promptPrefix.length).trim();
+            // If there's content after the prompt, user is typing
+            if (afterPrompt.length > 0) {
+                return "busy";
+            }
+        }
+    }
+    return "not_busy";
+}