mixdog 0.9.95 → 0.9.97

package/src/standalone/{engine-daemon-transport.mjs → session-transport.mjs}

@@ -1,34 +1,49 @@
-// Machine-global ENGINE daemon — HTTP + SSE transport (server side).
+// Machine-global session HTTP + SSE transport (server side).
 //
-// Sibling of channel-daemon-transport.mjs, deliberately separate: the channels
+// Sibling of channel-transport.mjs, deliberately separate: the channels
 // transport routes notifies to ONE pointer client (remote ownership), while
-// engine frames are shared state — every attached client (terminal TUI and the
+// session frames are shared state — every attached client (terminal TUI and the
 // desktop app at the same time) must observe the same snapshot stream. Mixing
 // the two routing rules into one server would put the pointer semantics on a
 // path that must never target a single client.
 //
 // This module owns ONLY the transport (sockets, client registry, frame fan-out,
-// discovery file, lifecycle). The engine pool is injected via `handleCall`, so
+// lifecycle). The session pool is injected via `handleCall`, so
 // the same transport is exercised by the real daemon entry AND by the smoke
-// harness with a stub engine factory (no provider, no model download).
+// harness with a stub session runtime (no provider, no model download).
 import http from 'node:http';
 import { createHash, randomUUID } from 'node:crypto';
-import { rmSync } from 'node:fs';
-import { writeJsonAtomicSync } from '../runtime/shared/atomic-file.mjs';
 import { sendJson, sendError } from '../runtime/memory/lib/http-wire.mjs';
-import { ENGINE_DAEMON_PROTOCOL, engineRuntimeVersion } from './engine-daemon-protocol.mjs';
+import {
+  compareRuntimeVersions,
+  SESSION_CAPABILITY_FINGERPRINT,
+  SESSION_PROTOCOL,
+  SESSION_REVISION,
+  runtimeVersion,
+} from './session-wire.mjs';
+import { createFairCallScheduler } from './fair-call-scheduler.mjs';
 
 // A loopback front door still buffers whatever a client sends before it can be
 // parsed, so the body has an explicit ceiling instead of the client's memory.
-const MAX_BODY_BYTES = Math.max(1, Number(process.env.MIXDOG_ENGINE_DAEMON_MAX_BODY_MB) || 64)
+const MAX_BODY_BYTES = Math.max(1, Number(process.env.MIXDOG_SESSION_MAX_BODY_MB) || 32)
   * 1024 * 1024;
 
