Session IDs and admin controls for browser terminals (attach, drop, TTL)

Direct answer

A stable session ID makes a browser terminal persistent. The server must treat session_id as the key for the session lifecycle, buffers, and metadata; the client must reuse the same session_id on reconnect; and the system must expose a minimal admin surface to list, drop, and expire sessions so you do not accumulate invisible long-lived shells.

Mechanism (what “stable” means)

1) IDs are stable across reconnects

“Stable” means: the UI can disconnect and later reconnect to the same terminal session without guessing.

Practical sources of stability:

• deterministic from UI state (window id + tab id)
• explicit “new session” action creates a new ID
• the user can re-open a known session from a sessions list

Anti-patterns:

• random UUID every time you open the page
• tying session identity to a single connection

2) Attach semantics are explicit

Define the policy when a second client connects to the same session_id:

• single-attach (recommended baseline): reject the second attach
• handoff: new attach closes old connection and takes over
• multi-attach: allow multiple clients (harder; inputs can collide)

Phone-first operator tools usually want single-attach or handoff, not multi-attach.

3) Metadata exists and drives cleanup

At minimum, track:

• created_at
• last_seen (updated on attach, input, or heartbeat)
• bytes_buffered (or chunk count)
• optional: active_client boolean

This metadata enables TTL reaping and basic “what is stuck?” reasoning.

4) TTL reaping is not optional

Assume sessions will be abandoned. Implement a TTL policy:

• if now - last_seen > TTL -> terminate session and delete buffers
• TTL is a safety cap, not a UI feature

Without TTL, “persistent” becomes “leaking.”

5) Admin surface: list + drop

A minimal admin surface prevents operational dead ends:

• list sessions + last_seen + size
• drop a session (terminate the process, delete buffers)
• optionally “drop all” (gated)

This is not “product UI.” It is an operator escape hatch.

Common failure modes

Failure mode: “IDs drift and reconnect attaches to nothing”

Symptom: reconnect creates a new session; the old one is lost.

Root cause: IDs are generated per page load.

Fix: deterministic IDs or explicit session list; store in local state.

Failure mode: “Two clients fight over one session”

Symptom: interleaved keystrokes; corrupted state.

Root cause: multi-attach without input arbitration.

Fix: enforce single-attach or handoff.

Failure mode: “Sessions accumulate and consume resources”

Symptom: you discover dozens of shells; the box runs hot.

Root cause: no TTL and no drop control.

Fix: TTL + admin drop + limits per user/token.

How to verify

1. Reconnect stability

   • Disconnect and reconnect to the same session_id.
   • Expected: same session, buffer continuity.

2. Attach policy

   • Attempt to attach from two browsers.
   • Expected: enforced policy (reject or handoff), no silent multi-attach.

3. TTL enforcement

   • Let a session go idle past TTL.
   • Expected: session is reaped; reconnect yields “expired.”

4. Drop

   • Drop a stuck session from admin surface.
   • Expected: session terminated; resources released; session disappears from list.

Link up (pillar)

• Phone Terminal Codex

Read next (sibling)

• Terminal session streaming: minimal message shape

Scope boundary

This note covers session identity and operational controls. It does not define an authentication model or multi-tenant isolation. If you expose any terminal surface beyond a trusted boundary, treat it as privileged remote execution.