Session association and thumbnails :: Shell Architecture

Intent

Protocol sketch for re-associating Open Terminal sessions (or whole multi-tab UIs) with another process, and for live thumbnail subscription. Complements open-terminal host layout modes. No full IPC in v0 — types/stubs only in the host repo.

Tool Runs (tool-run diagnostics) register as additional surfaces on the same association bus: a compile run collapses to a tile, keeps shellSessionId, and asks the host to focusSurface / flash when the user follows a magic link from the CLI stub.

Layout modes (context)

Mode	Summary
Standalone	Classic Terminal-like; tabs top or left; tabs + surface may share one HWND.
Decoupled index	Index window holds tabs/thumbs; sessions in separate OS windows.
Project-grouped manager	Dedicated manager; tabs grouped by DevCentr spawn-project; vertical tabs default. See DevCentr terminal manager.
Nested zones	Optional contained tiling; group registers to zone for display. See Nested zones.
Other	Future OK; do not over-specify.

Mode

Summary

Standalone

Classic Terminal-like; tabs top or left; tabs + surface may share one HWND.

Decoupled index

Index window holds tabs/thumbs; sessions in separate OS windows.

Project-grouped manager

Dedicated manager; tabs grouped by DevCentr spawn-project; vertical tabs default. See DevCentr terminal manager.

Nested zones

Optional contained tiling; group registers to zone for display. See Nested zones.

Other

Future OK; do not over-specify.

Decoupled index and project-grouped manager are layout modes, not the only ones. Re-association lets a standalone multi-tab UI (or individual sessions) join a subscriber later.

Roles

Role	Responsibility	v0
Session process	Owns PTY + paint surface; ideally produces thumbnail frames; remains its own OS process (taskbar-visible).	Required
Subscriber	Controller / index UI: receives registration (tabs, titles), may show thumbs, focus/spawn/close via association API. Not sole owner.	Recommended. Multiple subscribers allowed.
Manager (later)	Exclusive control: may hide sessions from taskbar, reject extra subscribers, own lifecycle tightly.	Deferred. Do not require exclusive manager in v0.

Role

Responsibility

Session process

Owns PTY + paint surface; ideally produces thumbnail frames; remains its own OS process (taskbar-visible).

Required

Subscriber

Controller / index UI: receives registration (tabs, titles), may show thumbs, focus/spawn/close via association API. Not sole owner.

Recommended. Multiple subscribers allowed.

Manager (later)

Exclusive control: may hide sessions from taskbar, reject extra subscribers, own lifecycle tightly.

Deferred. Do not require exclusive manager in v0.

Handshake sketch

Operations

register — offer registration for one session or a multi-tab group (tab array + titles + layout hint).
subscribe / unsubscribe — attach a subscriber UI; sessions keep running if all subscribers leave.
focusSurface — activate a registered live window.
Thumbnail channel — permission + producer role + optional shared-memory address for frames.

Registration fields

SessionRegistration
  groupId
  sourceLayout          // standalone | decoupledIndex | other
  tabs[]                // id, title, surfaceId
  thumbnailPermission   // bool
  thumbProducer         // sessionHost | subscriber | none
  thumbnailShmAddress   // optional token / name

Thumbnail model (ideal)

Session/host creates thumbnails (producer).
Managing UI is a subscriber (consumer).
Prefer shared-memory thumbnail addresses so multiple subscribers can map without per-frame bitmap copies (taskbar-like realtime; watch CPU/GPU cost and refresh rate).

v0 association ASCII

  [ Session proc A ]--produces thumbs--> shm / notify
  [ Session proc B ]--produces thumbs--> shm / notify
           ^                ^
           | register /     | subscribe (tabs, titles,
           | focus/close    | thumb permission, shm addr)
           |                |
     +-----+----------------+-----+
     |  Subscriber UI(s)          |
     |  index tabs / thumb grid   |
     |  (not exclusive owner)     |
     +----------------------------+
              ^
              | optional Nth subscriber
     +--------+-------------------+
     |  Another subscriber UI     |
     +----------------------------+

Open questions

Shared-memory thumb performance and lifetime (map/unmap, refresh Hz, multi-subscriber contention, DPI/scale).
When to introduce exclusive manager (hide taskbar windows / reject subscribers).
Transport: named pipe, local socket, dew bus, other — undecided.
Group vs per-session registration semantics when re-associating a whole standalone multi-tab UI.
Permission UX: per-subscriber opt-in vs session-global offer.
Fallback if session cannot produce thumbs (DWM capture? subscriber capture?).

Demo

Interactive mock: shell-context-demo · Association.

Session association and thumbnails