claude-code-session-manager 0.108.0 → 0.110.0

package/src/main/webRemote.cjs

@@ -31,6 +31,7 @@ const { claudeHome } = require('./lib/schedulerPaths.cjs');
 const { schemas } = require('./ipcSchemas.cjs');
 const { summarize: _sharedSummarize } = require('./lib/summarize.cjs');
 const { makeState, confirmSas: confirmSasLogic } = require('./lib/e2eStateMachine.cjs');
+const { createClientSessions, LEGACY_CLIENT_KEY } = require('./lib/remoteClientSessions.cjs');
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
@@ -68,107 +69,8 @@ const MSG_MAX_BYTES = 256 * 1024;
 const { ALLOWED_COMMANDS, MUTATE_COMMANDS, SAS_GATED_READS } = require('./ipcSchemas.cjs');
 
 // ─── E2E encryption helpers (P-256 ECDH + AES-256-GCM, ADR §5.2) ────────────
-
-/**
- * Generate a P-256 ECDH keypair. Public key is SPKI DER base64url; private key
- * is PKCS8 DER base64url. Both are stored in web-remote.json at 0600.
- */
-function generateE2EKeyPair() {
-  const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', {
-    namedCurve: 'P-256',
-    publicKeyEncoding: { type: 'spki', format: 'der' },
-    privateKeyEncoding: { type: 'pkcs8', format: 'der' },
-  });
-  return {
-    e2ePrivateKey: privateKey.toString('base64url'),
-    e2ePublicKey: publicKey.toString('base64url'),
-  };
-}
-
-/**
- * Derive an AES-256-GCM session key from two P-256 public keys via ECDH + HKDF.
- * @param myPrivateKeyB64  Agent's PKCS8 private key, base64url DER
- * @param peerPublicKeyB64 Browser's SPKI public key, base64url DER
- * @param deviceId         Used as HKDF salt for domain separation
- * @returns 32-byte Buffer (AES-256-GCM key)
- */
-function deriveSessionKey(myPrivateKeyB64, peerPublicKeyB64, deviceId) {
-  const myPrivKey = crypto.createPrivateKey({
-    key: Buffer.from(myPrivateKeyB64, 'base64url'),
-    format: 'der',
-    type: 'pkcs8',
-  });
-  const peerPubKey = crypto.createPublicKey({
-    key: Buffer.from(peerPublicKeyB64, 'base64url'),
-    format: 'der',
-    type: 'spki',
-  });
-  const sharedSecret = crypto.diffieHellman({ privateKey: myPrivKey, publicKey: peerPubKey });
-  // HKDF: salt = deviceId bytes for domain separation, info = fixed protocol label.
-  const salt = Buffer.from(deviceId, 'utf8');
-  const info = Buffer.from('sm-e2e-v1', 'utf8');
-  return Buffer.from(crypto.hkdfSync('sha256', sharedSecret, salt, info, 32));
-}
-
-/**
- * Derive a 6-digit Short Authentication String from the ECDH shared secret.
- * Uses a separate HKDF info label ('sm-sas-v1') so the SAS is independent of
- * the session key. Both sides compute the same value; user confirms they match.
- */
-function deriveSas(myPrivateKeyB64, peerPublicKeyB64, deviceId) {
-  const myPrivKey = crypto.createPrivateKey({
-    key: Buffer.from(myPrivateKeyB64, 'base64url'),
-    format: 'der',
-    type: 'pkcs8',
-  });
-  const peerPubKey = crypto.createPublicKey({
-    key: Buffer.from(peerPublicKeyB64, 'base64url'),
-    format: 'der',
-    type: 'spki',
-  });
-  const sharedSecret = crypto.diffieHellman({ privateKey: myPrivKey, publicKey: peerPubKey });
-  const salt = Buffer.from(deviceId, 'utf8');
-  const info = Buffer.from('sm-sas-v1', 'utf8');
-  const sasBytes = Buffer.from(crypto.hkdfSync('sha256', sharedSecret, salt, info, 3));
-  const sasNum = ((sasBytes[0] << 16) | (sasBytes[1] << 8) | sasBytes[2]) % 1_000_000;
-  return sasNum.toString().padStart(6, '0');
-}
-
-/**
- * Encrypt a plaintext JSON string into an AES-256-GCM box.
- * @returns { nonce: base64url, ciphertext: base64url } — the nonce is 12 random bytes
- */
-function encryptBox(plaintext, sessionKey) {
-  const nonce = crypto.randomBytes(12);
-  const cipher = crypto.createCipheriv('aes-256-gcm', sessionKey, nonce);
-  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-  const tag = cipher.getAuthTag(); // 16-byte GCM authentication tag
-  return {
-    nonce: nonce.toString('base64url'),
-    // Append the GCM tag to the ciphertext so decryptBox can locate it.
-    ciphertext: Buffer.concat([encrypted, tag]).toString('base64url'),
-  };
-}
-
-/**
- * Decrypt an AES-256-GCM box produced by encryptBox (or the browser's equivalent).
- * @returns Decrypted UTF-8 string, or null if authentication fails.
- */
-function decryptBox(nonceB64, ciphertextB64, sessionKey) {
-  try {
-    const nonce = Buffer.from(nonceB64, 'base64url');
-    const data = Buffer.from(ciphertextB64, 'base64url');
-    if (data.length < 16) return null; // too short to contain tag
-    const tag = data.subarray(data.length - 16);
-    const ciphertext = data.subarray(0, data.length - 16);
-    const decipher = crypto.createDecipheriv('aes-256-gcm', sessionKey, nonce);
-    decipher.setAuthTag(tag);
-    const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
-    return plain;
-  } catch {
-    return null; // authentication failed — drop the message
-  }
-}
+// Implemented in ./lib/remoteE2eCrypto.cjs (shared with the desktop client role).
+const { generateE2EKeyPair, deriveSessionKey, deriveSas, encryptBox, decryptBox } = require('./lib/remoteE2eCrypto.cjs');
 
 // ─── Module state ────────────────────────────────────────────────────────────
 
