@holon-run/agentinbox 0.6.0 → 1.0.0-beta.0

package/dist/src/runtime_gate.js

@@ -10,37 +10,55 @@ 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 = 900;
-const DEFAULT_TMUX_SAMPLE_DELAY_MS = 900;
-const ACTIVE_BUFFER_MARKERS = [
-    "esc to interrupt",
-    "Working (",
-    "⠼ ",
-];
-const TYPING_PROMPT_PREFIXES = [
-    "› ",
-    "> ",
-];
+const DEFAULT_GATING_POLICY = {
+    iTerm2SampleDelayMs: 900,
+    tmuxSampleDelayMs: 900,
+    normalizedBufferTailLines: 20,
+    activeBufferMarkers: [
+        "esc to interrupt",
+        "Working (",
+        "⠼ ",
+    ],
+    typingPromptPrefixes: [
+        "› ",
+        "> ",
+    ],
+};
 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(), gatingPolicy = DEFAULT_GATING_POLICY) {
+        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"), gatingPolicy),
+            new Iterm2TerminalStateProbe(undefined, {}, this.logger.child("iterm2_terminal"), gatingPolicy),
+            new ClaudeCodeTerminalStateProbe(undefined, undefined, undefined, this.logger.child("claude_terminal")),
+            new TmuxTerminalStateProbe(undefined, {}, this.logger.child("tmux_terminal"), gatingPolicy),
+        ];
     }
     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 +66,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 +129,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 +179,16 @@ class CodexTerminalStateProbe {
     sessionFileReader;
     statReader;
     nowFn;
-    constructor(iTermProbe = new Iterm2TerminalStateProbe(), tmuxProbe = new TmuxTerminalStateProbe(), sessionFileReader, statReader, nowFn = () => Date.now()) {
+    logger;
+    gatingPolicy;
+    constructor(iTermProbe = new Iterm2TerminalStateProbe(undefined, {}, new logging_1.NoopLogger(), DEFAULT_GATING_POLICY), tmuxProbe = new TmuxTerminalStateProbe(undefined, {}, new logging_1.NoopLogger(), DEFAULT_GATING_POLICY), sessionFileReader, statReader, nowFn = () => Date.now(), logger = new logging_1.NoopLogger(), gatingPolicy = DEFAULT_GATING_POLICY) {
         this.iTermProbe = iTermProbe;
         this.tmuxProbe = tmuxProbe;
         this.sessionFileReader = sessionFileReader;
         this.statReader = statReader;
         this.nowFn = nowFn;
+        this.logger = logger;
+        this.gatingPolicy = gatingPolicy;
     }
     supports(target) {
         return target.runtimeKind === "codex";
@@ -117,26 +196,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 +272,13 @@ exports.CodexTerminalStateProbe = CodexTerminalStateProbe;
 class Iterm2TerminalStateProbe {
     execAsync;
     options;
-    constructor(execAsync = execFileAsync, options = {}) {
+    logger;
+    gatingPolicy;
+    constructor(execAsync = execFileAsync, options = {}, logger = new logging_1.NoopLogger(), gatingPolicy = DEFAULT_GATING_POLICY) {
         this.execAsync = execAsync;
         this.options = options;
+        this.logger = logger;
+        this.gatingPolicy = gatingPolicy;
     }
     supports(target) {
         // Only support iTerm2 targets that are NOT Claude Code
@@ -168,17 +291,39 @@ 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
-        return this.checkWithCommandLineTools(sessionId);
+        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 {
@@ -188,12 +333,25 @@ class Iterm2TerminalStateProbe {
             });
             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 && data.lines) {
-                    const bufferTail = data.lines.join("\n");
+                if (data.cursor && Array.isArray(data.lines)) {
+                    const bufferTail = normalizeProbeTailFromLines(data.lines, this.gatingPolicy.normalizedBufferTailLines);
+                    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;
@@ -201,70 +359,135 @@ class Iterm2TerminalStateProbe {
                     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);
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? this.gatingPolicy.iTerm2SampleDelayMs);
                         const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
                             env: { ...process.env, PYTHONIOENCODING: "utf-8" }
                         });
                         const secondData = JSON.parse(secondResult.stdout);
-                        if (secondData.status === "available" && secondData.lines) {
-                            const secondBufferTail = secondData.lines.join("\n");
-                            if (bufferTail !== secondBufferTail) {
+                        if (secondData.status === "available" && Array.isArray(secondData.lines)) {
+                            const secondBufferTail = normalizeProbeTailFromLines(secondData.lines, this.gatingPolicy.normalizedBufferTailLines);
+                            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)) {
+                        if (containsActiveBufferMarker(bufferTail, this.gatingPolicy.activeBufferMarkers)) {
+                            this.logger.trace("probe_python_result", {
+                                sessionId,
+                                result: { presence: "available", busy: "busy" },
+                                reason: "active_buffer_marker",
+                            });
                             return { presence: "available", busy: "busy" };
                         }
-                        return { presence: "available", busy: "idle" };
+                        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);
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? this.gatingPolicy.iTerm2SampleDelayMs);
                         const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
                             env: { ...process.env, PYTHONIOENCODING: "utf-8" }
                         });
                         const secondData = JSON.parse(secondResult.stdout);
-                        if (secondData.status === "available" && secondData.lines) {
-                            const secondBufferTail = secondData.lines.join("\n");
-                            if (bufferTail !== secondBufferTail) {
+                        if (secondData.status === "available" && Array.isArray(secondData.lines)) {
+                            const secondBufferTail = normalizeProbeTailFromLines(secondData.lines, this.gatingPolicy.normalizedBufferTailLines);
+                            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)) {
+                        if (containsActiveBufferMarker(bufferTail, this.gatingPolicy.activeBufferMarkers)) {
+                            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 {
+        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) {
+    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);
@@ -276,18 +499,33 @@ class Iterm2TerminalStateProbe {
         if (!first) {
             return { presence: "available", busy: "unknown" };
         }
-        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_ITERM2_SAMPLE_DELAY_MS);
+        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? this.gatingPolicy.iTerm2SampleDelayMs);
         const second = await this.readBufferTail(it2api, sessionId);
         if (!second) {
             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)) {
+        if (containsActiveBufferMarker(second, this.gatingPolicy.activeBufferMarkers)) {
+            this.logger.trace("probe_cli_result", {
+                sessionId,
+                result: { presence: "available", busy: "busy" },
+                reason: "active_buffer_marker",
+            });
             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) {
@@ -296,7 +534,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";
         }
     }
@@ -311,7 +555,7 @@ class Iterm2TerminalStateProbe {
     async readBufferTail(it2api, sessionId) {
         try {
             const result = await this.execAsync(it2api, ["get-buffer", sessionId]);
-            return normalizeBufferTail(result.stdout);
+            return normalizeBufferTail(result.stdout, this.gatingPolicy.normalizedBufferTailLines);
         }
         catch {
             return null;
@@ -322,9 +566,13 @@ exports.Iterm2TerminalStateProbe = Iterm2TerminalStateProbe;
 class TmuxTerminalStateProbe {
     execAsync;
     options;
-    constructor(execAsync = execFileAsync, options = {}) {
+    logger;
+    gatingPolicy;
+    constructor(execAsync = execFileAsync, options = {}, logger = new logging_1.NoopLogger(), gatingPolicy = DEFAULT_GATING_POLICY) {
         this.execAsync = execAsync;
         this.options = options;
+        this.logger = logger;
+        this.gatingPolicy = gatingPolicy;
     }
     supports(target) {
         return target.backend === "tmux" && typeof target.tmuxPaneId === "string" && target.tmuxPaneId.trim().length > 0;
@@ -332,39 +580,86 @@ 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);
         if (!first) {
             return { presence: "available", busy: "unknown" };
         }
-        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_TMUX_SAMPLE_DELAY_MS);
+        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? this.gatingPolicy.tmuxSampleDelayMs);
         const second = await this.readBufferTail(paneId);
         if (!second) {
             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)) {
+        if (containsActiveBufferMarker(second, this.gatingPolicy.activeBufferMarkers)) {
+            this.logger.trace("probe_result", {
+                targetId: target.targetId,
+                paneId,
+                result: { presence: "available", busy: "busy" },
+                reason: "active_buffer_marker",
+            });
             return { presence: "available", busy: "busy" };
         }
         // 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) {
@@ -397,8 +692,8 @@ class TmuxTerminalStateProbe {
     }
     async readBufferTail(paneId) {
         try {
-            const result = await this.execAsync("tmux", ["capture-pane", "-p", "-t", paneId, "-S", "-20"]);
-            return normalizeBufferTail(result.stdout);
+            const result = await this.execAsync("tmux", ["capture-pane", "-p", "-t", paneId, "-S", `-${this.gatingPolicy.normalizedBufferTailLines}`]);
+            return normalizeBufferTail(result.stdout, this.gatingPolicy.normalizedBufferTailLines);
         }
         catch {
             return null;
@@ -406,10 +701,10 @@ class TmuxTerminalStateProbe {
     }
 }
 exports.TmuxTerminalStateProbe = TmuxTerminalStateProbe;
-function containsActiveBufferMarker(bufferTail) {
-    return ACTIVE_BUFFER_MARKERS.some((marker) => bufferTail.includes(marker));
+function containsActiveBufferMarker(bufferTail, markers = DEFAULT_GATING_POLICY.activeBufferMarkers) {
+    return markers.some((marker) => bufferTail.includes(marker));
 }
-function hasVisibleTypingPrompt(bufferTail, prefixes = TYPING_PROMPT_PREFIXES) {
+function hasVisibleTypingPrompt(bufferTail, prefixes = DEFAULT_GATING_POLICY.typingPromptPrefixes) {
     const lines = bufferTail
         .split("\n")
         .map((line) => line.trimEnd())
@@ -467,7 +762,7 @@ function typingPromptPrefixesForRuntime(runtimeKind) {
     if (runtimeKind === "claude_code") {
         return ["❯ ", "› "];
     }
-    return TYPING_PROMPT_PREFIXES;
+    return DEFAULT_GATING_POLICY.typingPromptPrefixes;
 }
 function parseOptionalInt(value) {
     if (!value) {
@@ -476,16 +771,19 @@ function parseOptionalInt(value) {
     const parsed = Number.parseInt(value, 10);
     return Number.isFinite(parsed) ? parsed : null;
 }
-function normalizeBufferTail(buffer) {
+function normalizeBufferTail(buffer, tailLines = DEFAULT_GATING_POLICY.normalizedBufferTailLines) {
     const normalized = buffer
         .replace(/\r/g, "")
         .split("\n")
         .map((line) => line.trimEnd())
-        .slice(-20)
+        .slice(-tailLines)
         .join("\n")
         .trim();
     return normalized.length > 0 ? normalized : null;
 }
+function normalizeProbeTailFromLines(lines, tailLines = DEFAULT_GATING_POLICY.normalizedBufferTailLines) {
+    return normalizeBufferTail(lines.join("\n"), tailLines);
+}
 function resolveIterm2ApiPath(override) {
     if (override) {
         return override;
@@ -622,15 +920,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 {
@@ -639,19 +940,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";
         }
     }
@@ -678,26 +984,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
@@ -709,10 +1032,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" };
         }
     }