mixdog 0.9.95 → 0.9.96

package/src/standalone/engine-daemon-service.mjs

@@ -10,8 +10,30 @@
 // The engine factory is injected (`createEngine`) so the daemon entry supplies
 // the real createEngineSession while tests supply a stub.
 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 requireDesktopBackend = createRequire(import.meta.url);
+
+async function loadDesktopBackendModule(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 = requireDesktopBackend.resolve(modulePath);
+  delete requireDesktopBackend.cache[resolved];
+  return requireDesktopBackend(resolved);
+}
 
 /** JSON-safe projection of an engine snapshot. Functions, symbols, and
  *  undefined never survive a transport hop; dropping them here (instead of at
@@ -68,6 +90,8 @@ export function sanitizeForWire(value, depth = 0, seen = new WeakSet()) {
 
 export function createEngineDaemonService({
   createEngine,
+  sessionExists = null,
+  listSessions = null,
   desktopRuntime = null,
   publishIntervalMs = 16,
   onFrame = () => {},
@@ -77,12 +101,32 @@ export function createEngineDaemonService({
   evictSweepMs = null,
 } = {}) {
   if (typeof createEngine !== 'function') throw new Error('createEngine 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);
+  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 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();
+  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
@@ -91,7 +135,7 @@ export function createEngineDaemonService({
   // 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_ENGINE_IDLE_EVICT_MS) || 2 * 60_000);
   const EVICT_SWEEP_MS = Number(evictSweepMs) > 0 ? Number(evictSweepMs) : 30_000;
   let evictTimer = null;
 
@@ -134,15 +178,30 @@ export function createEngineDaemonService({
       startEvictionSweep();
       log(`session ${currentSessionId(entry) || '(creating)'} unwatched (client ${token} gone) — retained`);
     }
-    if (desktopBackend) desktopBackend.subscribers.delete(token);
+    for (const backend of desktopBackendsById.values()) {
+      backend.subscribers.delete(token);
+    }
     return { ok: true };
   }
 
+  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 engineBusy(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.engine.getState?.() || {});
     } catch {
       // An engine we cannot read is never assumed idle — losing a live turn is
       // far worse than holding an extra process for one sweep.
@@ -166,6 +225,26 @@ export function createEngineDaemonService({
     evictTimer.unref?.();
   }
 
+  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;
     // Store states are immutable snapshots (every mutation makes a new object),
@@ -239,6 +318,8 @@ export function createEngineDaemonService({
   /** Advance the engine'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) {
@@ -267,6 +348,30 @@ export function createEngineDaemonService({
     return String(entry?.engine?.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 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;
+    }
+    sessionsById.set(nextId, entry);
+    entry.indexedSessionId = nextId;
+    return nextId;
+  }
+
   /** Publish one durable session-addressed frame. The engine pool is a daemon
    *  implementation detail and never enters the client contract. */
   function publishStep(entry, step) {
@@ -296,71 +401,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.engine.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);
@@ -397,8 +462,17 @@ export function createEngineDaemonService({
     const entry = {
       engine, 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?.() || {};
+      indexSessionEntry(entry, initialState.sessionId);
+      updateEntryBusy(entry, initialState);
+    } catch {
+      updateEntryBusy(entry, { busy: true });
+    }
     addSubscriber(entry, ctx);
     try {
       entry.unsubscribe = engine.subscribe?.(() => schedulePublish(entry)) ?? null;
@@ -442,6 +516,11 @@ 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 engine.
+    advance(entry);
+    retainUnwatched(entry, 'headless session load');
     log(`session ${sessionId} loaded on demand`);
     return entry;
   }
@@ -454,36 +533,45 @@ export function createEngineDaemonService({
     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 loadSessionEngine(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,
-  } = {}) {
+  async function runSessionAction({
+    sessionId, action, args = [], open: openHints = {}, baseRevision = null,
+  } = {}, allowedActions) {
     if (closed) throw new Error('engine daemon 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`);
+    if (typeof target !== 'function') throw new TypeError(`session action ${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.
+    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 backend without
+    // serializing transcripts/catalogs into the daemon log.
     const valueSummary = value === null || value === undefined
       ? String(value)
       : typeof value === 'object'
@@ -491,37 +579,126 @@ 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();
-    }
+    retainUnwatched(entry);
     return {
       value: sanitizeForWire(value) ?? null,
       sessionId: String(entry.engine.getState?.()?.sessionId || id),
       ...bodyForClient(step, Number.isInteger(baseRevision) ? baseRevision : null),
-      sync: syncSurfaceOf(entry, { refresh: shaping }),
     };
   }
 
+  async function listSessionCatalog(options = {}) {
+    if (closed) throw new Error('engine daemon 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 backend 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) {
+    void ctx;
+    return runSessionAction(params, 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.
 
-  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),
     };
   }
 
@@ -555,8 +732,8 @@ export function createEngineDaemonService({
       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 +741,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 || '');
@@ -600,6 +787,7 @@ export function createEngineDaemonService({
         return { sessionId: id, unsubscribed: true };
       }
       entry.retainedAt = Date.now();
+      releaseProjection(entry);
       startEvictionSweep();
     }
     log(`session unsubscribed session=${id}${token ? ` client=${token}` : ''}`);
@@ -612,33 +800,47 @@ 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 target = typeof entry.engine.submitAsync === 'function'
+      ? entry.engine.submitAsync
+      : entry.engine.submit;
+    if (typeof target !== 'function') throw new TypeError('engine submit intake is unavailable');
+    // 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 || {}));
+    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 rawResult = await target.call(entry.engine, 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({
@@ -654,6 +856,7 @@ export function createEngineDaemonService({
     const approved = await target.call(entry.engine, 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,10 +868,15 @@ 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();
+    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 }); }
     catch (err) { log(`session dispose failed session=${sessionId}: ${err?.message || err}`); }
     if (announce && sessionId) {
@@ -707,13 +915,14 @@ export function createEngineDaemonService({
 
   function publishDesktopEvent(desktopId, message) {
     const wire = sanitizeForWire(message);
-    if (!wire || !desktopBackend || desktopBackend.desktopId !== desktopId) return;
+    const backend = desktopBackendsById.get(desktopId);
+    if (!wire || !backend) return;
     onFrame({
       type: 'desktop-event',
       key: desktopEventKey(desktopId, wire),
       desktopId,
       message: wire,
-    }, desktopBackend.subscribers);
+    }, backend.subscribers);
   }
 
   async function initializeDesktopBackend({ desktopId, moduleUrl, options = {} } = {}) {
@@ -729,19 +938,19 @@ export function createEngineDaemonService({
     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}`);
+    const existingByModule = desktopBackendsByModule.get(requestedModule);
+    if (existingByModule) return existingByModule;
+    const existingById = desktopBackendsById.get(requestedId);
+    if (existingById) {
+      if (existingById.moduleUrl !== requestedModule) {
+        throw new Error(`desktopId ${requestedId} is already bound to another backend module`);
       }
-      return desktopBackend;
+      return existingById;
     }
-    if (desktopBackendPromise) return desktopBackendPromise;
-    desktopBackendPromise = (async () => {
-      const loaded = await import(requestedModule);
+    const pending = desktopBackendPromises.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');
       }
@@ -763,14 +972,18 @@ export function createEngineDaemonService({
         instance,
         subscribers: new Set(),
       };
-      desktopBackend = record;
-      log(`desktop backend loaded id=${requestedId}`);
+      desktopBackendsById.set(requestedId, record);
+      desktopBackendsByModule.set(requestedModule, record);
+      log(`desktop backend loaded id=${requestedId} module=${requestedModule}`);
       return record;
     })();
+    desktopBackendPromises.set(requestedModule, loading);
     try {
-      return await desktopBackendPromise;
+      return await loading;
     } finally {
-      desktopBackendPromise = null;
+      if (desktopBackendPromises.get(requestedModule) === loading) {
+        desktopBackendPromises.delete(requestedModule);
+      }
     }
   }
 
@@ -783,10 +996,9 @@ export function createEngineDaemonService({
 
   function requireDesktopBackend(desktopId) {
     const id = String(desktopId || '');
-    if (!desktopBackend || desktopBackend.desktopId !== id) {
-      throw new Error('desktop backend is not initialized');
-    }
-    return desktopBackend;
+    const backend = desktopBackendsById.get(id);
+    if (!backend) throw new Error('desktop backend is not initialized');
+    return backend;
   }
 
   async function desktopInvoke({ desktopId, method, args = [] } = {}, ctx = null) {
@@ -818,6 +1030,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,7 +1045,7 @@ 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) {
@@ -837,9 +1057,12 @@ export function createEngineDaemonService({
   async function stop(reason = 'service stop') {
     closed = true;
     if (evictTimer) { clearInterval(evictTimer); evictTimer = null; }
-    const backend = desktopBackend;
-    desktopBackend = null;
-    if (backend?.instance?.dispose) {
+    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}`); }
     }
@@ -849,16 +1072,37 @@ 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,
+      };
+    },
+    /** 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 backend of desktopBackendsById.values()) {
+        const count = Number(backend?.instance?.clientCount ?? 0);
+        if (Number.isSafeInteger(count) && count > 0) total += count;
+      }
+      return total;
     },
   };
 }