@@ -185,12 +87,10 @@ let _destroyed = false; // set at app shutdown to stop reconnect loops
 
 // E2E session state — reset on each new WS connection.
 // .state: 'idle' | 'pending_sas' | 'authenticated' | 'failed'
-let _e2e = makeState();
-// Browser SPKI pubkey (base64url) that produced the current _e2e session, and the
-// deviceId it was received on — tracked so a manual SAS confirmation can pin it to
-// that device's `verifiedPeerPubKey` for auto-trust on future reconnects.
-let _e2ePeerPubKey = null;
-let _e2eDeviceId = null;
+// One record per connected client (keyed by relay-stamped fromConn, else 'legacy').
+// Each holds its own ECDH session key + SAS state, the browser pubkey that produced
+// it, and the deviceId it arrived on (for TOFU pinning on manual SAS confirmation).
+const _clients = createClientSessions();
 
 // ─── Config helpers ───────────────────────────────────────────────────────────
 
@@ -242,14 +142,14 @@ async function saveConfig(data) {
 
 // ─── Audit log ────────────────────────────────────────────────────────────────
 
-// Format: <ISO>  <type>  deviceId=<id>  msgId=<uuid>  result=ok|error:<code>
+// Format: <ISO>  <type>  deviceId=<id>  client=<clientId|connKey|->  msgId=<uuid>  result=ok|error:<code>
 // NEVER log token values or payload content.
-async function auditLog(ts, type, deviceId, msgId, result) {
+async function auditLog(ts, type, deviceId, msgId, result, client) {
   try {
     const ymd = ts.slice(0, 10);
     const logPath = path.join(AUDIT_LOG_DIR, `remote-audit-${ymd}.log`);
     const clean = (s) => String(s ?? '').replace(/[\r\n\t]+/g, ' ').slice(0, 200);
-    const line = `${ts}  ${clean(type)}  deviceId=${clean(deviceId) || '-'}  msgId=${clean(msgId) || '-'}  result=${result}\n`;
+    const line = `${ts}  ${clean(type)}  deviceId=${clean(deviceId) || '-'}  client=${clean(client && (client.clientId || client.key)) || '-'}  msgId=${clean(msgId) || '-'}  result=${result}\n`;
     const handle = await fsp.open(logPath, 'a', 0o600);
     try {
       await handle.write(line);
@@ -317,27 +217,73 @@ async function getDeviceTicket(deviceToken) {
 
 // ─── E2E state helpers ────────────────────────────────────────────────────────
 
-function resetE2e(state = 'idle') {
-  _e2e = makeState(state);
-  _e2ePeerPubKey = null;
-  _e2eDeviceId = null;
+// Tear down every client session (connection-level reset).
+function resetE2e() {
+  teardownAllClients();
+}
+
+// Mark one client's session failed without touching any other client.
+function failClient(client) {
+  client.e2e = makeState('failed');
+  client.peerPubKey = null;
+  client.deviceId = null;
+}
+
+function makeClientlessState() {
+  return { e2e: makeState() };
+}
+
+function anyAuthenticated() {
+  return _clients.authenticated().length > 0;
+}
+
+// Every client currently awaiting SAS confirmation.
+function pendingClients() {
+  return _clients.values().filter((r) => r.e2e.state === 'pending_sas');
+}
+
+const MAX_PINNED_PEER_KEYS = 20;
+
+// True when `pubKey` is pinned on `device` (new list, or the legacy single key — read-only compat).
+function isPinnedPeerKey(device, pubKey) {
+  if (!pubKey) return false;
+  if (device.verifiedPeerPubKey && device.verifiedPeerPubKey === pubKey) return true;
+  return Array.isArray(device.verifiedPeerPubKeys) && device.verifiedPeerPubKeys.some((p) => p && p.pubKey === pubKey);
+}
+
+// Append a pin (never removing another client's), dedupe by pubKey, keep the newest MAX.
+function addPinnedPeerKey(device, pubKey, clientId) {
+  const prev = Array.isArray(device.verifiedPeerPubKeys) ? device.verifiedPeerPubKeys : [];
+  const next = prev.filter((p) => p && p.pubKey !== pubKey);
+  next.push({ pubKey, clientId: clientId ?? null, pinnedAt: new Date().toISOString() });
+  return next.slice(-MAX_PINNED_PEER_KEYS);
 }
 
 // ─── WebSocket lifecycle ──────────────────────────────────────────────────────
 
 // Single source of truth for the status payload shape shared by the
 // broadcast push (webRemote:status) and the get-status IPC pull — both must
-// report the same connected/e2e/device view of `cfg` + `_ws`/`_e2e` module state.
+// report the same connected/e2e/device view of `cfg` + `_ws`/`_clients` module state.
 function computeStatus(cfg) {
   const connected = _ws !== null && _ws.readyState === WebSocket.OPEN;
+  const authed = _clients.authenticated()[0] || null;
+  const pending = _clients.values().find((r) => r.e2e.state === 'pending_sas') || null;
+  const shown = authed || pending || _clients.values()[0] || null;
+  const e2eState = shown ? shown.e2e.state : 'idle';
   return {
     enabled: cfg.remoteEnabled,
     remoteControlEnabled: cfg.remoteControlEnabled ?? false,
     connected,
-    e2eActive: connected && _e2e.sessionKey !== null,
-    e2eAuthenticated: connected && _e2e.state === 'authenticated',
-    e2eState: connected ? _e2e.state : 'idle',
-    pendingSas: connected && _e2e.state === 'pending_sas' ? _e2e.pendingSas : null,
+    e2eActive: connected && _clients.values().some((r) => r.e2e.sessionKey !== null),
+    e2eAuthenticated: connected && authed !== null,
+    e2eState: connected ? e2eState : 'idle',
+    pendingSas: connected && !authed && pending ? pending.e2e.pendingSas : null,
+    clients: _clients.values().map((r) => ({
+      key: r.key,
+      clientId: r.clientId ?? null,
+      state: r.e2e.state,
+      pendingSas: r.e2e.state === 'pending_sas' ? r.e2e.pendingSas : null,
+    })),
     devices: (cfg.devices || []).map(({ deviceId, deviceName, issuedAt, lastConnectedAt }) => ({
       deviceId, deviceName, issuedAt, lastConnectedAt,
     })),
@@ -481,7 +427,7 @@ async function connect() {
     broadcastStatus();
     // v2: begin pushing the live session list once connected.
     // Reset diff-guard so the new client always receives a full session-list push.
-    _lastSessionListJson = null;
+    for (const c of _clients.values()) c.lastSessionListJson = null;
     startSessionListPush();
   });
 
@@ -526,6 +472,7 @@ async function connect() {
 }
 
 async function handleTokenRevoked(deviceId) {
+  teardownAllClients();
   logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'token revoked', meta: { deviceId } });
   const cfg = await loadConfig();
   const devices = (cfg.devices || []).filter((d) => d.deviceId !== deviceId);
@@ -547,24 +494,48 @@ const SESSION_INIT_TAIL_BYTES = 512 * 1024; // bound the initial read
 
 const _sessionWatchers = new Map(); // tabId → watcher
 let _sessionListTimer = null;
-let _lastSessionListJson = null; // diff-guard: skip push when snapshot unchanged
 
-/** Push an unsolicited event to the browser(s). Encrypts when an E2E key is active. */
-function pushEvent(type, payload) {
+/** Push an unsolicited event to ONE client, E2E-encrypted with its key and unicast via toConn. */
+function pushEventTo(client, type, payload) {
   if (!_ws || _ws.readyState !== WebSocket.OPEN) return;
+  if (!client || client.e2e.state !== 'authenticated' || !client.e2e.sessionKey) return;
   const inner = { type, id: crypto.randomUUID(), payload, ts: Date.now() };
   try {
-    if (_e2e.sessionKey) {
-      const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), _e2e.sessionKey);
-      _ws.send(JSON.stringify({ type: 'e2e:box', id: inner.id, payload: { nonce, ciphertext }, ts: Date.now() }));
-    } else {
-      _ws.send(JSON.stringify(inner));
-    }
+    const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), client.e2e.sessionKey);
+    const out = { type: 'e2e:box', id: inner.id, payload: { nonce, ciphertext }, ts: Date.now() };
+    if (client.key !== LEGACY_CLIENT_KEY) out.toConn = client.key;
+    _ws.send(JSON.stringify(out));
   } catch (e) {
     logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'pushEvent failed', meta: { type, error: e?.message } });
   }
 }
 
+/** Authenticated clients subscribed to a tab's session state/summary. */
+function subscribersOf(tabId) {
+  return _clients.authenticated().filter((c) => c.subscriptions.has(tabId));
+}
+
+/** Stop every shared session watcher that no client subscribes to any more. */
+function pruneSessionWatchers() {
+  for (const tabId of Array.from(_sessionWatchers.keys())) {
+    if (!_clients.values().some((c) => c.subscriptions.has(tabId))) stopSessionWatch(tabId);
+  }
+}
+
+/** Tear down one client (its PTY streams + subscriptions) without touching others. */
+function teardownClient(key) {
+  const rec = _clients.teardown(key);
+  pruneSessionWatchers();
+  return rec;
+}
+
+/** Tear down every client — no client keeps a PTY stream or subscription afterwards. */
+function teardownAllClients() {
+  const n = _clients.teardownAll();
+  pruneSessionWatchers();
+  return n;
+}
+
 /** Extract concatenated text from an assistant transcript line, or '' if none. */
 function extractAssistantText(raw) {
   const msg = raw?.message || raw;
@@ -660,8 +631,8 @@ async function pollSessionWatcher(w) {
   if (nextState && nextState !== w.state) {
     w.state = nextState;
     // Guard: don't push state if SAS not yet confirmed (watcher may outlive an auth reset).
-    if (_e2e.state === 'authenticated') {
-      pushEvent('event:session:state', { tabId: w.tabId, state: w.state, since: Date.now() });
+    for (const c of subscribersOf(w.tabId)) {
+      pushEventTo(c, 'event:session:state', { tabId: w.tabId, state: w.state, since: Date.now() });
     }
   }
   if (newAssistantText && newMsgId !== w.lastMsgId) {
@@ -712,6 +683,41 @@ function stopAllSessionWatches() {
   if (_sessionListTimer) { clearInterval(_sessionListTimer); _sessionListTimer = null; }
 }
 
+/**
+ * Pure builder for the phone's session list: one project entry per tab, then
+ * each tab's ACTIVE Epics (from active-index.json via readIndex). Never throws.
+ */
+function buildRemoteSessionList(tabs, readIndex) {
+  const out = [];
+  const seenEpics = new Set();
+  for (const tab of Array.isArray(tabs) ? tabs : []) {
+    if (!tab) continue;
+    const project = tab.label || path.basename(tab.cwd || '');
+    out.push({ kind: 'project', tabId: tab.sessionId, cwd: tab.cwd, title: tab.label || tab.cwd, project });
+    let sessions = null;
+    try { sessions = readIndex(tab.cwd)?.sessions; } catch { sessions = null; }
+    if (!sessions || typeof sessions !== 'object') continue;
+    for (const epic of Object.values(sessions)) {
+      if (!epic || epic.status !== 'active') continue;
+      if (typeof epic.claudeSessionId !== 'string' || !epic.claudeSessionId) continue;
+      if (seenEpics.has(epic.id)) continue;
+      seenEpics.add(epic.id);
+      const firstLine = typeof epic.goalText === 'string' ? epic.goalText.split('\n')[0].trim().slice(0, 80).trim() : '';
+      out.push({
+        kind: 'epic',
+        tabId: epic.claudeSessionId,
+        epicId: epic.id,
+        cwd: epic.worktree?.dir || epic.cwd,
+        title: firstLine || epic.id,
+        project,
+        tag: epic.tag,
+        agentType: epic.agentType,
+      });
+    }
+  }
+  return out;
+}
+
 /** Push the current session list (reuses sessionsStore — the canonical source). */
 async function pushSessionList() {
   try {
@@ -723,23 +729,24 @@ async function pushSessionList() {
     // Don't push before SAS is confirmed — session cwds/titles are sensitive user data.
     // A relay that completes e2e:hello before the user confirms the SAS would otherwise
     // receive the full session list immediately (same threat SAS_GATED_READS blocks for
-    // cmd:sessions:load). Guard here so _lastSessionListJson is not poisoned either.
-    if (_e2e.state !== 'authenticated') return;
+    // cmd:sessions:load). Guard here so client.lastSessionListJson is not poisoned either.
+    if (!anyAuthenticated()) return;
     const sessionsStore = require('./sessionsStore.cjs');
     const data = await sessionsStore.load();
-    // Normalize persisted tabs → SessionMeta. tabId === sessionId so it
+    // Tabs + their ACTIVE Epics → SessionMeta. tabId === claude sessionId so it
     // matches the transcript JSONL name used by cmd:session:subscribe.
-    const sessions = (data?.tabs ?? []).map((t) => ({
-      tabId: t.sessionId,
-      cwd: t.cwd,
-      title: t.label || t.cwd,
-      state: _sessionWatchers.get(t.sessionId)?.state ?? null,
+    const { readActiveIndex } = require('./lib/epicMint.cjs');
+    const sessions = buildRemoteSessionList(data?.tabs ?? [], readActiveIndex).map((s) => ({
+      ...s,
+      state: _sessionWatchers.get(s.tabId)?.state ?? null,
     }));
     const payload = { sessions, activeTabId: data?.activeTabId ?? null };
     const json = JSON.stringify(payload);
-    if (json === _lastSessionListJson) return;
-    _lastSessionListJson = json;
-    pushEvent('event:session:list', payload);
+    for (const c of _clients.authenticated()) {
+      if (json === c.lastSessionListJson) continue;
+      c.lastSessionListJson = json;
+      pushEventTo(c, 'event:session:list', payload);
+    }
   } catch (e) {
     logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'pushSessionList failed', meta: { error: e?.message } });
   }
@@ -764,14 +771,16 @@ const SUMMARY_MIN_CHARS = 280; // below this, push raw — not worth an API call
  * completed turn per subscribed tab (~$1/$5 per 1M tokens).
  */
 async function maybeSummarize(w) {
-  // Guard: don't push summaries (session transcript content) before SAS confirmed.
-  if (_e2e.state !== 'authenticated') return;
+  // Guard: summaries (session transcript content) go only to SAS-confirmed subscribers.
+  if (subscribersOf(w.tabId).length === 0) return;
   const text = w.lastAssistantText;
   if (!text) return;
   const ofMessageId = w.lastMsgId;
 
   if (text.length < SUMMARY_MIN_CHARS) {
-    pushEvent('event:session:summary', { tabId: w.tabId, summary: text, ofMessageId, model: 'raw', ts: Date.now() });
+    for (const c of subscribersOf(w.tabId)) {
+      pushEventTo(c, 'event:session:summary', { tabId: w.tabId, summary: text, ofMessageId, model: 'raw', ts: Date.now() });
+    }
     return;
   }
 
@@ -779,23 +788,25 @@ async function maybeSummarize(w) {
   if (degraded) {
     logs.writeLine({ scope: 'webRemote', level: 'warn', message: `summary degraded: ${degraded}`, meta: {} });
   }
-  pushEvent('event:session:summary', {
-    tabId: w.tabId, summary, ofMessageId, model,
-    ...(degraded ? { degraded } : {}),
-    ts: Date.now(),
-  });
+  for (const c of subscribersOf(w.tabId)) {
+    pushEventTo(c, 'event:session:summary', {
+      tabId: w.tabId, summary, ofMessageId, model,
+      ...(degraded ? { degraded } : {}),
+      ts: Date.now(),
+    });
+  }
 }
 
 /**
- * Shared finish-up for any path that transitions _e2e into 'authenticated'
+ * Shared finish-up for any path that transitions a client's e2e state into 'authenticated'
  * (manual SAS confirmation or pinned-key auto-trust): log, broadcast the new
  * status, and flush the session list immediately rather than waiting for the
  * next SESSION_LIST_PUSH_MS tick.
  */
-function finalizeE2eAuthenticated(logMessage) {
+function finalizeE2eAuthenticated(logMessage, client) {
   logs.writeLine({ scope: 'webRemote', level: 'info', message: logMessage });
   broadcastStatus();
-  _lastSessionListJson = null;
+  if (client) client.lastSessionListJson = null;
   pushSessionList().catch(() => {});
 }
 
@@ -839,6 +850,22 @@ async function handleMessage(raw, device) {
     return;
   }
 
+  // Relay notice that a browser closed: tear down only that client. Never a command.
+  if (type === 'event:client:disconnected') {
+    const key = _clients.clientKeyOf({ fromConn: envelope.fromConn ?? payload?.fromConn });
+    if (key !== LEGACY_CLIENT_KEY) {
+      const reason = envelope.reason ?? payload?.reason;
+      const rec = teardownClient(key);
+      await auditLog(new Date().toISOString(), 'client:disconnected', device.deviceId, id,
+        `reason=${String(reason ?? '-').replace(/[^\w:.-]/g, '_').slice(0, 40)}`, rec || { key });
+      broadcastStatus();
+    }
+    return;
+  }
+
+  // Per-client E2E record, keyed by the relay-stamped fromConn (else 'legacy').
+  const client = _clients.getOrCreate(_clients.clientKeyOf(envelope), { clientId: envelope.fromClientId ?? null });
+
   // ── E2E key exchange ───────────────────────────────────────────────────────
   // Browser sends e2e:hello with its ephemeral P-256 public key (SPKI base64url).
   // We compute the shared session key and acknowledge.
@@ -883,8 +910,8 @@ async function handleMessage(raw, device) {
       }
     } catch (e) {
       logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'e2e:hello peer key validation failed — session dropped', meta: { error: e?.message } });
-      await auditLog(new Date().toISOString(), 'e2e:hello', device.deviceId, undefined, 'error:invalid_peer_key');
-      resetE2e('failed'); // surface key-validation failure to UI — user must reconnect
+      await auditLog(new Date().toISOString(), 'e2e:hello', device.deviceId, undefined, 'error:invalid_peer_key', client);
+      failClient(client); // surface key-validation failure to UI — user must reconnect
       broadcastStatus();
       return;
     }
@@ -896,31 +923,31 @@ async function handleMessage(raw, device) {
       } catch (sasErr) {
         // SAS derivation failed — session cannot be verified by the user.
         // Mark failed so confirm-sas returns ok:false and the UI prompts retry.
-        resetE2e('failed');
+        failClient(client);
         logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'E2E SAS derivation failed — session marked failed', meta: { error: sasErr?.message } });
         broadcastStatus();
         return;
       }
-      _e2ePeerPubKey = browserPubKey;
-      _e2eDeviceId = device.deviceId;
+      client.peerPubKey = browserPubKey;
+      client.deviceId = device.deviceId;
       // TOFU pinning: if this exact (deviceId, browserPubKey) pair was already
       // manually SAS-confirmed once, skip pending_sas and auto-authenticate — the
       // user already verified this browser. A different/first-seen pubKey always
       // falls through to the manual pending_sas flow below, unchanged.
-      if (device.verifiedPeerPubKey && device.verifiedPeerPubKey === browserPubKey) {
-        _e2e = makeState('authenticated', sessionKey, null);
-        finalizeE2eAuthenticated('E2E session auto-authenticated — pinned browser key matched');
-        respond(id, undefined, 'e2e:ready');
+      if (isPinnedPeerKey(device, browserPubKey)) {
+        client.e2e = makeState('authenticated', sessionKey, null);
+        finalizeE2eAuthenticated('E2E session auto-authenticated — pinned browser key matched', client);
+        respond(id, undefined, 'e2e:ready', client);
         return;
       }
-      _e2e = makeState('pending_sas', sessionKey, pendingSas);
+      client.e2e = makeState('pending_sas', sessionKey, pendingSas);
       logs.writeLine({ scope: 'webRemote', level: 'info', message: 'E2E session key established — SAS pending confirmation' });
       broadcastStatus();
       // Acknowledge with e2e:ready (unencrypted — session just started)
-      respond(id, undefined, 'e2e:ready');
+      respond(id, undefined, 'e2e:ready', client);
     } catch (e) {
       logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'E2E key derivation failed', meta: { error: e?.message } });
-      resetE2e('failed');
+      failClient(client);
       broadcastStatus();
     }
     return;
@@ -928,13 +955,13 @@ async function handleMessage(raw, device) {
 
   // ── Decrypt e2e:box messages ──────────────────────────────────────────────
   if (type === 'e2e:box') {
-    if (!_e2e.sessionKey) {
+    if (!client.e2e.sessionKey) {
       logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'e2e:box received but no session key — dropping' });
       return;
     }
     const { nonce, ciphertext } = payload || {};
     if (!nonce || !ciphertext) return;
-    const plaintext = decryptBox(nonce, ciphertext, _e2e.sessionKey);
+    const plaintext = decryptBox(nonce, ciphertext, client.e2e.sessionKey);
     if (!plaintext) {
       logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'e2e:box decryption failed (auth tag mismatch)' });
       return;
@@ -947,7 +974,7 @@ async function handleMessage(raw, device) {
       return;
     }
     // Dispatch as if it arrived unencrypted
-    await dispatchEnvelope(inner, device);
+    await dispatchEnvelope(inner, device, client);
     return;
   }
 
@@ -955,14 +982,14 @@ async function handleMessage(raw, device) {
   if (!type.startsWith('cmd:')) return;
   // After E2E is established, reject plaintext commands — a malicious relay cannot
   // silently downgrade the session by stripping e2e:hello (PENTEST.md §H1).
-  if (_e2e.sessionKey) {
+  if (client.e2e.sessionKey) {
     logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'plaintext cmd rejected — e2e session active' });
     return;
   }
-  await dispatchEnvelope(envelope, device);
+  await dispatchEnvelope(envelope, device, client);
 }
 
-async function dispatchEnvelope(envelope, device) {
+async function dispatchEnvelope(envelope, device, client) {
   const { type, id, payload } = envelope;
   if (typeof type !== 'string' || !type.startsWith('cmd:')) return;
 
@@ -971,22 +998,22 @@ async function dispatchEnvelope(envelope, device) {
   // Kill switch — re-reads config with 1s TTL
   const cfg = await loadConfig();
   if (!cfg.remoteEnabled) {
-    await auditLog(ts, type, device.deviceId, id, 'error:disabled');
-    respond(id, { error: 'rejected' }); // opaque — reason stays in audit log only
+    await auditLog(ts, type, device.deviceId, id, 'error:disabled', client);
+    respond(id, { error: 'rejected' }, undefined, client); // opaque — reason stays in audit log only
     return;
   }
 
   // Allowlist check — reject unknown cmd:* types with opaque error (oracle prevention)
   if (!ALLOWED_COMMANDS.has(type)) {
-    await auditLog(ts, type, device.deviceId, id, 'error:not_allowed');
-    respond(id, { error: 'rejected' });
+    await auditLog(ts, type, device.deviceId, id, 'error:not_allowed', client);
+    respond(id, { error: 'rejected' }, undefined, client);
     return;
   }
 
   // MUTATE tier gate — write/exec commands require remoteControlEnabled=true (default false)
   if (MUTATE_COMMANDS.has(type) && !cfg.remoteControlEnabled) {
-    await auditLog(ts, type, device.deviceId, id, 'error:not_allowed');
-    respond(id, { error: 'rejected' }); // opaque — reason stays in audit log only
+    await auditLog(ts, type, device.deviceId, id, 'error:not_allowed', client);
+    respond(id, { error: 'rejected' }, undefined, client); // opaque — reason stays in audit log only
     return;
   }
 
@@ -994,27 +1021,27 @@ async function dispatchEnvelope(envelope, device) {
   // user confirms the SAS on the desktop. This prevents a compromised relay
   // from exfiltrating session lists, PRDs, run logs, or transcript summaries
   // by completing the ECDH handshake without the user's knowledge.
-  if ((MUTATE_COMMANDS.has(type) || SAS_GATED_READS.has(type)) && _e2e.state !== 'authenticated') {
-    await auditLog(ts, type, device.deviceId, id, 'error:e2e_not_authenticated');
-    respond(id, { error: 'rejected' }); // opaque — reason stays in audit log only
+  if ((MUTATE_COMMANDS.has(type) || SAS_GATED_READS.has(type)) && client.e2e.state !== 'authenticated') {
+    await auditLog(ts, type, device.deviceId, id, 'error:e2e_not_authenticated', client);
+    respond(id, { error: 'rejected' }, undefined, client); // opaque — reason stays in audit log only
     return;
   }
 
   // Dispatch
   let result;
   try {
-    result = await dispatchCommand(type, payload ?? {});
-    await auditLog(ts, type, device.deviceId, id, 'ok');
+    result = await dispatchCommand(type, payload ?? {}, client);
+    await auditLog(ts, type, device.deviceId, id, 'ok', client);
   } catch (e) {
     const code = e?.name === 'ZodError' ? 'schema_invalid' : 'dispatch_error';
-    await auditLog(ts, type, device.deviceId, id, `error:${code}`);
+    await auditLog(ts, type, device.deviceId, id, `error:${code}`, client);
     result = { error: 'rejected' }; // opaque on-wire — reason stays in audit log only
   }
 
-  respond(id, result);
+  respond(id, result, undefined, client);
 }
 
-function respond(msgId, payload, typeOverride) {
+function respond(msgId, payload, typeOverride, client) {
   if (!_ws || _ws.readyState !== WebSocket.OPEN) return;
   const responseType = typeOverride || (msgId ? `resp:${msgId}` : undefined);
   if (!responseType) return;
@@ -1027,23 +1054,28 @@ function respond(msgId, payload, typeOverride) {
   };
 
   try {
-    // Encrypt the response if a session key is active.
-    if (_e2e.sessionKey && !typeOverride) {
-      const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), _e2e.sessionKey);
-      _ws.send(JSON.stringify({
-        type: 'e2e:box',
-        id: msgId,
-        payload: { nonce, ciphertext },
-        ts: Date.now(),
-      }));
-    } else {
-      _ws.send(JSON.stringify(inner));
-    }
+    // Encrypt with the requesting client's key; unicast via toConn for relay-stamped clients.
+    const out = client && client.e2e.sessionKey && !typeOverride
+      ? (() => {
+          const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), client.e2e.sessionKey);
+          return { type: 'e2e:box', id: msgId, payload: { nonce, ciphertext }, ts: Date.now() };
+        })()
+      : inner;
+    if (client && client.key !== LEGACY_CLIENT_KEY) out.toConn = client.key;
+    _ws.send(JSON.stringify(out));
   } catch (e) {
     logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'respond send failed', meta: { error: e?.message } });
   }
 }
 
+function stopClientPtyStream(client, tabId) {
+  const unsub = client.ptyStreams.get(tabId);
+  client.ptyStreams.delete(tabId);
+  if (unsub) {
+    try { unsub(); } catch { /* listener already gone */ }
+  }
+}
+
 // Lazy-loaded dispatch map — avoids circular require at module load time.
 let _dispatchMap = null;
 
@@ -1059,12 +1091,22 @@ function getDispatchMap() {
     'cmd:sessions:load': async () =>
       sessionsStore.load(),
 
+    'cmd:sessions:list': async () => {
+      const { readActiveIndex } = require('./lib/epicMint.cjs');
+      const data = await sessionsStore.load();
+      return {
+        sessions: buildRemoteSessionList(data?.tabs ?? [], readActiveIndex),
+        activeTabId: data?.activeTabId ?? null,
+      };
+    },
+
     'cmd:sessions:save': async (payload) => {
       const parsed = schemas.sessionsPayload.parse(payload);
       return sessionsStore.save(parsed);
     },
 
-    'cmd:pty:spawn': async (payload) => {
+    'cmd:pty:spawn': async (payload, reqClient) => {
+      const client = reqClient || _clients.getOrCreate(LEGACY_CLIENT_KEY);
       const parsed = schemas.ptySpawn.parse(payload);
       // Path safety — validatePath rejects anything outside home dir.
       validatePath(parsed.cwd);
@@ -1072,7 +1114,25 @@ function getDispatchMap() {
       // remotely-controlled 8 KiB string to spawn is a landmine if pty.cjs
       // ever uses it. Remote callers have no legitimate need for it.
       const { startupCommand: _ignored, ...safePayload } = parsed;
-      return ptyManager.spawn(safePayload);
+      const result = await ptyManager.spawn(safePayload);
+      // Stream output to the peer — replaces any prior subscription for this tab.
+      // Chunk contents are sensitive: never logged.
+      const tabId = safePayload.tabId;
+      stopClientPtyStream(client, tabId);
+      const unsub = ptyManager.addOutputListener(
+        tabId,
+        (_id, data) => {
+          if (client.e2e.state !== 'authenticated' || !loadConfigSync().remoteEnabled) return;
+          pushEventTo(client, 'event:pty:data', { tabId, data });
+        },
+        (_id, info) => {
+          if (client.ptyStreams.get(tabId) === unsub) client.ptyStreams.delete(tabId);
+          if (client.e2e.state !== 'authenticated' || !loadConfigSync().remoteEnabled) return;
+          pushEventTo(client, 'event:pty:exit', { tabId, exitCode: info?.exitCode, signal: info?.signal });
+        },
+      );
+      client.ptyStreams.set(tabId, unsub);
+      return result;
     },
 
     'cmd:pty:write': async (payload) => {
@@ -1086,8 +1146,11 @@ function getDispatchMap() {
       return { ok: true };
     },
 
-    'cmd:pty:kill': async (payload) => {
+    'cmd:pty:kill': async (payload, reqClient) => {
       const parsed = schemas.ptyTabId.parse(payload);
+      // Kill ends the PTY itself, so every client's stream for it ends.
+      for (const c of _clients.values()) stopClientPtyStream(c, parsed.tabId);
+      void reqClient;
       ptyManager.kill(parsed.tabId);
       return { ok: true };
     },
@@ -1100,17 +1163,24 @@ function getDispatchMap() {
     'cmd:app:version': async () =>
       app.getVersion(),
 
+    'cmd:app:info': async () =>
+      ({ version: app.getVersion(), platform: process.platform }),
+
     // v2 mobile: start/stop pushing live state + summary for a session.
-    'cmd:session:subscribe': async (payload) => {
+    'cmd:session:subscribe': async (payload, reqClient) => {
+      const client = reqClient || _clients.getOrCreate(LEGACY_CLIENT_KEY);
       const parsed = schemas.sessionSubscribe.parse(payload);
       validatePath(parsed.cwd); // home-dir boundary before any fs access
       startSessionWatch(parsed.tabId, parsed.cwd);
+      client.subscriptions.add(parsed.tabId);
       return { ok: true };
     },
 
-    'cmd:session:unsubscribe': async (payload) => {
+    'cmd:session:unsubscribe': async (payload, reqClient) => {
+      const client = reqClient || _clients.getOrCreate(LEGACY_CLIENT_KEY);
       const parsed = schemas.ptyTabId.parse(payload);
-      stopSessionWatch(parsed.tabId);
+      client.subscriptions.delete(parsed.tabId);
+      pruneSessionWatchers();
       return { ok: true };
     },
 
@@ -1122,16 +1192,43 @@ function getDispatchMap() {
       chatRunner.enqueueExternalPrompt(parsed.tabId, parsed.prompt);
       return { ok: true };
     },
+
+    'cmd:session:options': async () => {
+      const { EpicTagSchema } = require('./lib/promptSessionSchema.cjs');
+      const agentLibrary = require('./agentLibrary.cjs');
+      const macroLibrary = require('./lib/macroLibrary.cjs');
+      const { tabs } = await sessionsStore.load();
+      const personas = await agentLibrary.listPersonas();
+      return {
+        projects: tabs.map((t) => ({ cwd: t.cwd, title: t.label })),
+        agents: personas.map((a) => ({ name: a.name, description: a.description })),
+        tags: EpicTagSchema.options,
+        macros: await macroLibrary.listMacros(),
+      };
+    },
+
+    // Input boundary: cwd must be exactly an open tab's cwd and agentName a
+    // listed persona, checked before the payload goes anywhere near the fs.
+    'cmd:session:create': async (payload) => {
+      const parsed = schemas.remoteSessionCreate.parse(payload);
+      const agentLibrary = require('./agentLibrary.cjs');
+      const { tabs } = await sessionsStore.load();
+      if (!tabs.some((t) => t.cwd === parsed.cwd)) throw new Error('cwd is not an open project');
+      const personas = await agentLibrary.listPersonas();
+      if (!personas.some((a) => a.name === parsed.agentName)) throw new Error('unknown agent');
+      chatRunner.requestExternalNewSession(parsed);
+      return { ok: true };
+    },
   };
 
   return _dispatchMap;
 }
 
-async function dispatchCommand(type, payload) {
+async function dispatchCommand(type, payload, client) {
   const map = getDispatchMap();
   const handler = map[type];
   if (!handler) throw new Error(`no handler for ${type}`);
-  return handler(payload);
+  return handler(payload, client);
 }
 
 // ─── Pairing ─────────────────────────────────────────────────────────────────
@@ -1177,6 +1274,7 @@ async function pair(otp) {
     // Set once a browser's SAS is manually confirmed; TOFU-pinned for auto-trust
     // on future reconnects from the same (deviceId, browserPubKey) pair.
     verifiedPeerPubKey: null,
+    verifiedPeerPubKeys: [],
   }];
 
   await saveConfig({ ...cfg, devices });
@@ -1190,6 +1288,7 @@ async function pair(otp) {
 }
 
 async function revokeDevice(deviceId) {
+  teardownAllClients();
   invalidateConfigCache();
   const cfg = await loadConfig();
   const devices = (cfg.devices || []).filter((d) => d.deviceId !== deviceId);
@@ -1214,6 +1313,7 @@ async function revokeDevice(deviceId) {
  * This is the local-side "kill everything" action (ADR §4.1).
  */
 async function revokeAllDevices() {
+  teardownAllClients();
   const cfg = await loadConfig();
   const revokedCount = (cfg.devices || []).length;
   await saveConfig({ ...cfg, remoteEnabled: false, devices: [] });
@@ -1237,20 +1337,34 @@ function registerRemoteHandlers() {
   // User confirmed that the SAS shown on both desktop and browser match.
   // Returns ok:false if the session is not in the pending_sas state (e.g. key
   // missing, already failed, already authenticated, or reconnected).
-  ipcMain.handle('webRemote:confirm-sas', async () => {
-    const { ok, error, next } = confirmSasLogic(_e2e);
+  ipcMain.handle('webRemote:confirm-sas', validated(schemas.webRemoteConfirmSas, async (arg) => {
+    const clientKey = arg?.clientKey;
+    let target;
+    if (clientKey !== undefined) {
+      target = _clients.get(clientKey) || makeClientlessState();
+    } else {
+      const pending = pendingClients();
+      if (pending.length > 1) {
+        logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'confirm-sas rejected — multiple clients pending', meta: { pending: pending.length } });
+        return { ok: false, error: 'ambiguous_pending_sas' };
+      }
+      target = pending[0] || _clients.get(LEGACY_CLIENT_KEY) || makeClientlessState();
+    }
+    const { ok, error, next } = confirmSasLogic(target.e2e);
     if (!ok) {
-      logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'confirm-sas rejected — wrong state', meta: { state: _e2e.state, error } });
+      logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'confirm-sas rejected — wrong state', meta: { state: target.e2e.state, error } });
       return { ok: false, error };
     }
-    _e2e = next;
+    target.e2e = next;
     // Pin this browser's pubkey to the device so future reconnects with the same
-    // key auto-authenticate (see e2e:hello above) instead of re-prompting forever.
-    if (_e2ePeerPubKey && _e2eDeviceId) {
+    // key auto-authenticate (see e2e:hello above). Appends; other clients' pins stay.
+    if (target.peerPubKey && target.deviceId) {
       try {
         const cfg = await loadConfig();
         const devices = (cfg.devices || []).map((d) =>
-          d.deviceId === _e2eDeviceId ? { ...d, verifiedPeerPubKey: _e2ePeerPubKey } : d
+          d.deviceId === target.deviceId
+            ? { ...d, verifiedPeerPubKeys: addPinnedPeerKey(d, target.peerPubKey, target.clientId) }
+            : d
         );
         await saveConfig({ ...cfg, devices });
       } catch (e) {
@@ -1260,9 +1374,9 @@ function registerRemoteHandlers() {
     // Flush the session list immediately — the push loop was suppressed while
     // state !== 'authenticated', so the mobile app would otherwise wait up to
     // SESSION_LIST_PUSH_MS for the first useful data.
-    finalizeE2eAuthenticated('E2E session authenticated — SAS confirmed by user');
+    finalizeE2eAuthenticated('E2E session authenticated — SAS confirmed by user', target);
     return { ok: true };
-  });
+  }));
 
   ipcMain.handle('webRemote:enable', async () => {
     const cfg = await loadConfig();
@@ -1290,6 +1404,7 @@ function registerRemoteHandlers() {
   ipcMain.handle('webRemote:disable-control', async () => {
     const cfg = await loadConfig();
     await saveConfig({ ...cfg, remoteControlEnabled: false });
+    teardownAllClients(); // no client keeps a PTY stream once control is off
     broadcastStatus();
     return { ok: true };
   });
@@ -1359,6 +1474,17 @@ module.exports = {
   _internal: {
     handleMessage,
     resetE2e,
-    getE2eState: () => _e2e,
+    getE2eState: (clientKey = LEGACY_CLIENT_KEY) => (_clients.get(clientKey) || { e2e: makeState() }).e2e,
+  },
+  __test: {
+    getDispatchMap,
+    buildRemoteSessionList,
+    setWs: (ws) => { _ws = ws; },
+    invalidateConfigCache,
+    setE2eAuthenticated: (key, clientKey = LEGACY_CLIENT_KEY) => {
+      _clients.getOrCreate(clientKey).e2e = makeState('authenticated', key, null);
+    },
+    revokeAllDevices,
+    streamCount: () => _clients.values().reduce((n, c) => n + c.ptyStreams.size, 0),
   },
 };