botmux 3.4.3 → 3.5.0

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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"}