@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.990

package/dist/senses/shepherd/cmux.js

@@ -0,0 +1,483 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUIET_MAX_MS = exports.HOOKED_QUIET_MS = exports.QUIET_MS = exports.POLL_MS = exports.BACKGROUND_GRACE_MS = exports.GRACE_MS = exports.CMUX_STATUS_KEY = void 0;
+exports.realSchedule = realSchedule;
+exports.readCmuxHookSession = readCmuxHookSession;
+exports.createCmuxHost = createCmuxHost;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+const terminal_process_1 = require("./terminal-process");
+const prompt_state_1 = require("./prompt-state");
+const redact_1 = require("./redact");
+/**
+ * The cmux host (0.64.22 or later). A return is cmux's own "agent stopped" signal: an
+ * `agent.hook.Stop` event, which cmux publishes for every agent its hooks cover (Claude Code,
+ * Codex, Copilot and more). After a short grace period, a stop is dropped if the agent resumed. A
+ * stop that cmux's session store says left background work running waits longer, and is then
+ * passed on marked as such: the agent is still working, not handing back control. Every terminal
+ * whose agent is not idle is also polled: output that stops changing for a quiet window counts
+ * as a return. That covers an agent cmux does not hook, and a hooked agent sitting mid-turn at a
+ * prompt that fires no stop (a permission or trust question); a hooked agent gets a longer window,
+ * because its stop normally speaks first. cmux has no bell or output event, so polling is the fallback.
+ */
+exports.CMUX_STATUS_KEY = "ouro";
+exports.GRACE_MS = 3_000;
+/** A stop with background work still running waits this much longer before it is judged (as working, unless the work finished). */
+exports.BACKGROUND_GRACE_MS = 30_000;
+exports.POLL_MS = 4_000;
+exports.QUIET_MS = 8_000;
+/** A hooked agent mid-turn: long enough that a stop hook or a spinner normally speaks before the quiet screen does. */
+exports.HOOKED_QUIET_MS = 20_000;
+/** A quiet terminal judged as still working or not an agent is checked less often, doubling up to this. */
+exports.QUIET_MAX_MS = 60_000;
+const POLL_LINES = 40;
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+const STOP_HOOKS = new Set(["Stop", "StopFailure"]);
+/** Hooks after which the agent waits for the human: a stop, or a session that has not been given work yet. */
+const IDLE_HOOKS = new Set([...STOP_HOOKS, "SessionStart"]);
+/** Hooks that say nothing about whether the main agent is working. */
+const NEUTRAL_HOOKS = new Set(["SubagentStop", "Notification"]);
+/** Keys cmux presses with `surface.send_key`, by its own names; every other key is typed as its character. */
+const NAMED_KEYS = { enter: "enter", escape: "escape", up: "up", down: "down", tab: "tab", "ctrl-c": "ctrl+c" };
+const SUBMIT_DELAY_MS = 300;
+/** A timer that can be cancelled; the sense and the host take it as an option so tests can drive time. */
+function realSchedule(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    return () => clearTimeout(timer);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+/** A v1 socket argument: quoted, with the characters cmux's tokenizer treats as special escaped. */
+function socketQuote(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/** cmux keeps each hooked agent's session in `~/.cmuxterm/<agent>-hook-sessions.json`, keyed by the agent's own session id. */
+function readCmuxHookSession(homeDir, agent, sessionId) {
+    try {
+        const store = JSON.parse(fs.readFileSync(path.join(homeDir, ".cmuxterm", `${path.basename(agent)}-hook-sessions.json`), "utf-8"));
+        const sessions = isRecord(store) && isRecord(store.sessions) ? store.sessions : {};
+        // Hook events name the session `<agent>-<id>`; the store keys it by the bare id.
+        const key = [sessionId, sessionId.replace(`${agent}-`, "")].find((candidate) => isRecord(sessions[candidate]));
+        return key ? sessions[key] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function createCmuxHost(client, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const now = options.now ?? Date.now;
+    const schedule = options.schedule ?? realSchedule;
+    /** What hook events taught: which surface a session runs in, and which agent and folder it has. */
+    const hooked = new Map();
+    const sessionSurface = new Map();
+    /** Terminals showing a Shepherd status, so it can be cleared when the agent resumes. */
+    const statused = new Map();
+    /** Quiet windows stretched by `pace`. */
+    const quietMs = new Map();
+    // Keep only an opaque digest, never a second private screen store. A copied/forged
+    // inspection has no original-screen authority and is conservatively refused.
+    const inspectedScreens = new WeakMap();
+    /** One status entry per terminal: cmux keys status pills per workspace, and a workspace can hold several agents. */
+    const statusKey = (surface) => `${exports.CMUX_STATUS_KEY}_${surface.ref.replace(/\W/g, "_")}`;
+    const clearStatus = (surfaceId) => {
+        const entry = statused.get(surfaceId);
+        if (!entry)
+            return;
+        statused.delete(surfaceId);
+        client.command(`clear_status ${entry.key} --tab=${entry.workspaceId}`).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_status_error", message: "could not clear a Shepherd status", meta: { error: error.message } });
+        });
+    };
+    async function surfaceEntries(strict = false) {
+        const tree = await client.call("system.tree", { all_windows: true });
+        const records = (value) => {
+            if (strict && (!Array.isArray(value) || !value.every(isRecord)))
+                throw new Error("invalid cmux terminal inventory");
+            return list(value);
+        };
+        const seen = new Set();
+        return records(tree.windows).flatMap((window) => records(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => records(workspace.panes).flatMap((pane) => records(pane.surfaces)).map((surface) => {
+            if (strict && (typeof surface.id !== "string" || !surface.id.trim() || typeof surface.type !== "string"
+                || !["terminal", "browser"].includes(surface.type) || seen.has(surface.id)))
+                throw new Error("invalid cmux terminal inventory identity");
+            seen.add(str(surface.id) ?? "");
+            return {
+                id: str(surface.id) ?? "",
+                ref: str(surface.ref) ?? "",
+                workspace: str(workspace.ref),
+                workspaceTitle: str(workspace.title),
+                workspaceId: str(workspace.id) ?? "",
+                title: str(surface.title) ?? "",
+                tty: str(surface.tty),
+                type: str(surface.type) ?? "",
+                agent: hooked.get(str(surface.id) ?? "")?.agent ?? null,
+                cwd: hooked.get(str(surface.id) ?? "")?.cwd ?? null,
+                // The human's terminal: the focused surface of the selected workspace in a visible window.
+                focused: surface.focused === true && workspace.selected === true && window.visible !== false,
+                ...(surface.focused === true && workspace.selected === true && window.visible !== false && window.key === true
+                    ? { selected: true } : {}),
+            };
+        }));
+    }
+    async function retirementInventory() {
+        return (await surfaceEntries(true)).filter(surface => surface.type === "terminal").map(surface => surface.id);
+    }
+    async function surfaces(freshFocus = false, strictInventory = false) {
+        const entries = await surfaceEntries(strictInventory);
+        const identities = await (options.identifyTerminals ?? terminal_process_1.identifyTerminalProcesses)(entries.filter((entry) => entry.type === "terminal" && entry.tty).map((entry) => entry.tty));
+        // Process lookup is awaited. On inspection paths, do not return focus from
+        // the tree sampled before that await. A moved/rebound TTY loses authority.
+        const current = freshFocus ? await surfaceEntries(strictInventory) : entries;
+        return current.map((entry) => {
+            const bound = entries.some(before => before.id === entry.id && before.tty === entry.tty && before.workspaceId === entry.workspaceId && before.type === entry.type);
+            const identity = entry.tty && bound ? identities.get(entry.tty.replace(/^\/dev\//, "")) : undefined;
+            return { ...entry, agent: identity?.agent ?? entry.agent, cwd: identity?.cwd ?? entry.cwd, ...(identity?.instance ? { instance: identity.instance } : {}) };
+        });
+    }
+    async function locate(sessionId) {
+        const surface = (await surfaces()).find((entry) => entry.id === sessionId || entry.ref === sessionId);
+        if (!surface)
+            throw new Error(`no cmux terminal ${sessionId}`);
+        return surface;
+    }
+    async function read(sessionId, lines) {
+        const result = await client.call("surface.read_text", { surface_id: sessionId, lines, scrollback: true });
+        return typeof result.text === "string" ? result.text : "";
+    }
+    const sameBinding = (a, b) => a.id.toLowerCase() === b.id.toLowerCase() && a.workspaceId.toLowerCase() === b.workspaceId.toLowerCase() &&
+        a.type === b.type && a.tty === b.tty && a.instance === b.instance && a.cwd === b.cwd &&
+        a.agent === b.agent && a.focused === b.focused && a.title === b.title &&
+        a.ref === b.ref && a.workspace === b.workspace && a.workspaceTitle === b.workspaceTitle && a.selected === b.selected;
+    async function explicitTarget(sessionId) {
+        if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(sessionId))
+            throw new Error("cmux inspection requires a surface UUID");
+        const target = (await surfaces(true)).find(entry => entry.id.toLowerCase() === sessionId.toLowerCase() && entry.type === "terminal");
+        if (!target)
+            throw new Error("cmux inspection target disappeared");
+        return target;
+    }
+    async function boundRead(target) {
+        const result = await client.call("surface.read_text", { surface_id: target.id, workspace_id: target.workspaceId, lines: 80, scrollback: false });
+        if (str(result.surface_id)?.toLowerCase() !== target.id.toLowerCase() ||
+            str(result.workspace_id)?.toLowerCase() !== target.workspaceId.toLowerCase() ||
+            typeof result.text !== "string")
+            throw new Error("cmux inspection target echo or text unavailable");
+        return result.text;
+    }
+    async function inspect(sessionId) {
+        const before = await explicitTarget(sessionId);
+        const first = await boundRead(before);
+        const current = await explicitTarget(sessionId);
+        const screen = await boundRead(current);
+        const after = await explicitTarget(sessionId);
+        const stable = sameBinding(before, current) && sameBinding(current, after) && first === screen;
+        const state = stable ? (0, prompt_state_1.inspectCodingPrompt)(after.agent ?? "unknown", screen) : { activity: "unknown", composer: "unknown" };
+        const { workspaceId: _workspaceId, type: _type, ...session } = after;
+        const screenFingerprint = (0, node_crypto_1.createHash)("sha256").update(screen).digest("hex");
+        const inspection = {
+            session, instance: after.instance ?? null, screen: (0, redact_1.redactSecrets)(screen), ...state,
+            screenFingerprint,
+            backgroundWork: state.activity === "unknown" ? null : state.activity === "working",
+        };
+        inspectedScreens.set(inspection, { hash: screenFingerprint, target: after });
+        return inspection;
+    }
+    return {
+        name: "cmux",
+        async list() {
+            return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ workspaceId: _workspaceId, type: _type, ...session }) => session);
+        },
+        retirementInventory,
+        read,
+        inspect,
+        async promptIfUnchanged(sessionId, line, expected, canSend) {
+            // Resolve first, then re-inspect. No server-side atomic CAS exists in cmux
+            // 0.64: these are fresh client-side observations, not a lock on a human's UI.
+            const target = await explicitTarget(sessionId);
+            const current = await inspect(sessionId);
+            const original = inspectedScreens.get(expected);
+            const fresh = inspectedScreens.get(current);
+            if (!expected.instance || expected.activity !== "idle" || expected.composer !== "empty" ||
+                expected.backgroundWork !== false || expected.session.focused ||
+                current.instance !== expected.instance || current.activity !== "idle" ||
+                current.composer !== "empty" || current.backgroundWork !== false || current.session.focused ||
+                !current.session.tty || !current.session.cwd ||
+                current.session.id !== expected.session.id || current.session.tty !== expected.session.tty ||
+                current.session.cwd !== expected.session.cwd || current.session.agent !== expected.session.agent ||
+                current.session.workspace !== expected.session.workspace || current.screen !== expected.screen ||
+                !sameBinding(target, fresh.target) || !original || !sameBinding(original.target, fresh.target) ||
+                fresh.hash !== original.hash) {
+                return { state: "not_sent", reason: "inspection changed or lacks idle empty unfocused instance authority" };
+            }
+            const inputTarget = { workspace_id: target.workspaceId, surface_id: target.id };
+            // The sense owns generation, shutdown, recent focus and guidance. Its
+            // synchronous last check closes invalidation during the awaited host reads.
+            if (canSend && !canSend())
+                return { state: "not_sent", reason: "parent dispatch guard invalidated" };
+            // From this point every exception is uncertain, including a rejected or
+            // partially accepted paste. Never turn it into a definite not_sent.
+            await client.call("terminal.paste", { ...inputTarget, text: line, submit_key: "none" });
+            await new Promise(resolve => schedule(() => resolve(undefined), SUBMIT_DELAY_MS));
+            await client.call("surface.send_key", { ...inputTarget, key: "enter" });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_cmux_prompted", message: "typed a guarded line into a cmux terminal", meta: { chars: line.length } });
+            return { state: "sent" };
+        },
+        async prompt(sessionId, line) {
+            const surface = await locate(sessionId);
+            const target = { workspace_id: surface.workspaceId, surface_id: surface.id };
+            // A paste lands as one block, so no character of it is read as a keystroke; Enter follows on its own.
+            await client.call("terminal.paste", { ...target, text: line, submit_key: "none" });
+            await new Promise((resolve) => schedule(() => resolve(undefined), SUBMIT_DELAY_MS));
+            await client.call("surface.send_key", { ...target, key: "enter" });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_cmux_prompted", message: "typed a line into a cmux terminal", meta: { chars: line.length } });
+        },
+        async key(sessionId, key) {
+            const surface = await locate(sessionId);
+            const target = { workspace_id: surface.workspaceId, surface_id: surface.id };
+            const named = NAMED_KEYS[key];
+            if (named)
+                await client.call("surface.send_key", { ...target, key: named });
+            else
+                await client.call("surface.send_text", { ...target, text: key });
+        },
+        async signal(sessionId, status, notification) {
+            const surface = await locate(sessionId);
+            const key = statusKey(surface);
+            await client.command(status
+                ? `set_status ${key} ${socketQuote(status)} --tab=${surface.workspaceId} --panel=${surface.id}`
+                : `clear_status ${key} --tab=${surface.workspaceId}`);
+            if (status)
+                statused.set(surface.id, { key, workspaceId: surface.workspaceId });
+            else
+                statused.delete(surface.id);
+            if (notification)
+                await client.call("notification.create", { title: notification.title, subtitle: "", body: notification.body, workspace_id: surface.workspaceId });
+        },
+        pace(sessionId, slower) {
+            if (slower)
+                quietMs.set(sessionId, Math.min((quietMs.get(sessionId) ?? exports.QUIET_MS) * 2, exports.QUIET_MAX_MS));
+            else
+                quietMs.delete(sessionId);
+        },
+        watch(handlers) {
+            let closed = false;
+            let cursor = null;
+            let attempt = 0;
+            let stream = null;
+            let cancelReconnect = null;
+            let cancelPoll = null;
+            const pending = new Map();
+            const screens = new Map();
+            const forget = (surfaceId) => {
+                hooked.delete(surfaceId);
+                for (const [session, surface] of sessionSurface)
+                    if (surface === surfaceId)
+                        sessionSurface.delete(session);
+            };
+            const cancelPending = (surfaceId) => {
+                pending.get(surfaceId)?.();
+                pending.delete(surfaceId);
+            };
+            /** A stop becomes a return only if nothing resumed it within the grace period; background work earns it a longer wait. */
+            const stopped = (surfaceId, transitionId, agent, sessionId, cwd, waited = false) => {
+                cancelPending(surfaceId);
+                pending.set(surfaceId, schedule(() => {
+                    pending.delete(surfaceId);
+                    const session = sessionId ? readCmuxHookSession(homeDir, agent, sessionId) : null;
+                    const backgroundWork = session?.hadPendingBackgroundWorkAtStop === true || session?.agentLifecycle === "backgroundWorkPending" || session?.agentLifecycle === "running";
+                    if (backgroundWork && !waited) {
+                        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_stop_deferred", message: "a cmux stop left background work running; waiting longer", meta: { agent } });
+                        return stopped(surfaceId, transitionId, agent, sessionId, cwd, true);
+                    }
+                    handlers.returned({ sessionId: surfaceId, transitionId, agent, cwd: str(session?.cwd) ?? cwd, lastBody: str(session?.lastBody), backgroundWork });
+                }, waited ? exports.BACKGROUND_GRACE_MS : exports.GRACE_MS));
+            };
+            const onEvent = (frame) => {
+                const name = str(frame.name) ?? "";
+                const payload = isRecord(frame.payload) ? frame.payload : {};
+                const surfaceId = str(payload.surface_id) ?? str(frame.surface_id);
+                if (name === "surface.focused" && surfaceId) {
+                    quietMs.delete(surfaceId);
+                    return handlers.focused(surfaceId);
+                }
+                if (name === "surface.closed" && surfaceId) {
+                    cancelPending(surfaceId);
+                    forget(surfaceId);
+                    screens.delete(surfaceId);
+                    statused.delete(surfaceId);
+                    return;
+                }
+                if (!name.startsWith("agent.hook.") || (payload.phase !== undefined && payload.phase !== "received"))
+                    return;
+                const hook = name.slice("agent.hook.".length);
+                const sessionId = str(payload.session_id);
+                if (sessionId && surfaceId)
+                    sessionSurface.set(sessionId, surfaceId);
+                const surface = surfaceId ?? (sessionId ? sessionSurface.get(sessionId) : undefined);
+                if (!surface)
+                    return;
+                const agent = str(payload._source) ?? str(frame.source) ?? "unknown";
+                const cwd = str(payload.cwd);
+                const neutral = NEUTRAL_HOOKS.has(hook);
+                // An idle agent's return came from its stop; the quiet-screen poll leaves it alone until it works again.
+                hooked.set(surface, { agent, cwd, sessionId, idle: IDLE_HOOKS.has(hook) || (neutral && hooked.get(surface)?.idle === true) });
+                if (STOP_HOOKS.has(hook))
+                    return stopped(surface, `cmux:${String(frame.boot_id)}:${String(frame.seq)}`, agent, sessionId, cwd);
+                if (neutral || hook === "SessionStart")
+                    return;
+                // The agent is working again: no pending stop, no stale status, and its quiet screen is checked at the normal pace.
+                cancelPending(surface);
+                clearStatus(surface);
+                quietMs.delete(surface);
+                // An agent that exited leaves a plain terminal, which the quiet-screen fallback watches again.
+                if (hook === "SessionEnd")
+                    forget(surface);
+            };
+            const connect = () => {
+                cancelReconnect = null;
+                stream = client.stream({ ...(cursor !== null ? { after_seq: cursor } : {}), categories: ["agent", "surface"], include_heartbeats: false }, {
+                    onFrame: (frame) => {
+                        if (frame.type === "ack") {
+                            attempt = 0;
+                            const resume = isRecord(frame.resume) ? frame.resume : {};
+                            // A first connection, a restart or a gap starts from cmux's latest event: old stops are not replayed as new returns.
+                            if (cursor === null || resume.gap === true)
+                                cursor = typeof resume.latest_seq === "number" ? resume.latest_seq : cursor;
+                            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_cmux_connected", message: "cmux event stream connected", meta: { gap: resume.gap === true } });
+                            return;
+                        }
+                        if (frame.type !== "event" || typeof frame.seq !== "number" || (cursor !== null && frame.seq <= cursor))
+                            return;
+                        cursor = frame.seq;
+                        onEvent(frame);
+                    },
+                    onClose: (error) => {
+                        stream = null;
+                        if (closed)
+                            return;
+                        const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+                        attempt += 1;
+                        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_closed", message: "cmux event stream closed; reconnecting", meta: { delay, error: error?.message ?? null } });
+                        cancelReconnect = schedule(connect, delay);
+                    },
+                });
+            };
+            let lastObserved = [];
+            /** Inventory reads stay outside the judge queue; idle-hook terminals are observed but never rejudged here. */
+            const poll = async () => {
+                try {
+                    const terminals = (await surfaces(false, !!handlers.observed)).filter((surface) => surface.type === "terminal");
+                    if (closed)
+                        return;
+                    const seen = new Set(terminals.map((surface) => surface.id));
+                    for (const id of screens.keys())
+                        if (!seen.has(id))
+                            screens.delete(id);
+                    const rows = [];
+                    for (const surface of terminals) {
+                        const idle = hooked.get(surface.id)?.idle === true;
+                        if (idle)
+                            screens.delete(surface.id);
+                        if (idle && !handlers.observed)
+                            continue;
+                        let text;
+                        try {
+                            text = await read(surface.id, POLL_LINES);
+                        }
+                        catch (error) {
+                            rows.push({ session: surface, activity: "unknown", observedAt: null, error: "read_failed" });
+                            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_poll_error",
+                                message: "could not read one cmux terminal; other terminals remain observable", meta: { error: (0, redact_1.redactSecrets)(String(error)) } });
+                            continue;
+                        }
+                        if (closed)
+                            return;
+                        rows.push({ session: surface, activity: surface.agent ? (0, prompt_state_1.inspectCodingPrompt)(surface.agent, text).activity : "unknown", observedAt: now() });
+                        if (idle)
+                            continue;
+                        const hash = (0, node_crypto_1.createHash)("sha256").update(text).digest("hex");
+                        const last = screens.get(surface.id);
+                        const at = now();
+                        if (!last)
+                            screens.set(surface.id, { hash, changedAt: at, active: false });
+                        else if (last.hash !== hash) {
+                            screens.set(surface.id, { hash, changedAt: at, active: true });
+                            clearStatus(surface.id);
+                        }
+                        else if (last.active && at - last.changedAt >= Math.max(quietMs.get(surface.id) ?? exports.QUIET_MS, hooked.has(surface.id) ? exports.HOOKED_QUIET_MS : 0)) {
+                            last.active = false;
+                            handlers.returned({ sessionId: surface.id, transitionId: `cmux:quiet:${surface.id}:${last.changedAt}`, agent: surface.agent, cwd: surface.cwd ?? null, title: surface.title, workspaceTitle: surface.workspaceTitle, lastBody: null, backgroundWork: null });
+                        }
+                    }
+                    if (closed)
+                        return;
+                    lastObserved = rows;
+                    handlers.observed?.({ at: now(), sessions: rows });
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_poll_error", message: "could not poll cmux terminals; the next poll retries", meta: { error: error.message } });
+                    if (!closed)
+                        handlers.observed?.({ at: now(), sessions: lastObserved, error: "host_unavailable" });
+                }
+                if (!closed)
+                    cancelPoll = schedule(() => void poll(), exports.POLL_MS);
+            };
+            connect();
+            void poll();
+            return {
+                close() {
+                    closed = true;
+                    cancelReconnect?.();
+                    cancelPoll?.();
+                    for (const cancel of pending.values())
+                        cancel();
+                    stream?.close();
+                },
+            };
+        },
+    };
+}