mixdog 0.9.95 → 0.9.97

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

@@ -1,19 +1,40 @@
-// Engine pool hosted by the machine-global engine daemon.
+// Session runtime pool hosted by the machine-global daemon.
 //
-// One process owns every live session engine; the terminal TUI and the desktop
+// One process owns every live session runtime; the terminal TUI and the desktop
 // app attach as VIEWS over the transport. That inverts today's model (each
-// client boots its own engine and the session store arbitrates ownership with
+// client boots its own session runtime and the session store arbitrates ownership with
 // generation counters + heartbeat vetoes): with a single writer, cross-client
 // editing is just fan-out, and the split-brain guards can never trip against
 // our own second client.
 //
-// The engine factory is injected (`createEngine`) so the daemon entry supplies
-// the real createEngineSession while tests supply a stub.
+// The session runtime factory is injected by the daemon entry.
 import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import {
+  SESSION_CONFIGURE_ACTION_SET,
+  SESSION_READ_ACTION_SET,
+} from './session-protocol.mjs';
 
 const MAX_CLONE_DEPTH = 24;
+const requireDesktopService = createRequire(import.meta.url);
 
-/** JSON-safe projection of an engine snapshot. Functions, symbols, and
+async function loadDesktopServiceModule(moduleUrl) {
+  const parsed = new URL(moduleUrl);
+  if (!parsed.pathname.toLowerCase().endsWith('.cjs')) {
+    return import(moduleUrl);
+  }
+  // Node's CJS bridge ignores URL search parameters and otherwise returns the
+  // previous install's cached exports after an in-place desktop update. Keep
+  // already-instantiated adapters alive, but load this newly keyed artifact
+  // from disk for the new desktop build.
+  const modulePath = fileURLToPath(parsed);
+  const resolved = requireDesktopService.resolve(modulePath);
+  delete requireDesktopService.cache[resolved];
+  return requireDesktopService(resolved);
+}
+
+/** JSON-safe projection of a session snapshot. Functions, symbols, and
  *  undefined never survive a transport hop; dropping them here (instead of at
  *  JSON.stringify time) keeps object identity stable for the receiver and
  *  makes cycles impossible rather than fatal. */
@@ -66,8 +87,10 @@ export function sanitizeForWire(value, depth = 0, seen = new WeakSet()) {
   }
 }
 
