@johnhenry/wsh 0.20.0 → 0.21.0

package/README.md

@@ -186,7 +186,79 @@ paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
 Not implemented (each has a tracking issue): WebTransport, relay/reverse
-mode, attach/resume of server-side sessions.
+mode.
+
+### Sessions: attach / resume / detach
+
+By default a pty/exec session dies with the connection that opened it. Pass
+`sessions` and it outlives it, so a dropped socket (a flaky link, a closed
+tab) can be picked up again:
+
+```js
+createWshServer({
+  auth, exec: true, pty: { spawn: nodePty.spawn },
+  sessions: {
+    detachTtlMs: 300_000,   // how long a session nobody is attached to keeps running (0 = kill at once)
+    maxDetached: 16,        // unattended sessions kept at once; the longest-detached is killed beyond that
+    ringBytes: 1 << 20,     // output history kept per session: what a resume can replay
+    // sessionSecret: process.env.WSH_SESSION_SECRET,  // fixes the token key (default: random per process)
+  },
+});
+```
+
+```js
+// original connection
+const s = await client.openSession({ type: 'pty' });
+s.onData = (d) => term.write(d);            // s.seq counts the output bytes received so far
+const { sessionId, resumeToken } = s;       // keep these
+const lastSeq = s.seq;                      // ... the socket drops ...
+
+// fresh connection, same key
+const { session } = await client2.resumeSession(sessionId, resumeToken, { lastSeq });
+session.onData = (d) => term.write(d);      // only the bytes after lastSeq, then live output
+await session.write('ls\n');                // and it is the same process
+```
+
+- **`seq` is the cumulative count of output bytes** the host has produced for
+  a session (stream data or `SessionData` alike). The client counts what it
+  received -- `WshSession.seq` -- so no per-frame field exists, and
+  `Resume.last_seq` is exactly that number. The host keeps the newest
+  `ringBytes` of output and replays `ring[last_seq - ringStart ..]`. A
+  `last_seq` older than the ring still holds is refused with an
+  `output gap` error naming where the history starts (fall back to
+  `attachSession()` for the retained tail); one newer than the session has
+  produced is refused too. While nobody is attached the process keeps running
+  and keeps filling the ring (it is never paused), so a chatty process loses its
+  oldest output rather than blocking.
+- **Token:** `HMAC-SHA256(secret, session_id || expiry)` in the spec's
+  40-byte token format, minted at open, returned as `OpenOk.token` and checked
+  in constant time. **`Resume` needs the token AND ownership** (the same key, or
+  for a password login the same username) -- it is the credentialed connection
+  coming back. **`Attach` accepts the token OR ownership**, so the owner can
+  re-attach with nothing but the session id, and a token holder can join as a
+  guest. Refusals do not say whether the session exists.
+- **What arrives:** the Presence reply names a new channel (`channel_id`) and the
+  `seq` of its first byte; the replay and live output follow as `SessionData` on
+  it. That channel is always message-backed, even for an `exec` session that was
+  opened on a data stream -- neither stock client opens a stream for attach/resume
+  -- so `resumeSession()`/`attachSession()` return the Presence with a
+  non-enumerable `session` (a `WshSession`) to read and write it. A client that
+  ignores that can read the same frames with `addControlListener()`.
+- **Several connections** may attach to one session (up to 16): output fans out
+  to all of them, `attachSession(id, { readOnly: true })` attaches a viewer whose
+  input is dropped, and every change in who is attached is broadcast as `Presence`
+  (the roster, without channel ids).
+- **Ending vs leaving:** `Close` on a channel (which `session.close()` and a
+  graceful `client.disconnect()` send) *ends* the session when its owner sends it,
+  and merely leaves it for anyone else. To walk away from a session and keep it
+  running, `client.detach(sessionId)` first; losing the connection also detaches.
+  `client.listRemoteSessions()` lists the sessions your key owns, attached or not.
+- Exit: when the process ends, everyone attached gets `Exit` + `Close`; the
+  record then lingers for `detachTtlMs` so a late resume still collects the tail
+  and the exit code.
+- Not built: ACL grants (`SessionGrant`/`SessionRevoke`) and `ControlChanged` --
+  only the owner re-attaches as a controller; everyone else needs the token.
+  Sessions are in-memory: a server restart ends them all.
 
 ### MCP tools
 
@@ -361,8 +433,9 @@ Opening a PTY/exec session returns a session-scoped credential alongside the cha
 session.sessionId;   // server-assigned session id (undefined for e.g. file channels)
 session.resumeToken; // token minted at open time; only the opener receives it
 
-// The original opener, reclaiming its session from a fresh connection:
-await client.resumeSession(session.sessionId, session.resumeToken);
+// The original opener, reclaiming its session from a fresh connection,
+// replaying only the output it has not yet seen (`session.seq` counts it):
+await client.resumeSession(session.sessionId, session.resumeToken, { lastSeq });
 
 // Any other authorized principal attaches without a token -- ownership
 // or an ACL grant is enough:
