crewly 1.6.1 → 1.6.2

package/dist/backend/backend/src/websocket/chat-v2.gateway.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 type { Server as HttpServer } from 'http';
+import { WebSocketServer, WebSocket } from 'ws';
+import type { ChatV2Service } from '../services/chat-v2/chat-v2.service.js';
+import type { ChatAgentPresenceStatus, ChatChannelDTO, ChatMessageDTO } from '../services/chat-v2/types.js';
+/** Server→client wire frame. Discriminated by `type`. */
+export type ChatWireEvent = {
+    type: 'message';
+    payload: {
+        channelId: string;
+        message: ChatMessageDTO;
+    };
+} | {
+    type: 'presence';
+    payload: {
+        agentSession: string;
+        status: ChatAgentPresenceStatus;
+        lastSeenAt?: number | null;
+    };
+} | {
+    type: 'pong';
+    ts: number;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
+/** Client→server wire frame (Phase 1 only has `ping`). */
+export interface ChatClientFrame {
+    type: 'ping';
+    ts: number;
+}
+/**
+ * Pluggable auth for the WS handshake. Must resolve the `?token=` query
+ * parameter into a userId, or throw to reject the connection.
+ *
+ * In production this verifies the OSS session JWT. In dev (no secret
+ * configured) `DevTokenVerifier` allows any token (or none) and returns a
+ * static userId — sufficient for localhost tests.
+ */
+export interface ChatWsTokenVerifier {
+    (token: string | null): Promise<{
+        userId: string;
+    } | null>;
+}
+/** Constructor options for {@link ChatV2Gateway}. */
+export interface ChatV2GatewayOptions {
+    service: ChatV2Service;
+    verifyToken: ChatWsTokenVerifier;
+    /** Mount path on the HTTP server. Defaults to `/ws/chat`. */
+    path?: string;
+    /** Optional WebSocketServer override for tests. */
+    webSocketServerImpl?: typeof WebSocketServer;
+    /** Optional clock override (tests). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Default WS mount path — matches the frontend `?${qs}` URL in client.ts. */
+export declare 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 declare const devAnonymousTokenVerifier: ChatWsTokenVerifier;
+/**
+ * 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 declare class ChatV2Gateway {
+    private readonly service;
+    private readonly verifyToken;
+    private readonly path;
+    private readonly webSocketServerImpl;
+    private readonly now;
+    private readonly logger;
+    private wss;
+    private attached;
+    /** channelId → set of subscribers listening on that channel. */
+    private readonly subscribers;
+    constructor(options: ChatV2GatewayOptions);
+    /**
+     * 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: HttpServer): void;
+    /**
+     * 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: string, event: ChatWireEvent): void;
+    /**
+     * Count of currently-open subscribers for a channel. Exposed for tests
+     * and future observability dashboards.
+     */
+    subscriberCount(channelId: string): number;
+    /** Total open sockets across all channels. Observability helper. */
+    totalSubscribers(): number;
+    /**
+     * Gracefully close all sockets. Called during shutdown.
+     */
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    handleConnection(ws: WebSocket, req: {
+        url?: string;
+        headers: Record<string, string | undefined>;
+    }): Promise<void>;
+    /**
+     * 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).
+     */
+    private handleMessage;
+    private registerSubscriber;
+    private unregisterSubscriber;
+    /**
+     * Send an error frame then close with 1008. Used for all pre-subscribe
+     * rejections (auth, malformed URL, missing channelId, not-found).
+     */
+    private sendErrorAndClose;
+}
+/**
+ * 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 declare function buildPresenceEvent(agentSession: string, status: ChatAgentPresenceStatus, lastSeenAt?: number | null): Extract<ChatWireEvent, {
+    type: 'presence';
+}>;
+/**
+ * Build a message wire frame from a DTO. Used by both the controller (on
+ * HTTP persist) and the dispatcher (on agent reply).
+ */
+export declare function buildMessageEvent(channelId: string, message: ChatMessageDTO): Extract<ChatWireEvent, {
+    type: 'message';
+}>;
+export type { ChatChannelDTO };
+//# sourceMappingURL=chat-v2.gateway.d.ts.map

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

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

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;