@agentdeck/bridge 1.0.4 → 1.0.5

package/dist/session-focus-relay.js

@@ -14,8 +14,13 @@ import WebSocket from 'ws';
 import { listActive as listActiveSessions } from './session-registry.js';
 import { debug } from './logger.js';
 const TAG = 'focus-relay';
-/** Events relayed from focused session to daemon clients */
-const RELAYED_EVENTS = new Set([
+/**
+ * Events relayed from a focused session to daemon clients. Canonical set for
+ * BOTH ends of the relay: the daemon side filters here, and the worker side
+ * (`DaemonWsClient.forwardEvent`) imports this same set — the two ends cannot
+ * drift on which events ride the push socket.
+ */
+export const RELAYED_EVENTS = new Set([
     'state_update',
     'prompt_options',
     'usage_update',
@@ -33,37 +38,136 @@ const ROUTED_COMMANDS = new Set([
 export class SessionFocusRelay {
     ws = null;
     focusedSessionId = null;
-    focusedPort = null;
+    focusedTarget = null;
     onEvent = null;
     closed = false;
+    /** Resolver for a remote session's live push socket (same-socket reverse control). */
+    sameSocketResolver = null;
+    /** When focused via same-socket, the worker's push socket we drive commands down. */
+    focusedSender = null;
     /** Set handler for relayed events. Daemon should merge and broadcast. */
     setEventHandler(handler) {
         this.onEvent = handler;
     }
+    /**
+     * Install a resolver mapping a sessionId to its live push socket. This is the
+     * ONLY reverse path for remote (cross-machine) sessions: the daemon drives the
+     * session by writing `session_command_down` frames back down the socket the
+     * worker already opened — so NAT'd / SSH-only workers need no inbound
+     * reachability, and the daemon never dials back.
+     */
+    setSameSocketResolver(resolver) {
+        this.sameSocketResolver = resolver;
+    }
+    /**
+     * Feed a `session_event_up` event that rode back up a worker's push socket
+     * (same-socket reverse control). Only applied while that session is focused.
+     */
+    ingestReverseEvent(sessionId, event) {
+        if (sessionId !== this.focusedSessionId || !this.focusedSender)
+            return;
+        if (!RELAYED_EVENTS.has(event.type))
+            return;
+        debug(TAG, `Relay(same-socket) ${event.type} from session ${sessionId}`);
+        // prompt_options used to be source-less, allowing a late event from the
+        // previous focus to become buttons for the newly selected session. Stamp
+        // the relay identity before it leaves this boundary (parity with the
+        // local dial path's stamping in connect()).
+        const tagged = event.type === 'prompt_options'
+            ? { ...event, sessionId, focusedSessionId: sessionId }
+            : event;
+        this.onEvent?.(tagged);
+    }
+    /**
+     * Drop the same-socket focus when the focused worker's push socket goes away.
+     * `closedSocket` guards against the stale-socket race: when a worker
+     * reconnects, the NEW socket takes over focus (see `migrateSender`) before
+     * the OLD one finishes closing — the old close must not tear the new focus
+     * down. A no-arg call (legacy) unfocuses unconditionally.
+     */
+    handleSenderClosed(sessionId, closedSocket) {
+        if (sessionId !== this.focusedSessionId || !this.focusedSender)
+            return;
+        if (closedSocket !== undefined && closedSocket !== this.focusedSender)
+            return;
+        this.unfocus();
+    }
+    /**
+     * A currently-focused session re-registered with a new push socket (worker
+     * reconnect). Move the focus to the new socket so control continues without
+     * an unfocus/refocus cycle: stop the old sender's forwarding (best-effort),
+     * swap, and re-send `session_focus_down` down the new socket.
+     */
+    migrateSender(sessionId, newSender) {
+        if (sessionId !== this.focusedSessionId || !this.focusedSender)
+            return;
+        if (this.focusedSender === newSender)
+            return;
+        if (this.focusedSender.readyState === WebSocket.OPEN) {
+            try {
+                this.focusedSender.send(JSON.stringify({ type: 'session_unfocus_down', sessionId }));
+            }
+            catch { /* closing */ }
+        }
+        this.focusedSender = newSender;
+        debug(TAG, `Migrated focus for ${sessionId} to new push socket`);
+        try {
+            newSender.send(JSON.stringify({ type: 'session_focus_down', sessionId }));
+        }
+        catch { /* closing */ }
+    }
     /** Get currently focused session ID */
     getFocusedSessionId() {
         return this.focusedSessionId;
     }
     /** Focus a session by ID. Disconnects from previous session. */
     focus(sessionId) {
-        if (this.focusedSessionId === sessionId && this.ws?.readyState === WebSocket.OPEN) {
+        const stillLive = (this.focusedSender && this.focusedSender.readyState === WebSocket.OPEN) ||
+            this.ws?.readyState === WebSocket.OPEN;
+        if (this.focusedSessionId === sessionId && stillLive) {
             debug(TAG, `Already focused on ${sessionId}`);
             return;
         }
         this.unfocus();
-        const sessions = listActiveSessions();
-        const session = sessions.find(s => s.id === sessionId && s.agentType !== 'daemon');
+        // 1. Same-socket: if the worker has a live push socket, drive it down that
+        //    socket. No inbound dial, works for NAT'd / SSH-only workers. This is
+        //    the ONLY path for remote sessions — a remote session whose socket
+        //    dropped stays unfocusable until its worker reconnects.
+        const sender = this.sameSocketResolver?.(sessionId) ?? null;
+        if (sender && sender.readyState === WebSocket.OPEN) {
+            this.focusedSessionId = sessionId;
+            this.focusedSender = sender;
+            debug(TAG, `Focusing session ${sessionId} via same-socket reverse control`);
+            try {
+                sender.send(JSON.stringify({ type: 'session_focus_down', sessionId }));
+            }
+            catch { /* closing */ }
+            return;
+        }
+        // 2. Local sessions: dial the bridge's loopback port from sessions.json
+        //    (the pre-existing local focus mechanism).
+        const session = listActiveSessions().find(s => s.id === sessionId && s.agentType !== 'daemon');
         if (!session) {
-            debug(TAG, `Session ${sessionId} not found or is daemon`);
+            debug(TAG, `Session ${sessionId} not found, not local, or is daemon`);
             return;
         }
         this.focusedSessionId = sessionId;
-        this.focusedPort = session.port;
-        debug(TAG, `Focusing session ${session.projectName}:${session.port}`);
+        this.focusedTarget = { host: '127.0.0.1', port: session.port };
+        debug(TAG, `Focusing session ${sessionId} at 127.0.0.1:${session.port}`);
         this.connect();
     }
     /** Unfocus current session. */
     unfocus() {
+        // Same-socket: tell the worker to stop forwarding events up its push socket.
+        if (this.focusedSender) {
+            if (this.focusedSender.readyState === WebSocket.OPEN && this.focusedSessionId) {
+                try {
+                    this.focusedSender.send(JSON.stringify({ type: 'session_unfocus_down', sessionId: this.focusedSessionId }));
+                }
+                catch { /* closing */ }
+            }
+            this.focusedSender = null;
+        }
         if (this.ws) {
             this.ws.removeAllListeners();
             this.ws.close();
@@ -73,14 +177,23 @@ export class SessionFocusRelay {
             debug(TAG, `Unfocused session ${this.focusedSessionId}`);
         }
         this.focusedSessionId = null;
-        this.focusedPort = null;
+        this.focusedTarget = null;
     }
     /** Route a command to the focused session. Returns true if handled. */
     routeCommand(cmd) {
-        if (!this.focusedSessionId || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.focusedSessionId || !ROUTED_COMMANDS.has(cmd.type)) {
             return false;
         }
-        if (!ROUTED_COMMANDS.has(cmd.type)) {
+        // Same-socket (remote sessions): send the command down the worker's push socket.
+        if (this.focusedSender) {
+            if (this.focusedSender.readyState !== WebSocket.OPEN)
+                return false;
+            debug(TAG, `Routing(same-socket) ${cmd.type} → session ${this.focusedSessionId}`);
+            this.focusedSender.send(JSON.stringify({ type: 'session_command_down', sessionId: this.focusedSessionId, command: cmd }));
+            return true;
+        }
+        // Local sessions: the loopback WS dialed in connect().
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             return false;
         }
         debug(TAG, `Routing ${cmd.type} → session ${this.focusedSessionId}`);
@@ -93,13 +206,15 @@ export class SessionFocusRelay {
         this.unfocus();
     }
     connect() {
-        if (this.closed || !this.focusedPort)
+        if (this.closed || !this.focusedTarget)
             return;
-        const ws = new WebSocket(`ws://127.0.0.1:${this.focusedPort}`);
+        const { port } = this.focusedTarget;
+        // Local sessions only — loopback, no token (same-machine is authenticated).
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`);
         this.ws = ws;
         const sessionId = this.focusedSessionId;
         ws.on('open', () => {
-            debug(TAG, `Connected to session ${sessionId} on port ${this.focusedPort}`);
+            debug(TAG, `Connected to session ${sessionId} at 127.0.0.1:${port}`);
         });
         ws.on('message', (raw) => {
             if (this.focusedSessionId !== sessionId)

package/dist/session-focus-relay.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-focus-relay.js","sourceRoot":"","sources":["../src/session-focus-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,MAAM,GAAG,GAAG,aAAa,CAAC;AAE1B,4DAA4D;AAC5D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,cAAc;IACd,gBAAgB;IAChB,cAAc;CACf,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,SAAS;IACT,WAAW;IACX,QAAQ;IACR,eAAe;IACf,aAAa;IACb,iBAAiB;IACjB,aAAa;CACd,CAAC,CAAC;AAIH,MAAM,OAAO,iBAAiB;IACpB,EAAE,GAAqB,IAAI,CAAC;IAC5B,gBAAgB,GAAkB,IAAI,CAAC;IACvC,WAAW,GAAkB,IAAI,CAAC;IAClC,OAAO,GAA6B,IAAI,CAAC;IACzC,MAAM,GAAG,KAAK,CAAC;IAEvB,yEAAyE;IACzE,eAAe,CAAC,OAA0B;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,uCAAuC;IACvC,mBAAmB;QACjB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,SAAiB;QACrB,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAClF,KAAK,CAAC,GAAG,EAAE,sBAAsB,SAAS,EAAE,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;QAEf,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC;QACnF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,KAAK,CAAC,GAAG,EAAE,WAAW,SAAS,yBAAyB,CAAC,CAAC;YAC1D,OAAO;QACT,CAAC;QAED,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;QAChC,KAAK,CAAC,GAAG,EAAE,oBAAoB,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,+BAA+B;IAC/B,OAAO;QACL,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC;YAC7B,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,KAAK,CAAC,GAAG,EAAE,qBAAqB,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,uEAAuE;IACvE,YAAY,CAAC,GAAkB;QAC7B,IAAI,CAAC,IAAI,CAAC,gBAAgB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAChF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,IAAI,cAAc,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2BAA2B;IAC3B,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAE7C,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,kBAAkB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAExC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACjB,KAAK,CAAC,GAAG,EAAE,wBAAwB,SAAS,YAAY,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAoB,EAAE,EAAE;YACxC,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;gBAAE,OAAO;YAEhD,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAgB,CAAC;gBACtD,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjC,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,CAAC,IAAI,iBAAiB,SAAS,EAAE,CAAC,CAAC;oBAC1D,oEAAoE;oBACpE,uEAAuE;oBACvE,oEAAoE;oBACpE,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,KAAK,gBAAgB,IAAI,SAAS;wBACvD,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE;wBACpD,CAAC,CAAC,GAAG,CAAC;oBACR,IAAI,CAAC,OAAO,EAAE,CAAC,MAAqB,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,2BAA2B;YAC7B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAClB,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACxC,KAAK,CAAC,GAAG,EAAE,WAAW,SAAS,YAAY,CAAC,CAAC;gBAC7C,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;YACjB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"session-focus-relay.js","sourceRoot":"","sources":["../src/session-focus-relay.ts"],"names":[],"mappings":"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"}

package/dist/session-push-channel.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Push-channel message handling — the daemon side of the session bridge's
+ * `DaemonWsClient` socket (`session_push_register` / `session_push_state` /
+ * `session_event_up`).
+ *
+ * Extracted from the `startDaemon` closure so the REAL registration /
+ * state-update / reverse-event logic is integration-testable with fake
+ * sockets: the reviewer-required regressions (ssh -L loopback registration,
+ * overlapping old/new sockets, event ownership) drive this exact handler.
+ */
+import type { WebSocket } from 'ws';
+import type { SessionFocusRelay } from './session-focus-relay.js';
+/** The slice of BridgeCore the push channel needs — keeps tests free of the real core. */
+export interface PushChannelCore {
+    broadcastSessionsList(): Promise<void>;
+    maybeBroadcastSessionsList(): void;
+}
+export interface PushChannelDeps {
+    core: PushChannelCore;
+    focusRelay: SessionFocusRelay;
+    /** Production reads the socket's remote address; tests inject a fake. */
+    getSenderIp?: (sender: WebSocket) => string;
+}
+/**
+ * Returns a handler for push-channel frames. The daemon calls it from its WS
+ * message dispatch; a `true` return means the frame was consumed.
+ */
+export declare function createPushChannelHandler(deps: PushChannelDeps): (msg: {
+    type?: string;
+}, sender: WebSocket) => boolean;
+//# sourceMappingURL=session-push-channel.d.ts.map

package/dist/session-push-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-push-channel.d.ts","sourceRoot":"","sources":["../src/session-push-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAUpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,0BAA0B,IAAI,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC;CAC7C;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,eAAe,IAInB,KAAK;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,SAAS,KAAG,OAAO,CA2E7F"}

package/dist/session-push-channel.js

@@ -0,0 +1,94 @@
+import { debug } from './logger.js';
+import { isLocalConnection } from './auth.js';
+import { updatePushState } from './session-aggregator.js';
+import { registerRemoteSession, updateRemoteSessionState, removeRemoteSession, getRemoteSession, } from './remote-sessions.js';
+function defaultGetSenderIp(sender) {
+    return sender._socket?.remoteAddress ?? '';
+}
+/**
+ * Returns a handler for push-channel frames. The daemon calls it from its WS
+ * message dispatch; a `true` return means the frame was consumed.
+ */
+export function createPushChannelHandler(deps) {
+    const { core, focusRelay } = deps;
+    const getSenderIp = deps.getSenderIp ?? defaultGetSenderIp;
+    return function handlePushChannelMessage(msg, sender) {
+        if (msg.type === 'session_push_register') {
+            const { sessionId, port: sessionPort, agentType: at, projectName: pn, host, remoteAttach, weight } = msg;
+            debug('daemon', `session_push_register: ${sessionId} port=${sessionPort} agent=${at} host=${host ?? '-'} remote=${remoteAttach === true}`);
+            // A session on ANOTHER machine isn't in this daemon's sessions.json, so
+            // it is tracked in memory and driven back down this very socket.
+            // Classification: the worker's explicit `remoteAttach` intent wins — an
+            // `ssh -L`-forwarded worker arrives on loopback and is indistinguishable
+            // from a local session by IP. The non-local-IP heuristic stays as
+            // back-compat for older workers that never send the flag.
+            const senderIp = getSenderIp(sender);
+            if (remoteAttach === true || (senderIp && !isLocalConnection(senderIp))) {
+                const displayHost = typeof host === 'string' && host ? host : senderIp.replace(/^::ffff:/, '');
+                registerRemoteSession({
+                    sessionId,
+                    host: displayHost,
+                    port: sessionPort,
+                    agentType: at,
+                    projectName: pn,
+                    weight,
+                    sender,
+                });
+                // If this session is currently focused via an OLDER socket (worker
+                // reconnect), move the focus to the new one before the old close fires.
+                focusRelay.migrateSender(sessionId, sender);
+                // Prune when the worker's push socket drops (process exit / network
+                // loss) — but only if this socket is still the registered sender: a
+                // reconnected worker's NEW registration must survive the OLD close.
+                sender.once('close', () => {
+                    removeRemoteSession(sessionId, sender);
+                    focusRelay.handleSenderClosed(sessionId, sender);
+                    core.broadcastSessionsList().catch(() => { });
+                });
+                core.broadcastSessionsList().catch(() => { });
+            }
+            // Acknowledge registration — unconditionally, local registrations too:
+            // the worker's `registered` / `isConnected` flags depend on this ack.
+            try {
+                sender.send(JSON.stringify({ type: 'session_push_ack', sessionId }));
+            }
+            catch { /* client disconnecting */ }
+            return true; // consumed
+        }
+        if (msg.type === 'session_push_state') {
+            const { sessionId, state, modelName, effortLevel, permissionMode } = msg;
+            if (sessionId && state) {
+                // Whenever a remote registration exists, the WHOLE update is keyed to
+                // its registered sender socket — the aggregator cache included. In the
+                // local + --remote-daemon dual-registration case the sessions list
+                // dedups to the local row (daemon-server.ts) whose displayed state
+                // comes from this cache (session-aggregator.ts enricher via
+                // getPushState), so a stale pre-reconnect socket poisoning it would
+                // show through despite the registry's own guard. Sessions with no
+                // remote registration keep the plain unguarded local path.
+                const rs = getRemoteSession(sessionId);
+                const staleSender = rs?.sender !== undefined && rs.sender !== sender;
+                if (!staleSender) {
+                    updatePushState(sessionId, state, modelName, effortLevel, permissionMode);
+                    updateRemoteSessionState(sessionId, state, modelName, effortLevel, permissionMode, sender);
+                    // Trigger sessions list broadcast so clients get fresh state
+                    core.maybeBroadcastSessionsList();
+                }
+            }
+            return true; // consumed
+        }
+        if (msg.type === 'session_event_up') {
+            // A focused remote session's event rode back up its push socket
+            // (same-socket reverse control). Ownership check: only the session's
+            // registered sender may speak for it — a stale or foreign socket's
+            // events are dropped.
+            const { sessionId, event } = msg;
+            if (sessionId && event?.type && getRemoteSession(sessionId)?.sender === sender) {
+                focusRelay.ingestReverseEvent(sessionId, event);
+            }
+            return true; // consumed
+        }
+        return false;
+    };
+}
+//# sourceMappingURL=session-push-channel.js.map

package/dist/session-push-channel.js.map

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

package/dist/session-registry.d.ts

@@ -47,6 +47,9 @@ export interface SessionEntry {
     tty?: string;
     parentTty?: string;
     startedAt: string;
+    /** Explicit deck/tab sort override (default 0); lower sorts first. Set via
+     *  `agentdeck <agent> --weight <n>`. See shared sortSessions. */
+    weight?: number;
 }
 /** Check if a PID is alive */
 export declare function isProcessAlive(pid: number): boolean;
@@ -120,6 +123,7 @@ export declare function probeDaemonHealth(port: number): Promise<{
     mode?: string;
     pid?: number;
     isSwift?: boolean;
+    sameSocketControl?: boolean;
 } | null>;
 /**
  * Sweep the daemon port window for live daemons that file-based discovery
@@ -183,5 +187,127 @@ export declare function findDaemonPort(): number | null;
 export declare function findDaemonPortAsync(): Promise<{
     port: number;
     httpPort?: number;
+    sameSocketControl?: boolean;
 } | null>;
+/** True if a host string refers to this machine's loopback. */
+export declare function isLoopbackHost(host: string): boolean;
+/** Bracket bare IPv6 literals so they're valid in an http(s)/ws URL authority. */
+export declare function formatHostForUrl(host: string): string;
+/**
+ * Probe `/health` at an arbitrary host:port (not just 127.0.0.1). Returns the
+ * full health JSON (so callers can read `mode` and `pairingToken`) or null.
+ */
+export declare function probeHealthAt(host: string, port: number, timeoutMs?: number): Promise<Record<string, unknown> | null>;
+/** A resolved daemon endpoint, possibly on another machine. */
+export interface DaemonTarget {
+    host: string;
+    port: number;
+    /** Pairing token — required when `host` is not this machine. */
+    token?: string;
+    httpPort?: number;
+    /**
+     * Whether the daemon's `/health` advertises same-socket reverse control
+     * (`sameSocketControl: true`). The worker only sends `remoteAttach` in its
+     * push registration when the daemon can actually drive the session back down
+     * the socket — a daemon without the capability (e.g. the Swift App Store
+     * daemon) gets a plain local-style registration instead.
+     */
+    sameSocketControl?: boolean;
+}
+/** Parse a `host` or `host:port` (or `[v6]:port`) hint into host + port. */
+export declare function parseHostHint(hint: string): {
+    host: string;
+    port: number;
+};
+/**
+ * Injectable dependencies for {@link resolveDaemonTarget}. Production uses the
+ * real module functions; tests substitute fakes to assert the precedence and —
+ * critically — the opt-in gate, without touching the network. `warn` defaults
+ * to a once-per-key `logError` ({@link warnRemoteOnce}; keys are `host:port`,
+ * prefixed `local:` for the loopback branch — the only PTY-visible log
+ * primitive; this resolver re-runs on every `DaemonWsClient` reconnect
+ * backoff, so an unguarded warning would scribble over the agent TUI every
+ * ≤30s forever).
+ */
+export interface ResolveDaemonDeps {
+    findLocal: () => Promise<{
+        port: number;
+        httpPort?: number;
+        sameSocketControl?: boolean;
+    } | null>;
+    probeHealth: (host: string, port: number) => Promise<Record<string, unknown> | null>;
+    discover: () => Promise<Array<{
+        host: string;
+        port: number;
+        token?: string;
+        sameSocketControl?: boolean;
+    }>>;
+    warn: (key: string, message: string) => void;
+}
+/**
+ * Derive the remote-attach inputs from CLI flags + env — the single source that
+ * both `cli.ts` (pre-PTY "ignored" warning) and `index.ts` (target resolution)
+ * consume, so the two derivations cannot drift. `--remote-daemon` /
+ * `AGENTDECK_REMOTE_DAEMON=1` is THE opt-in; a host given without it
+ * (`ignoredHostHint`) is inert and the CLI warns before the PTY starts
+ * (post-PTY, stdout logging is swallowed).
+ */
+export declare function deriveRemoteAttachOpts(cliOpts: {
+    remoteDaemon?: boolean;
+    daemonHost?: string;
+}, env?: NodeJS.ProcessEnv): {
+    remote: boolean;
+    hostHint?: string;
+    ignoredHostHint: boolean;
+};
+/**
+ * Default `warn` dep: log a remote-attach warning at most once per key. The
+ * resolver re-runs on every reconnect backoff, and an unguarded warning would
+ * scribble over the agent TUI every few seconds forever.
+ * @internal Exported for tests only — the module-level Set has no reset, so
+ * tests must use keys unique to themselves.
+ */
+export declare function warnRemoteOnce(key: string, message: string): void;
+/**
+ * Resolve which daemon a session bridge should attach to, optionally on another
+ * machine. Precedence:
+ *   1. Local daemon (unchanged behavior — always preferred, never opt-in gated).
+ *   2. Explicit `hostHint` (cross-subnet / SSH where mDNS doesn't propagate).
+ *   3. mDNS browse on the LAN.
+ *
+ * OPT-IN INVARIANT (security boundary): `--remote-daemon` /
+ * `AGENTDECK_REMOTE_DAEMON=1` (`remote === true`) is THE opt-in switch, and it
+ * gates BOTH remote paths. `--daemon-host` / `AGENTDECK_DAEMON_HOST` only names
+ * the endpoint — without the switch it is ignored (the CLI warns pre-PTY).
+ * Nothing below the local check ever leaves the machine unless `remote === true`:
+ * with the switch absent the function returns local-or-null and the session
+ * stays local-only — byte-for-byte the pre-remote behavior.
+ *
+ * Within `remote === true`, EVERY accepted target must advertise the
+ * `sameSocketControl` capability — including a loopback one. An ssh -L
+ * forward of a remote daemon is indistinguishable from a genuine local
+ * daemon by IP, so the local-first step enforces the capability too rather
+ * than silently accepting a tunnel to a daemon that can never drive the
+ * session (plain registration: acked but unlistable/unfocusable):
+ *   - Capable local daemon ⇒ returned (a hostHint is NOT consulted — the
+ *     ordinary local-preferred behavior).
+ *   - Incapable local daemon + hostHint ⇒ fall through to the explicit-host
+ *     step: the user named a node, so probe THAT instead of dead-ending.
+ *   - Incapable local daemon, no hostHint ⇒ one-shot warning + null. No mDNS
+ *     fallthrough: a deliberately-built tunnel must not silently roam to
+ *     some other LAN daemon.
+ *   - An explicit host that is unreachable, not a daemon, or lacks the
+ *     capability returns null WITHOUT falling through to mDNS — the user
+ *     named a specific node and expects to hear about failure.
+ *   - mDNS selection is limited to daemons advertising `sameSocketControl`
+ *     (the discover step filters), so an unsupported daemon (e.g. Swift App
+ *     Store) is never selected as a remote target.
+ *
+ * Remote targets carry the daemon's advertised pairing `token`; local targets
+ * need none (the daemon treats same-machine connections as authenticated).
+ */
+export declare function resolveDaemonTarget(opts?: {
+    remote?: boolean;
+    hostHint?: string;
+}, deps?: Partial<ResolveDaemonDeps>): Promise<DaemonTarget | null>;
 //# sourceMappingURL=session-registry.d.ts.map

package/dist/session-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"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"}