@@ -374,6 +447,11 @@ await client.detach(session.sessionId);   // leave it running server-side
 await client.listRemoteSessions();        // sessions this key can see
 ```
 
+`@johnhenry/wsh/server` implements all of it with its [`sessions`
+option](#sessions-attach--resume--detach). The Rust `wsh-server` replays its whole
+ring on `Resume` regardless of `last_seq` (the position is defined in
+[spec/wsh-v1.md](spec/wsh-v1.md)).
+
 ## Pinning a Self-Signed Certificate
 
 Both transports normally need a certificate a public certificate authority
@@ -516,6 +594,7 @@ than left to be found.
 | Install an authorized key | `WshClient.addAuthorizedKey()` | `wsh_client::WshClient::add_authorized_key()`, `wsh copy-id` | **Wire-unified** (wsh #59): `AuthorizedKeyAdd`/`AuthorizedKeyResult`, replacing a Rust-CLI-only shell command with a message every implementation can send |
 | Host identity / TOFU | `WshKnownHosts` (localStorage-backed) | `KnownHosts`/`HostStatus` (`~/.wsh/known_hosts`-backed) | **Record unified, policy is not** (wsh #59): both pin `ServerHello.host_fingerprint`, which `@johnhenry/wsh/server` populates (with a proof of possession, [Host key](#host-key-fingerprint--tofu)) but no Rust `wsh-server` release does yet (see [Security](#security-model)). *When* to trust, prompt, or persist is deliberately left per-implementation -- a browser and a CLI have different UX for "first time seeing this host" |
 | Interactive shell UI | none -- this SDK is a protocol client, not a terminal emulator; pair with xterm.js/ghostty-web | `wsh connect`, `wsh sftp` (line-oriented REPL) | **Deliberately not unified** -- a browser embeds a terminal widget the host page owns; a CLI process owns its own TTY |
+| Attach / resume | `attachSession()`, `resumeSession()`, `WshSession.seq` | `attach_session()`, `resume_session()` | **Wire-unified** (`Attach`/`Resume`/`Presence`); `seq` = cumulative output bytes. `@johnhenry/wsh/server` honours `last_seq` (bounded ring, gap errors) and answers Presence with `channel_id`/`seq`; the Rust `wsh-server` replays its whole ring and leaves them unset |
 | Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service |
 | Post-quantum E2E (experimental) | `initiateE2E()` (WebCrypto ML-KEM-768 or `@noble/post-quantum` fallback) | `E2eKeyExchange` (`ml-kem` crate) | **Wire-unified** algorithm and transcript; key material backends differ by platform necessity |
 | Session recording/replay | `SessionRecorder`/`SessionPlayer` (asciicast v2) | none | **JS-only** -- no current Rust consumer needs playback; the format itself (asciicast v2) is not proprietary if one is added later |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",

package/src/client.mjs

@@ -244,6 +244,15 @@ export class WshClient {
   /** @type {Map<number, WshSession>} Active sessions keyed by channel ID. */
   #sessions = new Map();
 
+  /**
+   * In-flight attachSession()/resumeSession() calls awaiting the Presence
+   * that answers them. Like #pendingOpens, matched synchronously in
+   * #handleControl so the WshSession exists before the replay (which the
+   * host sends right behind the Presence) is dispatched.
+   * @type {Array<{sessionId: string, token?: Uint8Array}>}
+   */
+  #pendingAttaches = [];
+
   /**
    * FIFO queue of in-flight openSession() calls awaiting the next
    * OPEN_OK/OPEN_FAIL. Handled as a dedicated synchronous case in
@@ -743,27 +752,50 @@ export class WshClient {
    * @param {boolean} [opts.readOnly=false] - Attach in read-only mode
    * @param {Uint8Array} [opts.token] - Session-scoped token (optional; see above)
    * @param {number} [opts.timeout] - Timeout in ms
-   * @returns {Promise<object>} Server's PRESENCE response
+   * @returns {Promise<object>} Server's PRESENCE response. Against a host that
+   *   assigns the attachment a channel (`@johnhenry/wsh/server` with `sessions`)
+   *   the response also has a non-enumerable `session`: a message-backed
+   *   `WshSession` receiving the replay and live output (`onData`, `write()`,
+   *   `resize()`, `onExit`), whose `seq` is the position to resume from next time.
    */
   async attachSession(targetSessionId, { readOnly = false, token, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('attachSession');
 
     const attachMode = readOnly ? 'readonly' : 'control';
-    await this.#transport.sendControl(
-      attachMsg({ sessionId: targetSessionId, token, mode: attachMode })
+    return this.#attachOrResume(
+      targetSessionId, token, attachMsg({ sessionId: targetSessionId, token, mode: attachMode }),
+      timeout, 'attach', 'Failed to attach',
     );
+  }
 
-    const response = await this.#waitForMessage(
-      [MSG.PRESENCE, MSG.ERROR],
-      timeout,
-      'Timed out waiting for attach response'
-    );
+  /**
+   * Send an Attach/Resume and wait for the Presence that answers it.
+   * @private
+   */
+  async #attachOrResume(sessionId, token, msg, timeout, what, failure) {
+    const pending = { sessionId, token };
+    this.#pendingAttaches.push(pending);
+    try {
+      await this.#transport.sendControl(msg);
 
-    if (response.type === MSG.ERROR) {
-      throw new Error(`Failed to attach: ${response.message || 'rejected'}`);
-    }
+      const response = await this.#waitForMessage(
+        [MSG.PRESENCE, MSG.ERROR],
+        timeout,
+        `Timed out waiting for ${what} response`,
+        // A roster Presence about some other session this connection is in is not the answer.
+        (m) => m.type === MSG.ERROR || !Array.isArray(m.attachments) || m.attachments.length === 0
+          || m.attachments.some((a) => a?.session_id === sessionId),
+      );
 
-    return response;
+      if (response.type === MSG.ERROR) {
+        throw new Error(`${failure}: ${response.message || 'rejected'}`);
+      }
+
+      return response;
+    } finally {
+      const i = this.#pendingAttaches.indexOf(pending);
+      if (i !== -1) this.#pendingAttaches.splice(i, 1);
+    }
   }
 
   /**
@@ -779,28 +811,22 @@ export class WshClient {
    * @param {string} targetSessionId - Session ID to resume
    * @param {Uint8Array} token - Session-scoped resume token (see `WshSession.resumeToken`)
    * @param {object} [opts]
-   * @param {number} [opts.lastSeq=0] - Last sequence number this client already has (currently advisory -- the ring buffer replays its full contents regardless)
+   * @param {number} [opts.lastSeq=0] - Cumulative session output bytes this
+   *   client has already received (`WshSession.seq` of the session it lost).
+   *   A host with a bounded history replays only what follows and refuses a
+   *   position older than it still holds (use `attachSession()` then); the Rust
+   *   `wsh-server` ignores it and replays its whole ring.
    * @param {number} [opts.timeout=10000] - Timeout in ms
-   * @returns {Promise<object>} Server's PRESENCE response
+   * @returns {Promise<object>} Server's PRESENCE response, with a non-enumerable
+   *   `session` exactly as for `attachSession()`.
    */
   async resumeSession(targetSessionId, token, { lastSeq = 0, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('resumeSession');
 
-    await this.#transport.sendControl(
-      resumeMsg({ sessionId: targetSessionId, token, lastSeq })
-    );
-
-    const response = await this.#waitForMessage(
-      [MSG.PRESENCE, MSG.ERROR],
-      timeout,
-      'Timed out waiting for resume response'
+    return this.#attachOrResume(
+      targetSessionId, token, resumeMsg({ sessionId: targetSessionId, token, lastSeq }),
+      timeout, 'resume', 'Failed to resume',
     );
-
-    if (response.type === MSG.ERROR) {
-      throw new Error(`Failed to resume: ${response.message || 'rejected'}`);
-    }
-
-    return response;
   }
 
   /**
@@ -2390,6 +2416,28 @@ export class WshClient {
       return;
     }
 
+    // The Presence answering this connection's own Attach/Resume names the
+    // channel the host assigned (see AttachmentInfo.channel_id): build the
+    // session now, synchronously, so the replay right behind it finds it.
+    if (type === MSG.PRESENCE && this.#pendingAttaches.length > 0) {
+      const own = Array.isArray(msg.attachments)
+        ? msg.attachments.find((a) => a?.channel_id !== undefined && this.#pendingAttaches.some((p) => p.sessionId === a.session_id))
+        : undefined;
+      if (own) {
+        const pending = this.#pendingAttaches.find((p) => p.sessionId === own.session_id);
+        const session = new WshSession(this.#transport, own.channel_id, {}, 'pty', {
+          dataMode: 'virtual',
+          capabilities: ['resize', 'signal'],
+          sessionId: own.session_id,
+          resumeToken: pending.token,
+        });
+        session._setSeq(Number.isSafeInteger(own.seq) ? own.seq : 0);
+        this.#sessions.set(own.channel_id, session);
+        session._activateVirtual((m) => this.sendRelayControl(m));
+        Object.defineProperty(msg, 'session', { value: session, enumerable: false });
+      }
+    }
+
     // First, check if any waiters are listening for this message type.
     // A waiter carrying a `match` predicate only takes messages it claims,
     // so the queue is scanned rather than shifted blindly.

package/src/index.d.ts

@@ -1416,6 +1416,13 @@ export class WshSession {
    */
   readonly resumeToken: Uint8Array | undefined;
 
+  /**
+   * Cumulative session output bytes received so far -- the host's `seq` for
+   * the next byte. Pass it as `lastSeq` to `WshClient.resumeSession()`.
+   * Absolute for a session obtained from `attachSession()`/`resumeSession()`.
+   */
+  readonly seq: number;
+
   /** Called when stdout/stderr data arrives. */
   onData: ((data: Uint8Array) => void) | null;
 
@@ -1621,6 +1628,14 @@ export interface WshOpenSessionOptions {
   primer?: boolean;
 }
 
+/**
+ * The Presence answering `attachSession()` / `resumeSession()`. Against a host
+ * that assigns the attachment a channel (`@johnhenry/wsh/server` with `sessions`),
+ * `session` -- non-enumerable -- is the message-backed `WshSession` receiving
+ * the replay and live output.
+ */
+export type WshAttachResponse = WshMessage & { readonly session?: WshSession };
+
 /** Options for WshClient.attachSession(). */
 export interface WshAttachSessionOptions {
   readOnly?: boolean;
@@ -1637,7 +1652,12 @@ export interface WshAttachSessionOptions {
 
 /** Options for WshClient.resumeSession(). */
 export interface WshResumeSessionOptions {
-  /** Last sequence number this client already has (currently advisory). */
+  /**
+   * Cumulative session output bytes this client already has (`WshSession.seq`
+   * of the session it lost). A host with a bounded history replays only what
+   * follows and refuses a position older than it still holds; the Rust
+   * `wsh-server` ignores it and replays its whole ring. Default 0.
+   */
   lastSeq?: number;
   timeout?: number;
 }
@@ -1851,13 +1871,13 @@ export class WshClient {
    * already owning/being ACL-granted access to `targetSessionId`
    * server-side -- see `WshAttachSessionOptions.token`.
    */
-  attachSession(targetSessionId: string, opts?: WshAttachSessionOptions): Promise<WshMessage>;
+  attachSession(targetSessionId: string, opts?: WshAttachSessionOptions): Promise<WshAttachResponse>;
 
   /**
    * Resume a previously disconnected session. Unlike `attachSession()`,
    * `token` is required and verified unconditionally server-side.
    */
-  resumeSession(targetSessionId: string, token: Uint8Array, opts?: WshResumeSessionOptions): Promise<WshMessage>;
+  resumeSession(targetSessionId: string, token: Uint8Array, opts?: WshResumeSessionOptions): Promise<WshAttachResponse>;
 
   /**
    * Detach from a remote session, leaving it running server-side.

package/src/server/connection.mjs

@@ -19,11 +19,13 @@ import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
   MSG, serverHello, challenge, authOk, authFail, openOk, openFail, sessionData,
   exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk, mcpTools, mcpResult,
+  presence as presenceMsg, error as errorMsg, sessionList, detachOk, detachFail,
 } from '../messages.gen.mjs';
 import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
 } from '../auth.mjs';
 import { FILE_CHUNK_BYTES } from './fs.mjs';
+import { MAX_ATTACHMENTS } from './sessions.mjs';
 import { MCP_CALL_ID_FEATURE } from '../client.mjs';
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
@@ -33,6 +35,7 @@ const MAX_RENAME_PATH_BYTES = 4096;
 const WRITE_IDLE_MS = 30_000;
 
 const MAX_CHANNELS = 64;
+const REPLAY_CHUNK_BYTES = 32 * 1024;
 const USERNAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
 const enc = new TextEncoder();
 
@@ -49,6 +52,7 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {{ pubkey: boolean, password: Function | null }} cfg.methods - which auth methods are on
  * @param {object | null} cfg.hostKey - from loadHostKey
  * @param {object | null} cfg.mcp - from createMcpHost
+ * @param {object | null} cfg.sessions - a SessionRegistry (see sessions.mjs); null = sessions die with their connection
  * @param {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
  * @param {number} cfg.bindTimeoutMs - how long exec output waits for the data stream
  * @param {(line: string) => void} cfg.log
@@ -89,7 +93,9 @@ export function createConnectionFactory(cfg) {
     function shutdown(why) {
       if (state.closed) return;
       state.closed = true;
-      for (const ch of channels.values()) ch.kill?.();
+      // A hosted session survives its connection (it is detached, then expires or is resumed);
+      // everything else dies with it.
+      for (const ch of [...channels.values()]) (ch.detach ?? ch.kill)?.call(ch);
       channels.clear();
       for (const c of mcpCalls) c.abort(new Error('connection closed'));
       mcpCalls.clear();
@@ -99,8 +105,13 @@ export function createConnectionFactory(cfg) {
       log(`closed (${why})`);
     }
 
+    // A transport that closes right behind a message (a client's `disconnect()` sends Close for
+    // every channel and then goes) must not make the host forget that message: it is processed
+    // first, then the connection is torn down.
+    const shutdownAfterQueue = (why) => { chain = chain.then(() => shutdown(why)); };
+
     qmux.onError = (e) => log(`qmux error: ${e.message}`);
-    qmux.onClose = () => shutdown('peer sent CONNECTION_CLOSE');
+    qmux.onClose = () => shutdownAfterQueue('peer sent CONNECTION_CLOSE');
     qmux.onStreamOpen = (s) => {
       if (s.id !== 0) { bindDataStream(s); return; }
       control = s;
@@ -109,8 +120,8 @@ export function createConnectionFactory(cfg) {
         try { msgs = decoder.feed(d); } catch (e) { log(`frame decode error: ${e.message}`); return; }
         for (const m of msgs) chain = chain.then(() => handle(m)).catch((e) => log(`handler error: ${e.message}`));
       };
-      s.onEnd = () => shutdown('control stream FIN');
-      s.onReset = () => shutdown('control stream reset');
+      s.onEnd = () => shutdownAfterQueue('control stream FIN');
+      s.onReset = () => shutdownAfterQueue('control stream reset');
       for (const b of pendingSends.splice(0)) s.write(b).catch(() => {});
     };
     qmux.sendHandshake();
@@ -136,6 +147,10 @@ export function createConnectionFactory(cfg) {
         case MSG.CLOSE: { const ch = channels.get(m.channel_id); if (ch) { ch.kill?.(); } return; }
         case MSG.FILE_OP: return handleFileOp(m);
         case MSG.FILE_CHUNK: return (fileWrites.has(m.channel_id) ? handleWriteChunk(m) : channels.get(m.channel_id)?.chunk?.(m));
+        case MSG.ATTACH: return handleAttach(m, false);
+        case MSG.RESUME: return handleAttach(m, true);
+        case MSG.DETACH: return handleDetach(m);
+        case MSG.SESSION_LIST_REQUEST: return handleSessionList();
         case MSG.MCP_DISCOVER: return handleMcpDiscover();
         // Not awaited: the handler chain is serial, and a slow tool must not hold up
         // the next call (or a Close) behind it.
@@ -315,6 +330,118 @@ export function createConnectionFactory(cfg) {
       return send(exitMsg({ channelId, code })).then(() => send(closeMsg({ channelId })));
     }
 
+    // ── Hosted sessions (createWshServer({ sessions })) ───────────────
+
+    /** Who this connection authenticated as: its key, or its username for a password login. */
+    const principalKey = () => state.fingerprint ?? `password:${state.username}`;
+    const ownerRecord = () => ({ username: state.username, fingerprint: state.fingerprint, principal: principalKey() });
+
+    /**
+     * This connection's message-backed attachment to a hosted session: output, Presence and the
+     * final Exit/Close all go through one ordered chain, so a replay is never overtaken by live output.
+     */
+    function virtualAttachment(hosted, channelId, mode) {
+      let out = Promise.resolve();
+      const enqueue = (fn) => { out = out.then(fn).catch(() => {}); return out; };
+      return {
+        connId: cid, channelId, mode, username: state.username, principal: principalKey(),
+        write: (bytes) => enqueue(() => send(sessionData({ channelId, data: bytes }))),
+        notify: (msg) => enqueue(() => send(presenceMsg(msg))),
+        exit: (code) => enqueue(async () => {
+          channels.delete(channelId);
+          await send(exitMsg({ channelId, code }));
+          await send(closeMsg({ channelId }));
+        }),
+        flush: () => out,
+      };
+    }
+
+    /** The `channels` entry for a virtual attachment (an Attach/Resume, or a pty's own channel). */
+    function attachedChannel(hosted, att) {
+      const control = () => att.mode === 'control';
+      const ch = {
+        session: hosted, attachment: att,
+        input: (d) => { if (control()) hosted.handlers.input?.(d); },
+        resize: (c, r) => { if (control()) hosted.handlers.resize?.(c, r); },
+        signal: (name) => { if (control()) hosted.handlers.signal?.(name); },
+        // The client closed the channel: the session's owner ends it, anyone else just leaves it.
+        kill: () => {
+          if (att.principal === hosted.owner.principal && control()) hosted.kill();
+          else ch.detach();
+        },
+        detach: () => { channels.delete(att.channelId); hosted.detach(att); },
+      };
+      channels.set(att.channelId, ch);
+      return ch;
+    }
+
+    async function handleAttach(m, isResume) {
+      const reg = cfg.sessions;
+      const fail = (code, message) => send(errorMsg({ code, message }));
+      if (!reg) return fail(3, `${isResume ? 'resume' : 'attach'} is not enabled on this server (no "sessions" option)`);
+      const s = reg.get(m.session_id);
+      const mine = !!s && s.owner.principal === principalKey();
+      const tokenOk = !!s && m.token !== undefined && reg.checkToken(s, m.token);
+      // Attach: the token OR ownership. Resume: the token AND ownership (the credentialed connection coming back).
+      if (!s || !(isResume ? tokenOk && mine : tokenOk || mine)) {
+        log(`${isResume ? 'resume' : 'attach'} refused for ${String(m.session_id).slice(0, 8)}`);
+        return fail(2, 'unknown session or not authorized');
+      }
+      if ([...channels.values()].some((c) => c.session === s)) return fail(3, 'already attached to this session on this connection');
+      if (s.attachments.size >= MAX_ATTACHMENTS) return fail(3, 'too many attachments to this session');
+      if (channels.size >= MAX_CHANNELS) return fail(3, 'too many open channels');
+
+      let from = s.ring.start;
+      if (isResume) {
+        const last = m.last_seq;
+        if (!Number.isSafeInteger(last) || last < 0) return fail(3, 'last_seq must be a non-negative integer');
+        if (last > s.ring.end) return fail(4, `last_seq ${last} is ahead of the session (it has produced ${s.ring.end} bytes)`);
+        if (last < s.ring.start) {
+          return fail(4, `output gap: this session's retained output starts at seq ${s.ring.start} but last_seq is ${last}; attach for the retained output instead`);
+        }
+        from = last;
+      }
+      const mode = !isResume && /^(readonly|read|view|ro)$/i.test(String(m.mode ?? '')) ? 'readonly' : 'control';
+      const channelId = ++state.nextChannel;
+      const att = virtualAttachment(s, channelId, mode);
+      attachedChannel(s, att);
+
+      // Reply, replay, then (if the process is already over) its exit -- all before any live output,
+      // which only reaches `att` once `s.attach(att)` registers it, after these are queued.
+      const self = { session_id: s.id, mode, username: state.username, channel_id: channelId, seq: from };
+      att.notify({ attachments: [self, ...s.roster()] });
+      const replay = s.ring.read(from);
+      for (let off = 0; off < replay.byteLength; off += REPLAY_CHUNK_BYTES) att.write(replay.subarray(off, off + REPLAY_CHUNK_BYTES));
+      if (s.state === 'exited') att.exit(s.exitCode ?? 0);
+      else s.attach(att);
+      log(`${isResume ? 'resumed' : `attached (${mode})`} session ${s.id.slice(0, 8)} on channel ${channelId} from seq ${from}`);
+    }
+
+    async function handleDetach(m) {
+      const s = cfg.sessions?.get(m.session_id);
+      const entry = s && [...channels.entries()].find(([, c]) => c.session === s);
+      if (!entry) return send(detachFail({ reason: 'not attached to this session on this connection' }));
+      const [channelId, ch] = entry;
+      const flushed = ch.attachment.flush();
+      ch.detach();
+      await flushed;
+      await send(closeMsg({ channelId }));
+      return send(detachOk({ sessionId: s.id }));
+    }
+
+    function handleSessionList() {
+      const now = Date.now();
+      const sessions = (cfg.sessions?.listFor(principalKey()) ?? []).map((s) => ({
+        session_id: s.id,
+        username: s.owner.username,
+        fingerprint_short: (s.owner.fingerprint ?? '').slice(0, 8),
+        created_at_secs: Math.floor(s.createdAt / 1000),
+        idle_secs: Math.max(0, Math.floor((now - s.lastActivity) / 1000)),
+        attached_count: s.attachments.size,
+      }));
+      return send(sessionList({ sessions }));
+    }
+
     async function openExec(m) {
       if (!cfg.execRunner) return send(openFail({ reason: 'exec is not enabled on this server' }));
       const command = String(m.command ?? '').trim();
@@ -322,6 +449,7 @@ export function createConnectionFactory(cfg) {
 
       const channelId = ++state.nextChannel;
       const abort = new AbortController();
+      const hosted = cfg.sessions ? cfg.sessions.create({ owner: ownerRecord(), kind: 'exec', command }) : null;
       let stream = null;
       let primerChecked = false;
       let wq = Promise.resolve();
@@ -331,13 +459,14 @@ export function createConnectionFactory(cfg) {
       const endCbs = [];
       const signalCbs = [];
 
+      const signalTo = (name) => {
+        const n = name.replace(/^SIG/, '').toUpperCase();
+        for (const cb of signalCbs) cb(n);
+        if (/^(INT|TERM|KILL|HUP)$/.test(n) && signalCbs.length === 0) abort.abort();
+      };
       const ch = {
         kill: () => abort.abort(),
-        signal: (name) => {
-          const n = name.replace(/^SIG/, '').toUpperCase();
-          for (const cb of signalCbs) cb(n);
-          if (/^(INT|TERM|KILL|HUP)$/.test(n) && signalCbs.length === 0) abort.abort();
-        },
+        signal: signalTo,
         bind(s) {
           stream = s;
           s.onData = (d) => {
@@ -349,7 +478,8 @@ export function createConnectionFactory(cfg) {
             if (d.byteLength) for (const cb of inputCbs) cb(d);
           };
           s.onEnd = () => { for (const cb of endCbs) cb(); };
-          s.onReset = () => abort.abort();
+          // A hosted session outlives its stream; an unhosted one dies with it.
+          s.onReset = () => { if (!hosted) abort.abort(); };
           const pending = buffered.splice(0);
           wq = wq.then(async () => { for (const b of pending) await s.write(b).catch(() => {}); });
           for (const r of boundWaiters.splice(0)) r();
@@ -361,6 +491,49 @@ export function createConnectionFactory(cfg) {
       let timer = null;
       if (cfg.execOptions.timeoutMs > 0) timer = setTimeout(() => abort.abort(), cfg.execOptions.timeoutMs);
 
+      // Output to the opening connection's data stream (held until the client has opened it).
+      const toStream = (bytes) => {
+        if (!stream) { buffered.push(bytes); return Promise.resolve(); }
+        const s = stream;
+        wq = wq.then(() => s.write(bytes).catch(() => {}));
+        return wq;
+      };
+      // Output is ready but the client's stream may not have been bound yet (a host without
+      // announce support waits for the first byte): give it a bounded chance rather than
+      // dropping the output or hanging forever.
+      const closeStream = async (code) => {
+        if (!stream) await Promise.race([new Promise((r) => boundWaiters.push(r)), new Promise((r) => setTimeout(r, cfg.bindTimeoutMs))]);
+        if (!stream) log(`exec channel ${channelId}: data stream never appeared; output dropped`);
+        await wq;
+        try { await stream?.close(); } catch { /* peer gone */ }
+        await finishChannel(channelId, Number.isInteger(code) ? code : 0);
+      };
+
+      if (hosted) {
+        const att = {
+          connId: cid, channelId, mode: 'control', username: state.username, principal: principalKey(),
+          write: toStream,
+          notify: (msg) => send(presenceMsg(msg)),
+          exit: (code) => closeStream(code),
+          flush: () => wq,
+        };
+        hosted.handlers = {
+          input: (d) => { for (const cb of inputCbs) cb(d); },
+          inputEnd: () => { for (const cb of endCbs) cb(); },
+          signal: signalTo,
+          resize: () => {},
+          kill: () => abort.abort(),
+        };
+        ch.session = hosted;
+        ch.attachment = att;
+        ch.detach = () => {
+          channels.delete(channelId);
+          hosted.detach(att);
+          try { stream?.close().catch(() => {}); } catch { /* gone */ }
+        };
+        hosted.attach(att);
+      }
+
       const io = {
         user: state.username,
         env: m.env && typeof m.env === 'object' && cfg.execOptions.clientEnv !== false ? m.env : {},
@@ -369,9 +542,8 @@ export function createConnectionFactory(cfg) {
         signal: abort.signal,
         write(data) {
           const bytes = toBytes(data);
-          if (!stream) { buffered.push(bytes); return Promise.resolve(); }
-          const s = stream;
-          wq = wq.then(() => s.write(bytes).catch(() => {}));
+          if (!hosted) return toStream(bytes);
+          hosted.push(bytes);
           return wq;
         },
         onInput: (cb) => inputCbs.push(cb),
@@ -381,7 +553,7 @@ export function createConnectionFactory(cfg) {
 
       await send(openOk({
         channelId, dataMode: 'stream', capabilities: ['signal'],
-        sessionId: randomUUID(), token: randomBytes(16),
+        sessionId: hosted?.id ?? randomUUID(), token: hosted?.token ?? randomBytes(16),
       }));
       log(`exec channel ${channelId}: ${command}`);
 
@@ -390,20 +562,15 @@ export function createConnectionFactory(cfg) {
       runExec().catch((e) => log(`exec channel ${channelId}: ${e.message}`));
 
       async function runExec() {
-      let code;
-      try { code = await cfg.execRunner(command, io); } catch (e) {
-        await io.write(`wsh: ${e.message}\n`);
-        code = 1;
-      }
-      if (timer) clearTimeout(timer);
-      // Output is ready but the client's stream may not have been bound yet
-      // (a host without announce support waits for the first byte): give it
-      // a bounded chance rather than dropping the output or hanging forever.
-      if (!stream) await Promise.race([new Promise((r) => boundWaiters.push(r)), new Promise((r) => setTimeout(r, cfg.bindTimeoutMs))]);
-      if (!stream) log(`exec channel ${channelId}: data stream never appeared; output dropped`);
-      await wq;
-      try { await stream?.close(); } catch { /* peer gone */ }
-      await finishChannel(channelId, Number.isInteger(code) ? code : 0);
+        let code;
+        try { code = await cfg.execRunner(command, io); } catch (e) {
+          await io.write(`wsh: ${e.message}\n`);
+          code = 1;
+        }
+        if (timer) clearTimeout(timer);
+        // Hosted: everyone attached (this connection's stream included, if it is still there) hears the exit.
+        if (hosted) { hosted.finish(Number.isInteger(code) ? code : 0); return; }
+        await closeStream(code);
       }
     }
 
@@ -423,13 +590,31 @@ export function createConnectionFactory(cfg) {
       } catch (e) {
         return send(openFail({ reason: `pty spawn failed: ${e.message}` }));
       }
-      const ch = {
+      const ctl = {
         input: (data) => { try { proc.write(Buffer.from(data)); } catch { /* exited */ } },
         resize: (c, r) => { try { proc.resize(c || cols, r || rows); } catch { /* exited */ } },
         signal: (name) => { try { proc.kill(`SIG${name.replace(/^SIG/, '').toUpperCase()}`); } catch { /* exited */ } },
         kill: () => { try { proc.kill(); } catch { /* exited */ } },
       };
-      channels.set(channelId, ch);
+
+      if (cfg.sessions) {
+        const hosted = cfg.sessions.create({ owner: ownerRecord(), kind: 'pty', command: m.command });
+        hosted.handlers = ctl;
+        const att = virtualAttachment(hosted, channelId, 'control');
+        attachedChannel(hosted, att);
+        proc.onData((d) => hosted.push(Uint8Array.from(toBytes(d))));
+        proc.onExit(({ exitCode }) => hosted.finish(exitCode ?? 0));
+        const opened = send(openOk({
+          channelId, dataMode: 'virtual', capabilities: ['resize', 'signal'],
+          sessionId: hosted.id, token: hosted.token,
+        }));
+        hosted.attach(att);
+        await opened;
+        log(`pty channel ${channelId} opened (${cols}x${rows}), session ${hosted.id.slice(0, 8)}`);
+        return;
+      }
+
+      channels.set(channelId, ctl);
       let out = Promise.resolve();
       proc.onData((d) => { out = out.then(() => send(sessionData({ channelId, data: toBytes(d) }))); });
       proc.onExit(({ exitCode }) => { out.then(() => finishChannel(channelId, exitCode ?? 0)); });
@@ -556,7 +741,7 @@ export function createConnectionFactory(cfg) {
 
     return {
       receive(bytes) { if (!state.closed) qmux.receiveBytes(bytes); },
-      close() { shutdown('transport closed'); },
+      close() { shutdownAfterQueue('transport closed'); },
     };
   };
 }

package/src/server/index.d.ts

@@ -158,6 +158,17 @@ export interface WshServerMcpOptions {
   timeoutMs?: number;
 }
 
+export interface WshServerSessionsOptions {
+  /** How long a session with nobody attached keeps running (default 300000). `0` kills it the moment its last connection goes. */
+  detachTtlMs?: number;
+  /** Unattended sessions kept at once (default 16); beyond that the longest-detached is killed. */
+  maxDetached?: number;
+  /** Output history kept per session, in bytes (default 1 MiB) -- what a resume can replay. Older output is dropped; a Resume older than it is refused with an "output gap" error. */
+  ringBytes?: number;
+  /** Secret the session tokens are minted with (default: random per process). Fixing it makes tokens verifiable across restarts. */
+  sessionSecret?: string | Uint8Array;
+}
+
 export interface WshServerOptions {
   /** Bind address (default `127.0.0.1`). */
   host?: string;
@@ -177,6 +188,14 @@ export interface WshServerOptions {
   hostKey?: true | { file: string } | CryptoKeyPair;
   /** Enable file ops and uploads/downloads under one directory. Off by default. */
   fs?: WshServerFsOptions;
+  /**
+   * Keep pty/exec sessions alive across disconnects so `resumeSession()` /
+   * `attachSession()` / `detach()` / `listRemoteSessions()` work against them.
+   * `true` for the defaults. Off by default: sessions then die with their connection.
+   */
+  sessions?: true | WshServerSessionsOptions;
+  /** Alias for `sessions.sessionSecret`. */
+  sessionSecret?: string | Uint8Array;
   /** Serve MCP tools (`McpDiscover` / `McpCall`) and advertise `mcp-call-id`. Off by default. */
   mcp?: WshServerMcpOptions;
   /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */

package/src/server/index.mjs

@@ -14,6 +14,7 @@ import { spawnRunner } from './exec.mjs';
 import { normalizePty } from './pty.mjs';
 import { createFileAccess } from './fs.mjs';
 import { createMcpHost } from './mcp.mjs';
+import { SessionRegistry } from './sessions.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE };
@@ -30,6 +31,11 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  * @param {{ tools?: object[] | object, client?: object, authorize?: Function, maxConcurrent?: number, timeoutMs?: number }} [options.mcp]
  *   MCP tools served over `McpDiscover` / `McpCall`: `tools` (`{ name, description, inputSchema, call(args, { user, signal }) }`),
  *   and/or `client` (an `@modelcontextprotocol/sdk` Client to proxy). Off unless given.
+ * @param {true | { detachTtlMs?: number, maxDetached?: number, ringBytes?: number, sessionSecret?: string | Uint8Array }} [options.sessions]
+ *   Keep pty/exec sessions alive across disconnects so a client can `resumeSession()` / `attachSession()`
+ *   them: a per-server registry, a ring buffer of the newest `ringBytes` (default 1 MiB) of output, and
+ *   `detachTtlMs` (default 300000; 0 = kill on disconnect) / `maxDetached` (default 16) bounds. Off unless given.
+ * @param {string | Uint8Array} [options.sessionSecret] - Alias for `sessions.sessionSecret`.
  * @param {true | { file: string } | CryptoKeyPair} [options.hostKey] - The server's own Ed25519
  *   identity, advertised (with proof of possession) so clients can pin it. See `src/host-key.mjs`.
  * @param {object} [options.auth.rateLimit] - Password-failure throttle: `{ maxFailures=5, windowMs=60000,
@@ -39,7 +45,7 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
-  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, sessions, sessionSecret, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
@@ -63,6 +69,8 @@ export function createWshServer({
     failureDelayMs: rl.failureDelayMs ?? 250,
   };
   let host_ = null;
+  let registry = null;
+  const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
   return {
     async listen() {
@@ -75,9 +83,19 @@ export function createWshServer({
       }
       const authorize = await buildAuthorizer(auth);
       host_ = hostKey ? await loadHostKey(hostKey) : null;
+      if (sessionOptions) {
+        const secret = sessionOptions.sessionSecret ?? sessionSecret;
+        registry = new SessionRegistry({
+          secret: secret === undefined ? undefined : Buffer.from(secret),
+          detachTtlMs: sessionOptions.detachTtlMs,
+          maxDetached: sessionOptions.maxDetached,
+          ringBytes: sessionOptions.ringBytes,
+          log: onLog,
+        });
+      }
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
-        methods, hostKey: host_, rateLimit, mcp: mcpHost,
+        methods, hostKey: host_, rateLimit, mcp: mcpHost, sessions: registry,
       });
 
       wss = new WebSocketServer({ host, port });
@@ -109,6 +127,8 @@ export function createWshServer({
       bound = null;
       for (const client of server.clients) client.terminate();
       await new Promise((resolve) => server.close(resolve));
+      registry?.closeAll();
+      registry = null;
     },
 
     address() {

package/src/server/sessions.mjs

@@ -0,0 +1,263 @@
+/**
+ * Session registry for `@johnhenry/wsh/server`: what lets an exec/pty session
+ * outlive the connection that opened it (`createWshServer({ sessions })`).
+ *
+ * The registry is per server and holds a `HostedSession` for every pty/exec
+ * session. A connection's channel is an *attachment* to one: output is
+ * appended to the session's ring buffer and fanned out to every attachment,
+ * so when a socket drops the process keeps running and its newest output keeps
+ * accumulating until `detachTtlMs` elapses or a client resumes.
+ *
+ * `seq` -- the one design question the wire does not answer -- is defined as
+ * the cumulative count of output BYTES the host has produced for a session.
+ * A client counts what it has received (it sees every byte), passes that as
+ * `Resume.last_seq`, and the host replays `ring[last_seq - ringStart ..]`.
+ * See spec/wsh-v1.yaml (`Resume`, `AttachmentInfo`).
+ */
+
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+
+export const DEFAULT_RING_BYTES = 1024 * 1024;
+export const DEFAULT_DETACH_TTL_MS = 300_000;
+export const DEFAULT_MAX_DETACHED = 16;
+export const MAX_ATTACHMENTS = 16;
+
+const NO_EXPIRY = Buffer.alloc(8, 0xff);
+
+/**
+ * A bounded byte history addressed by absolute stream position.
+ * `start` is the seq of the oldest retained byte, `end` the seq one past the newest.
+ */
+export class ByteRing {
+  #chunks = [];
+  #size = 0;
+  start = 0;
+  end = 0;
+
+  constructor(maxBytes) {
+    this.max = maxBytes;
+  }
+
+  push(bytes) {
+    if (!bytes.byteLength) return;
+    this.#chunks.push(Uint8Array.from(bytes));
+    this.#size += bytes.byteLength;
+    this.end += bytes.byteLength;
+    while (this.#size > this.max) {
+      const excess = this.#size - this.max;
+      const first = this.#chunks[0];
+      if (first.byteLength <= excess) {
+        this.#chunks.shift();
+        this.#size -= first.byteLength;
+        this.start += first.byteLength;
+      } else {
+        this.#chunks[0] = first.subarray(excess);
+        this.#size -= excess;
+        this.start += excess;
+      }
+    }
+  }
+
+  /** Bytes from absolute position `from` (clamped to `start`) to the end. */
+  read(from = this.start) {
+    const skip = Math.max(0, from - this.start);
+    const out = new Uint8Array(Math.max(0, this.#size - skip));
+    let at = 0;
+    let seen = 0;
+    for (const c of this.#chunks) {
+      if (seen + c.byteLength > skip) {
+        const part = c.subarray(Math.max(0, skip - seen));
+        out.set(part, at);
+        at += part.byteLength;
+      }
+      seen += c.byteLength;
+    }
+    return out;
+  }
+}
+
+/**
+ * Mint a session token in the spec's format: `[8B expiry][32B HMAC-SHA256(secret, session_id || expiry)]`.
+ * A session's lifetime is governed by `detachTtlMs`, not by its token, so the expiry is the maximum.
+ */
+export function mintToken(secret, sessionId) {
+  const mac = createHmac('sha256', secret).update(sessionId).update(NO_EXPIRY).digest();
+  return new Uint8Array(Buffer.concat([NO_EXPIRY, mac]));
+}
+
+/** Constant-time verification of a token minted by `mintToken` for exactly this session id. */
+export function verifyToken(secret, sessionId, token) {
+  if (!(token instanceof Uint8Array) || token.byteLength !== 40) return false;
+  const buf = Buffer.from(token.buffer, token.byteOffset, token.byteLength);
+  const expiry = buf.subarray(0, 8);
+  if (expiry.readBigUInt64BE() < BigInt(Math.floor(Date.now() / 1000))) return false;
+  const want = createHmac('sha256', secret).update(sessionId).update(expiry).digest();
+  return timingSafeEqual(want, buf.subarray(8));
+}
+
+/**
+ * One attached connection's view of a session; `connection.mjs` builds them.
+ * @typedef {object} Attachment
+ * @property {number} connId
+ * @property {number} channelId
+ * @property {'control' | 'readonly'} mode
+ * @property {string} username
+ * @property {string} principal - who this connection authenticated as (see `principalKey`)
+ * @property {(bytes: Uint8Array) => unknown} write - live output
+ * @property {(msg: object) => unknown} notify - an ordered control message (e.g. Presence)
+ * @property {(code: number) => unknown} exit - the session ended
+ */
+
+export class HostedSession {
+  /** @type {Set<Attachment>} */
+  attachments = new Set();
+  state = 'attached';
+  exitCode = null;
+  createdAt = Date.now();
+  lastActivity = Date.now();
+  detachedAt = 0;
+  name;
+  #timer = null;
+
+  constructor(registry, { id, token, owner, kind, command, ringBytes }) {
+    this.registry = registry;
+    this.id = id;
+    this.token = token;
+    this.owner = owner;
+    this.kind = kind;
+    this.command = command;
+    this.ring = new ByteRing(ringBytes);
+    /** Set by the connection once the process exists: `{ input, inputEnd, resize, signal, kill }`. */
+    this.handlers = {};
+  }
+
+  /** Output from the process: retained in the ring, delivered to every attachment. */
+  push(bytes) {
+    this.lastActivity = Date.now();
+    this.ring.push(bytes);
+    for (const a of this.attachments) a.write(bytes);
+  }
+
+  attach(att) {
+    this.attachments.add(att);
+    this.state = 'attached';
+    this.#clearTimer();
+    this.broadcastPresence(att);
+  }
+
+  detach(att) {
+    if (!this.attachments.delete(att)) return;
+    this.broadcastPresence();
+    if (this.attachments.size === 0) this.#markDetached();
+  }
+
+  roster() {
+    return [...this.attachments].map((a) => ({ session_id: this.id, mode: a.mode, username: a.username }));
+  }
+
+  /** Tell every attachment (except `except`) who is attached now. */
+  broadcastPresence(except) {
+    if (this.attachments.size === 0) return;
+    const msg = { attachments: this.roster() };
+    for (const a of this.attachments) if (a !== except) a.notify(msg);
+  }
+
+  /** The process ended. Everyone attached hears Exit + Close; the record lingers for late resumes. */
+  finish(code) {
+    if (this.state === 'exited') return;
+    this.exitCode = code;
+    this.state = 'exited';
+    const att = [...this.attachments];
+    this.attachments.clear();
+    for (const a of att) a.exit(code);
+    this.#markDetached();
+  }
+
+  kill() {
+    try { this.handlers.kill?.(); } catch { /* already gone */ }
+  }
+
+  /** Forget the session (and stop it if it is still running). */
+  dispose() {
+    this.#clearTimer();
+    this.registry._forget(this);
+    if (this.state !== 'exited') {
+      this.kill();
+      this.state = 'exited';
+    }
+  }
+
+  #markDetached() {
+    this.detachedAt = Date.now();
+    if (this.state !== 'exited') this.state = 'detached';
+    this.#clearTimer();
+    const ttl = this.registry.detachTtlMs;
+    if (ttl <= 0) { this.dispose(); return; }
+    this.#timer = setTimeout(() => {
+      this.registry.log(`session ${this.id} expired after ${ttl}ms detached`);
+      this.dispose();
+    }, ttl);
+    this.#timer.unref?.();
+    this.registry._enforceMaxDetached(this);
+  }
+
+  #clearTimer() {
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}
+
+export class SessionRegistry {
+  /** @type {Map<string, HostedSession>} */
+  #sessions = new Map();
+
+  constructor({ secret, detachTtlMs = DEFAULT_DETACH_TTL_MS, maxDetached = DEFAULT_MAX_DETACHED, ringBytes = DEFAULT_RING_BYTES, log = () => {} } = {}) {
+    this.secret = secret ?? randomBytes(32);
+    this.detachTtlMs = detachTtlMs;
+    this.maxDetached = maxDetached;
+    this.ringBytes = ringBytes;
+    this.log = log;
+  }
+
+  /** @param {{ owner: { username: string, principal: string, fingerprint: string | null }, kind: 'pty' | 'exec', command?: string }} spec */
+  create({ owner, kind, command }) {
+    const id = randomUUID();
+    const s = new HostedSession(this, { id, token: mintToken(this.secret, id), owner, kind, command, ringBytes: this.ringBytes });
+    this.#sessions.set(id, s);
+    return s;
+  }
+
+  get(id) {
+    return typeof id === 'string' ? this.#sessions.get(id) : undefined;
+  }
+
+  checkToken(session, token) {
+    return verifyToken(this.secret, session.id, token);
+  }
+
+  /** Sessions this principal owns. */
+  listFor(principal) {
+    return [...this.#sessions.values()].filter((s) => s.owner.principal === principal);
+  }
+
+  get size() { return this.#sessions.size; }
+
+  /** Kill everything (server shutdown). */
+  closeAll() {
+    for (const s of [...this.#sessions.values()]) s.dispose();
+  }
+
+  _forget(session) {
+    this.#sessions.delete(session.id);
+  }
+
+  /** Keep at most `maxDetached` unattended sessions: the longest-detached are killed first. */
+  _enforceMaxDetached() {
+    const detached = [...this.#sessions.values()].filter((s) => s.attachments.size === 0).sort((a, b) => a.detachedAt - b.detachedAt);
+    while (detached.length > this.maxDetached) {
+      const victim = detached.shift();
+      this.log(`session ${victim.id} evicted (more than ${this.maxDetached} detached)`);
+      victim.dispose();
+    }
+  }
+}

package/src/session.mjs

@@ -76,6 +76,12 @@ export class WshSession {
    */
   #resumeToken;
 
+  /**
+   * Cumulative session OUTPUT BYTES received so far (see `seq`).
+   * @type {number}
+   */
+  #seq = 0;
+
   /**
    * Stream IDs returned by the server in OPEN_OK.
    * Typically { stdin: number, stdout: number } or a single bidirectional ID.
@@ -270,6 +276,27 @@ export class WshSession {
     return this.#resumeToken;
   }
 
+  /**
+   * How many bytes of this session's output this client has received: the
+   * host's `seq` for the next byte. Pass it as `lastSeq` to
+   * `WshClient.resumeSession()` so a resume replays only what was missed. For a
+   * session obtained from `attachSession()`/`resumeSession()` it starts at the
+   * host's position of the first replayed byte, so it is an absolute position
+   * either way. Counts bytes delivered to `onData`.
+   * @returns {number}
+   */
+  get seq() {
+    return this.#seq;
+  }
+
+  /**
+   * Set the starting position of a session obtained by attach/resume.
+   * @internal
+   */
+  _setSeq(n) {
+    this.#seq = n;
+  }
+
   /** Current session state. */
   get state() {
     return this.#state;
@@ -657,6 +684,7 @@ export class WshSession {
         if (msg.data && msg.data.byteLength > 0) {
           this.#virtualBackend?.pushData(msg.data);
           try {
+            this.#seq += msg.data.byteLength;
             this.onData?.(msg.data);
           } catch (err) {
             console.error('[wsh:session] onData handler error:', err);
@@ -688,6 +716,7 @@ export class WshSession {
           .then((plaintext) => {
             this.#virtualBackend?.pushData(plaintext);
             try {
+              this.#seq += plaintext.byteLength;
               this.onData?.(plaintext);
             } catch (err) {
               console.error('[wsh:session] onData handler error:', err);
@@ -898,6 +927,7 @@ export class WshSession {
             }
             for (const plaintext of deliverable) {
               try {
+                this.#seq += plaintext.byteLength;
                 this.onData?.(plaintext);
               } catch (err) {
                 console.error('[wsh:session] onData handler error:', err);
@@ -905,6 +935,7 @@ export class WshSession {
             }
           } else {
             try {
+              this.#seq += value.byteLength;
               this.onData?.(value);
             } catch (err) {
               console.error('[wsh:session] onData handler error:', err);