feat: deep-link support (PID navigation + focus existing tab)

[jesse23]

What

Implements the three deep-link features from docs/specs/deep-link.md, enabling third-party tools (e.g. Vibe Island) to integrate with webtty with no changes on their side.

Feature	Description
Focus existing tab	On /s/<id> load, client posts a focus-request on BroadcastChannel('webtty:focus:<sessionId>'). If an existing tab acks within 200ms, the new tab shows a fallback UI instead of mounting a second terminal to the same PTY.
PID in session API	GET /api/sessions now includes pid: number | null per session — null before the first WebSocket connection spawns the PTY.
PID-based navigation	GET /p/<pid> resolves the OS PTY PID to a session and issues 302 Location: /s/<id>. Returns 404 for unknown or non-integer PIDs.

Integration surface for external tools:

Action	How
Discover running webtty	GET http://127.0.0.1:2346/api/sessions
List sessions with PIDs	Same endpoint — returns [{ id, createdAt, connected, pid }]
Jump by session ID	open http://127.0.0.1:2346/s/<id>
Jump by PTY PID	open http://127.0.0.1:2346/p/<pid>

Changes

File	What
src/pty/types.ts	Add pid: number to PtyProcess interface
src/pty/node-pty.d.ts	Declare pid on IPty
src/pty/bun.ts	Expose proc.pid
src/pty/node.ts	Expose ptyProc.pid
src/server/session.ts	Include pid in sessionToJson output
src/server/routes.ts	Add GET /p/:pid handler
src/client/index.ts	BroadcastChannel focus handshake
docs/specs/deep-link.md	Mark all features ✅; correct /p/<pid> behaviour to 302

Manual test steps

bun run build && bunx webtty

Focus existing tab

1. Open http://127.0.0.1:2346/s/main in a browser tab — terminal loads normally.
2. Open the same URL in a second tab.
3. The second tab should show Session already open in another tab. (no terminal mounts).
4. The first tab should come to the foreground (window.focus()).

PID in session API

1. With a session open and a terminal connected, run:

   curl http://127.0.0.1:2346/api/sessions

2. Response should include "pid": <number> (not null) for connected sessions.
3. Create a session via POST /api/sessions without connecting a WS — pid should be null.

PID-based navigation

1. Note the pid from the step above (e.g. 12345).
2. Run:

   open http://127.0.0.1:2346/p/12345

   Or with curl (manual redirect):

   curl -v http://127.0.0.1:2346/p/12345

3. Should redirect 302 Location: /s/main and land on the terminal page.
4. Try an unknown PID (/p/99999) — should return 404.

[Copilot]

Pull request overview

Adds deep-link integration features to webtty so external tools can discover sessions, map PTY PIDs to sessions, and navigate/focus appropriately without requiring tool-side changes.

Changes:

• Expose PTY pid through PTY backends → sessions → GET /api/sessions (pid: number | null).
• Add GET /p/<pid> route that resolves a PTY PID to a session and redirects to /s/<id>.
• Implement a client-side BroadcastChannel “focus existing tab” handshake to avoid mounting duplicate terminals for the same session.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/server/websocket.test.ts	Adds coverage ensuring /p/:pid redirects after a PTY is spawned via WS.
src/server/session.ts	Extends sessionToJson output to include pid (or null).
src/server/session.test.ts	Adds unit tests for pid serialization behavior.
src/server/routes.ts	Implements GET /p/<pid> PID-to-session redirect logic.
src/server/routes.test.ts	Adds route tests for /api/sessions pid presence and /p/:pid 404 cases.
src/pty/types.ts	Extends PtyProcess interface with pid: number.
src/pty/node.ts	Surfaces ptyProc.pid via the PtyProcess abstraction.
src/pty/node-pty.d.ts	Updates local node-pty shim typing to include IPty.pid.
src/pty/bun.ts	Surfaces proc.pid via the PtyProcess abstraction.
src/client/index.ts	Adds BroadcastChannel focus handshake and fallback UI for secondary tabs.
docs/specs/deep-link.md	Documents the deep-link behaviors and third-party integration surface.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.