-function readLimitedBody(req) {
+function readLimitedBody(req, {
+  reserve = () => true,
+  release = () => {},
+} = {}) {
   return new Promise((resolve, reject) => {
     let settled = false;
+    let reserved = 0;
+    const releaseReserved = () => {
+      if (reserved <= 0) return;
+      release(reserved);
+      reserved = 0;
+    };
     const fail = (message, statusCode) => {
       if (settled) return;
       settled = true;
+      releaseReserved();
       const error = new Error(message);
       error.statusCode = statusCode;
       try { req.destroy(); } catch {}
@@ -45,21 +60,32 @@ function readLimitedBody(req) {
       if (settled) return;
       size += chunk.length;
       if (size > MAX_BODY_BYTES) { fail('request body too large', 413); return; }
+      if (!reserve(chunk.length)) { fail('daemon request memory budget is busy', 503); return; }
+      reserved += chunk.length;
       chunks.push(chunk);
     });
     req.on('end', () => {
       if (settled) return;
       settled = true;
-      const raw = Buffer.concat(chunks).toString('utf8').trim();
-      if (!raw) { resolve({}); return; }
-      try { resolve(JSON.parse(raw)); }
+      try {
+        const raw = Buffer.concat(chunks).toString('utf8').trim();
+        if (!raw) { resolve({}); return; }
+        resolve(JSON.parse(raw));
+      }
       catch (error) {
         const err = new Error(`invalid JSON body: ${error.message}`);
         err.statusCode = 400;
         reject(err);
       }
+      finally { releaseReserved(); }
+    });
+    req.on('error', (error) => {
+      if (!settled) {
+        settled = true;
+        releaseReserved();
+        reject(error);
+      }
     });
-    req.on('error', (error) => { if (!settled) { settled = true; reject(error); } });
   });
 }
 
@@ -89,10 +115,15 @@ function isPidAlive(pid) {
 // terminal frames therefore concatenate, bounded so a wedged reader can never
 // grow the daemon's heap without limit.
 const TERMINAL_BACKLOG_MAX_CHARS = 256 * 1024;
+const SSE_PENDING_MAX_BYTES = Math.max(
+  256 * 1024,
+  (Number(process.env.MIXDOG_SESSION_SSE_PENDING_MB) || 8)
+    * 1024 * 1024,
+);
 
 function terminalDataFrame(frame) {
   return frame?.type === 'desktop-event'
-    && frame.message?.kind === 'backend-event'
+    && frame.message?.kind === 'desktop-event'
     && frame.message?.name === 'terminal-data'
     && typeof frame.message?.value?.data === 'string'
     ? frame
@@ -114,9 +145,8 @@ function mergePendingFrame(existing, frame, json) {
   return { frame: merged, json: JSON.stringify(merged) };
 }
 
-export function createEngineDaemonTransport({
+export function createSessionTransport({
   handleCall,
-  discoveryPath,
   serverToken = randomUUID(),
   log = () => {},
   clientGraceMs = 10_000,
@@ -124,6 +154,7 @@ export function createEngineDaemonTransport({
   onClientsEmpty = null,
   onClientRegistered = null,
   onClientDropped = null,
+  onUpgradeRequested = null,
   getStatus = () => ({}),
 } = {}) {
   if (typeof handleCall !== 'function') throw new Error('handleCall is required');
@@ -136,23 +167,112 @@ export function createEngineDaemonTransport({
   let sweepTimer = null;
   let everHadLifecycleClient = false;
   let closed = false;
+  let drainingReason = '';
+  const BODY_INFLIGHT_MAX_BYTES = Math.max(
+    MAX_BODY_BYTES,
+    (Number(process.env.MIXDOG_SESSION_BODY_INFLIGHT_MB) || 64)
+      * 1024 * 1024,
+  );
+  let bodyBytesInFlight = 0;
+  const readBody = (req) => readLimitedBody(req, {
+    reserve(bytes) {
+      if (bodyBytesInFlight + bytes > BODY_INFLIGHT_MAX_BYTES) return false;
+      bodyBytesInFlight += bytes;
+      return true;
+    },
+    release(bytes) {
+      bodyBytesInFlight = Math.max(0, bodyBytesInFlight - bytes);
+    },
+  });
   // Idempotency cache: a transport retry of the SAME callId must never run a
-  // second engine mutation (submit/abort are not idempotent).
+  // second session mutation (submit/abort are not idempotent).
   const callCache = new Map();
+  let callCacheBytes = 0;
+  // These routes are safe to replay and can return large snapshots. Keeping
+  // them in the mutation-dedup cache retained multiple transcript copies for
+  // a full minute under review polling and pane reconciliation.
+  const REPLAY_SAFE_CALLS = new Set([
+    'project.list',
+    'project.inspect',
+    'session.list',
+    'session.read',
+    'session.subscribe',
+    'session.unsubscribe',
+  ]);
   const CALL_CACHE_TTL_MS = 60_000;
   // Bound the dedup table: a call that never settles would otherwise pin its
   // entry for the daemon's whole life.
-  const CALL_CACHE_MAX = Math.max(512, Number(process.env.MIXDOG_ENGINE_DAEMON_CALL_CACHE) || 4096);
+  const CALL_CACHE_MAX = Math.max(512, Number(process.env.MIXDOG_SESSION_CALL_CACHE) || 4096);
+  const CALL_CACHE_MAX_BYTES = Math.max(
+    1024 * 1024,
+    (Number(process.env.MIXDOG_SESSION_CALL_CACHE_MB) || 8)
+      * 1024 * 1024,
+  );
   // A burst of panes used to enqueue every handleCall() as a microtask. Node
   // drains the whole microtask queue before returning to HTTP, so enough cheap
   // calls could starve /health and /client/register even though no explicit
   // mutex existed. Admit one call per event-loop turn while allowing admitted
   // async calls to overlap; control-plane routes never enter this queue.
-  const CALL_ACTIVE_MAX = Math.max(8, Number(process.env.MIXDOG_ENGINE_DAEMON_ACTIVE_CALLS) || 64);
-  const CALL_QUEUE_MAX = Math.max(CALL_ACTIVE_MAX, Number(process.env.MIXDOG_ENGINE_DAEMON_CALL_QUEUE) || 1024);
-  const callQueue = [];
-  let activeCalls = 0;
-  let callDispatchScheduled = false;
+  // No default concurrency gate: independent session work starts in parallel.
+  // The scheduler still launches one item per check phase so synchronous setup
+  // cannot monopolize the HTTP/control-plane turn. Operators may explicitly
+  // set finite lane limits for constrained hosts.
+  const configuredLaneLimit = (name) => {
+    const parsed = Math.floor(Number(process.env[name]));
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : Infinity;
+  };
+  const CALL_QUEUE_MAX = Math.max(1024, Number(process.env.MIXDOG_SESSION_CALL_QUEUE) || 1024);
+  const CRITICAL_CALLS = new Set([
+    'session.abort',
+    'session.approve',
+    'session.unsubscribe',
+    'desktop.control',
+    'desktop.unsubscribe',
+  ]);
+  const INTERACTIVE_CALLS = new Set([
+    'session.create',
+    'session.read',
+    'session.subscribe',
+    'session.submit',
+    'session.configure',
+    'project.list',
+    'project.inspect',
+    'project.add',
+    'project.touch',
+    'project.rename',
+    'project.remove',
+    'project.ensureDirectory',
+    'desktop.init',
+  ]);
+  const INTERACTIVE_DESKTOP_METHODS = new Set([
+    'termEnsure',
+    'termWrite',
+    'termResize',
+    'termDispose',
+    'termProfiles',
+  ]);
+  const normalCalls = createFairCallScheduler({
+    name: 'session service call',
+    activeMax: configuredLaneLimit('MIXDOG_SESSION_ACTIVE_CALLS'),
+    queueMax: CALL_QUEUE_MAX,
+    minOwnerQueue: Math.max(8, Math.floor(CALL_QUEUE_MAX / 16)),
+    dispatchBurst: 1,
+    yieldUnbounded: true,
+  });
+  const criticalCalls = createFairCallScheduler({
+    name: 'session service critical call',
+    activeMax: configuredLaneLimit('MIXDOG_SESSION_URGENT_RESERVE'),
+    queueMax: Math.max(32, Math.min(256, CALL_QUEUE_MAX)),
+    minOwnerQueue: 8,
+  });
+  const interactiveCalls = createFairCallScheduler({
+    name: 'session service interactive call',
+    activeMax: configuredLaneLimit('MIXDOG_SESSION_INTERACTIVE_RESERVE'),
+    queueMax: Math.max(64, Math.min(512, CALL_QUEUE_MAX)),
+    minOwnerQueue: 8,
+    dispatchBurst: 1,
+    yieldUnbounded: true,
+  });
   // A timed-out registration may already have committed server-side. Replaying
   // the same registrationId returns that token instead of leaking a second
   // client record and another lifecycle reference.
@@ -160,58 +280,65 @@ export function createEngineDaemonTransport({
   const REGISTRATION_REPLAY_TTL_MS = 30_000;
   const REGISTRATION_REPLAY_MAX = 256;
 
-  function pruneCallCache() {
-    while (callCache.size > CALL_CACHE_MAX) {
-      const oldest = callCache.keys().next();
-      if (oldest.done) return;
-      callCache.delete(oldest.value);
+  function deleteCallCacheEntry(key, record = callCache.get(key)) {
+    if (!record || callCache.get(key) !== record) return false;
+    callCache.delete(key);
+    callCacheBytes = Math.max(0, callCacheBytes - (record.bytes || 0));
+    return true;
+  }
+
+  function estimateRetainedBytes(value, limit = CALL_CACHE_MAX_BYTES + 1, seen = new Set()) {
+    if (typeof value === 'string') return Math.min(limit, value.length * 2 + 16);
+    if (typeof value === 'number' || typeof value === 'bigint') return 8;
+    if (typeof value === 'boolean' || value == null) return 4;
+    if (typeof value !== 'object' || seen.has(value)) return 0;
+    seen.add(value);
+    let bytes = Array.isArray(value) ? 32 : 64;
+    const entries = Array.isArray(value) ? value : Object.entries(value);
+    for (const entry of entries) {
+      if (Array.isArray(value)) bytes += 8 + estimateRetainedBytes(entry, limit - bytes, seen);
+      else bytes += String(entry[0]).length * 2 + 16
+        + estimateRetainedBytes(entry[1], limit - bytes, seen);
+      if (bytes >= limit) break;
     }
+    seen.delete(value);
+    return Math.min(limit, bytes);
   }
 
-  function scheduleCallDispatch() {
-    if (closed || callDispatchScheduled || activeCalls >= CALL_ACTIVE_MAX || callQueue.length === 0) return;
-    callDispatchScheduled = true;
-    setImmediate(() => {
-      callDispatchScheduled = false;
-      if (closed) {
-        const error = new Error('engine daemon transport is closed');
-        error.statusCode = 503;
-        for (const queued of callQueue.splice(0)) queued.reject(error);
-        return;
+  function pruneCallCache() {
+    while (callCache.size > CALL_CACHE_MAX || callCacheBytes > CALL_CACHE_MAX_BYTES) {
+      let removed = false;
+      for (const [key, record] of callCache) {
+        // Never lose the dedup identity of an in-flight mutation.
+        if (!record.settled) continue;
+        deleteCallCacheEntry(key, record);
+        removed = true;
+        break;
       }
-      if (activeCalls >= CALL_ACTIVE_MAX) return;
-      const queued = callQueue.shift();
-      if (!queued) return;
-      activeCalls += 1;
-      Promise.resolve()
-        .then(queued.run)
-        .then(queued.resolve, queued.reject)
-        .finally(() => {
-          activeCalls = Math.max(0, activeCalls - 1);
-          scheduleCallDispatch();
-        });
-      // Start at most ONE handler in this check phase. A fresh immediate gives
-      // socket I/O (especially health/register) a poll phase between starts.
-      scheduleCallDispatch();
-    });
+      if (!removed) return;
+    }
   }
 
-  function dispatchCall(run) {
-    if (closed) {
-      const error = new Error('engine daemon transport is closed');
-      error.statusCode = 503;
-      return Promise.reject(error);
-    }
-    if (callQueue.length >= CALL_QUEUE_MAX) {
-      const error = new Error('engine daemon call queue is full');
-      error.statusCode = 503;
-      return Promise.reject(error);
+  function callLane(name, args = {}) {
+    if (CRITICAL_CALLS.has(name)) return 'critical';
+    if (INTERACTIVE_CALLS.has(name)) return 'interactive';
+    if (name === 'desktop.invoke') {
+      const adapterMethod = String(args?.method || '');
+      const desktopMethod = adapterMethod === 'invokeDesktopOperation'
+        ? String(args?.args?.[0] || '')
+        : adapterMethod;
+      if (INTERACTIVE_DESKTOP_METHODS.has(desktopMethod)) return 'interactive';
     }
-    const promise = new Promise((resolve, reject) => {
-      callQueue.push({ run, resolve, reject });
-    });
-    scheduleCallDispatch();
-    return promise;
+    return 'normal';
+  }
+
+  function dispatchCall(ownerKey, run, { lane = 'normal', signal = null } = {}) {
+    const scheduler = lane === 'critical'
+      ? criticalCalls
+      : lane === 'interactive'
+        ? interactiveCalls
+        : normalCalls;
+    return scheduler.enqueue(ownerKey, run, { signal });
   }
 
   function nowMs() { return Date.now(); }
@@ -233,7 +360,7 @@ export function createEngineDaemonTransport({
     if (lifecycleClientCount() > 0) return;
     // Never re-arm an ALREADY armed grace: the 5s sweep also calls this, and
     // cancel+rearm on every tick pushed the 10s deadline out forever — the
-    // daemon could never self-shut down through the engine front door.
+    // daemon could never self-shut down through the session front door.
     if (graceTimer) return;
     graceTimer = setTimeout(() => {
       graceTimer = null;
@@ -260,9 +387,9 @@ export function createEngineDaemonTransport({
   function dropClient(token, reason) {
     if (!clients.has(token)) return;
     removeClientRecord(token);
-    // The engine pool refcounts VIEWS by client token: a client that is gone
-    // must stop holding engines open (and must stop being counted as the
-    // reason another client's engine survives).
+    // The session runtime pool refcounts VIEWS by client token: a client that is gone
+    // must stop holding session runtimes open (and must stop being counted as the
+    // reason another client's session runtime survives).
     if (typeof onClientDropped === 'function') {
       try { onClientDropped(token, reason); } catch {}
     }
@@ -270,6 +397,14 @@ export function createEngineDaemonTransport({
     maybeArmGrace(reason);
   }
 
+  function beginDrain(reason = 'daemon replacement') {
+    if (drainingReason) return false;
+    drainingReason = String(reason || 'daemon replacement');
+    cancelGrace();
+    for (const token of [...clients.keys()]) dropClient(token, drainingReason);
+    return true;
+  }
+
   function startSweep() {
     if (sweepTimer || closed) return;
     sweepTimer = setInterval(() => {
@@ -282,7 +417,7 @@ export function createEngineDaemonTransport({
     sweepTimer.unref?.();
   }
 
-  function registerClient({ leadPid, cwd, lifecycle = true, registrationId = null } = {}) {
+  function registerClient({ leadPid, cwd, lifecycle = true, registrationId = null, revision = 0 } = {}) {
     const pid = parsePid(leadPid) || 0;
     const ownsLifecycle = lifecycle !== false;
     const replayId = registrationId ? String(registrationId).slice(0, 200) : null;
@@ -290,7 +425,8 @@ export function createEngineDaemonTransport({
     if (replay) {
       const sameIdentity = replay.leadPid === pid
         && replay.cwd === (cwd || null)
-        && replay.lifecycle === ownsLifecycle;
+        && replay.lifecycle === ownsLifecycle
+        && replay.revision === Math.max(0, Number(revision) || 0);
       if (sameIdentity && clients.has(replay.token)) {
         log(`client registration replay token=${replay.token} lead=${pid}`);
         return replay.token;
@@ -309,12 +445,14 @@ export function createEngineDaemonTransport({
       leadPid: pid,
       cwd: cwd || null,
       lifecycle: ownsLifecycle,
+      revision: Math.max(0, Number(revision) || 0),
       sse: null,
       // True while the socket asked us to stop writing (see writeFrame).
       paused: false,
       // Frames are latest-wins per key while a client has no stream: a
       // reconnecting viewer wants the CURRENT snapshot, never a backlog.
       pending: new Map(),
+      pendingBytes: 0,
       lastSeen: nowMs(),
     });
     if (ownsLifecycle) {
@@ -341,6 +479,7 @@ export function createEngineDaemonTransport({
         leadPid: pid,
         cwd: cwd || null,
         lifecycle: ownsLifecycle,
+        revision: Math.max(0, Number(revision) || 0),
         timer,
       });
     }
@@ -352,36 +491,76 @@ export function createEngineDaemonTransport({
     while (client.sse && !client.paused && client.pending.size > 0) {
       const [key, entry] = client.pending.entries().next().value;
       client.pending.delete(key);
+      client.pendingBytes = Math.max(0, client.pendingBytes - (entry.bytes || 0));
       try {
         if (client.sse.write(`data: ${entry.json}\n\n`) === false) client.paused = true;
       } catch {
         client.sse = null;
         client.pending.set(key, entry);
+        client.pendingBytes += entry.bytes || 0;
         return;
       }
     }
   }
 
+  function pendingEntry(frame, json) {
+    return { frame, json, bytes: Buffer.byteLength(json) + 8 };
+  }
+
+  function resyncEntry(frame) {
+    if (frame?.type !== 'session-state' || !frame.sessionId) return null;
+    const marker = {
+      type: 'session-state',
+      key: frame.key,
+      sessionId: frame.sessionId,
+      revision: -1,
+      baseRevision: -2,
+      patch: { set: {}, remove: [], itemsAppend: null },
+      resyncRequired: true,
+    };
+    return pendingEntry(marker, JSON.stringify(marker));
+  }
+
+  function setPending(client, key, entry) {
+    const previous = client.pending.get(key);
+    if (previous) client.pendingBytes = Math.max(0, client.pendingBytes - (previous.bytes || 0));
+    client.pending.delete(key);
+    client.pending.set(key, entry);
+    client.pendingBytes += entry.bytes || 0;
+    while (client.pendingBytes > SSE_PENDING_MAX_BYTES && client.pending.size > 0) {
+      const [oldestKey, oldest] = client.pending.entries().next().value;
+      const marker = resyncEntry(oldest.frame);
+      if (marker && marker.bytes < oldest.bytes) {
+        client.pending.set(oldestKey, marker);
+        client.pendingBytes += marker.bytes - oldest.bytes;
+        continue;
+      }
+      client.pending.delete(oldestKey);
+      client.pendingBytes = Math.max(0, client.pendingBytes - (oldest.bytes || 0));
+    }
+  }
+
   function writeFrame(client, frame, json) {
     const key = frame.key || `${frame.type}:${frame.sessionId || frame.desktopId || ''}`;
     // A stalled reader must never make the daemon buffer a whole stream in
     // Node's socket queue: while the socket is full the backlog collapses to
     // one frame per key, exactly like a client with no stream at all.
     if (!client.sse || client.paused) {
-      client.pending.set(key, mergePendingFrame(client.pending.get(key), frame, json));
+      const merged = mergePendingFrame(client.pending.get(key), frame, json);
+      setPending(client, key, pendingEntry(merged.frame, merged.json));
       return;
     }
     try {
       if (client.sse.write(`data: ${json}\n\n`) === false) client.paused = true;
     } catch {
       client.sse = null;
-      client.pending.set(key, mergePendingFrame(client.pending.get(key), frame, json));
+      const merged = mergePendingFrame(client.pending.get(key), frame, json);
+      setPending(client, key, pendingEntry(merged.frame, merged.json));
     }
   }
 
   /** Session and desktop state reaches only subscribed client tokens. Calls
-   *  without a target set retain the transport-level broadcast used by
-   *  diagnostics and compatibility tests. */
+   *  without a target set retain the transport-level diagnostic broadcast. */
   function broadcast(frame, targetTokens = null) {
     const json = JSON.stringify(frame);
     if (targetTokens) {
@@ -432,7 +611,7 @@ export function createEngineDaemonTransport({
       clearInterval(ka);
       if (c.sse === res) { c.sse = null; c.paused = false; }
       // Stream loss alone never drops the client: a desktop reload or a TUI
-      // resize can bounce the stream while the engine keeps running.
+      // resize can bounce the stream while the session runtime keeps running.
       maybeArmGrace('sse closed');
     };
     res.on('close', cleanup);
@@ -453,11 +632,31 @@ export function createEngineDaemonTransport({
           pid: process.pid,
           clients: lifecycleClientCount(),
           connections: clients.size,
-          protocol: ENGINE_DAEMON_PROTOCOL,
-          version: engineRuntimeVersion(),
+          protocol: SESSION_PROTOCOL,
+          revision: SESSION_REVISION,
+          capabilityFingerprint: SESSION_CAPABILITY_FINGERPRINT,
+          draining: drainingReason || null,
+          version: runtimeVersion(),
           ...getStatus(),
-          activeCalls,
-          queuedCalls: callQueue.length,
+          activeCalls: normalCalls.active + interactiveCalls.active + criticalCalls.active,
+          queuedCalls: normalCalls.queued + interactiveCalls.queued + criticalCalls.queued,
+          queuedUrgentCalls: criticalCalls.queued,
+          queuedInteractiveCalls: interactiveCalls.queued,
+          callOwners: normalCalls.snapshot().owners,
+          callQueues: {
+            critical: criticalCalls.snapshot(),
+            interactive: interactiveCalls.snapshot(),
+            normal: normalCalls.snapshot(),
+          },
+          transportMemory: {
+            bodyBytesInFlight,
+            bodyBytesMax: BODY_INFLIGHT_MAX_BYTES,
+            callCacheEntries: callCache.size,
+            callCacheBytes,
+            callCacheMaxBytes: CALL_CACHE_MAX_BYTES,
+            ssePendingBytes: [...clients.values()]
+              .reduce((sum, client) => sum + (client.pendingBytes || 0), 0),
+          },
         });
         return;
       }
@@ -465,18 +664,33 @@ export function createEngineDaemonTransport({
       if (token !== serverToken) { sendError(res, 'forbidden', 403); return; }
 
       if (req.method === 'POST' && pathName === '/client/register') {
-        const body = await readLimitedBody(req);
+        const body = await readBody(req);
+        if (drainingReason) {
+          sendError(res, `daemon is draining: ${drainingReason}`, 503);
+          return;
+        }
+        const clientProtocol = Number(body.protocol);
+        if (clientProtocol !== SESSION_PROTOCOL) {
+          sendError(res, `session protocol ${SESSION_PROTOCOL} required`, 409);
+          return;
+        }
         const clientToken = registerClient({
           leadPid: body.leadPid,
           cwd: body.cwd,
           lifecycle: body.lifecycle !== false,
           registrationId: body.registrationId,
+          revision: body.revision,
+        });
+        sendJson(res, {
+          token: clientToken,
+          pid: process.pid,
+          protocol: SESSION_PROTOCOL,
+          revision: SESSION_REVISION,
         });
-        sendJson(res, { token: clientToken, pid: process.pid });
         return;
       }
       if (req.method === 'POST' && pathName === '/client/deregister') {
-        const body = await readLimitedBody(req);
+        const body = await readBody(req);
         if (body.token) dropClient(String(body.token), 'deregister');
         sendJson(res, { ok: true });
         return;
@@ -487,36 +701,63 @@ export function createEngineDaemonTransport({
         return; // stream stays open
       }
       if (req.method === 'POST' && pathName === '/call') {
-        const body = await readLimitedBody(req);
+        const body = await readBody(req);
         const clientToken = body.token ? String(body.token) : null;
         const c = clientToken ? clients.get(clientToken) : null;
         if (!c) { sendError(res, 'unknown client token', 404); return; }
         c.lastSeen = nowMs();
         const name = String(body.name || '');
         const callId = body.callId ? String(body.callId) : null;
+        const addressedSessionId = String(body.args?.sessionId || '').trim();
+        const ownerKey = addressedSessionId
+          ? `session:${addressedSessionId}`
+          : c.leadPid
+            ? `pid:${c.leadPid}`
+            : `client:${clientToken}`;
+        // Scheduling fairness follows the addressed session, but idempotency
+        // belongs to the CALLING PROCESS. Two clients legitimately issuing the
+        // same callId against one shared session must not dedupe each other.
+        const cacheOwnerKey = c.leadPid
+          ? `pid:${c.leadPid}`
+          : `client:${clientToken}`;
+        const cacheKey = callId && !REPLAY_SAFE_CALLS.has(name)
+          ? `${cacheOwnerKey}\u0000${callId}`
+          : null;
         // A retry is the SAME payload under the same id. A different payload
         // that reuses an id (submission ids are caller-supplied) is a NEW call
         // and must never be answered out of another call's result.
         const signature = callId ? callSignature(name, body.args) : null;
-        const cached = callId ? callCache.get(callId) : null;
+        const cached = cacheKey ? callCache.get(cacheKey) : null;
         let dispatch;
         if (cached && (!cached.signature || !signature || cached.signature === signature)) {
           dispatch = cached.promise;
         } else {
-          dispatch = dispatchCall(() => handleCall(name, body.args || {}, {
-            clientToken,
-            leadPid: c.leadPid ?? null,
-            cwd: c.cwd ?? null,
-          }));
-          if (callId) {
-            const record = { promise: dispatch, at: nowMs(), signature };
-            callCache.set(callId, record);
+          dispatch = dispatchCall(
+            ownerKey,
+            () => handleCall(name, body.args || {}, {
+              clientToken,
+              leadPid: c.leadPid ?? null,
+              cwd: c.cwd ?? null,
+              revision: c.revision ?? 0,
+            }),
+            { lane: callLane(name, body.args || {}) },
+          );
+          if (cacheKey) {
+            const record = {
+              promise: dispatch, at: nowMs(), signature, settled: false, bytes: 0,
+            };
+            callCache.set(cacheKey, record);
             pruneCallCache();
             // TTL starts at SETTLE: a long-running submit must not expire its
             // dedup entry mid-flight and let a retry run the turn twice.
-            dispatch.then(() => {}, () => {}).then(() => {
+            dispatch.then((result) => {
+              record.bytes = estimateRetainedBytes(result);
+              callCacheBytes += record.bytes;
+            }, () => {}).then(() => {
+              record.settled = true;
+              pruneCallCache();
               const t = setTimeout(() => {
-                if (callCache.get(callId) === record) callCache.delete(callId);
+                deleteCallCacheEntry(cacheKey, record);
               }, CALL_CACHE_TTL_MS);
               t.unref?.();
             });
@@ -526,7 +767,7 @@ export function createEngineDaemonTransport({
           const result = await dispatch;
           sendJson(res, { result });
         } catch (err) {
-          // Engine errors travel as a 200 {error} envelope so the client can
+          // Session call errors travel as a 200 {error} envelope so the client can
           // tell a failed CALL from a dead TRANSPORT (which must re-attach).
           sendJson(res, { error: err?.message || String(err) }, 200);
         }
@@ -537,38 +778,59 @@ export function createEngineDaemonTransport({
         if (typeof onClientsEmpty === 'function') { try { onClientsEmpty(); } catch {} }
         return;
       }
+      if (req.method === 'POST' && pathName === '/upgrade') {
+        const body = await readBody(req);
+        const requestedProtocol = Number(body.protocol);
+        const requestedRevision = Math.max(0, Number(body.revision) || 0);
+        const requestedVersion = String(body.version || '0.0.0');
+        const revisionOrder = requestedRevision - SESSION_REVISION;
+        const versionOrder = compareRuntimeVersions(requestedVersion, runtimeVersion());
+        const newerBuild = requestedProtocol === SESSION_PROTOCOL
+          && (revisionOrder > 0 || (revisionOrder === 0 && versionOrder > 0));
+        if (!newerBuild) {
+          sendError(
+            res,
+            `replacement must use protocol ${SESSION_PROTOCOL} with a revision/build newer than ${SESSION_REVISION}/${runtimeVersion()}`,
+            409,
+          );
+          return;
+        }
+        sendJson(res, {
+          accepted: true,
+          protocol: SESSION_PROTOCOL,
+          currentRevision: SESSION_REVISION,
+          currentVersion: runtimeVersion(),
+          requestedRevision,
+          requestedVersion,
+        });
+        queueMicrotask(() => {
+          try {
+            onUpgradeRequested?.({
+              protocol: SESSION_PROTOCOL,
+              revision: requestedRevision,
+              version: requestedVersion,
+            });
+          } catch {}
+        });
+        return;
+      }
       sendError(res, 'not found', 404);
     } catch (err) {
       try { sendError(res, err?.message || String(err), err?.statusCode || 500); } catch {}
     }
   }
 
-  function writeDiscovery() {
-    if (!discoveryPath) return;
-    try {
-      writeJsonAtomicSync(discoveryPath, {
-        pid: process.pid,
-        port: boundPort,
-        token: serverToken,
-        startedAt: Date.now(),
-      }, { compact: true });
-    } catch (err) {
-      log(`discovery write failed: ${err?.message || err}`);
-    }
-  }
-
   function start() {
     return new Promise((resolve, reject) => {
       server = http.createServer(handleRequest);
       server.on('error', reject);
-      // 127.0.0.1 ONLY — the engine daemon executes tools; it must never be
+      // 127.0.0.1 ONLY — the session service executes tools; it must never be
       // reachable off-box.
       server.listen(0, '127.0.0.1', () => {
         server.removeListener('error', reject);
         boundPort = server.address().port;
         server.on('error', (err) => log(`server error: ${err?.message || err}`));
-        writeDiscovery();
-        log(`engine daemon transport listening on 127.0.0.1:${boundPort} pid=${process.pid}`);
+        log(`session service transport listening on 127.0.0.1:${boundPort} pid=${process.pid}`);
         resolve({ port: boundPort, token: serverToken });
       });
     });
@@ -578,13 +840,12 @@ export function createEngineDaemonTransport({
     closed = true;
     cancelGrace();
     if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
-    const stopped = new Error('engine daemon transport is closed');
-    stopped.statusCode = 503;
-    for (const queued of callQueue.splice(0)) queued.reject(stopped);
+    normalCalls.close('session service transport is closed');
+    interactiveCalls.close('session service transport is closed');
+    criticalCalls.close('session service transport is closed');
     for (const replay of registrationReplays.values()) clearTimeout(replay.timer);
     registrationReplays.clear();
     for (const token of [...clients.keys()]) removeClientRecord(token);
-    if (discoveryPath) { try { rmSync(discoveryPath, { force: true }); } catch {} }
     await new Promise((resolve) => {
       if (!server) { resolve(); return; }
       server.close(() => resolve());
@@ -596,8 +857,16 @@ export function createEngineDaemonTransport({
     start,
     stop,
     broadcast,
+    beginDrain,
     get port() { return boundPort; },
     get clientCount() { return lifecycleClientCount(); },
     get connectionCount() { return clients.size; },
+    get activeCount() {
+      return normalCalls.active + interactiveCalls.active + criticalCalls.active;
+    },
+    get queuedCount() {
+      return normalCalls.queued + interactiveCalls.queued + criticalCalls.queued;
+    },
+    get draining() { return Boolean(drainingReason); },
   };
 }