crewly 1.6.0 → 1.6.2

package/dist/backend/backend/src/websocket/chat-v2.gateway.js

@@ -0,0 +1,401 @@
+/**
+ * ChatV2Gateway — native WebSocket gateway for the Phase 1 Chat MVP.
+ *
+ * Listens on `/ws/chat?channelId=X&token=Y&lastSeenSeq=N` and fans out
+ * wire-format frames to subscribers per Sam's tech spec §6 / the frontend
+ * contract implemented by Max in `packages/chat-ui/src/api/client.ts`.
+ *
+ * Wire contract this gateway must honor (enforced by co-located tests):
+ *  - Client→server: `{type:"ping",ts}` every 25s
+ *  - Server→client: `{type:"pong",ts}` echo within 10s
+ *  - Server→client: `{type:"message",payload:{channelId,message:MessageDTO}}`
+ *  - Server→client: `{type:"presence",payload:{agentSession,status,lastSeenAt?}}`
+ *  - Server→client: `{type:"error",code,message}` followed by close() on fatal
+ *
+ * This module is intentionally thin: it does not persist, does not dispatch
+ * to agents, and does not manage presence state. The controller/dispatcher
+ * call `broadcast()` after the service layer writes to SQLite, so the
+ * gateway's only job is routing frames to the right sockets.
+ *
+ * Upgrade-handoff pattern copied from `BrowserBridgeService.attach()` —
+ * Socket.IO's Engine.IO upgrade handler would otherwise corrupt frames on
+ * non-`/socket.io/` paths, so we intercept the `upgrade` event on the
+ * HTTP server and handle `/ws/chat` exclusively.
+ *
+ * @module websocket/chat-v2.gateway
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { ChatError, CHAT_ERROR_CODES } from '../services/chat-v2/types.js';
+import { LoggerService } from '../services/core/logger.service.js';
+/** Default WS mount path — matches the frontend `?${qs}` URL in client.ts. */
+export const CHAT_V2_WS_PATH = '/ws/chat';
+/**
+ * Always-accept token verifier used when `CREWLY_JWT_SECRET` is not
+ * configured. Returns the SAME `userId` that `requireAuth`'s dev
+ * fallback uses (`dev-user-001`) so that channels created via the
+ * REST API are owned by the same principal the WS client will verify
+ * as. Not for production — in production a JWT-verifying `verifyToken`
+ * function is passed to `ChatV2Gateway` instead.
+ */
+export const devAnonymousTokenVerifier = async () => ({
+    userId: 'dev-user-001',
+});
+/**
+ * A WebSocket gateway that fans chat events out to subscribers.
+ *
+ * Lifecycle:
+ *  1. `attach(httpServer)` — hooks the upgrade interceptor
+ *  2. `broadcast(channelId, event)` — called by controller after persist
+ *  3. `close()` — shutdown hook (graceful close all sockets)
+ *
+ * The gateway owns the WebSocketServer and the subscribers map. It never
+ * reaches into the service layer on its own — all domain data arrives via
+ * `broadcast()` from callers who have already persisted.
+ */
+export class ChatV2Gateway {
+    service;
+    verifyToken;
+    path;
+    webSocketServerImpl;
+    now;
+    logger;
+    wss = null;
+    attached = false;
+    /** channelId → set of subscribers listening on that channel. */
+    subscribers = new Map();
+    constructor(options) {
+        this.service = options.service;
+        this.verifyToken = options.verifyToken;
+        this.path = options.path ?? CHAT_V2_WS_PATH;
+        this.webSocketServerImpl = options.webSocketServerImpl ?? WebSocketServer;
+        this.now = options.now ?? Date.now;
+        this.logger = LoggerService.getInstance().createComponentLogger('ChatV2Gateway');
+    }
+    /**
+     * Mount the gateway on an HTTP server.
+     *
+     * Uses `noServer:true` + an `httpServer.emit` override identical to
+     * `BrowserBridgeService.attach()` — the override exclusively handles
+     * upgrades whose pathname matches `this.path`, so Engine.IO never sees
+     * them and cannot corrupt the frames.
+     *
+     * @param httpServer - Shared Node HTTP server instance
+     */
+    attach(httpServer) {
+        if (this.attached) {
+            this.logger.warn('chat-v2 WS gateway already attached');
+            return;
+        }
+        this.attached = true;
+        this.wss = new this.webSocketServerImpl({
+            noServer: true,
+            perMessageDeflate: false,
+        });
+        // Two-part installation:
+        //   1. Register an explicit `upgrade` listener. This guarantees the
+        //      event is wired even when we're the ONLY listener (tests, dev
+        //      standalone — no Socket.IO). In production Socket.IO ALSO
+        //      listens; both fire, but step 2 keeps them from colliding.
+        //   2. Override `httpServer.emit` so that a `/ws/chat` upgrade event
+        //      is handled exclusively, with no other listeners (Engine.IO's
+        //      in particular) seeing it. Without this, Engine.IO's 1s
+        //      socket.end() timer and compression bits would corrupt our
+        //      frames. Same pattern as `BrowserBridgeService.attach()`.
+        const pathMatches = (req) => {
+            const url = req.url || '';
+            const host = req.headers.host || 'localhost';
+            try {
+                return new URL(url, `http://${host}`).pathname === this.path;
+            }
+            catch {
+                return false;
+            }
+        };
+        const performUpgrade = (request, socket, head) => {
+            if (!pathMatches(request))
+                return;
+            this.wss.handleUpgrade(request, socket, head, (ws, req) => {
+                this.wss.emit('connection', ws, req);
+            });
+        };
+        // Register the listener so the 'upgrade' event fires at all (Node's
+        // HTTP server routes upgrade requests to the regular request handler
+        // when no 'upgrade' listener is registered).
+        httpServer.on('upgrade', performUpgrade);
+        const originalEmit = httpServer.emit.bind(httpServer);
+        httpServer.emit = (event, ...args) => {
+            if (event === 'upgrade') {
+                const request = args[0];
+                if (pathMatches(request)) {
+                    // Run our upgrade handler exclusively — skip every other
+                    // listener (Engine.IO's especially) so their post-hooks cannot
+                    // corrupt our socket.
+                    performUpgrade(args[0], args[1], args[2]);
+                    return true;
+                }
+            }
+            return originalEmit(event, ...args);
+        };
+        this.wss.on('connection', (ws, req) => {
+            // ts-jest in CI sometimes resolves req.url as undefined when the
+            // upgrade interceptor is exercised from a test — guard both.
+            void this.handleConnection(ws, req);
+        });
+        this.wss.on('error', (err) => {
+            this.logger.error('WS server error', { error: err.message });
+        });
+        this.logger.info('chat-v2 WS gateway attached', { path: this.path });
+    }
+    /**
+     * Broadcast a wire event to every subscriber on `channelId`.
+     *
+     * Safe to call synchronously from inside a DB transaction — sends are
+     * queued on the underlying socket and do not block.
+     *
+     * @param channelId - Target channel
+     * @param event - Wire frame to push
+     */
+    broadcast(channelId, event) {
+        const set = this.subscribers.get(channelId);
+        if (!set || set.size === 0)
+            return;
+        const frame = JSON.stringify(event);
+        for (const sub of set) {
+            if (sub.ws.readyState !== WebSocket.OPEN)
+                continue;
+            try {
+                sub.ws.send(frame);
+            }
+            catch (err) {
+                this.logger.warn('chat-v2 ws send failed', {
+                    channelId,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    /**
+     * Count of currently-open subscribers for a channel. Exposed for tests
+     * and future observability dashboards.
+     */
+    subscriberCount(channelId) {
+        return this.subscribers.get(channelId)?.size ?? 0;
+    }
+    /** Total open sockets across all channels. Observability helper. */
+    totalSubscribers() {
+        let n = 0;
+        for (const set of this.subscribers.values())
+            n += set.size;
+        return n;
+    }
+    /**
+     * Gracefully close all sockets. Called during shutdown.
+     */
+    async close() {
+        if (!this.wss)
+            return;
+        for (const set of this.subscribers.values()) {
+            for (const sub of set) {
+                try {
+                    sub.ws.close(1001, 'server shutdown');
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        this.subscribers.clear();
+        await new Promise((resolve) => {
+            this.wss.close(() => resolve());
+        });
+        this.wss = null;
+    }
+    // -------------------------------------------------------------------------
+    // Connection lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Handle a freshly-upgraded socket: parse query string, verify token,
+     * authorize against the channel, and register the subscriber.
+     *
+     * On any failure we send a single `{type:"error",...}` frame and close
+     * with a 1008 (policy violation) code — matching the frontend's
+     * "fatal, stop reconnecting" contract.
+     */
+    async handleConnection(ws, req) {
+        const host = req.headers.host || 'localhost';
+        let parsed;
+        try {
+            parsed = new URL(req.url ?? '', `http://${host}`);
+        }
+        catch {
+            this.sendErrorAndClose(ws, 'bad_request', 'malformed URL');
+            return;
+        }
+        const channelId = parsed.searchParams.get('channelId');
+        const token = parsed.searchParams.get('token');
+        // lastSeenSeq is accepted but not yet acted on (Phase 1.5 replay).
+        // Parsing validates that callers send a number if they send it at all.
+        const lastSeenSeqRaw = parsed.searchParams.get('lastSeenSeq');
+        if (lastSeenSeqRaw !== null && !/^\d+$/.test(lastSeenSeqRaw)) {
+            this.sendErrorAndClose(ws, 'bad_request', 'lastSeenSeq must be a non-negative integer');
+            return;
+        }
+        if (!channelId) {
+            this.sendErrorAndClose(ws, 'bad_request', 'channelId is required');
+            return;
+        }
+        let identity;
+        try {
+            identity = await this.verifyToken(token);
+        }
+        catch (err) {
+            this.logger.warn('chat-v2 ws token verify threw', {
+                err: err instanceof Error ? err.message : String(err),
+            });
+            this.sendErrorAndClose(ws, 'unauthorized', 'token verification failed');
+            return;
+        }
+        if (!identity) {
+            this.sendErrorAndClose(ws, 'unauthorized', 'invalid token');
+            return;
+        }
+        // Authorize: the channel must exist AND be owned by this user (or —
+        // in a later iteration — be readable by the agent identified here).
+        try {
+            this.service.getChannel(channelId, { userId: identity.userId, source: 'oss' });
+        }
+        catch (err) {
+            if (err instanceof ChatError && err.code === CHAT_ERROR_CODES.CHANNEL_NOT_FOUND) {
+                // 404 leaks less than 403 for ownership checks (consistent with §7.2)
+                this.sendErrorAndClose(ws, 'channel_not_found', 'channel not found');
+                return;
+            }
+            this.sendErrorAndClose(ws, 'internal_error', 'authorization failed');
+            return;
+        }
+        const subscriber = {
+            ws,
+            channelId,
+            userId: identity.userId,
+            connectedAt: this.now(),
+        };
+        this.registerSubscriber(subscriber);
+        ws.on('message', (data) => this.handleMessage(subscriber, data));
+        ws.on('close', () => this.unregisterSubscriber(subscriber));
+        ws.on('error', (err) => {
+            this.logger.warn('chat-v2 ws socket error', {
+                channelId: subscriber.channelId,
+                err: err.message,
+            });
+        });
+        this.logger.debug('chat-v2 ws connection established', {
+            channelId,
+            userId: identity.userId,
+            total: this.totalSubscribers(),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Message routing
+    // -------------------------------------------------------------------------
+    /**
+     * Handle a frame from the client.
+     *
+     * Phase 1 only understands `{type:"ping",ts}`; any other shape is
+     * silently dropped (forward-compat with future client-origin frames).
+     */
+    handleMessage(sub, raw) {
+        let parsed = null;
+        try {
+            const text = typeof raw === 'string' ? raw : Buffer.isBuffer(raw) ? raw.toString('utf-8') : String(raw);
+            const obj = JSON.parse(text);
+            if (obj && obj.type === 'ping') {
+                const ts = typeof obj.ts === 'number' ? obj.ts : this.now();
+                parsed = { type: 'ping', ts };
+            }
+        }
+        catch {
+            // malformed frame — drop
+            return;
+        }
+        if (!parsed)
+            return;
+        // Echo pong with the client's own ts — the client uses the round-trip
+        // for its 10s timeout, not strict clock agreement.
+        const pong = { type: 'pong', ts: parsed.ts };
+        if (sub.ws.readyState === WebSocket.OPEN) {
+            try {
+                sub.ws.send(JSON.stringify(pong));
+            }
+            catch {
+                // ignore — the socket will close and the close handler cleans up
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Subscriber bookkeeping
+    // -------------------------------------------------------------------------
+    registerSubscriber(sub) {
+        let set = this.subscribers.get(sub.channelId);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(sub.channelId, set);
+        }
+        set.add(sub);
+    }
+    unregisterSubscriber(sub) {
+        const set = this.subscribers.get(sub.channelId);
+        if (!set)
+            return;
+        set.delete(sub);
+        if (set.size === 0)
+            this.subscribers.delete(sub.channelId);
+    }
+    /**
+     * Send an error frame then close with 1008. Used for all pre-subscribe
+     * rejections (auth, malformed URL, missing channelId, not-found).
+     */
+    sendErrorAndClose(ws, code, message) {
+        try {
+            if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                ws.send(JSON.stringify({ type: 'error', code, message }));
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            ws.close(1008, code);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Channel presence broadcast helper (future — not wired in Phase 1)
+// ---------------------------------------------------------------------------
+/**
+ * Build a presence wire frame. Placed here so both the gateway's tests and
+ * future presence emitters use the same shape.
+ *
+ * @param agentSession - The agent whose presence changed
+ * @param status - New status
+ * @param lastSeenAt - Optional last-seen timestamp (ms)
+ */
+export function buildPresenceEvent(agentSession, status, lastSeenAt) {
+    return {
+        type: 'presence',
+        payload: { agentSession, status, lastSeenAt: lastSeenAt ?? null },
+    };
+}
+/**
+ * Build a message wire frame from a DTO. Used by both the controller (on
+ * HTTP persist) and the dispatcher (on agent reply).
+ */
+export function buildMessageEvent(channelId, message) {
+    return {
+        type: 'message',
+        payload: { channelId, message },
+    };
+}
+//# sourceMappingURL=chat-v2.gateway.js.map

package/dist/backend/backend/src/websocket/chat-v2.gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-v2.gateway.js","sourceRoot":"","sources":["../../../../../backend/src/websocket/chat-v2.gateway.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/websocket/terminal.gateway.d.ts

@@ -28,6 +28,14 @@ export declare class TerminalGateway {
     private sessionSubscriptions;
     /** Set of sessions with persistent monitoring (not stopped on client disconnect) */
     private persistentMonitoringSessions;
+    /**
+     * Pending retry timers for eager monitoring attempts that fired before the
+     * PTY session was registered in the SessionBackend.
+     *
+     * Keyed by session name. Cleared on first successful attach, on stop, and
+     * on destroy so a backoff schedule never leaks a timer past the gateway.
+     */
+    private pendingMonitoringRetries;
     /** Current active chat conversation ID for orchestrator responses */
     private activeConversationId;
     /**
@@ -106,15 +114,42 @@ export declare class TerminalGateway {
     private stopPtyStreaming;
     /**
      * Start persistent monitoring for the orchestrator session.
-     * This ensures chat responses are captured even when no WebSocket clients are viewing the terminal.
+     *
+     * Ensures chat responses are captured even when no WebSocket clients are
+     * viewing the terminal. If the PTY session is not yet registered in the
+     * SessionBackend (e.g. eager call from boot fires before
+     * createAgentSession's backend registration completes), schedules bounded
+     * retries on the {@link TERMINAL_GATEWAY_CONSTANTS.MONITORING_RETRY_BACKOFFS_MS}
+     * backoff schedule. Persistent flag stays set across retries so a parallel
+     * subscriber path doesn't bypass eventual attachment.
      *
      * @param sessionName - The orchestrator session name to monitor
-     * @returns True if monitoring started successfully
+     * @returns True if monitoring started synchronously on first attempt; false
+     *          if a retry was scheduled (caller-visible failure is reserved for
+     *          terminal failure after all retries, surfaced via ERROR log only).
      */
     startOrchestratorChatMonitoring(sessionName: string): boolean;
+    /**
+     * Schedule the next bounded retry attempt to attach orchestrator monitoring.
+     *
+     * @param sessionName - Session name being monitored
+     * @param attemptIndex - 0-based index into MONITORING_RETRY_BACKOFFS_MS
+     */
+    private scheduleMonitoringRetry;
+    /**
+     * Clear any pending monitoring retry timer for a session.
+     *
+     * Idempotent — safe to call when no retry is queued.
+     *
+     * @param sessionName - Session name whose retry should be cleared
+     */
+    private clearPendingMonitoringRetry;
     /**
      * Stop persistent monitoring for the orchestrator session.
      *
+     * Cancels any in-flight retry schedule so a stop mid-backoff doesn't leak
+     * a timer that later attaches to a session the caller already gave up on.
+     *
      * @param sessionName - The orchestrator session name
      */
     stopOrchestratorChatMonitoring(sessionName: string): void;

package/dist/backend/backend/src/websocket/terminal.gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal.gateway.d.ts","sourceRoot":"","sources":["../../../../../backend/src/websocket/terminal.gateway.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal.gateway.d.ts","sourceRoot":"","sources":["../../../../../backend/src/websocket/terminal.gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAY7D;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB,CAAuC;IAE/D,iEAAiE;IACjE,OAAO,CAAC,oBAAoB,CAAsC;IAElE,oFAAoF;IACpF,OAAO,CAAC,4BAA4B,CAA0B;IAE9D;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB,CAA0C;IAE1E,qEAAqE;IACrE,OAAO,CAAC,oBAAoB,CAAuB;IAEnD;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAqB;IAE7C;;;OAGG;IACH,OAAO,CAAC,0BAA0B,CAAqB;IAEvD;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAuE;IAEnG;;;;OAIG;gBACS,EAAE,EAAE,cAAc;IAQ9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+C1B;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IA6BlC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIhD;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAiD7D;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAiEzB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;;;;;;;;;;OAeG;IACH,+BAA+B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAoC7D;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAwD/B;;;;;;OAMG;IACH,OAAO,CAAC,2BAA2B;IAQnC;;;;;;;OAOG;IACH,8BAA8B,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMzD;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAKlC;;;;;OAKG;IACH,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IA8BjE;;;;;;OAMG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4DlF;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;;OAKG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKtC;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKxC;;;;;OAKG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIxC;;;;OAIG;IACH,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI5D;;;;OAIG;IACH,uBAAuB,IAAI,MAAM,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;;OAKG;YACW,wBAAwB;IA+FtC;;;;OAIG;IACH,kBAAkB,IAAI;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACtB;IAeD;;;;OAIG;IACH,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOnD;;;;;OAKG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,SAAS,GAAG,OAAgB,GAAG,IAAI;IAQ/F;;;;OAIG;IACH,2BAA2B,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI;IAQ5D;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;IAQpD;;;;OAIG;IACH,4BAA4B,CAAC,SAAS,EAAE;QACvC,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAQR;;;;OAIG;IACH,4BAA4B,CAAC,WAAW,EAAE;QACzC,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAQR;;;;OAIG;IACH,qBAAqB,CAAC,YAAY,EAAE,OAAO,GAAG,IAAI;IAQlD;;OAEG;IACH,OAAO,IAAI,IAAI;CA0Bf;AAQD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/backend/backend/src/websocket/terminal.gateway.js

@@ -11,6 +11,7 @@
  */
 import { LoggerService } from '../services/core/logger.service.js';
 import { getSessionBackendSync, } from '../services/session/index.js';
+import { TERMINAL_GATEWAY_CONSTANTS } from '../constants.js';
 import { InProcessLogBuffer } from '../services/agent/crewly-agent/in-process-log-buffer.js';
 /**
  * Terminal Gateway class for WebSocket-based terminal streaming.
@@ -30,6 +31,14 @@ export class TerminalGateway {
     sessionSubscriptions = new Map();
     /** Set of sessions with persistent monitoring (not stopped on client disconnect) */
     persistentMonitoringSessions = new Set();
+    /**
+     * Pending retry timers for eager monitoring attempts that fired before the
+     * PTY session was registered in the SessionBackend.
+     *
+     * Keyed by session name. Cleared on first successful attach, on stop, and
+     * on destroy so a backoff schedule never leaks a timer past the gateway.
+     */
+    pendingMonitoringRetries = new Map();
     /** Current active chat conversation ID for orchestrator responses */
     activeConversationId = null;
     /**
@@ -297,13 +306,25 @@ export class TerminalGateway {
     }
     /**
      * Start persistent monitoring for the orchestrator session.
-     * This ensures chat responses are captured even when no WebSocket clients are viewing the terminal.
+     *
+     * Ensures chat responses are captured even when no WebSocket clients are
+     * viewing the terminal. If the PTY session is not yet registered in the
+     * SessionBackend (e.g. eager call from boot fires before
+     * createAgentSession's backend registration completes), schedules bounded
+     * retries on the {@link TERMINAL_GATEWAY_CONSTANTS.MONITORING_RETRY_BACKOFFS_MS}
+     * backoff schedule. Persistent flag stays set across retries so a parallel
+     * subscriber path doesn't bypass eventual attachment.
      *
      * @param sessionName - The orchestrator session name to monitor
-     * @returns True if monitoring started successfully
+     * @returns True if monitoring started synchronously on first attempt; false
+     *          if a retry was scheduled (caller-visible failure is reserved for
+     *          terminal failure after all retries, surfaced via ERROR log only).
      */
     startOrchestratorChatMonitoring(sessionName) {
         this.logger.info('Starting persistent orchestrator chat monitoring', { sessionName });
+        // Cancel any in-flight retry from a previous start call so we don't
+        // stack two backoff schedules on the same session.
+        this.clearPendingMonitoringRetry(sessionName);
         // Force cleanup any stale subscription from a previous session.
         // When the orchestrator is restarted, the old PTY session is destroyed but
         // the subscription entry may still exist pointing to the dead session.
@@ -317,19 +338,92 @@ export class TerminalGateway {
         // Mark session as persistent so it won't be stopped when clients disconnect
         this.persistentMonitoringSessions.add(sessionName);
         const started = this.startPtyStreaming(sessionName);
-        if (!started) {
-            this.logger.warn('Failed to start orchestrator chat monitoring', { sessionName });
+        if (started) {
+            return true;
+        }
+        // Backend hasn't registered the session yet (race with createAgentSession).
+        // Keep persistentMonitoringSessions flagged and schedule bounded retries.
+        this.logger.warn('PTY not ready for orchestrator chat monitoring, scheduling retries', { sessionName, schedule: TERMINAL_GATEWAY_CONSTANTS.MONITORING_RETRY_BACKOFFS_MS });
+        this.scheduleMonitoringRetry(sessionName, 0);
+        return false;
+    }
+    /**
+     * Schedule the next bounded retry attempt to attach orchestrator monitoring.
+     *
+     * @param sessionName - Session name being monitored
+     * @param attemptIndex - 0-based index into MONITORING_RETRY_BACKOFFS_MS
+     */
+    scheduleMonitoringRetry(sessionName, attemptIndex) {
+        const schedule = TERMINAL_GATEWAY_CONSTANTS.MONITORING_RETRY_BACKOFFS_MS;
+        if (attemptIndex >= schedule.length) {
+            // Exhausted retries — log diagnostics and give up. Drop the
+            // persistent flag so a subsequent subscriber-driven attach can
+            // still proceed via the normal subscribeToSession path.
+            const backend = getSessionBackendSync();
+            this.logger.error('Orchestrator chat monitoring failed after all retries — orc output will not stream until a client subscribes', {
+                sessionName,
+                attempts: schedule.length,
+                availableSessions: backend?.listSessions() ?? [],
+            });
             this.persistentMonitoringSessions.delete(sessionName);
+            this.pendingMonitoringRetries.delete(sessionName);
+            return;
+        }
+        const delayMs = schedule[attemptIndex];
+        const timer = setTimeout(() => {
+            this.pendingMonitoringRetries.delete(sessionName);
+            // Stop guard: the persistent flag is cleared by
+            // stopOrchestratorChatMonitoring. If it's gone, abandon retry.
+            if (!this.persistentMonitoringSessions.has(sessionName)) {
+                this.logger.debug('Monitoring retry abandoned — persistent flag cleared', {
+                    sessionName,
+                    attemptIndex,
+                });
+                return;
+            }
+            const started = this.startPtyStreaming(sessionName);
+            if (started) {
+                this.logger.info('Orchestrator chat monitoring attached on retry', {
+                    sessionName,
+                    attemptIndex: attemptIndex + 1,
+                    delayMs,
+                });
+                return;
+            }
+            this.scheduleMonitoringRetry(sessionName, attemptIndex + 1);
+        }, delayMs);
+        // Allow the process to exit even if a retry is still pending.
+        // Without unref, lingering timers keep node alive past graceful shutdown.
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+        this.pendingMonitoringRetries.set(sessionName, timer);
+    }
+    /**
+     * Clear any pending monitoring retry timer for a session.
+     *
+     * Idempotent — safe to call when no retry is queued.
+     *
+     * @param sessionName - Session name whose retry should be cleared
+     */
+    clearPendingMonitoringRetry(sessionName) {
+        const timer = this.pendingMonitoringRetries.get(sessionName);
+        if (timer) {
+            clearTimeout(timer);
+            this.pendingMonitoringRetries.delete(sessionName);
         }
-        return started;
     }
     /**
      * Stop persistent monitoring for the orchestrator session.
      *
+     * Cancels any in-flight retry schedule so a stop mid-backoff doesn't leak
+     * a timer that later attaches to a session the caller already gave up on.
+     *
      * @param sessionName - The orchestrator session name
      */
     stopOrchestratorChatMonitoring(sessionName) {
         this.logger.info('Stopping persistent orchestrator chat monitoring', { sessionName });
+        this.clearPendingMonitoringRetry(sessionName);
         this.stopPtyStreaming(sessionName, true);
     }
     /**
@@ -778,6 +872,13 @@ export class TerminalGateway {
      * Destroy the gateway and clean up all subscriptions.
      */
     destroy() {
+        // Cancel any pending monitoring retries before tearing down.
+        // Otherwise a queued retry could fire after destroy and attach
+        // a listener to a session whose owner has gone away.
+        for (const timer of this.pendingMonitoringRetries.values()) {
+            clearTimeout(timer);
+        }
+        this.pendingMonitoringRetries.clear();
         // Unsubscribe from all PTY sessions
         for (const unsubscribe of this.sessionSubscriptions.values()) {
             unsubscribe();