Greptile Summary

This PR fixes a blank terminal regression (#1689) introduced in v0.4.0 by restructuring the guard in the WebSocket open message handler: the buffered history replay is now unconditional, while the terminalManager.subscribe() call retains the !subscriptions.has(id) guard to prevent double-delivery of live PTY events.

• mux-websocket.ts — moves the getBuffer send outside the !subscriptions.has(id) check and exports TerminalManager for unit testing; adds a detailed explanatory comment.
• mux-websocket.test.ts — adds eight new TerminalManager unit tests covering empty-buffer-on-fresh-open, data accumulation, PTY lifecycle (kill on last-subscriber-leave), fresh-PTY-on-re-open, and multi-subscriber retention.

Confidence Score: 5/5

Safe to merge — the change is a focused, single-file guard restructure with no new async paths or state mutations.

The buffer-send is moved exactly one block outward with no other behavioral changes. The subscribe guard remains intact to prevent double live-delivery. Node.js's single-threaded event loop means there is no window for data loss between the buffer read and the subscribe call. The mock's no-op onData disposable correctly mirrors how TerminalManager actually delivers data (one shared pty.onData handler fans out to terminal.subscribers, so the per-call disposable is never used in production either). Eight new tests pin every lifecycle variant the fix touches.

No files require special attention.

Sequence Diagram

sequenceDiagram
    participant C as Browser (MuxProvider)
    participant WS as WebSocket Handler
    participant TM as TerminalManager
    participant PTY as node-pty (tmux)

    C->>WS: "open {id, tmuxName}"
    WS->>TM: open(id, tmuxName)
    TM-->>PTY: spawn / attach (if no PTY)
    WS->>C: "{type:"opened"}"

    note over WS,TM: Buffer replay — always, unconditional
    WS->>TM: getBuffer(id)
    TM-->>WS: accumulated tmux output (may be "")
    alt buffer non-empty
        WS->>C: "{type:"data", data: buffer}"
    end

    note over WS,TM: Subscribe — guarded by !subscriptions.has(id)
    alt not yet subscribed on this connection
        WS->>TM: subscribe(id, callback)
        TM-->>WS: unsub()
        WS->>WS: subscriptions.set(id, unsub)
    end

    PTY-->>TM: onData(live chunk)
    TM-->>WS: callback(live chunk)
    WS->>C: "{type:"data", data: chunk}"

    C->>WS: close
    WS->>TM: unsub() for each subscription
    TM-->>PTY: pty.kill() (if last subscriber)

_{Reviews (1): Last reviewed commit: "fix(web): always replay terminal buffer ..." | Re-trigger Greptile}

Thanks for the catch — confirmed and fixed.

Root cause of the regression in this PR: my branch was based off a stale local `main` (`e94ff281`, May 1 15:45) that predates `b2cdf7ad` (the project-scoping commit, May 1 16:15). `b2cdf7ad` is not an ancestor of `e94ff281`, so the local `mux-websocket.ts` had zero `projectId` references when I made the edit. When the patch landed on real `upstream/main` (which has 35 `projectId` references), it stripped them.

Fix: rebased onto `upstream/main` and re-applied the change preserving:

• `terminalManager.getBuffer(id, projectId)`
• `bufferMsg` with `...(projectId && { projectId })`
• `subscriptions.has(subscriptionKey)` (not `subscriptions.has(id)`)

The PR diff is now exactly: move buffer-send out from under the `subscriptionKey` guard, keep the guard around `subscribe()` only — `projectId` plumbing untouched.

Also added a test that pins the project-scoping invariant so this can't regress: two sessions with the same id under different projects keep their PTY data isolated, and cross-project `getBuffer` lookups don't leak.

`pnpm --filter @aoagents/ao-web exec vitest run server/tests/mux-websocket.test.ts` — 18/18 pass.