botmux 3.4.2 → 3.5.0

package/dist/utils/stuck-detector.js

@@ -0,0 +1,188 @@
+/**
+ * Lightweight, AI-free "stuck" detector — fires a callback when a written input
+ * has not produced a completed turn within a timeout window.
+ *
+ * Scope (intentionally narrow): this PR targets the specific Codex PreToolUse
+ * hook-review blocking state, where the CLI renders a review screen and waits
+ * for t/Enter/Esc (level 1) or t/Esc (level 2). Generic [Y/n]/permission/
+ * Press-to-continue prompts are NOT handled here — they require semantic parsing
+ * that cannot be safely inferred from a regex, and belong in a follow-up PR.
+ *
+ * The detector does NOT itself decide the CLI is stuck. It only tracks elapsed
+ * time since the last write and asks the owner (worker) to confirm via the
+ * `isActuallyStuck` callback — the worker knows whether inflight inputs exist,
+ * whether a TUI prompt card is already posted, and whether the PTY has been
+ * quiet. This avoids false positives from legitimately long turns.
+ */
+/**
+ * Codex renders two distinct hook-review screens. We match each independently
+ * because their titles and control hints differ, and the safe button set differs
+ * (level 1 has Enter to drill in; level 2 has no Enter).
+ *
+ * Level 1 — hooks browser (the screen that actually blocks on startup):
+ *   Title:  "Hooks"
+ *   State:  "1 hook needs review before it can run."
+ *   Table:  "Event  Installed  Active  Review  Description" header + a row
+ *           whose Review column > 0 (e.g. "PreToolUse  1  0  1  ...")
+ *   Footer: "Press t to trust all; enter to review hooks; esc to close"
+ *
+ * Level 2 — per-hook review (after pressing Enter on level 1):
+ *   Title:  "PreToolUse hooks"
+ *   State:  "1 hook needs review before it can run."
+ *   Body:   "[!] Hook 1 · new" + "Trust  New hook - review required"
+ *   Footer: "Press t to trust; esc to go back"
+ *
+ * Matching rules (addresses retained-history and pasted-text false positives):
+ *  - Only inspect the bottom VIEWPORT_LINES of the snapshot — the TUI shows the
+ *    active screen at the bottom; stale overview text scrolled off the top must
+ *    not count.
+ *  - The footer (control hint) MUST be present in the viewport and anchors the
+ *    active region. We scan upward from the footer to find the nearest title.
+ *  - Level 2 is checked first: if the nearest title above the footer is
+ *    "PreToolUse hooks" AND the L2 body semantics are present, it is level 2
+ *    even if a stale "Hooks" overview lingers further up.
+ *  - Each level requires its semantic content rows, not just title + footer.
+ */
+const VIEWPORT_LINES = 40;
+/** Strip ANSI escape sequences and carriage returns so a line's visible text
+ *  can be matched against plain-text patterns. */
+function stripAnsi(line) {
+    return line.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '').replace(/\r/g, '');
+}
+export function matchHookReviewScreen(snapshot) {
+    if (!snapshot)
+        return undefined;
+    const rawLines = snapshot.split('\n');
+    // Strip ANSI/CR from every line — the PTY carries color codes and the
+    // renderer can emit \r\n; matching against raw bytes would miss the footer.
+    const lines = rawLines.map(stripAnsi);
+    // Only inspect the bottom of the screen — the active viewport. Stale overview
+    // text that scrolled off the top must not trigger a match.
+    const viewport = lines.slice(-VIEWPORT_LINES);
+    // Trim trailing blank lines: the footer (control hint) must be the LAST
+    // non-empty line of the viewport. If there is content below the footer,
+    // the footer belongs to a scrolled-off screen, not the active one.
+    let end = viewport.length;
+    while (end > 0 && viewport[end - 1].trim() === '')
+        end--;
+    if (end === 0)
+        return undefined;
+    const trimmed = viewport.slice(0, end);
+    // The footer MUST be the last non-empty line of the viewport, matched as a
+    // whole line (^...$) — not a substring. A line like "The old footer said: ..."
+    // must NOT match.
+    const lastLine = trimmed[trimmed.length - 1].trim();
+    let level;
+    if (/^Press t to trust all; enter to review hooks; esc to close$/i.test(lastLine)) {
+        level = 1;
+    }
+    else if (/^Press t to trust; esc to go back$/i.test(lastLine)) {
+        level = 2;
+    }
+    if (!level)
+        return undefined;
+    const footerIdx = trimmed.length - 1;
+    // Scan upward from the footer to find the nearest title line. The title must
+    // be within the active region (not separated by too many blank lines / other
+    // content), otherwise the footer may belong to a different screen.
+    let titleIdx = -1;
+    for (let i = footerIdx - 1; i >= 0 && footerIdx - i < 30; i--) {
+        const line = trimmed[i].trim();
+        if (line === 'Hooks' || /^PreToolUse hooks$/i.test(line)) {
+            titleIdx = i;
+            break;
+        }
+    }
+    if (titleIdx < 0)
+        return undefined;
+    // Bind footer level to title: a level-1 footer (trust all / review / close)
+    // can only belong to the "Hooks" overview; a level-2 footer (trust / back)
+    // can only belong to the "PreToolUse hooks" detail. This prevents a stale
+    // overview title above a detail footer (or vice versa) from misclassifying.
+    const titleLine = trimmed[titleIdx].trim();
+    if (level === 1 && titleLine !== 'Hooks')
+        return undefined;
+    if (level === 2 && !/^PreToolUse hooks$/i.test(titleLine))
+        return undefined;
+    const region = trimmed.slice(titleIdx, footerIdx + 1).join('\n');
+    // Require the pending-review state line in the active region.
+    if (!/hook needs review|needs review before it can run/i.test(region))
+        return undefined;
+    // Level 2 (detail): require the "Trust" action line in the region.
+    if (level === 2) {
+        if (/Trust\s+New hook/i.test(region))
+            return 'hook review level 2';
+        return undefined;
+    }
+    // Level 1 (overview): require the table header + a row with Review > 0 to
+    // confirm this is the active hooks browser, not a pasted snippet.
+    const hasTableHeader = /Event\s+Installed\s+Active\s+Review/i.test(region);
+    const hasReviewRow = /PreToolUse\s+\d+\s+\d+\s+[1-9]/i.test(region);
+    if (hasTableHeader && hasReviewRow)
+        return 'hook review level 1';
+    return undefined;
+}
+export class StuckDetector {
+    timeoutMs;
+    callbacks;
+    timer = null;
+    armedAt = 0;
+    firedThisWindow = false;
+    disposed = false;
+    constructor(timeoutMs, callbacks) {
+        this.timeoutMs = timeoutMs;
+        this.callbacks = callbacks;
+    }
+    /** Arm the detector — call right after writing input to the PTY. */
+    arm() {
+        if (this.disposed)
+            return;
+        this.disarm();
+        this.armedAt = Date.now();
+        this.firedThisWindow = false;
+        this.timer = setTimeout(() => this.tick(), this.timeoutMs);
+    }
+    /** Disarm — call when the turn completes (prompt ready) or the CLI exits. */
+    disarm() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.armedAt = 0;
+        this.firedThisWindow = false;
+    }
+    dispose() {
+        this.disposed = true;
+        this.disarm();
+    }
+    tick() {
+        this.timer = null;
+        if (this.disposed)
+            return;
+        if (this.firedThisWindow)
+            return;
+        if (!this.callbacks.isActuallyStuck()) {
+            // CLI may have just finished — re-arm for the next window in case it
+            // immediately blocks again on a follow-up prompt.
+            this.arm();
+            return;
+        }
+        // Only fire when the snapshot matches a known hook-review pattern.
+        // A 15s PTY silence alone does NOT prove the turn is stuck — long model
+        // thinking or tool calls can be quiet. Without a pattern match we silently
+        // re-arm and keep waiting, never posting a false "CLI stuck" warning.
+        const matched = this.matchSnapshot();
+        if (!matched) {
+            this.arm();
+            return;
+        }
+        this.firedThisWindow = true;
+        const elapsed = Date.now() - this.armedAt;
+        this.callbacks.onStuck(elapsed, matched);
+    }
+    matchSnapshot() {
+        const snap = this.callbacks.getSnapshot?.();
+        return snap ? matchHookReviewScreen(snap) : undefined;
+    }
+}
+//# sourceMappingURL=stuck-detector.js.map