-export function createEngineDaemonService({
-  createEngine,
+export function createSessionService({
+  createSessionRuntime = null,
+  sessionExists = null,
+  listSessions = null,
   desktopRuntime = null,
   publishIntervalMs = 16,
   onFrame = () => {},
@@ -76,30 +99,46 @@ export function createEngineDaemonService({
   idleEvictMs = null,
   evictSweepMs = null,
 } = {}) {
-  if (typeof createEngine !== 'function') throw new Error('createEngine is required');
+  const createRuntime = createSessionRuntime;
+  if (typeof createRuntime !== 'function') throw new Error('createSessionRuntime is required');
+  // Revisions optimize deltas inside one daemon lifetime; sessionId + full
+  // snapshots remain the durable contract. Start each daemon far above the
+  // prior wall-clock epoch so a view reconnecting after replacement accepts
+  // the new daemon's first full snapshot.
+  const configuredRevisionEpoch = Number(process.env.MIXDOG_SESSION_REVISION_EPOCH);
+  const revisionEpoch = Number.isSafeInteger(configuredRevisionEpoch)
+    && configuredRevisionEpoch >= 0
+    ? configuredRevisionEpoch
+    : Math.floor(Date.now() * 1_000);
 
   // One daemon-owned execution entry per live session. Entries are never
   // addressed by clients; sessionId is the only identity outside this module.
   const sessions = new Set();
-  let desktopBackend = null;
-  let desktopBackendPromise = null;
+  const sessionsById = new Map();
+  let busyEntries = 0;
+  // Desktop adapters are keyed by their exact module URL so a dev preview and
+  // installed build never share module state accidentally.
+  const desktopServicesById = new Map();
+  const desktopServicesByModule = new Map();
+  const desktopServicePromises = new Map();
+  let projectStorePromise = null;
   let closed = false;
   // A turn belongs to the DAEMON, not to whoever is watching it: closing the
-  // desktop window or restarting the TUI must never interrupt work. An engine
+  // desktop window or restarting the TUI must never interrupt work. An session runtime
   // whose last view left is RETAINED while it is busy and evicted only after it
   // has been idle and unwatched for this long. With a view release no longer
   // destroying anything, this sweep is the ONLY reclaim path besides shutdown.
   const IDLE_EVICT_MS = Number(idleEvictMs) > 0
     ? Number(idleEvictMs)
-    : Math.max(60_000, Number(process.env.MIXDOG_ENGINE_IDLE_EVICT_MS) || 15 * 60_000);
+    : Math.max(60_000, Number(process.env.MIXDOG_SESSION_IDLE_EVICT_MS) || 2 * 60_000);
   const EVICT_SWEEP_MS = Number(evictSweepMs) > 0 ? Number(evictSweepMs) : 30_000;
   let evictTimer = null;
 
   // ── Cross-client subscriptions ──────────────────────────────────────────────
-  // An engine is shared by construction (terminal + desktop converge on one
-  // engine per session), but each client process only refcounts the mirrors it
+  // An session runtime is shared by construction (terminal + desktop converge on one
+  // session runtime per session), but each client process only refcounts the mirrors it
   // holds ITSELF. Without a daemon-side viewer set, the first client to quit
-  // destroyed an engine the other one was still streaming — the turn cut out
+  // destroyed an session runtime the other one was still streaming — the turn cut out
   // mid-answer and the surviving view stalled. Viewers are keyed by daemon
   // CLIENT token, so "the last view left" is a machine-wide fact.
   function subscriberToken(ctx) {
@@ -116,15 +155,15 @@ export function createEngineDaemonService({
   }
 
   /** A client that deregistered (or whose process died) stops being a viewer.
-   *  Its engines are never destroyed here: work outlives the client that
-   *  walked away, so an engine nobody watches goes back on the idle clock. */
+   *  Its session runtimes are never destroyed here: work outlives the client that
+   *  walked away, so an session runtime nobody watches goes back on the idle clock. */
   function releaseClient(clientToken) {
     const token = String(clientToken || '');
     if (!token) return { ok: true };
     for (const entry of sessions) {
       if (!entry.subscribers?.delete(token)) continue;
       if (entry.subscribers.size > 0) continue;
-      if (entry.reservedOnly && !engineBusy(entry)) {
+      if (entry.reservedOnly && !sessionBusy(entry)) {
         void destroy(entry, 'unclaimed session reservation', {
           keepBackgroundWork: true,
         });
@@ -134,17 +173,32 @@ export function createEngineDaemonService({
       startEvictionSweep();
       log(`session ${currentSessionId(entry) || '(creating)'} unwatched (client ${token} gone) — retained`);
     }
-    if (desktopBackend) desktopBackend.subscribers.delete(token);
+    for (const service of desktopServicesById.values()) {
+      service.subscribers.delete(token);
+    }
     return { ok: true };
   }
 
-  function engineBusy(entry) {
+  function stateBusy(state) {
+    return state?.busy === true || state?.commandBusy === true
+      || (Array.isArray(state?.queued) && state.queued.length > 0);
+  }
+
+  function updateEntryBusy(entry, state) {
+    const next = stateBusy(state);
+    if (entry.busy === next) return next;
+    if (entry.busy === true) busyEntries = Math.max(0, busyEntries - 1);
+    if (next) busyEntries += 1;
+    entry.busy = next;
+    return next;
+  }
+
+  function sessionBusy(entry) {
+    if (typeof entry?.busy === 'boolean') return entry.busy;
     try {
-      const state = entry.engine.getState?.() || {};
-      return state.busy === true || state.commandBusy === true
-        || (Array.isArray(state.queued) && state.queued.length > 0);
+      return updateEntryBusy(entry, entry.runtime.getState?.() || {});
     } catch {
-      // An engine we cannot read is never assumed idle — losing a live turn is
+      // An session runtime we cannot read is never assumed idle — losing a live turn is
       // far worse than holding an extra process for one sweep.
       return true;
     }
@@ -156,18 +210,48 @@ export function createEngineDaemonService({
       const now = Date.now();
       for (const entry of [...sessions]) {
         if (!entry.retainedAt) continue;
-        // A client came back to it: watched engines are never reclaimed.
+        // A client came back to it: watched session runtimes are never reclaimed.
         if (entry.subscribers?.size > 0) { entry.retainedAt = null; continue; }
-        if (engineBusy(entry)) { entry.retainedAt = now; continue; }
+        if (sessionBusy(entry)) { entry.retainedAt = now; continue; }
         if (now - entry.retainedAt < IDLE_EVICT_MS) continue;
         void destroy(entry, 'idle and unwatched');
       }
+      stopEvictionSweepIfIdle();
     }, EVICT_SWEEP_MS);
     evictTimer.unref?.();
   }
 
+  function stopEvictionSweepIfIdle() {
+    if (!evictTimer) return;
+    for (const entry of sessions) {
+      if (!entry.disposed && entry.retainedAt && (entry.subscribers?.size || 0) === 0) return;
+    }
+    clearInterval(evictTimer);
+    evictTimer = null;
+  }
+
+  function retainUnwatched(entry, reason = 'headless session budget') {
+    if (!entry || entry.disposed || (entry.subscribers?.size || 0) > 0) return;
+    entry.headless = true;
+    entry.retainedAt = Date.now();
+    releaseProjection(entry);
+    startEvictionSweep();
+  }
+
+  function releaseProjection(entry) {
+    if (!entry) return;
+    entry.snapshotSource = null;
+    entry.snapshotCache = null;
+    entry.fieldCache?.clear?.();
+    entry.itemCache?.clear?.();
+    entry.fieldCache = null;
+    entry.itemCache = null;
+    entry.publishedSnapshot = null;
+    entry.publishedSessionId = '';
+  }
+
   function snapshotOf(entry) {
-    const raw = entry.engine.getState?.() ?? null;
+    const raw = entry.runtime.getState?.() ?? null;
     // Store states are immutable snapshots (every mutation makes a new object),
     // so identity is a sound cache key. Without this the whole transcript was
     // re-sanitized on every call AND every published frame.
@@ -236,9 +320,11 @@ export function createEngineDaemonService({
     return { set, remove, itemsAppend };
   }
 
-  /** Advance the engine's published revision one step. */
+  /** Advance the session runtime's published revision one step. */
   function advance(entry) {
     const snapshot = snapshotOf(entry);
+    indexSessionEntry(entry, snapshot?.sessionId);
+    updateEntryBusy(entry, snapshot);
     const previous = entry.publishedSnapshot;
     const previousRevision = entry.revision || 0;
     if (snapshot === previous) {
@@ -264,18 +350,38 @@ export function createEngineDaemonService({
   }
 
   function currentSessionId(entry) {
-    return String(entry?.engine?.getState?.()?.sessionId || '');
+    return String(entry?.runtime?.getState?.()?.sessionId || '');
+  }
+
+  function indexSessionEntry(entry, sessionId = currentSessionId(entry)) {
+    const nextId = String(sessionId || '');
+    const previousId = String(entry?.indexedSessionId || '');
+    if (previousId && previousId !== nextId && sessionsById.get(previousId) === entry) {
+      sessionsById.delete(previousId);
+    }
+    if (!entry || entry.disposed || !nextId) {
+      if (entry) entry.indexedSessionId = '';
+      return '';
+    }
+    const existing = sessionsById.get(nextId);
+    if (existing && existing !== entry && !existing.disposed) {
+      // Do not redirect an established address to a second session runtime. The load
+      throw new Error(`duplicate session address: ${nextId}`);
+    }
+    sessionsById.set(nextId, entry);
+    entry.indexedSessionId = nextId;
+    return nextId;
   }
 
-  /** Publish one durable session-addressed frame. The engine pool is a daemon
+  /** Publish one durable session-addressed frame. The runtime pool is a daemon
    *  implementation detail and never enters the client contract. */
   function publishStep(entry, step) {
     const sessionId = currentSessionId(entry);
     if (!sessionId) return;
-    // Engine revisions may predate the session address (a reservation becomes
+    // Session runtime revisions may predate the session address (a reservation becomes
     // a materialized session during newSession/resume). A session subscriber
-    // has no copy of that engine-only base, so the first frame for each session
-    // address must be FULL; only later frames may use engine revision deltas.
+    // has no copy of that session runtime-only base, so the first frame for each session
+    // address must be FULL; only later frames may use session runtime revision deltas.
     const body = entry.publishedSessionId === sessionId
       ? frameBody(step)
       : { revision: step.revision, full: step.snapshot };
@@ -296,71 +402,31 @@ export function createEngineDaemonService({
     return { revision: step.revision, full: step.snapshot };
   }
 
-  /** Values the store returns SYNCHRONOUSLY in-process. A view cannot await
-   *  them (EngineHost does `engine.listSessions().flatMap(...)` inline), so
-   *  they ride every open/call response and the view answers from its mirror. */
-  let sharedSyncCache = null;
-  let sharedSyncEpoch = -1;
-
-  function syncSurfaceOf(entry, { refresh = false, refreshFromStorage = false } = {}) {
-    // listSessions() reads the session STORE — a scan measured in hundreds of
-    // milliseconds on a large store. Recomputing it on every call made each
-    // round trip pay for it; only session-shaping calls need a fresh surface.
-    if (!refresh && !refreshFromStorage && sharedSyncCache && sharedSyncEpoch === syncEpoch) {
-      return sharedSyncCache;
-    }
-    const surface = {};
-    try {
-      const sessions = entry.engine.listSessions?.(
-        refreshFromStorage ? { refreshFromStorage: true } : undefined,
-      );
-      if (Array.isArray(sessions)) surface.sessions = sanitizeForWire(sessions);
-    } catch { /* a store read must never fail a call */ }
-    try {
-      const dir = entry.engine.sessionStoreDir?.();
-      if (typeof dir === 'string') surface.sessionStoreDir = dir;
-    } catch { /* optional */ }
-    sharedSyncCache = surface;
-    sharedSyncEpoch = syncEpoch;
-    return surface;
-  }
-
-  // The session LIST is process-global: every entry reads the same store. A
-  // shape change made through ONE entry must therefore expire the cached
-  // surface of every OTHER entry, or a pane keeps serving a list that predates
-  // the session another view just created, renamed, or deleted.
-  let syncEpoch = 0;
-  function invalidateSyncSurfaces() {
-    syncEpoch += 1;
-    sharedSyncCache = null;
-  }
-
   /** Entry that currently holds a session live. */
   function sessionOwner(sessionId) {
     const id = String(sessionId || '');
     if (!id) return null;
-    for (const entry of sessions) {
-      if (entry.disposed) continue;
-      if (currentSessionId(entry) === id) return entry;
+    const entry = sessionsById.get(id) || null;
+    if (!entry || entry.disposed) {
+      if (entry) sessionsById.delete(id);
+      return null;
     }
-    return null;
+    return entry;
   }
 
-  // Calls that change WHICH sessions exist or which one is loaded. Only these
-  // invalidate the cached sync surface (a store scan).
-  const SESSION_SHAPING_METHODS = new Set([
-    'resume', 'resumeSession', 'newSession', 'switchContext', 'deleteSession',
-    'renameSessionTitle', 'setSessionArchived', 'prefetchSession', 'submit',
-  ]);
-
-  // Engine LIFETIME belongs to the daemon: a view drives a session, it never
-  // ends one. `subscribe` would also hand a wire client a callback it cannot
-  // receive, and reservation is the daemon's own creation step.
-  const FORBIDDEN_SESSION_METHODS = new Set(['dispose', 'subscribe', 'reserveSession']);
-
   function publish(entry) {
     if (closed || entry.disposed) return;
     try {
+      if ((entry.subscribers?.size || 0) === 0) {
+        // A headless turn still needs busy/index liveness, but no client can
+        // consume a wire projection. Avoid cloning the growing transcript on
+        // every token; the next subscriber receives a fresh full snapshot.
+        const raw = entry.runtime.getState?.() || {};
+        indexSessionEntry(entry, raw.sessionId);
+        updateEntryBusy(entry, raw);
+        releaseProjection(entry);
+        return;
+      }
       // Identical state produces no frame at all; a changed one travels as a
       // DELTA against the revision every attached view already holds.
       const step = advance(entry);
@@ -371,7 +437,7 @@ export function createEngineDaemonService({
     }
   }
 
-  /** Engine events fire per streamed token. Publish immediately after an idle
+  /** Session runtime events fire per streamed token. Publish immediately after an idle
    *  interval, then coalesce the rest of the burst to one display-frame clock.
    *  This avoids charging every first token a fixed delay. */
   function schedulePublish(entry) {
@@ -385,8 +451,9 @@ export function createEngineDaemonService({
   }
 
   async function createEntry(params = {}, ctx = null) {
-    if (closed) throw new Error('engine daemon service is closed');
-    const engine = await createEngine({
+    if (closed) throw new Error('session service is closed');
+    const runtime = await createRuntime({
+      sessionId: params.sessionId,
       cwd: params.cwd || process.cwd(),
       provider: params.provider,
       model: params.model,
@@ -395,13 +462,22 @@ export function createEngineDaemonService({
       desktopSession: params.desktopSession ?? null,
     });
     const entry = {
-      engine, cwd: params.cwd || process.cwd(), timer: null, disposed: false,
+      runtime, cwd: params.cwd || process.cwd(), timer: null, disposed: false,
       unsubscribe: null, subscribers: new Set(), reservedOnly: false, lastPublishedAt: 0,
+      indexedSessionId: '', busy: null, headless: !subscriberToken(ctx), retainedAt: null,
+      revision: revisionEpoch,
     };
     sessions.add(entry);
+    try {
+      const initialState = runtime.getState?.() || {};
+      indexSessionEntry(entry, initialState.sessionId);
+      updateEntryBusy(entry, initialState);
+    } catch {
+      updateEntryBusy(entry, { busy: true });
+    }
     addSubscriber(entry, ctx);
     try {
-      entry.unsubscribe = engine.subscribe?.(() => schedulePublish(entry)) ?? null;
+      entry.unsubscribe = runtime.subscribe?.(() => schedulePublish(entry)) ?? null;
     } catch (err) {
       log(`session subscribe failed: ${err?.message || err}`);
     }
@@ -410,31 +486,32 @@ export function createEngineDaemonService({
 
   // ── Session-addressed calls ─────────────────────────────────────────────────
   // Views are RENDERERS: a desktop pane (or a TUI tab) must be able to hand the
-  // backend a prompt for any session it can see, without owning an engine for
-  // it first. The daemon resolves the session to its engine — LOADING one when
+  // service a prompt for any session it can see, without owning an session runtime for
+  // it first. The daemon resolves the session to its session runtime — LOADING one when
   // nothing hosts it — so "that session is not live here" can never reject user
   // input (user: 채팅이 안 쳐짐).
   const sessionLoads = new Map(); // sessionId -> Promise<entry>
 
-  async function loadSessionEngine(sessionId, hints) {
+  async function loadSessionRuntime(sessionId, hints) {
     const entry = await createEntry({
+      sessionId,
       cwd: hints.cwd,
       provider: hints.provider,
       model: hints.model,
       toolMode: hints.toolMode,
       desktopSession: hints.desktopSession ?? null,
     });
-    // Nothing is watching this engine yet: it is the daemon's own load, so the
+    // Nothing is watching this session runtime yet: it is the daemon's own load, so the
     // idle sweep must be able to reclaim it if no view ever attaches.
     entry.headless = true;
     let resumed = false;
     try {
-      resumed = await entry.engine.resume?.(sessionId, hints.resumeOptions || undefined) === true;
+      resumed = await entry.runtime.resume?.(sessionId, hints.resumeOptions || undefined) === true;
     } catch (err) {
       await destroy(entry, 'session load failed');
       throw err;
     }
-    const state = entry.engine.getState?.() || {};
+    const state = entry.runtime.getState?.() || {};
     const loaded = String(state.sessionId || '');
     // Fork-on-resume names its origin; any other id is a failed load.
     const forkedFrom = String(state.sessionForkedFrom || '');
@@ -442,48 +519,62 @@ export function createEngineDaemonService({
       await destroy(entry, 'session load mismatch');
       throw new Error(`session ${sessionId} could not be resumed`);
     }
+    // Publish/index the resumed identity before sessionLoads releases its
+    // single-flight promise. A second pane arriving in the next microtask must
+    // find this owner in O(1), not create a duplicate session runtime.
+    advance(entry);
+    retainUnwatched(entry, 'headless session load');
     log(`session ${sessionId} loaded on demand`);
     return entry;
   }
 
-  /** The engine hosting sessionId: the existing owner, or a fresh load. One
-   *  load per session at a time — concurrent panes converge on one engine. */
+  /** The runtime hosting sessionId: the existing owner, or a fresh load. One
+   *  load per session at a time — concurrent panes converge on one session runtime. */
   async function entryForSession(sessionId, hints = {}) {
     const owner = sessionOwner(sessionId);
     if (owner) return owner;
     const inFlight = sessionLoads.get(sessionId);
     if (inFlight) return inFlight;
     let loading;
-    loading = loadSessionEngine(sessionId, hints).finally(() => {
+    loading = (async () => {
+      if (typeof sessionExists === 'function'
+        && await sessionExists(sessionId) !== true) {
+        // A session may have been created while the durable check was in
+        // flight. Reuse that owner, but never materialize an unknown address
+        // merely because a stale pane subscribed to it.
+        const lateOwner = sessionOwner(sessionId);
+        if (lateOwner) return lateOwner;
+        throw new Error(`session ${sessionId} is not available`);
+      }
+      return loadSessionRuntime(sessionId, hints);
+    })().finally(() => {
       if (sessionLoads.get(sessionId) === loading) sessionLoads.delete(sessionId);
     });
     sessionLoads.set(sessionId, loading);
     return loading;
   }
 
-  /** Apply one compatibility store method to whatever engine owns a SESSION. */
-  async function sessionCall({
-    sessionId, method, args = [], open: openHints = {}, baseRevision = null,
-  } = {}) {
-    if (closed) throw new Error('engine daemon service is closed');
+  async function runSessionAction({
+    sessionId, action, args = [], open: openHints = {}, baseRevision = null,
+  } = {}, allowedActions) {
+    if (closed) throw new Error('session service is closed');
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
-    const name = String(method || '');
-    // `name in Object.prototype` blocks toString/valueOf/hasOwnProperty: they
-    // are functions on every object but were never part of the engine contract.
-    if (!name || name === 'constructor' || name.startsWith('__')
-      || FORBIDDEN_SESSION_METHODS.has(name) || name in Object.prototype) {
-      throw new TypeError(`engine method ${name} is unavailable`);
-    }
+    const name = requireSessionAction(action, allowedActions);
     const entry = await entryForSession(id, openHints || {});
-    const target = entry.engine[name];
-    if (typeof target !== 'function') throw new TypeError(`engine method ${name} is unavailable`);
-    const value = await target.apply(entry.engine, Array.isArray(args) ? args : []);
-    const shaping = SESSION_SHAPING_METHODS.has(name);
-    if (shaping) invalidateSyncSurfaces();
-    // Keep one compact record that the call reached the backend without
-    // serializing transcripts/catalogs into the daemon log. A cold pane peek
-    // previously wrote hundreds of KB synchronously on the request path.
+    const target = entry.runtime[name];
+    if (typeof target !== 'function') throw new TypeError(`session action ${name} is unavailable`);
+    const value = await target.apply(entry.runtime, Array.isArray(args) ? args : []);
+    if (name === 'setCwd' && value) {
+      try {
+        const projects = await loadProjectStore();
+        projects.touchProjectSelected?.(value);
+      } catch (error) {
+        log(`project recency update failed (non-fatal): ${error?.message || error}`);
+      }
+    }
+    // Keep one compact record that the action reached the service without
+    // serializing transcripts/catalogs into the daemon log.
     const valueSummary = value === null || value === undefined
       ? String(value)
       : typeof value === 'object'
@@ -491,42 +582,140 @@ export function createEngineDaemonService({
           ? `array(${value.length})`
           : `object${Array.isArray(value.items) ? ` items=${value.items.length}` : ''}`
         : String(value).replace(/\s+/g, ' ').slice(0, 160);
-    log(`session call ${name} session=${id} result=${valueSummary}`);
+    log(`session action ${name} session=${id} result=${valueSummary}`);
     const step = advance(entry);
     if (step.changed) {
       publishStep(entry, step);
     }
-    // Still unwatched: keep it on the retention clock exactly like an engine a
-    // view released, so an untouched load cannot leak past the idle window.
-    if (entry.headless) {
-      entry.retainedAt = Date.now();
-      startEvictionSweep();
-    }
+    // Still unwatched: keep it on the retention clock exactly like a session runtime
+    // released by its view, so an untouched load cannot leak past the idle window.
+    retainUnwatched(entry);
     return {
       value: sanitizeForWire(value) ?? null,
-      sessionId: String(entry.engine.getState?.()?.sessionId || id),
+      sessionId: String(entry.runtime.getState?.()?.sessionId || id),
       ...bodyForClient(step, Number.isInteger(baseRevision) ? baseRevision : null),
-      sync: syncSurfaceOf(entry, { refresh: shaping }),
     };
   }
 
+  async function listSessionCatalog(options = {}) {
+    if (closed) throw new Error('session service is closed');
+    if (typeof listSessions !== 'function') {
+      throw new Error('session catalog is unavailable');
+    }
+    const sessions = await listSessions(options || {});
+    return { sessions: sanitizeForWire(Array.isArray(sessions) ? sessions : []) };
+  }
+
+  async function loadProjectStore() {
+    if (typeof desktopRuntime?.loadProjects !== 'function') {
+      throw new Error('project service is unavailable');
+    }
+    projectStorePromise ??= Promise.resolve(desktopRuntime.loadProjects()).catch((error) => {
+      projectStorePromise = null;
+      throw error;
+    });
+    return projectStorePromise;
+  }
+
+  function requiredProjectPath(path) {
+    const value = String(path || '').trim();
+    if (!value) throw new TypeError('project path is required');
+    return value;
+  }
+
+  async function listProjectCatalog() {
+    const projects = await loadProjectStore();
+    return {
+      projects: sanitizeForWire(projects.listProjects?.() || []),
+    };
+  }
+
+  async function inspectProjectPath({ path } = {}) {
+    const projects = await loadProjectStore();
+    const resolved = projects.resolveProjectPath?.(requiredProjectPath(path)) || '';
+    if (!resolved) throw new TypeError('project path is required');
+    return {
+      path: resolved,
+      exists: projects.pathExists?.(resolved) === true,
+      directory: projects.isDirectory?.(resolved) === true,
+    };
+  }
+
+  async function addProjectEntry({ path } = {}) {
+    const projects = await loadProjectStore();
+    const project = projects.addProject?.(requiredProjectPath(path)) || null;
+    if (!project) throw new Error('project could not be registered');
+    return { project: sanitizeForWire(project) };
+  }
+
+  async function touchProjectEntry({ path } = {}) {
+    const projects = await loadProjectStore();
+    return {
+      project: sanitizeForWire(projects.touchProjectSelected?.(requiredProjectPath(path)) || null),
+    };
+  }
+
+  async function renameProjectEntry({ path, name = '' } = {}) {
+    const projects = await loadProjectStore();
+    const project = projects.renameProject?.(requiredProjectPath(path), String(name || '')) || null;
+    if (!project) throw new Error('project is not registered');
+    return { project: sanitizeForWire(project) };
+  }
+
+  async function removeProjectEntry({ path } = {}) {
+    const projects = await loadProjectStore();
+    return { removed: projects.removeProject?.(requiredProjectPath(path)) === true };
+  }
+
+  async function ensureProjectDirectory({ path } = {}) {
+    const projects = await loadProjectStore();
+    const resolved = projects.ensureDir?.(requiredProjectPath(path)) || '';
+    if (!resolved) throw new Error('project directory could not be created');
+    return { path: resolved };
+  }
+
+  function requireSessionAction(action, allowed) {
+    const name = String(action || '');
+    if (!allowed.has(name)) throw new TypeError(`session action ${name || '(empty)'} is unavailable`);
+    return name;
+  }
+
+  async function configureSession(params = {}, ctx = null) {
+    const revision = Math.max(0, Number(ctx?.revision) || 0);
+    const action = revision < 1 && params?.action === 'setBackend'
+      ? 'setChannelProvider'
+      : params?.action;
+    // Revision 0 desktop adapters routed some reads through configure because
+    // their local read list lagged the session surface. A newer daemon accepts
+    // those reads without weakening the current revision's finite lanes.
+    if (revision < 1 && SESSION_READ_ACTION_SET.has(String(action || ''))) {
+      return runSessionAction({ ...params, action }, SESSION_READ_ACTION_SET);
+    }
+    return runSessionAction({ ...params, action }, SESSION_CONFIGURE_ACTION_SET);
+  }
+
   // ── Durable session protocol ───────────────────────────────────────────────
   // A connection is only a subscription. Session execution is accepted,
   // queued, and owned here; unsubscribe/client death never calls abort or
   // dispose. The client addresses a durable session id instead of a
-  // client-owned engine handle.
+  // client-owned session runtime handle.
 
-  function sessionResult(entry, step, baseRevision = null, extra = {}) {
+  function sessionResult(
+    entry,
+    step,
+    baseRevision = null,
+    extra = {},
+  ) {
     return {
       sessionId: currentSessionId(entry),
+      reservedOnly: entry.reservedOnly === true,
       ...extra,
       ...bodyForClient(step, Number.isInteger(baseRevision) ? baseRevision : null),
-      sync: syncSurfaceOf(entry),
     };
   }
 
   async function createSession(params = {}, ctx = null) {
-    if (closed) throw new Error('engine daemon service is closed');
+    if (closed) throw new Error('session service is closed');
     const requestedId = String(params.sessionId || '').trim();
     if (requestedId) {
       if (!/^[A-Za-z0-9_-]+$/.test(requestedId)) throw new TypeError('sessionId is invalid');
@@ -537,26 +726,27 @@ export function createEngineDaemonService({
         return sessionResult(owner, step);
       }
     }
-    const entry = await createEntry(params, ctx);
+    const reservedSessionId = requestedId
+      || `sess_daemon_${Date.now()}_${randomUUID().replaceAll('-', '')}`;
+    const entry = await createEntry({ ...params, sessionId: reservedSessionId }, ctx);
     try {
       let sessionId = currentSessionId(entry);
       if (!sessionId) {
-        sessionId = requestedId
-          || `sess_daemon_${Date.now()}_${randomUUID().replaceAll('-', '')}`;
+        sessionId = reservedSessionId;
         if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) throw new TypeError('sessionId is invalid');
-        const target = entry.engine.reserveSession;
+        const target = entry.runtime.reserveSession;
         if (typeof target !== 'function') {
-          throw new TypeError('engine method reserveSession is unavailable');
+          throw new TypeError('session action reserveSession is unavailable');
         }
-        await target.call(entry.engine, sessionId);
+        await target.call(entry.runtime, sessionId);
         entry.reservedOnly = true;
         sessionId = currentSessionId(entry);
       }
       if (!sessionId) throw new Error('session creation returned no sessionId');
       const step = advance(entry);
       if (step.changed) publishStep(entry, step);
-      invalidateSyncSurfaces();
       log(`session created session=${sessionId}`);
+      retainUnwatched(entry, 'headless session create');
       return sessionResult(entry, step);
     } catch (error) {
       await destroy(entry, 'session creation failed', { keepBackgroundWork: true });
@@ -564,16 +754,26 @@ export function createEngineDaemonService({
     }
   }
 
-  async function readSession({ sessionId, open: openHints = {}, baseRevision = null } = {}) {
+  async function readSession(params = {}, ctx = null) {
+    const {
+      sessionId, open: openHints = {}, baseRevision = null, baseSyncRevision = null,
+    } = params;
+    if (params.action != null) {
+      void ctx;
+      return runSessionAction(params, SESSION_READ_ACTION_SET);
+    }
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const entry = await entryForSession(id, openHints || {});
     const step = advance(entry);
+    retainUnwatched(entry, 'headless session read');
     return sessionResult(entry, step, baseRevision);
   }
 
   async function subscribeSession(
-    { sessionId, open: openHints = {}, baseRevision = null } = {},
+    {
+      sessionId, open: openHints = {}, baseRevision = null, baseSyncRevision = null,
+    } = {},
     ctx = null,
   ) {
     const id = String(sessionId || '');
@@ -593,13 +793,14 @@ export function createEngineDaemonService({
     const token = subscriberToken(ctx);
     if (token) entry.subscribers?.delete(token);
     if ((entry.subscribers?.size || 0) === 0) {
-      if (entry.reservedOnly && !engineBusy(entry)) {
+      if (entry.reservedOnly && !sessionBusy(entry)) {
         await destroy(entry, 'unclaimed session reservation', {
           keepBackgroundWork: true,
         });
         return { sessionId: id, unsubscribed: true };
       }
       entry.retainedAt = Date.now();
+      releaseProjection(entry);
       startEvictionSweep();
     }
     log(`session unsubscribed session=${id}${token ? ` client=${token}` : ''}`);
@@ -612,33 +813,45 @@ export function createEngineDaemonService({
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const entry = await entryForSession(id, openHints || {});
-    const target = entry.engine.submit;
-    if (typeof target !== 'function') throw new TypeError('engine method submit is unavailable');
-    // Engine submit is an intake operation: it records/queues synchronously and
-    // returns before provider execution. Awaiting Promise.resolve only
-    // normalizes embedders; it never waits for the turn.
-    const accepted = await Promise.resolve(target.call(entry.engine, prompt, options || {}));
+    const target = entry.runtime.submitAsync;
+    if (typeof target !== 'function') throw new TypeError('session runtime must implement submitAsync');
+    // Await intake only: submitAsync resolves once the prompt is represented by
+    // the queue/user row, while provider execution remains daemon-owned and
+    // detached.
+    const accepted = await Promise.resolve(target.call(entry.runtime, prompt, options || {}));
+    const firstSubmit = accepted === true && entry.reservedOnly;
     if (accepted === true) {
       entry.reservedOnly = false;
-      // First submit materializes a reserved session in the store.
-      invalidateSyncSurfaces();
     }
     const step = advance(entry);
     if (step.changed) publishStep(entry, step);
+    retainUnwatched(entry, 'headless session submit');
     log(`session submit session=${id} accepted=${accepted === true}`);
-    return sessionResult(entry, step, baseRevision, { accepted: accepted === true });
+    return sessionResult(
+      entry,
+      step,
+      baseRevision,
+      { accepted: accepted === true },
+    );
   }
 
-  async function abortSession({ sessionId, open: openHints = {}, baseRevision = null } = {}) {
+  async function abortSession({
+    sessionId, open: openHints = {}, options = {},
+    baseRevision = null,
+  } = {}) {
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const entry = await entryForSession(id, openHints || {});
-    const target = entry.engine.abort;
-    if (typeof target !== 'function') throw new TypeError('engine method abort is unavailable');
-    const aborted = await target.call(entry.engine);
+    const target = entry.runtime.abort;
+    if (typeof target !== 'function') throw new TypeError('session action abort is unavailable');
+    const rawResult = await target.call(entry.runtime, options || {});
+    const abortResult = rawResult && typeof rawResult === 'object'
+      ? rawResult
+      : { aborted: rawResult === true };
     const step = advance(entry);
     if (step.changed) publishStep(entry, step);
-    return sessionResult(entry, step, baseRevision, { aborted: aborted === true });
+    retainUnwatched(entry, 'headless session abort');
+    return sessionResult(entry, step, baseRevision, abortResult);
   }
 
   async function approveSession({
@@ -647,13 +860,14 @@ export function createEngineDaemonService({
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const entry = await entryForSession(id, openHints || {});
-    const target = entry.engine.resolveToolApproval;
+    const target = entry.runtime.resolveToolApproval;
     if (typeof target !== 'function') {
-      throw new TypeError('engine method resolveToolApproval is unavailable');
+      throw new TypeError('session action resolveToolApproval is unavailable');
     }
-    const approved = await target.call(entry.engine, approvalId, decision);
+    const approved = await target.call(entry.runtime, approvalId, decision);
     const step = advance(entry);
     if (step.changed) publishStep(entry, step);
+    retainUnwatched(entry, 'headless session approval');
     return sessionResult(entry, step, baseRevision, { approved: approved === true });
   }
 
@@ -665,11 +879,17 @@ export function createEngineDaemonService({
     if (!entry || entry.disposed) return { ok: true };
     const sessionId = currentSessionId(entry);
     entry.disposed = true;
+    releaseProjection(entry);
     if (entry.timer) { clearTimeout(entry.timer); entry.timer = null; }
     try { entry.unsubscribe?.(); } catch {}
     sessions.delete(entry);
-    invalidateSyncSurfaces();
-    try { await entry.engine.dispose?.(reason, { keepBackgroundWork }); }
+    stopEvictionSweepIfIdle();
+    if (entry.indexedSessionId && sessionsById.get(entry.indexedSessionId) === entry) {
+      sessionsById.delete(entry.indexedSessionId);
+    }
+    if (entry.busy === true) busyEntries = Math.max(0, busyEntries - 1);
+    entry.busy = false;
+    try { await entry.runtime.dispose?.(reason, { keepBackgroundWork }); }
     catch (err) { log(`session dispose failed session=${sessionId}: ${err?.message || err}`); }
     if (announce && sessionId) {
       onFrame({
@@ -683,7 +903,7 @@ export function createEngineDaemonService({
     return { ok: true };
   }
 
-  // ── Desktop backend adapter ────────────────────────────────────────────────
+  // ── Desktop service adapter ────────────────────────────────────────────────
   // The adapter is a BUILD artifact supplied by the desktop install, but it is
   // instantiated here. Electron and its renderer only keep a transport view;
   // project/session/capability execution therefore shares this daemon process
@@ -693,11 +913,11 @@ export function createEngineDaemonService({
     if (kind === 'session-state') {
       return `desktop-event:${desktopId}:${kind}:${String(message?.sessionId || '')}`;
     }
-    // Backend events are NOT one lane. Under one shared `backend-event` key a
+    // Service events are NOT one lane. Under one shared `desktop-event` key a
     // terminal flood clobbered LSP/folder events — and every other terminal —
     // whenever the stream backed up, because the backlog is latest-wins per
     // key. Name (and terminal id) keep each producer on its own key.
-    if (kind === 'backend-event') {
+    if (kind === 'desktop-event') {
       const name = String(message?.name || '');
       const terminalId = name === 'terminal-data' ? String(message?.value?.id || '') : '';
       return `desktop-event:${desktopId}:${kind}:${name}${terminalId ? `:${terminalId}` : ''}`;
@@ -707,17 +927,18 @@ export function createEngineDaemonService({
 
   function publishDesktopEvent(desktopId, message) {
     const wire = sanitizeForWire(message);
-    if (!wire || !desktopBackend || desktopBackend.desktopId !== desktopId) return;
+    const service = desktopServicesById.get(desktopId);
+    if (!wire || !service) return;
     onFrame({
       type: 'desktop-event',
       key: desktopEventKey(desktopId, wire),
       desktopId,
       message: wire,
-    }, desktopBackend.subscribers);
+    }, service.subscribers);
   }
 
-  async function initializeDesktopBackend({ desktopId, moduleUrl, options = {} } = {}) {
-    if (closed) throw new Error('engine daemon service is closed');
+  async function initializeDesktopService({ desktopId, moduleUrl, options = {} } = {}) {
+    if (closed) throw new Error('session service is closed');
     const requestedId = String(desktopId || '').trim();
     if (!requestedId || !/^[A-Za-z0-9_-]+$/.test(requestedId)) {
       throw new TypeError('desktopId is invalid');
@@ -725,27 +946,27 @@ export function createEngineDaemonService({
     const requestedModule = String(moduleUrl || '').trim();
     let parsed;
     try { parsed = new URL(requestedModule); }
-    catch { throw new TypeError('desktop backend moduleUrl is invalid'); }
+    catch { throw new TypeError('desktop service moduleUrl is invalid'); }
     if (parsed.protocol !== 'file:') {
-      throw new TypeError('desktop backend moduleUrl must be a file URL');
-    }
-    if (desktopBackend) {
-      if (desktopBackend.moduleUrl !== requestedModule) {
-        // The daemon owns one canonical backend for its whole lifetime. A dev
-        // and installed Electron can attach concurrently without racing to
-        // replace it; protocol negotiation restarts genuinely incompatible
-        // daemons before desktop.init reaches this point.
-        log(`desktop backend already active; ignoring alternate module ${requestedModule}`);
+      throw new TypeError('desktop service moduleUrl must be a file URL');
+    }
+    const existingByModule = desktopServicesByModule.get(requestedModule);
+    if (existingByModule) return existingByModule;
+    const existingById = desktopServicesById.get(requestedId);
+    if (existingById) {
+      if (existingById.moduleUrl !== requestedModule) {
+        throw new Error(`desktopId ${requestedId} is already bound to another service module`);
       }
-      return desktopBackend;
+      return existingById;
     }
-    if (desktopBackendPromise) return desktopBackendPromise;
-    desktopBackendPromise = (async () => {
-      const loaded = await import(requestedModule);
-      if (typeof loaded.createDesktopBackend !== 'function') {
-        throw new TypeError('desktop backend module has no createDesktopBackend export');
+    const pending = desktopServicePromises.get(requestedModule);
+    if (pending) return pending;
+    const loading = (async () => {
+      const loaded = await loadDesktopServiceModule(requestedModule);
+      if (typeof loaded.createDesktopService !== 'function') {
+        throw new TypeError('desktop service module has no createDesktopService export');
       }
-      const instance = await loaded.createDesktopBackend({
+      const instance = await loaded.createDesktopService({
         options: sanitizeForWire(options) || {},
         runtime: desktopRuntime,
         emit: (message) => publishDesktopEvent(requestedId, message),
@@ -755,7 +976,7 @@ export function createEngineDaemonService({
       });
       if (!instance || typeof instance.invoke !== 'function'
         || typeof instance.control !== 'function') {
-        throw new TypeError('desktop backend adapter is invalid');
+        throw new TypeError('desktop service adapter is invalid');
       }
       const record = {
         desktopId: requestedId,
@@ -763,53 +984,56 @@ export function createEngineDaemonService({
         instance,
         subscribers: new Set(),
       };
-      desktopBackend = record;
-      log(`desktop backend loaded id=${requestedId}`);
+      desktopServicesById.set(requestedId, record);
+      desktopServicesByModule.set(requestedModule, record);
+      log(`desktop service loaded id=${requestedId} module=${requestedModule}`);
       return record;
     })();
+    desktopServicePromises.set(requestedModule, loading);
     try {
-      return await desktopBackendPromise;
+      return await loading;
     } finally {
-      desktopBackendPromise = null;
+      if (desktopServicePromises.get(requestedModule) === loading) {
+        desktopServicePromises.delete(requestedModule);
+      }
     }
   }
 
   async function desktopInit(params = {}, ctx = null) {
-    const backend = await initializeDesktopBackend(params);
+    const service = await initializeDesktopService(params);
     const token = subscriberToken(ctx);
-    if (token) backend.subscribers.add(token);
-    return { desktopId: backend.desktopId };
+    if (token) service.subscribers.add(token);
+    return { desktopId: service.desktopId };
   }
 
-  function requireDesktopBackend(desktopId) {
+  function requireDesktopService(desktopId) {
     const id = String(desktopId || '');
-    if (!desktopBackend || desktopBackend.desktopId !== id) {
-      throw new Error('desktop backend is not initialized');
-    }
-    return desktopBackend;
+    const service = desktopServicesById.get(id);
+    if (!service) throw new Error('desktop service is not initialized');
+    return service;
   }
 
   async function desktopInvoke({ desktopId, method, args = [] } = {}, ctx = null) {
-    const backend = requireDesktopBackend(desktopId);
+    const service = requireDesktopService(desktopId);
     const token = subscriberToken(ctx);
-    if (token) backend.subscribers.add(token);
+    if (token) service.subscribers.add(token);
     const name = String(method || '');
-    if (!name) throw new TypeError('desktop backend method is required');
-    return sanitizeForWire(await backend.instance.invoke(name, Array.isArray(args) ? args : [])) ?? null;
+    if (!name) throw new TypeError('desktop service method is required');
+    return sanitizeForWire(await service.instance.invoke(name, Array.isArray(args) ? args : [])) ?? null;
   }
 
   async function desktopControl({ desktopId, message } = {}, ctx = null) {
-    const backend = requireDesktopBackend(desktopId);
+    const service = requireDesktopService(desktopId);
     const token = subscriberToken(ctx);
-    if (token) backend.subscribers.add(token);
-    await backend.instance.control(sanitizeForWire(message) || {});
+    if (token) service.subscribers.add(token);
+    await service.instance.control(sanitizeForWire(message) || {});
     return { ok: true };
   }
 
   async function desktopUnsubscribe({ desktopId } = {}, ctx = null) {
-    const backend = requireDesktopBackend(desktopId);
+    const service = requireDesktopService(desktopId);
     const token = subscriberToken(ctx);
-    if (token) backend.subscribers.delete(token);
+    if (token) service.subscribers.delete(token);
     return { ok: true, unsubscribed: true };
   }
 
@@ -818,6 +1042,14 @@ export function createEngineDaemonService({
     'desktop.invoke': desktopInvoke,
     'desktop.control': desktopControl,
     'desktop.unsubscribe': desktopUnsubscribe,
+    'project.list': listProjectCatalog,
+    'project.inspect': inspectProjectPath,
+    'project.add': addProjectEntry,
+    'project.touch': touchProjectEntry,
+    'project.rename': renameProjectEntry,
+    'project.remove': removeProjectEntry,
+    'project.ensureDirectory': ensureProjectDirectory,
+    'session.list': listSessionCatalog,
     'session.create': createSession,
     'session.read': readSession,
     'session.subscribe': subscribeSession,
@@ -825,23 +1057,26 @@ export function createEngineDaemonService({
     'session.submit': submitSession,
     'session.abort': abortSession,
     'session.approve': approveSession,
-    'session.invoke': sessionCall,
+    'session.configure': configureSession,
   };
 
   async function handleCall(name, args = {}, ctx = null) {
     const route = routes[String(name || '')];
-    if (!route) throw new Error(`unknown engine daemon call ${name}`);
+    if (!route) throw new Error(`unknown session service call ${name}`);
     return route(args || {}, ctx);
   }
 
   async function stop(reason = 'service stop') {
     closed = true;
     if (evictTimer) { clearInterval(evictTimer); evictTimer = null; }
-    const backend = desktopBackend;
-    desktopBackend = null;
-    if (backend?.instance?.dispose) {
-      try { await backend.instance.dispose(reason); }
-      catch (error) { log(`desktop backend dispose failed: ${error?.message || error}`); }
+    const services = [...new Set(desktopServicesById.values())];
+    desktopServicesById.clear();
+    desktopServicesByModule.clear();
+    desktopServicePromises.clear();
+    for (const service of services) {
+      if (!service?.instance?.dispose) continue;
+      try { await service.instance.dispose(reason); }
+      catch (error) { log(`desktop service dispose failed: ${error?.message || error}`); }
     }
     for (const entry of [...sessions]) {
       await destroy(entry, reason);
@@ -849,16 +1084,38 @@ export function createEngineDaemonService({
   }
 
   return {
-    handleCall, createSession, readSession, subscribeSession, unsubscribeSession,
+    handleCall, listSessionCatalog, createSession, readSession, subscribeSession, unsubscribeSession,
     submitSession, abortSession, approveSession,
-    sessionCall, stop, releaseClient,
+    configureSession, stop, releaseClient,
     get size() { return sessions.size; },
     /** Live work the daemon must not abandon (self-shutdown guard). */
-    get busyCount() { return [...sessions].filter((entry) => engineBusy(entry)).length; },
-    /** Phone clients hosted by the daemon-owned desktop adapter. */
+    get busyCount() { return busyEntries; },
+    get status() {
+      let watched = 0;
+      let retained = 0;
+      let projected = 0;
+      for (const entry of sessions) {
+        if ((entry.subscribers?.size || 0) > 0) watched += 1;
+        else if (entry.retainedAt) retained += 1;
+        if (entry.snapshotCache || entry.publishedSnapshot) projected += 1;
+      }
+      return {
+        live: sessions.size,
+        busy: busyEntries,
+        watched,
+        retained,
+        projected,
+        evictionSweepActive: evictTimer !== null,
+      };
+    },
+    /** Phone clients hosted by daemon-owned desktop adapters. */
     get externalClientCount() {
-      const count = Number(desktopBackend?.instance?.clientCount ?? 0);
-      return Number.isSafeInteger(count) && count > 0 ? count : 0;
+      let total = 0;
+      for (const service of desktopServicesById.values()) {
+        const count = Number(service?.instance?.clientCount ?? 0);
+        if (Number.isSafeInteger(count) && count > 0) total += count;
+      }
+      return total;
     },
   };
 }