@ouro.bot/cli 0.1.0-alpha.895 → 0.1.0-alpha.898

package/dist/repertoire/tools-shepherd.js

@@ -0,0 +1,180 @@
+"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.shepherdToolDefinitions = exports.shepherdSignalToolDefinition = exports.shepherdReadToolDefinition = exports.shepherdOverviewToolDefinition = void 0;
+exports.shepherdToolsEnabled = shepherdToolsEnabled;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const shepherd_config_1 = require("../heart/shepherd-config");
+const runtime_1 = require("../nerves/runtime");
+const host_1 = require("../senses/shepherd/host");
+const redact_1 = require("../senses/shepherd/redact");
+const returns_1 = require("../senses/shepherd/returns");
+/**
+ * Shepherd's tools: every coding-agent session on this machine's terminal host with what Shepherd
+ * last decided about it (`shepherd_overview`), what a session shows (`shepherd_read`), and a status
+ * line or notification for the human (`shepherd_signal`).
+ */
+const STATUS_MAX_CHARS = 120;
+const READ_MAX_CHARS = 16_000;
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function shepherdToolsEnabled(agentRoot) {
+    if (!agentRoot)
+        return false;
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(agentRoot, "agent.json"), "utf-8"));
+        return config.senses?.shepherd?.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+function hostFor(agentName) {
+    const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName);
+    const resolved = (0, shepherd_config_1.resolveShepherdConnection)(agentName, machine.ok ? machine.config : {});
+    return resolved.ok ? (0, host_1.createShepherdHost)(resolved.connection, { agentName }) : resolved.error;
+}
+async function withHost(tool, ctx, run) {
+    if (!ctx?.agentName || !ctx.agentRoot)
+        return JSON.stringify({ error: "the Shepherd tools need an agent runtime" });
+    const host = hostFor(ctx.agentName);
+    if (typeof host === "string")
+        return JSON.stringify({ error: host });
+    try {
+        const result = await run(host);
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.shepherd_tool", message: "ran a Shepherd tool", meta: { tool } });
+        return JSON.stringify(result);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_tool_error", message: "Shepherd tool call failed", meta: { tool, error: error.message } });
+        return JSON.stringify({ error: error.message });
+    }
+}
+exports.shepherdOverviewToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_overview",
+            description: "Every terminal session on this machine's terminal host (cmux), with the coding agent there when known, and the last time Shepherd judged a return of control in it: when, what kind (premature, gate, done, unclear, loop_guard, error), whether it answered, and why. Read-only.",
+            parameters: { type: "object", properties: {}, additionalProperties: false },
+        },
+    },
+    handler: (_args, ctx) => withHost("shepherd_overview", ctx, async (host) => {
+        const last = new Map();
+        for (const record of (0, returns_1.readReturns)(ctx.agentRoot))
+            last.set(record.session, record);
+        return {
+            host: host.name,
+            sessions: (await host.list()).map((session) => {
+                const record = last.get(session.id);
+                return { ...session, ...(record ? { lastReturn: { at: record.at, kind: record.kind, action: record.action, reason: record.reason, reply: record.reply, task: record.task } } : {}) };
+            }),
+        };
+    }),
+    summaryKeys: [],
+    riskProfile: { mutates: "none", risk: "low" },
+};
+function boundedLines(value) {
+    const parsed = typeof value === "number" ? value : Number.parseInt(text(value), 10);
+    return Number.isFinite(parsed) ? Math.min(400, Math.max(1, Math.trunc(parsed))) : 60;
+}
+exports.shepherdReadToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_read",
+            description: "Read the text of one terminal session (what a coding agent shows now and what it did recently). Secret-shaped strings are redacted and the text is bounded. Read-only. Take the session id or ref from shepherd_overview.",
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref (surface:12) from shepherd_overview." },
+                    lines: { type: "number", description: "How many lines, 1-400. Default 60." },
+                },
+                required: ["session"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        if (!session)
+            return Promise.resolve(JSON.stringify({ error: "name a session id or ref from shepherd_overview" }));
+        return withHost("shepherd_read", ctx, async (host) => {
+            const screen = (0, redact_1.redactSecrets)(await host.read(session, boundedLines(args.lines)));
+            return { session, text: screen.slice(-READ_MAX_CHARS), truncated: screen.length > READ_MAX_CHARS };
+        });
+    },
+    summaryKeys: ["session"],
+    riskProfile: { mutates: "none", risk: "low" },
+};
+exports.shepherdSignalToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_signal",
+            description: `Tell the human something through the terminal host. status sets Shepherd's one-line status on that session's workspace (at most ${STATUS_MAX_CHARS} characters; an empty string clears it). notify_title with notify_body also posts a desktop notification there. It never types into a terminal.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref from shepherd_overview." },
+                    status: { type: "string", description: "One line for the status, or an empty string to clear it." },
+                    notify_title: { type: "string", description: "Desktop notification title." },
+                    notify_body: { type: "string", description: "Desktop notification body." },
+                },
+                required: ["session", "status"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        const status = text(args.status).trim();
+        const title = text(args.notify_title).trim();
+        if (!session)
+            return Promise.resolve(JSON.stringify({ error: "name a session id or ref from shepherd_overview" }));
+        if (status.length > STATUS_MAX_CHARS || /[\r\n]/.test(status))
+            return Promise.resolve(JSON.stringify({ error: `status must be one line of at most ${STATUS_MAX_CHARS} characters` }));
+        return withHost("shepherd_signal", ctx, async (host) => {
+            await host.signal(session, status || null, title ? { title, body: text(args.notify_body) } : undefined);
+            return { session, status: status ? "set" : "cleared", notified: !!title };
+        });
+    },
+    summaryKeys: ["session", "status"],
+    riskProfile: { mutates: "external_side_effect", risk: "high", reason: "changes what the terminal host shows the human (a status line or a desktop notification)" },
+};
+exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition];

package/dist/repertoire/tools.js

@@ -37,7 +37,7 @@ const tools_unraid_1 = require("./tools-unraid");
 const tools_flow_1 = require("./tools-flow");
 const tools_steward_policy_1 = require("./tools-steward-policy");
 const tools_house_care_1 = require("./tools-house-care");
-const tools_cmux_1 = require("./tools-cmux");
+const tools_shepherd_1 = require("./tools-shepherd");
 const steward_policy_1 = require("../heart/steward-policy");
 const relationship_authorization_1 = require("./relationship-authorization");
 const tool_approval_1 = require("../heart/tool-approval");
@@ -98,7 +98,7 @@ Object.defineProperty(exports, "speakTool", { enumerable: true, get: function ()
 var tools_surface_2 = require("./tools-surface");
 Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });
 // All tool definitions in a single registry
-const additionalDefinitions = [...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...tools_house_care_1.houseCareToolDefinitions, tools_surface_1.surfaceToolDefinition, ...tools_cmux_1.cmuxToolDefinitions];
+const additionalDefinitions = [...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...tools_house_care_1.houseCareToolDefinitions, tools_surface_1.surfaceToolDefinition, ...tools_shepherd_1.shepherdToolDefinitions];
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
 class ToolSelectionError extends Error {
 }
@@ -172,8 +172,8 @@ function selectToolsForChannel(capabilities, toolPreferences, _context, provider
         });
         ordinary = [
             ...tools_base_1.baseToolDefinitions,
-            // The cmux sense's tools exist only for an agent that turned the sense on in agent.json.
-            ...((0, tools_cmux_1.cmuxToolsEnabled)(context?.agentRoot ?? safeGetAgentRoot()) ? tools_cmux_1.cmuxToolDefinitions : []),
+            // The Shepherd tools exist only for an agent that turned the sense on in agent.json.
+            ...((0, tools_shepherd_1.shepherdToolsEnabled)(context?.agentRoot ?? safeGetAgentRoot()) ? tools_shepherd_1.shepherdToolDefinitions : []),
             ...(capabilities?.channel === "bluebubbles" ? tools_bluebubbles_1.bluebubblesToolDefinitions : []),
             ...(capabilities?.channel === "voice" ? tools_voice_1.voiceToolDefinitions : []),
             ...((0, tools_voice_local_1.localAudioToolGate)({ ...context, context: _context }).ok ? [tools_voice_local_1.voiceLocalAudioToolDefinition] : []),

package/dist/senses/{cmux → shepherd}/client.js

@@ -37,7 +37,7 @@ exports.CmuxSocketError = void 0;
 exports.createCmuxClient = createCmuxClient;
 const node_crypto_1 = require("node:crypto");
 const net = __importStar(require("node:net"));
-const cmux_config_1 = require("../../heart/cmux-config");
+const shepherd_config_1 = require("../../heart/shepherd-config");
 const runtime_1 = require("../../nerves/runtime");
 class CmuxSocketError extends Error {
     code;
@@ -63,7 +63,7 @@ function parseRecord(line) {
 }
 function createCmuxClient(connection, options = {}) {
     const timeoutMs = options.timeoutMs ?? 5_000;
-    const repair = (0, cmux_config_1.cmuxRepairHint)(options.agentName ?? "<agent>");
+    const repair = (0, shepherd_config_1.shepherdRepairHint)(options.agentName ?? "<agent>");
     const wrap = (line) => connection.auth.kind === "capability"
         ? `_cmux_capability_v1 ${connection.auth.token} ${line}`
         : line;
@@ -146,7 +146,7 @@ function createCmuxClient(connection, options = {}) {
         async call(method, params = {}) {
             const text = await request(v2Line(method, params));
             const result = parseV2(text);
-            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.cmux_call", message: "cmux socket call answered", meta: { method } });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_call", message: "cmux socket call answered", meta: { method } });
             return result;
         },
         async command(line) {

package/dist/senses/shepherd/cmux.js

@@ -0,0 +1,332 @@
+"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.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");
+/**
+ * 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. Terminals no hook has spoken for
+ * (an agent cmux does not hook, such as Agency today) are polled: output that stops changing for a
+ * quiet window counts as a return. 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 quiet terminal judged as still working or not an agent is checked less often, doubling up to this. */
+exports.QUIET_MAX_MS = 300_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 that say nothing about whether the main agent is working. */
+const NEUTRAL_HOOKS = new Set(["SubagentStop", "Notification"]);
+const NAMED_KEYS = new Set(["enter", "escape", "up", "down", "tab"]);
+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();
+    /** 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 surfaces() {
+        const tree = await client.call("system.tree", { all_windows: true });
+        return list(tree.windows).flatMap((window) => list(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => list(workspace.panes).flatMap((pane) => list(pane.surfaces)).map((surface) => ({
+            id: str(surface.id) ?? "",
+            ref: str(surface.ref) ?? "",
+            workspace: str(workspace.ref),
+            workspaceId: str(workspace.id) ?? "",
+            title: str(surface.title) ?? "",
+            type: str(surface.type) ?? "",
+            agent: hooked.get(str(surface.id) ?? "")?.agent ?? 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,
+        })));
+    }
+    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 : "";
+    }
+    return {
+        name: "cmux",
+        async list() {
+            return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ id, ref, workspace, title, agent, focused }) => ({ id, ref, workspace, title, agent, focused }));
+        },
+        read,
+        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 };
+            if (NAMED_KEYS.has(key))
+                await client.call("surface.send_key", { ...target, key });
+            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);
+                hooked.set(surface, { agent, cwd, sessionId });
+                if (STOP_HOOKS.has(hook))
+                    return stopped(surface, `cmux:${String(frame.boot_id)}:${String(frame.seq)}`, agent, sessionId, cwd);
+                if (NEUTRAL_HOOKS.has(hook))
+                    return;
+                // The agent is working again: no pending stop, and no stale status.
+                cancelPending(surface);
+                clearStatus(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);
+                    },
+                });
+            };
+            /** Terminals with no hook: output that changed and then held still for the quiet window is a return. */
+            const poll = async () => {
+                try {
+                    const terminals = (await surfaces()).filter((surface) => surface.type === "terminal" && !hooked.has(surface.id));
+                    const seen = new Set(terminals.map((surface) => surface.id));
+                    for (const id of screens.keys())
+                        if (!seen.has(id))
+                            screens.delete(id);
+                    for (const surface of terminals) {
+                        const hash = (0, node_crypto_1.createHash)("sha256").update(await read(surface.id, POLL_LINES)).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 >= (quietMs.get(surface.id) ?? exports.QUIET_MS)) {
+                            last.active = false;
+                            handlers.returned({ sessionId: surface.id, transitionId: `cmux:quiet:${surface.id}:${last.changedAt}`, agent: null, cwd: null, lastBody: null, backgroundWork: null });
+                        }
+                    }
+                }
+                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)
+                    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();
+                },
+            };
+        },
+    };
+}