package/dist/utils/stuck-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck-detector.js","sourceRoot":"","sources":["../../src/utils/stuck-detector.ts"],"names":[],"mappings":"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"}

package/dist/utils/stuck-key-guard.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Stuck-warning key-injection guard.
+ *
+ * Extracted from worker.ts's `tui_keys` message handler so the fail-closed
+ * boundary (lifetime pre-check, fresh capture, backend/lifetime re-check,
+ * page-type re-match, write success/failure → delivered/expired) can be unit
+ * tested in isolation. The production handler delegates to this function.
+ *
+ * Fail-closed contract:
+ *   - expected lifetime missing / unequal → no keys written, send expired
+ *   - fresh capture returns null or throws  → no keys written, send expired
+ *   - backend/lifetime changed after capture, OR page type no longer matches
+ *     → no keys written, send expired
+ *   - write success → send delivered; write returns false or throws → send expired
+ *
+ * backend/lifetime are read via getters (not value snapshots) so the guard can
+ * re-check LIVE state after `await capture()` — a backend replacement or CLI
+ * restart that happens mid-capture must still be detected.
+ */
+import type { SessionBackend } from '../adapters/backend/types.js';
+export interface StuckKeyGuardMessage {
+    stuckNonce: number;
+    stuckPageType: string;
+    stuckCliLifetime?: number;
+    keys: string[];
+    isFinal: boolean;
+}
+export interface StuckKeyGuardResult {
+    /** What was sent back to the daemon, if anything. */
+    sent: 'delivered' | 'expired' | 'none';
+    /** Whether keys were actually written to the backend. */
+    wroteKeys: boolean;
+}
+/**
+ * Decide whether to re-arm the stuck detector after a tui_keys click.
+ *
+ * The detector re-arms ONLY when the card-handler explicitly flagged this as a
+ * stuck-warning Enter action (advances to the next review layer) AND keys were
+ * actually written. An expired click (CLI recovered, page changed — wroteKeys
+ * is false) must NOT re-arm: the detector should stay disarmed until the next
+ * real stall, otherwise a recovered CLI could immediately re-trigger a warning.
+ */
+export declare function shouldRearmStuckDetector(rearmStuckDetector: boolean, wroteKeys: boolean): boolean;
+export interface StuckKeyGuardDeps {
+    /** Live read of the current backend (may change between calls / awaits). */
+    getBackend: () => SessionBackend | null;
+    /** Live read of the current CLI lifetime nonce (incremented on every backend replacement). */
+    getCurrentLifetime: () => number;
+    renderCols: number;
+    renderRows: number;
+    turnId: string | undefined;
+    dispatchAttempt: number | undefined;
+    /** Fresh PTY capture. Returns null on no-screenshot; may throw. */
+    capture: (backend: SessionBackend, cols: number, rows: number, opts: {
+        filter: boolean;
+    }) => Promise<{
+        content: string | null;
+    } | null>;
+    /** Classifier: returns the page type label or undefined if no match. */
+    match: (snap: string) => string | undefined;
+    /** Writes keys to the backend. Returns true on success, false on failure. */
+    writeKeys: (keys: string[], isFinal: boolean) => Promise<boolean>;
+    /** Sends a message back to the daemon. */
+    sendExpired: (nonce: number, turnId: string | undefined, dispatchAttempt: number | undefined) => void;
+    sendDelivered: (nonce: number, turnId: string | undefined, dispatchAttempt: number | undefined) => void;
+    log: (msg: string) => void;
+}
+/**
+ * Process a stuck-warning card's tui_keys click with full fail-closed guards.
+ *
+ * Returns a result describing what happened (for testing); production callers
+ * use `result.wroteKeys` to decide whether to re-arm the stuck detector.
+ */
+export declare function processStuckWarningTuiKeys(msg: StuckKeyGuardMessage, deps: StuckKeyGuardDeps): Promise<StuckKeyGuardResult>;
+//# sourceMappingURL=stuck-key-guard.d.ts.map

