diff --git a/packages/opencode/src/server/routes/instance/httpapi/handlers/pty.ts b/packages/opencode/src/server/routes/instance/httpapi/handlers/pty.ts
index 7b8395d809..369ca91d02 100644
--- a/packages/opencode/src/server/routes/instance/httpapi/handlers/pty.ts
+++ b/packages/opencode/src/server/routes/instance/httpapi/handlers/pty.ts
@@ -153,6 +153,12 @@ export const ptyConnectRoute = HttpRouter.use((router) =>
           return HttpServerResponse.empty()
         }
 
+        // No `pending[]`-style early-frame buffer (the legacy Hono handler had one).
+        // `request.upgrade` returns a Socket without running the WS handshake; the
+        // handshake fires inside `socket.runRaw` below, AFTER `pty.connect` resolves
+        // and the message callback is registered. The client therefore can't fire
+        // `open` and start sending until the listener is already wired. Don't move
+        // `runRaw` ahead of `pty.connect` without re-introducing a buffer.
         yield* socket
           .runRaw((message) => handlePtyInput(handler, message))
           .pipe(