claude-code-session-manager 0.108.0 → 0.109.0

package/src/main/remoteClient.cjs

@@ -0,0 +1,305 @@
+'use strict';
+
+// Desktop-to-desktop remote: the CLIENT role. Drives a paired Session Manager
+// agent (webRemote.cjs) over the relay using the same envelope protocol the
+// phone app speaks (web/remote-app/src/ws.ts). No Electron imports — IPC wiring
+// lives elsewhere.
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const { claudeHome } = require('./lib/schedulerPaths.cjs');
+const { writeJsonAtomicSync, readJsonOrSync } = require('./lib/atomicFs.cjs');
+const { generateE2EKeyPair, deriveSessionKey, deriveSas, encryptBox, decryptBox } = require('./lib/remoteE2eCrypto.cjs');
+const { ALLOWED_COMMANDS } = require('./ipcSchemas.cjs');
+
+// Hard-coded wss:// — same relay URL as webRemote.cjs, no plaintext downgrade.
+const RELAY_WSS_URL = 'wss://bilko.run/projects/session-manager/relay';
+const SEND_TIMEOUT_MS = 15_000;
+const WS_OPEN = 1;
+
+/** Default relay auth: the bilko.run relay has no desktop-client auth yet. */
+const defaultRelayAuth = {
+  async getBrowserTicket() { throw new Error('relay_client_auth_unavailable'); },
+  async getDevicePubKey() { throw new Error('relay_client_auth_unavailable'); },
+};
+
+function defaultWsFactory(url) {
+  const WebSocket = require('ws');
+  return new WebSocket(url, { rejectUnauthorized: true });
+}
+
+function defaultConfigPath() {
+  return path.join(claudeHome(), 'session-manager', 'remote-peers.json');
+}
+
+function createRemoteClient({ relayAuth = defaultRelayAuth, wsFactory = defaultWsFactory, configPath } = {}) {
+  const file = configPath || defaultConfigPath();
+  /** @type {Map<string, any>} peerId -> runtime state */
+  const runtime = new Map();
+  /** @type {Map<string, Set<Function>>} */
+  const subscribers = new Map();
+
+  function loadPeers() {
+    const data = readJsonOrSync(file, { peers: [] });
+    return Array.isArray(data?.peers) ? data.peers : [];
+  }
+  function savePeers(peers) {
+    writeJsonAtomicSync(file, { peers }, { mode: 0o600 });
+  }
+  function getPeer(peerId) {
+    return loadPeers().find((p) => p.peerId === peerId) || null;
+  }
+  function updatePeer(peerId, patch) {
+    const peers = loadPeers();
+    const i = peers.findIndex((p) => p.peerId === peerId);
+    if (i < 0) return;
+    peers[i] = { ...peers[i], ...patch };
+    savePeers(peers);
+  }
+
+  function rt(peerId) {
+    let s = runtime.get(peerId);
+    if (!s) {
+      s = {
+        status: 'idle', reason: null, sas: null, ws: null, sessionKey: null,
+        devicePubKey: null, pending: new Map(), attempt: 0,
+      };
+      runtime.set(peerId, s);
+    }
+    return s;
+  }
+
+  function failPending(s, err) {
+    for (const p of s.pending.values()) { clearTimeout(p.timer); p.reject(err); }
+    s.pending.clear();
+  }
+
+  function fail(peerId, reason) {
+    const s = rt(peerId);
+    s.status = 'failed';
+    s.reason = reason;
+    s.sessionKey = null;
+    s.sas = null;
+    failPending(s, new Error(reason));
+    const ws = s.ws;
+    s.ws = null;
+    try { ws?.close(); } catch { /* already closed */ }
+  }
+
+  function addPeer({ peerId, deviceId, machineName }) {
+    if (!peerId || !deviceId) throw new Error('peerId and deviceId required');
+    const peers = loadPeers();
+    const existing = peers.find((p) => p.peerId === peerId);
+    if (existing) return existing;
+    const kp = generateE2EKeyPair();
+    const peer = {
+      peerId,
+      deviceId,
+      machineName: machineName || '',
+      pairedAt: new Date().toISOString(),
+      clientPrivateKey: kp.e2ePrivateKey,
+      clientPublicKey: kp.e2ePublicKey,
+      verifiedDevicePubKey: null,
+    };
+    peers.push(peer);
+    savePeers(peers);
+    return peer;
+  }
+
+  function listPeers() {
+    // Never expose the private key to callers.
+    return loadPeers().map(({ clientPrivateKey, ...rest }) => rest);
+  }
+
+  function getStatus(peerId) {
+    const s = rt(peerId);
+    return { status: s.status, reason: s.reason, sas: s.sas };
+  }
+
+  function rawSend(ws, msg) {
+    ws.send(JSON.stringify(msg));
+  }
+
+  function handleInner(peerId, s, inner) {
+    if (!inner || typeof inner.type !== 'string') return;
+    if (inner.type.startsWith('resp:')) {
+      const p = s.pending.get(inner.id);
+      if (!p) return;
+      s.pending.delete(inner.id);
+      clearTimeout(p.timer);
+      p.resolve(inner.payload);
+      return;
+    }
+    if (inner.type.startsWith('event:')) {
+      for (const cb of subscribers.get(peerId) || []) {
+        try { cb(inner); } catch { /* subscriber errors never break the socket */ }
+      }
+    }
+  }
+
+  function handleMessage(peerId, s, peer, raw) {
+    let msg;
+    try { msg = JSON.parse(raw.toString()); } catch { return; }
+    if (!msg || typeof msg.type !== 'string') return;
+
+    if (msg.type === 'ping') {
+      if (s.ws && s.ws.readyState === WS_OPEN) rawSend(s.ws, { type: 'pong', id: msg.id, ts: Date.now() });
+      return;
+    }
+    if (msg.type === 'error') {
+      const code = msg.code || msg.payload?.code;
+      if (code === 'token_revoked') fail(peerId, 'token_revoked');
+      return;
+    }
+    if (msg.type === 'auth:ok') {
+      // Relay accepted the ticket: start the E2E handshake.
+      rawSend(s.ws, {
+        type: 'e2e:hello',
+        id: crypto.randomUUID(),
+        deviceId: peer.deviceId,
+        payload: { pubKey: peer.clientPublicKey },
+        ts: Date.now(),
+      });
+      return;
+    }
+    if (msg.type === 'e2e:ready') {
+      if (s.sessionKey) return;
+      try {
+        s.sessionKey = deriveSessionKey(peer.clientPrivateKey, s.devicePubKey, peer.deviceId);
+        s.sas = deriveSas(peer.clientPrivateKey, s.devicePubKey, peer.deviceId);
+      } catch {
+        fail(peerId, 'e2e_derivation_failed');
+        return;
+      }
+      s.status = peer.verifiedDevicePubKey && peer.verifiedDevicePubKey === s.devicePubKey
+        ? 'authenticated'
+        : 'pending_sas';
+      return;
+    }
+    if (msg.type === 'e2e:box') {
+      if (!s.sessionKey) return;
+      const { nonce, ciphertext } = msg.payload || {};
+      if (!nonce || !ciphertext) return;
+      const plain = decryptBox(nonce, ciphertext, s.sessionKey);
+      if (!plain) return;
+      let inner;
+      try { inner = JSON.parse(plain); } catch { return; }
+      handleInner(peerId, s, inner);
+    }
+  }
+
+  async function connect(peerId) {
+    const peer = getPeer(peerId);
+    if (!peer) throw new Error('unknown_peer');
+    const s = rt(peerId);
+    const attempt = ++s.attempt;
+    try { s.ws?.close(); } catch { /* already closed */ }
+    s.ws = null;
+    s.sessionKey = null;
+    s.sas = null;
+    s.reason = null;
+    s.status = 'connecting';
+
+    let ticket;
+    let devicePubKey;
+    try {
+      ticket = await relayAuth.getBrowserTicket(peer);
+      devicePubKey = await relayAuth.getDevicePubKey(peer.deviceId);
+    } catch (e) {
+      fail(peerId, e?.message || 'relay_auth_failed');
+      return getStatus(peerId);
+    }
+    if (attempt !== s.attempt) return getStatus(peerId); // superseded or removed
+    if (!ticket || !devicePubKey) {
+      fail(peerId, 'relay_auth_failed');
+      return getStatus(peerId);
+    }
+    // TOFU: a changed device key after pinning fails closed, before any socket opens.
+    if (peer.verifiedDevicePubKey && peer.verifiedDevicePubKey !== devicePubKey) {
+      fail(peerId, 'device_key_changed');
+      return getStatus(peerId);
+    }
+    s.devicePubKey = devicePubKey;
+
+    let ws;
+    try {
+      ws = wsFactory(`${RELAY_WSS_URL}?ticket=${encodeURIComponent(ticket)}`);
+    } catch {
+      fail(peerId, 'ws_create_failed');
+      return getStatus(peerId);
+    }
+    s.ws = ws;
+    ws.on('message', (data) => { if (s.ws === ws) handleMessage(peerId, s, peer, data); });
+    ws.on('close', () => {
+      if (s.ws !== ws) return;
+      s.ws = null;
+      s.sessionKey = null;
+      failPending(s, new Error('connection_closed'));
+      if (s.status !== 'failed') { s.status = 'idle'; s.sas = null; }
+    });
+    ws.on('error', () => { if (s.ws === ws) fail(peerId, 'ws_error'); });
+    return getStatus(peerId);
+  }
+
+  function confirmSas(peerId) {
+    const s = rt(peerId);
+    if (s.status !== 'pending_sas' || !s.devicePubKey) return { ok: false, reason: 'not_pending_sas' };
+    updatePeer(peerId, { verifiedDevicePubKey: s.devicePubKey });
+    s.status = 'authenticated';
+    return { ok: true };
+  }
+
+  function send(peerId, type, payload) {
+    if (typeof type !== 'string' || !ALLOWED_COMMANDS.has(type)) {
+      return Promise.reject(new Error('command_not_allowed'));
+    }
+    const s = rt(peerId);
+    if (!s.ws || s.ws.readyState !== WS_OPEN || !s.sessionKey) {
+      return Promise.reject(new Error('not_connected'));
+    }
+    const id = crypto.randomUUID();
+    const peer = getPeer(peerId);
+    if (!peer) return Promise.reject(new Error('unknown_peer'));
+    const inner = { type, id, payload: payload ?? {}, ts: Date.now() };
+    const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), s.sessionKey);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        s.pending.delete(id);
+        reject(new Error('timeout'));
+      }, SEND_TIMEOUT_MS);
+      s.pending.set(id, { resolve, reject, timer });
+      try {
+        rawSend(s.ws, { type: 'e2e:box', id, deviceId: peer.deviceId, payload: { nonce, ciphertext }, ts: Date.now() });
+      } catch (e) {
+        s.pending.delete(id);
+        clearTimeout(timer);
+        reject(e);
+      }
+    });
+  }
+
+  function onEvent(peerId, cb) {
+    let set = subscribers.get(peerId);
+    if (!set) { set = new Set(); subscribers.set(peerId, set); }
+    set.add(cb);
+    return () => { set.delete(cb); };
+  }
+
+  function removePeer(peerId) {
+    const s = runtime.get(peerId);
+    if (s) {
+      s.attempt++;
+      failPending(s, new Error('peer_removed'));
+      try { s.ws?.close(); } catch { /* already closed */ }
+      runtime.delete(peerId);
+    }
+    subscribers.delete(peerId);
+    savePeers(loadPeers().filter((p) => p.peerId !== peerId));
+  }
+
+  return { addPeer, listPeers, connect, confirmSas, getStatus, send, onEvent, removePeer };
+}
+
+const remoteClient = createRemoteClient();
+
+module.exports = { createRemoteClient, remoteClient, SEND_TIMEOUT_MS };

