mixdog 0.9.96 → 0.9.99

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

@@ -1,14 +1,13 @@
-// 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';
@@ -16,11 +15,15 @@ import {
   SESSION_CONFIGURE_ACTION_SET,
   SESSION_READ_ACTION_SET,
 } from './session-protocol.mjs';
+import {
+  materializePromptSubmission,
+  preparePromptSubmissionForProvider,
+} from '../runtime/attachments/store.mjs';
 
 const MAX_CLONE_DEPTH = 24;
-const requireDesktopBackend = createRequire(import.meta.url);
+const requireDesktopService = createRequire(import.meta.url);
 
-async function loadDesktopBackendModule(moduleUrl) {
+async function loadDesktopServiceModule(moduleUrl) {
   const parsed = new URL(moduleUrl);
   if (!parsed.pathname.toLowerCase().endsWith('.cjs')) {
     return import(moduleUrl);
@@ -30,12 +33,12 @@ async function loadDesktopBackendModule(moduleUrl) {
   // already-instantiated adapters alive, but load this newly keyed artifact
   // from disk for the new desktop build.
   const modulePath = fileURLToPath(parsed);
-  const resolved = requireDesktopBackend.resolve(modulePath);
-  delete requireDesktopBackend.cache[resolved];
-  return requireDesktopBackend(resolved);
+  const resolved = requireDesktopService.resolve(modulePath);
+  delete requireDesktopService.cache[resolved];
+  return requireDesktopService(resolved);
 }
 
-/** JSON-safe projection of an engine snapshot. Functions, symbols, and
+/** 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. */
@@ -88,8 +91,8 @@ export function sanitizeForWire(value, depth = 0, seen = new WeakSet()) {
   }
 }
 
-export function createEngineDaemonService({
-  createEngine,
+export function createSessionService({
+  createSessionRuntime = null,
   sessionExists = null,
   listSessions = null,
   desktopRuntime = null,
@@ -100,14 +103,13 @@ 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 an already-running legacy view (which compared
-  // revisions across reconnects) still accepts the replacement daemon's first
-  // full snapshot. New views explicitly reset their revision baseline on
-  // attachment replacement and do not depend on this compatibility seed.
-  const configuredRevisionEpoch = Number(process.env.MIXDOG_ENGINE_REVISION_EPOCH);
+  // 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
@@ -118,32 +120,29 @@ export function createEngineDaemonService({
   const sessions = new Set();
   const sessionsById = new Map();
   let busyEntries = 0;
-  // Desktop builds can overlap during an update (or while a dev preview is
-  // open). Their adapters are build artifacts and therefore must not be
-  // mistaken for one process-global implementation. Reuse an adapter only for
-  // the same module URL; compatible builds otherwise coexist on the stable
-  // daemon wire protocol.
-  const desktopBackendsById = new Map();
-  const desktopBackendsByModule = new Map();
-  const desktopBackendPromises = new Map();
+  // 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) || 2 * 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) {
@@ -160,15 +159,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,
         });
@@ -178,8 +177,8 @@ export function createEngineDaemonService({
       startEvictionSweep();
       log(`session ${currentSessionId(entry) || '(creating)'} unwatched (client ${token} gone) — retained`);
     }
-    for (const backend of desktopBackendsById.values()) {
-      backend.subscribers.delete(token);
+    for (const service of desktopServicesById.values()) {
+      service.subscribers.delete(token);
     }
     return { ok: true };
   }
@@ -198,12 +197,12 @@ export function createEngineDaemonService({
     return next;
   }
 
-  function engineBusy(entry) {
+  function sessionBusy(entry) {
     if (typeof entry?.busy === 'boolean') return entry.busy;
     try {
-      return updateEntryBusy(entry, entry.engine.getState?.() || {});
+      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;
     }
@@ -215,16 +214,26 @@ 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;
@@ -246,7 +255,7 @@ export function createEngineDaemonService({
   }
 
   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.
@@ -267,6 +276,20 @@ export function createEngineDaemonService({
     const items = entry.itemCache ??= new Map();
     const out = {};
     for (const [key, value] of Object.entries(raw)) {
+      if (key === 'queued' && Array.isArray(value)) {
+        const projected = value.map((item) => ({
+          id: item?.id,
+          submittedAt: item?.submittedAt,
+          text: String(item?.displayText ?? item?.text ?? '').slice(0, 2_000),
+          displayText: String(item?.displayText ?? item?.text ?? '').slice(0, 2_000),
+          mode: item?.mode || 'prompt',
+          priority: item?.priority || 'next',
+          ...(Array.isArray(item?.images) && item.images.length ? { images: item.images } : {}),
+        }));
+        fields.set(key, { source: value, value: projected });
+        out[key] = projected;
+        continue;
+      }
       if (key === 'items' && Array.isArray(value)) {
         const nextItems = new Map();
         out.items = value.map((item) => {
@@ -315,7 +338,7 @@ 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);
@@ -345,7 +368,7 @@ export function createEngineDaemonService({
   }
 
   function currentSessionId(entry) {
-    return String(entry?.engine?.getState?.()?.sessionId || '');
+    return String(entry?.runtime?.getState?.()?.sessionId || '');
   }
 
   function indexSessionEntry(entry, sessionId = currentSessionId(entry)) {
@@ -360,27 +383,23 @@ export function createEngineDaemonService({
     }
     const existing = sessionsById.get(nextId);
     if (existing && existing !== entry && !existing.disposed) {
-      // Do not redirect an established address to a second engine. The load
-      // coordinator normally makes this impossible; retaining the first owner
-      // is the safest fallback if an embedder mutates a session id directly.
-      entry.indexedSessionId = '';
-      log(`duplicate session address refused session=${nextId}`);
-      return nextId;
+      // 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 };
@@ -420,7 +439,7 @@ export function createEngineDaemonService({
         // 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.engine.getState?.() || {};
+        const raw = entry.runtime.getState?.() || {};
         indexSessionEntry(entry, raw.sessionId);
         updateEntryBusy(entry, raw);
         releaseProjection(entry);
@@ -436,7 +455,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) {
@@ -450,8 +469,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,
@@ -460,14 +480,14 @@ 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 = engine.getState?.() || {};
+      const initialState = runtime.getState?.() || {};
       indexSessionEntry(entry, initialState.sessionId);
       updateEntryBusy(entry, initialState);
     } catch {
@@ -475,7 +495,7 @@ export function createEngineDaemonService({
     }
     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}`);
     }
@@ -484,31 +504,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 || '');
@@ -518,15 +539,15 @@ export function createEngineDaemonService({
     }
     // 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 engine.
+    // 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;
@@ -543,7 +564,7 @@ export function createEngineDaemonService({
         if (lateOwner) return lateOwner;
         throw new Error(`session ${sessionId} is not available`);
       }
-      return loadSessionEngine(sessionId, hints);
+      return loadSessionRuntime(sessionId, hints);
     })().finally(() => {
       if (sessionLoads.get(sessionId) === loading) sessionLoads.delete(sessionId);
     });
@@ -554,14 +575,14 @@ export function createEngineDaemonService({
   async function runSessionAction({
     sessionId, action, args = [], open: openHints = {}, baseRevision = null,
   } = {}, allowedActions) {
-    if (closed) throw new Error('engine daemon service is closed');
+    if (closed) throw new Error('session service is closed');
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const name = requireSessionAction(action, allowedActions);
     const entry = await entryForSession(id, openHints || {});
-    const target = entry.engine[name];
+    const target = entry.runtime[name];
     if (typeof target !== 'function') throw new TypeError(`session action ${name} is unavailable`);
-    const value = await target.apply(entry.engine, Array.isArray(args) ? args : []);
+    const value = await target.apply(entry.runtime, Array.isArray(args) ? args : []);
     if (name === 'setCwd' && value) {
       try {
         const projects = await loadProjectStore();
@@ -570,7 +591,7 @@ export function createEngineDaemonService({
         log(`project recency update failed (non-fatal): ${error?.message || error}`);
       }
     }
-    // Keep one compact record that the action reached the backend without
+    // 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)
@@ -584,18 +605,18 @@ export function createEngineDaemonService({
     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.
+    // 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),
     };
   }
 
   async function listSessionCatalog(options = {}) {
-    if (closed) throw new Error('engine daemon service is closed');
+    if (closed) throw new Error('session service is closed');
     if (typeof listSessions !== 'function') {
       throw new Error('session catalog is unavailable');
     }
@@ -605,7 +626,7 @@ export function createEngineDaemonService({
 
   async function loadProjectStore() {
     if (typeof desktopRuntime?.loadProjects !== 'function') {
-      throw new Error('project backend is unavailable');
+      throw new Error('project service is unavailable');
     }
     projectStorePromise ??= Promise.resolve(desktopRuntime.loadProjects()).catch((error) => {
       projectStorePromise = null;
@@ -678,15 +699,24 @@ export function createEngineDaemonService({
   }
 
   async function configureSession(params = {}, ctx = null) {
-    void ctx;
-    return runSessionAction(params, SESSION_CONFIGURE_ACTION_SET);
+    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,
@@ -703,7 +733,7 @@ export function createEngineDaemonService({
   }
 
   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');
@@ -714,18 +744,19 @@ 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);
       }
@@ -780,7 +811,7 @@ 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,
         });
@@ -800,14 +831,16 @@ export function createEngineDaemonService({
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const entry = await entryForSession(id, openHints || {});
-    const target = typeof entry.engine.submitAsync === 'function'
-      ? entry.engine.submitAsync
-      : entry.engine.submit;
-    if (typeof target !== 'function') throw new TypeError('engine submit intake is unavailable');
+    const target = entry.runtime.submitAsync;
+    if (typeof target !== 'function') throw new TypeError('session runtime must implement submitAsync');
+    const intake = await preparePromptSubmissionForProvider(
+      materializePromptSubmission(prompt, options || {}),
+      entry.runtime.provider || entry.runtime.session?.provider || '',
+    );
     // Await intake only: submitAsync resolves once the prompt is represented by
     // the queue/user row, while provider execution remains daemon-owned and
-    // detached. Legacy embedders with synchronous submit retain the fallback.
-    const accepted = await Promise.resolve(target.call(entry.engine, prompt, options || {}));
+    // detached.
+    const accepted = await Promise.resolve(target.call(entry.runtime, intake.prompt, intake.options));
     const firstSubmit = accepted === true && entry.reservedOnly;
     if (accepted === true) {
       entry.reservedOnly = false;
@@ -831,9 +864,9 @@ 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.abort;
-    if (typeof target !== 'function') throw new TypeError('engine method abort is unavailable');
-    const rawResult = await target.call(entry.engine, options || {});
+    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 };
@@ -849,11 +882,11 @@ 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');
@@ -872,12 +905,13 @@ export function createEngineDaemonService({
     if (entry.timer) { clearTimeout(entry.timer); entry.timer = null; }
     try { entry.unsubscribe?.(); } catch {}
     sessions.delete(entry);
+    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.engine.dispose?.(reason, { keepBackgroundWork }); }
+    try { await entry.runtime.dispose?.(reason, { keepBackgroundWork }); }
     catch (err) { log(`session dispose failed session=${sessionId}: ${err?.message || err}`); }
     if (announce && sessionId) {
       onFrame({
@@ -891,7 +925,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
@@ -901,11 +935,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}` : ''}`;
@@ -915,18 +949,18 @@ export function createEngineDaemonService({
 
   function publishDesktopEvent(desktopId, message) {
     const wire = sanitizeForWire(message);
-    const backend = desktopBackendsById.get(desktopId);
-    if (!wire || !backend) return;
+    const service = desktopServicesById.get(desktopId);
+    if (!wire || !service) return;
     onFrame({
       type: 'desktop-event',
       key: desktopEventKey(desktopId, wire),
       desktopId,
       message: wire,
-    }, backend.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');
@@ -934,27 +968,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');
+      throw new TypeError('desktop service moduleUrl must be a file URL');
     }
-    const existingByModule = desktopBackendsByModule.get(requestedModule);
+    const existingByModule = desktopServicesByModule.get(requestedModule);
     if (existingByModule) return existingByModule;
-    const existingById = desktopBackendsById.get(requestedId);
+    const existingById = desktopServicesById.get(requestedId);
     if (existingById) {
       if (existingById.moduleUrl !== requestedModule) {
-        throw new Error(`desktopId ${requestedId} is already bound to another backend module`);
+        throw new Error(`desktopId ${requestedId} is already bound to another service module`);
       }
       return existingById;
     }
-    const pending = desktopBackendPromises.get(requestedModule);
+    const pending = desktopServicePromises.get(requestedModule);
     if (pending) return pending;
     const loading = (async () => {
-      const loaded = await loadDesktopBackendModule(requestedModule);
-      if (typeof loaded.createDesktopBackend !== 'function') {
-        throw new TypeError('desktop backend module has no createDesktopBackend export');
+      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),
@@ -964,7 +998,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,
@@ -972,56 +1006,56 @@ export function createEngineDaemonService({
         instance,
         subscribers: new Set(),
       };
-      desktopBackendsById.set(requestedId, record);
-      desktopBackendsByModule.set(requestedModule, record);
-      log(`desktop backend loaded id=${requestedId} module=${requestedModule}`);
+      desktopServicesById.set(requestedId, record);
+      desktopServicesByModule.set(requestedModule, record);
+      log(`desktop service loaded id=${requestedId} module=${requestedModule}`);
       return record;
     })();
-    desktopBackendPromises.set(requestedModule, loading);
+    desktopServicePromises.set(requestedModule, loading);
     try {
       return await loading;
     } finally {
-      if (desktopBackendPromises.get(requestedModule) === loading) {
-        desktopBackendPromises.delete(requestedModule);
+      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 || '');
-    const backend = desktopBackendsById.get(id);
-    if (!backend) throw new Error('desktop backend is not initialized');
-    return backend;
+    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 };
   }
 
@@ -1050,21 +1084,21 @@ export function createEngineDaemonService({
 
   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 backends = [...new Set(desktopBackendsById.values())];
-    desktopBackendsById.clear();
-    desktopBackendsByModule.clear();
-    desktopBackendPromises.clear();
-    for (const backend of backends) {
-      if (!backend?.instance?.dispose) continue;
-      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);
@@ -1093,13 +1127,14 @@ export function createEngineDaemonService({
         watched,
         retained,
         projected,
+        evictionSweepActive: evictTimer !== null,
       };
     },
     /** Phone clients hosted by daemon-owned desktop adapters. */
     get externalClientCount() {
       let total = 0;
-      for (const backend of desktopBackendsById.values()) {
-        const count = Number(backend?.instance?.clientCount ?? 0);
+      for (const service of desktopServicesById.values()) {
+        const count = Number(service?.instance?.clientCount ?? 0);
         if (Number.isSafeInteger(count) && count > 0) total += count;
       }
       return total;