package/dist/utils/stuck-key-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck-key-guard.d.ts","sourceRoot":"","sources":["../../src/utils/stuck-key-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,kBAAkB,EAAE,OAAO,EAC3B,SAAS,EAAE,OAAO,GACjB,OAAO,CAET;AAED,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;IACxC,8FAA8F;IAC9F,kBAAkB,EAAE,MAAM,MAAM,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,mEAAmE;IACnE,OAAO,EAAE,CACP,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KACtB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAChD,wEAAwE;IACxE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC5C,6EAA6E;IAC7E,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,0CAA0C;IAC1C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACtG,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACxG,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,oBAAoB,EACzB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CA4D9B"}

package/dist/utils/stuck-key-guard.js

@@ -0,0 +1,77 @@
+/**
+ * Decide whether to re-arm the stuck detector after a tui_keys click.
+ *
+ * The detector re-arms ONLY when the card-handler explicitly flagged this as a
+ * stuck-warning Enter action (advances to the next review layer) AND keys were
+ * actually written. An expired click (CLI recovered, page changed — wroteKeys
+ * is false) must NOT re-arm: the detector should stay disarmed until the next
+ * real stall, otherwise a recovered CLI could immediately re-trigger a warning.
+ */
+export function shouldRearmStuckDetector(rearmStuckDetector, wroteKeys) {
+    return rearmStuckDetector && wroteKeys;
+}
+/**
+ * Process a stuck-warning card's tui_keys click with full fail-closed guards.
+ *
+ * Returns a result describing what happened (for testing); production callers
+ * use `result.wroteKeys` to decide whether to re-arm the stuck detector.
+ */
+export async function processStuckWarningTuiKeys(msg, deps) {
+    const { stuckNonce, stuckPageType, stuckCliLifetime, keys, isFinal } = msg;
+    const { getBackend, getCurrentLifetime, renderCols, renderRows, turnId, dispatchAttempt, capture, match, writeKeys, sendExpired, sendDelivered, log } = deps;
+    // P1-2: validate the CLI lifetime the card was issued for BEFORE doing
+    // anything else. If the CLI restarted between card post and click,
+    // the live lifetime has changed and the card's expected lifetime won't match —
+    // fail-closed, do not inject keys into the new CLI. A missing expected
+    // lifetime is also rejected (stuck cards must always carry it).
+    const currentLifetime = getCurrentLifetime();
+    if (stuckCliLifetime === undefined || stuckCliLifetime !== currentLifetime) {
+        log(`TUI keys from stale stuck-warning card (nonce=${stuckNonce}, expectedLifetime=${stuckCliLifetime ?? 'none'}, currentLifetime=${currentLifetime}) — CLI replaced since card issued, dropping`);
+        sendExpired(stuckNonce, turnId, dispatchAttempt);
+        return { sent: 'expired', wroteKeys: false };
+    }
+    // Freeze the backend identity + CLI lifetime BEFORE capture. If the CLI
+    // restarts (new backend object / new cliLifetimeNonce) while we await the
+    // capture, the frozen values won't match the live ones and we drop the keys.
+    const frozenBackend = getBackend();
+    const frozenLifetime = getCurrentLifetime();
+    let currentSnap = null;
+    if (frozenBackend) {
+        try {
+            const fresh = await capture(frozenBackend, renderCols, renderRows, { filter: false });
+            currentSnap = fresh?.content ?? null;
+        }
+        catch {
+            currentSnap = null;
+        }
+    }
+    // Fail-closed: no fresh snapshot OR backend/lifetime changed during capture → expired.
+    // Re-read LIVE state via getters — the values may have changed while we awaited capture.
+    const liveBackend = getBackend();
+    const liveLifetime = getCurrentLifetime();
+    if (!currentSnap || frozenBackend !== liveBackend || frozenLifetime !== liveLifetime) {
+        log(`TUI keys from stale stuck-warning card (nonce=${stuckNonce}, expected=${stuckPageType}) — fresh capture failed or backend replaced, dropping`);
+        sendExpired(stuckNonce, turnId, dispatchAttempt);
+        return { sent: 'expired', wroteKeys: false };
+    }
+    const currentMatch = match(currentSnap);
+    if (currentMatch !== stuckPageType) {
+        log(`TUI keys from stale stuck-warning card (nonce=${stuckNonce}, expected=${stuckPageType}, current=${currentMatch ?? 'none'}) — dropped, notifying daemon`);
+        sendExpired(stuckNonce, turnId, dispatchAttempt);
+        return { sent: 'expired', wroteKeys: false };
+    }
+    let writeOk = false;
+    try {
+        writeOk = await writeKeys(keys, isFinal);
+    }
+    catch {
+        writeOk = false;
+    }
+    if (writeOk) {
+        sendDelivered(stuckNonce, turnId, dispatchAttempt);
+        return { sent: 'delivered', wroteKeys: true };
+    }
+    sendExpired(stuckNonce, turnId, dispatchAttempt);
+    return { sent: 'expired', wroteKeys: false };
+}
+//# sourceMappingURL=stuck-key-guard.js.map

package/dist/utils/stuck-key-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck-key-guard.js","sourceRoot":"","sources":["../../src/utils/stuck-key-guard.ts"],"names":[],"mappings":"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"}