package/src/main/remoteClientIpc.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * remoteClientIpc.cjs — IPC surface for the desktop-to-desktop remote client
+ * (remoteClient.cjs). Every payload is Zod-validated here, in main. Status
+ * changes and peer events are pushed to the renderer on `remoteClient:status`
+ * and `remoteClient:event`.
+ */
+
+const { ipcMain } = require('electron');
+const { z } = require('zod');
+const { remoteClient } = require('./remoteClient.cjs');
+const { ALLOWED_COMMANDS } = require('./ipcSchemas.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+
+const STATUS_POLL_MS = 1000;
+
+const peerId = z.string().min(1).max(128);
+const schemas = {
+  peer: z.object({ peerId }),
+  send: z.object({
+    peerId,
+    type: z.string().min(1).max(128).refine((t) => ALLOWED_COMMANDS.has(t), { message: 'command_not_allowed' }),
+    payload: z.unknown().optional(),
+  }),
+};
+
+function validated(schema, handler) {
+  return (_event, payload) => handler(schema.parse(payload));
+}
+
+function registerRemoteClientHandlers(getWindow, client = remoteClient) {
+  const unsubs = new Map(); // peerId -> unsubscribe for event forwarding
+  const lastStatus = new Map(); // peerId -> serialized status
+
+  const toWindow = (channel, payload) => sendIfAlive(getWindow(), channel, payload);
+
+  function publishStatus(id) {
+    const status = client.getStatus(id);
+    const key = JSON.stringify(status);
+    if (lastStatus.get(id) === key) return status;
+    lastStatus.set(id, key);
+    toWindow('remoteClient:status', { peerId: id, ...status });
+    return status;
+  }
+
+  function ensureForwarding(id) {
+    if (unsubs.has(id)) return;
+    unsubs.set(id, client.onEvent(id, (ev) => {
+      toWindow('remoteClient:event', { peerId: id, type: ev.type, payload: ev.payload });
+    }));
+  }
+
+  // remoteClient has no status callback; the socket moves status on its own
+  // (pending_sas, failed, idle), so poll for changes on known peers.
+  const timer = setInterval(() => {
+    for (const p of client.listPeers()) publishStatus(p.peerId);
+  }, STATUS_POLL_MS);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  ipcMain.handle('remoteClient:list', () => client.listPeers().map((p) => {
+    ensureForwarding(p.peerId);
+    return { ...p, ...client.getStatus(p.peerId) };
+  }));
+
+  ipcMain.handle('remoteClient:connect', validated(schemas.peer, async ({ peerId: id }) => {
+    ensureForwarding(id);
+    const connecting = client.connect(id);
+    publishStatus(id);
+    const status = await connecting;
+    publishStatus(id);
+    return status;
+  }));
+
+  ipcMain.handle('remoteClient:confirm-sas', validated(schemas.peer, ({ peerId: id }) => {
+    const res = client.confirmSas(id);
+    publishStatus(id);
+    return res;
+  }));
+
+  ipcMain.handle('remoteClient:remove', validated(schemas.peer, ({ peerId: id }) => {
+    client.removePeer(id);
+    const off = unsubs.get(id);
+    if (off) off();
+    unsubs.delete(id);
+    lastStatus.delete(id);
+    toWindow('remoteClient:status', { peerId: id, status: 'removed', reason: null, sas: null });
+    return { ok: true };
+  }));
+
+  ipcMain.handle('remoteClient:send', validated(schemas.send, ({ peerId: id, type, payload }) =>
+    client.send(id, type, payload)));
+
+  return () => {
+    clearInterval(timer);
+    for (const off of unsubs.values()) off();
+    unsubs.clear();
+  };
+}
+
+module.exports = { registerRemoteClientHandlers, schemas };

package/src/main/webRemote.cjs

@@ -68,107 +68,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 ────────────────────────────────────────────────────────────
 
@@ -317,7 +218,23 @@ async function getDeviceTicket(deviceToken) {
 
 // ─── E2E state helpers ────────────────────────────────────────────────────────
 
+// tabId → unsubscribe fn for the PtyManager output listener streaming to the peer.
+const _remotePtyStreams = new Map();
+
+function stopRemotePtyStream(tabId) {
+  const unsub = _remotePtyStreams.get(tabId);
+  _remotePtyStreams.delete(tabId);
+  if (unsub) {
+    try { unsub(); } catch { /* listener already gone */ }
+  }
+}
+
+function stopAllRemotePtyStreams() {
+  for (const tabId of [..._remotePtyStreams.keys()]) stopRemotePtyStream(tabId);
+}
+
 function resetE2e(state = 'idle') {
+  stopAllRemotePtyStreams();
   _e2e = makeState(state);
   _e2ePeerPubKey = null;
   _e2eDeviceId = null;
@@ -407,6 +324,7 @@ function scheduleReconnect() {
 async function disconnect() {
   cancelReconnect();
   stopHeartbeat();
+  stopAllRemotePtyStreams();
   resetE2e();
   if (_ws) {
     const ws = _ws;
@@ -526,6 +444,7 @@ async function connect() {
 }
 
 async function handleTokenRevoked(deviceId) {
+  stopAllRemotePtyStreams();
   logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'token revoked', meta: { deviceId } });
   const cfg = await loadConfig();
   const devices = (cfg.devices || []).filter((d) => d.deviceId !== deviceId);
@@ -712,6 +631,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 {
@@ -727,13 +681,12 @@ async function pushSessionList() {
     if (_e2e.state !== 'authenticated') 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);
@@ -1072,7 +1025,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;
+      stopRemotePtyStream(tabId);
+      const unsub = ptyManager.addOutputListener(
+        tabId,
+        (_id, data) => {
+          if (_e2e.state !== 'authenticated' || !loadConfigSync().remoteEnabled) return;
+          pushEvent('event:pty:data', { tabId, data });
+        },
+        (_id, info) => {
+          if (_remotePtyStreams.get(tabId) === unsub) _remotePtyStreams.delete(tabId);
+          if (_e2e.state !== 'authenticated' || !loadConfigSync().remoteEnabled) return;
+          pushEvent('event:pty:exit', { tabId, exitCode: info?.exitCode, signal: info?.signal });
+        },
+      );
+      _remotePtyStreams.set(tabId, unsub);
+      return result;
     },
 
     'cmd:pty:write': async (payload) => {
@@ -1088,6 +1059,7 @@ function getDispatchMap() {
 
     'cmd:pty:kill': async (payload) => {
       const parsed = schemas.ptyTabId.parse(payload);
+      stopRemotePtyStream(parsed.tabId);
       ptyManager.kill(parsed.tabId);
       return { ok: true };
     },
@@ -1190,6 +1162,7 @@ async function pair(otp) {
 }
 
 async function revokeDevice(deviceId) {
+  stopAllRemotePtyStreams();
   invalidateConfigCache();
   const cfg = await loadConfig();
   const devices = (cfg.devices || []).filter((d) => d.deviceId !== deviceId);
@@ -1214,6 +1187,7 @@ async function revokeDevice(deviceId) {
  * This is the local-side "kill everything" action (ADR §4.1).
  */
 async function revokeAllDevices() {
+  stopAllRemotePtyStreams();
   const cfg = await loadConfig();
   const revokedCount = (cfg.devices || []).length;
   await saveConfig({ ...cfg, remoteEnabled: false, devices: [] });
@@ -1361,4 +1335,12 @@ module.exports = {
     resetE2e,
     getE2eState: () => _e2e,
   },
+  __test: {
+    getDispatchMap,
+    buildRemoteSessionList,
+    setWs: (ws) => { _ws = ws; },
+    setE2eAuthenticated: (key) => { _e2e = makeState('authenticated', key, null); },
+    revokeAllDevices,
+    streamCount: () => _remotePtyStreams.size,
+  },
 };