@crazx/dsh-api-session-controller 0.1.6-alpha.1.zw.3 → 0.1.6-alpha.2.zw.2

package/lib/types/client/sessions/manager.js

@@ -1,6 +1,4 @@
-// SessionManager: the instance cluster Map<SessionId, Session> (lazy-built, resident) + the frame
-// dispatch entry + list state, constructed and held by ClientSessions (one per browser client).
-// List data never enters zustand; React connects via subscribe/getListSnapshot.
+/** Host catalog, durable projection caches, and explicitly retained Client instances. */
 import { SessionSeq } from '@deepseek-ai/dsh-session/types';
 import { mergeOrderedBaseline } from "../ordered-baseline.js";
 import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client';
@@ -20,16 +18,6 @@ export class SessionManager {
     sessions = new Map();
     /** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
     sessionDisposals = new Set();
-    /** Latest transient queues, retained independently of Session object materialization. */
-    queues = new Map();
-    /**
-     * Sessions that finished running while not selected — the sidebar's green
-     * "done" reminder (manager-owned, survives connection generations; cleared
-     * on select and session-removed, re-armed by the next completion).
-     */
-    completedNotifications = new Set();
-    /** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
-    prevRunning = new Map();
     /** Per-session projection value stores, retained independently of instance arrival (the
      *  title-snapshot precedent, generalized): push frames land here whether or not the Session
      *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -41,7 +29,7 @@ export class SessionManager {
     listPhase = 'pending';
     listError = null;
     listInflight = null;
-    /** Mutations arriving after a list request starts are replayed over its response. */
+    /** Active list request's mutation log; its identity also fences completion after reconnect. */
     listMutations = null;
     addresses = new Map();
     catalogs = new Map();
@@ -56,7 +44,6 @@ export class SessionManager {
      * one representation.
      */
     jobsBySession = new Map();
-    selected;
     listSnapshotCache;
     /** Entry-identity cache (reference stability): list rebuilds reuse the previous entry
      *  object when every field matches — wire refreshes mint all-new summary objects, so identity
@@ -66,59 +53,29 @@ export class SessionManager {
     notifier = new Notifier(() => {
         this.listSnapshotCache = this.buildListSnapshot();
     });
-    /**
-     * @param remote - generated Remote namespaces the Session cluster calls.
-     * @param restoredSelection - persisted real-Session selection candidate.
-     */
-    constructor(remote, restoredSelection, restoredAddress) {
+    /** @param remote - generated Remote namespaces used by catalog and history readers. */
+    constructor(remote) {
         this.remote = remote;
-        this.selected = restoredSelection;
-        if (restoredAddress !== undefined)
-            this.addresses.set(restoredAddress.childSessionId, restoredAddress);
         this.listSnapshotCache = this.buildListSnapshot();
     }
-    // ---- Selection ----
     /**
-     * Select a listed Session or a retained catalog-addressed child.
-     * @param sessionId - listed or catalog-addressed Session id.
+     * Resolve an acquisition target without materializing a Session.
+     * @param target - known identity or durable direct-parent address.
+     * @returns the resolved identity with its explicit or catalog-derived history route installed.
      */
-    select(sessionId) {
-        const address = this.navigationAddress(sessionId);
-        if (!this.summaries.some(summary => summary.sessionId === sessionId) && address === undefined) {
-            throw new Error(`sessions.select: unknown session ${sessionId}`);
+    resolveTarget(target) {
+        const id = typeof target === 'string' ? target : target.childSessionId;
+        const address = typeof target === 'string' ? this.navigationAddress(id) : target;
+        if (typeof target === 'string'
+            && !this.sessions.has(id)
+            && !this.summaries.some(summary => summary.sessionId === id)
+            && address === undefined) {
+            throw new Error(`sessions.retain: unknown session ${id}`);
         }
         if (address !== undefined)
-            this.addresses.set(sessionId, address);
-        this.sessions.get(sessionId)?.configureSubagent(address, address === undefined
-            ? undefined
-            : this.catalogs.get(address.parentSessionId)?.parentAvailable);
-        this.selected = sessionId;
-        // Looking at the session consumes its completion reminder (dot clears).
-        this.completedNotifications.delete(sessionId);
-        void this.refreshSubagents(sessionId);
-        this.notifier.notifyNow();
-    }
-    /**
-     * Select a healthy child through its durable direct-parent address.
-     * @param address - catalog-derived parent and child ids.
-     */
-    selectSubagent(address) {
-        const catalog = this.catalogs.get(address.parentSessionId);
-        const entry = catalog?.entries.find(candidate => candidate.id === address.childSessionId);
-        if (entry === undefined || entry.kind !== 'child' || entry.mode !== address.mode) {
-            throw new Error(`sessions.selectSubagent: ${address.childSessionId} is not a healthy catalog child`);
-        }
-        this.addresses.set(address.childSessionId, address);
-        this.sessions.get(address.childSessionId)?.configureSubagent(address, catalog?.parentAvailable);
-        this.selected = address.childSessionId;
-        this.completedNotifications.delete(address.childSessionId);
-        void this.refreshSubagents(address.childSessionId);
-        this.notifier.notifyNow();
-    }
-    /** Clear the selection (the layout falls to the no-session view state). */
-    clearSelection() {
-        this.selected = undefined;
-        this.notifier.notifyNow();
+            this.addresses.set(id, address);
+        this.sessions.get(id)?.configureSubagent(address, address === undefined ? undefined : this.catalogs.get(address.parentSessionId)?.parentAvailable);
+        return id;
     }
     /**
      * Return the durable catalog address retained for one child.
@@ -126,7 +83,7 @@ export class SessionManager {
      * @returns The direct-parent address, when navigation discovered one.
      */
     subagentAddress(sessionId) {
-        return this.addresses.get(sessionId);
+        return this.navigationAddress(sessionId);
     }
     /**
      * Resolve an address for breadcrumb navigation without retaining transport authority.
@@ -147,20 +104,22 @@ export class SessionManager {
     }
     // ---- Instance management ----
     /**
-     * Drop a session instance (scope-prune companion: instance
-     * and scope share one lifecycle). The host session log is the durable
-     * truth — a later get() lazily rebuilds and open() backfills history.
-     * @param sessionId - the session to drop.
+     * Withdraw an exact Client instance before running its teardown callbacks.
+     * @param sessionId - identity to withdraw.
+     * @param expected - instance being released; a replacement is left untouched.
+     * @returns completion of the detached instance's stream teardown.
      */
-    async drop(sessionId) {
+    drop(sessionId, expected) {
         const session = this.sessions.get(sessionId);
+        if (session !== expected)
+            return Promise.resolve();
         this.sessions.delete(sessionId);
-        if (session !== undefined)
-            await this.startSessionDisposal(session);
+        this.addresses.delete(sessionId);
+        return this.startSessionDisposal(session);
     }
     /**
-     * Stop owned timers and every remaining Session instance.
-     * @returns when every Session Remote iterator has completed teardown.
+     * Stop catalog requests and dispose every resident Session.
+     * @returns once catalog requests and every Session stream have stopped.
      */
     async dispose() {
         for (const timer of this.catalogDebounce.values())
@@ -170,6 +129,7 @@ export class SessionManager {
         this.openCatalogs.clear();
         const sessions = [...this.sessions.values()];
         this.sessions.clear();
+        this.addresses.clear();
         for (const session of sessions)
             void this.startSessionDisposal(session);
         await this.drainSessionDisposals();
@@ -187,7 +147,7 @@ export class SessionManager {
     }
     /**
      * Lazy build: return the existing instance or construct one (no auto-open —
-     * open is triggered by the container's select callback).
+     * the reference allocator opens history after binding the scope).
      * @param sessionId - the session to get.
      * @returns the resident instance.
      */
@@ -196,11 +156,6 @@ export class SessionManager {
         if (session === undefined) {
             session = this.createSession(sessionId);
             this.sessions.set(sessionId, session);
-            // Install the latest control baseline before the running-bit sync: a
-            // not-running summary must sweep replayed queue
-            // rows the same way a live status flip would (their retirement events dropped
-            // while the session was uninstantiated).
-            session.replaceControl(this.queues.get(sessionId) ?? []);
             // Sync the running and blank bits from the list snapshot into the new
             // instance (consistency when the list precedes open).
             const summary = this.summaries.find(s => s.sessionId === sessionId);
@@ -350,7 +305,7 @@ export class SessionManager {
         }
     }
     // ---- List API ----
-    /** Full refresh via session.list (single-flight: an in-flight call is reused). */
+    /** Full refresh via session.list (single-flight within one Host generation). */
     refreshList() {
         if (this.listInflight !== null)
             return this.listInflight;
@@ -363,30 +318,15 @@ export class SessionManager {
         this.listInflight = (async () => {
             try {
                 const result = await this.remote.session.list({});
+                if (this.listMutations !== mutations)
+                    return;
                 if (result.ok) {
                     const baseline = this.listPhase === 'pending'
                         ? [...result.value.items]
                         : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId);
-                    // Seed first observations from the pull-time baseline BEFORE replaying
-                    // in-flight mutations, then reconcile the reminders after EVERY
-                    // replayed mutation: an edge that happens entirely between mutations
-                    // (baseline idle → running → idle) must still arm, which a single
-                    // sync on the folded result would collapse away.
-                    for (const s of baseline) {
-                        if (!this.prevRunning.has(s.sessionId))
-                            this.prevRunning.set(s.sessionId, s.running);
-                    }
-                    let summaries = baseline;
-                    for (const mutation of mutations) {
-                        summaries = applyMutation(summaries, mutation);
-                        this.summaries = summaries;
-                        this.syncCompletedNotifications();
-                    }
-                    this.summaries = summaries;
+                    this.summaries = mutations.reduce(applyMutation, baseline);
                     this.listState = 'idle';
                     this.listPhase = 'ready';
-                    // Covers the empty-mutations pull (a plain baseline carries no edge).
-                    this.syncCompletedNotifications();
                     // Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source).
                     for (const s of this.summaries) {
                         const session = this.sessions.get(s.sessionId);
@@ -419,13 +359,17 @@ export class SessionManager {
             catch (error) {
                 if (!isRemoteFailure(error))
                     throw error;
+                if (this.listMutations !== mutations)
+                    return;
                 this.listState = 'error';
                 this.listError = error;
             }
             finally {
-                this.listMutations = null;
-                this.listInflight = null;
-                this.notifier.markDirty();
+                if (this.listMutations === mutations) {
+                    this.listMutations = null;
+                    this.listInflight = null;
+                    this.notifier.markDirty();
+                }
             }
         })();
         return this.listInflight;
@@ -524,8 +468,6 @@ export class SessionManager {
     recordMutation(mutation) {
         this.listMutations?.push(mutation);
         this.summaries = applyMutation(this.summaries, mutation);
-        // Eager edge reconciliation — a snapshot-build-time pass would miss consecutive status frames.
-        this.syncCompletedNotifications();
         this.notifier.markDirty();
     }
     // ---- Subscription API (for useSessionList) ----
@@ -545,6 +487,14 @@ export class SessionManager {
         this.notifier.ensureFresh();
         return this.listSnapshotCache;
     }
+    /**
+     * Read cached projection values for a Session that may exist only in a loaded subagent catalog.
+     * @param sessionId - Session whose control or history baseline supplied projections.
+     * @returns current values, or undefined before any projection store exists.
+     */
+    projectionValues(sessionId) {
+        return this.projectionStores.get(sessionId)?.values();
+    }
     // ---- Live control and Host-event sinks ----
     /**
      * Apply a complete control baseline or one later replacement frame.
@@ -560,22 +510,13 @@ export class SessionManager {
             this.notifier.markDirty();
             return;
         }
-        if (frame.type === 'jobs') {
-            if (frame.jobs.length === 0)
-                this.jobsBySession.delete(frame.sessionId);
-            else
-                this.jobsBySession.set(frame.sessionId, frame.jobs);
-            this.notifier.markDirty();
-            return;
-        }
-        this.queues.set(frame.sessionId, frame.items);
-        this.sessions.get(frame.sessionId)?.handleControlFrame(frame);
+        if (frame.jobs.length === 0)
+            this.jobsBySession.delete(frame.sessionId);
+        else
+            this.jobsBySession.set(frame.sessionId, frame.jobs);
+        this.notifier.markDirty();
     }
     replaceControlBaseline(baseline) {
-        this.queues.clear();
-        for (const [sessionId, items] of Object.entries(baseline.queues)) {
-            this.queues.set(sessionId, items);
-        }
         this.jobsBySession.clear();
         for (const [sessionId, jobs] of Object.entries(baseline.jobs)) {
             if (jobs.length > 0)
@@ -584,12 +525,8 @@ export class SessionManager {
         for (const [sessionId, block] of Object.entries(baseline.projections)) {
             const store = this.projectionStore(sessionId);
             const asOfSeq = sessionSeqCursor(block.asOfSeq);
-            store.truncate(asOfSeq);
             store.seed({ ...block, asOfSeq });
         }
-        for (const [sessionId, session] of this.sessions) {
-            session.replaceControl(this.queues.get(sessionId) ?? []);
-        }
         this.notifier.markDirty();
     }
     /**
@@ -610,7 +547,7 @@ export class SessionManager {
             this.markCatalogParentExpandable(summary.parentSessionId);
         }
         if (summary.parentSessionId !== undefined
-            && (this.selected === summary.parentSessionId || this.openCatalogs.has(summary.parentSessionId))) {
+            && this.openCatalogs.has(summary.parentSessionId)) {
             this.scheduleCatalogRefresh(summary.parentSessionId);
         }
     }
@@ -629,7 +566,6 @@ export class SessionManager {
             this.sessions.get(sessionId)?.handleRunning(false);
         else
             this.sessions.get(sessionId)?.handleRemoved();
-        this.queues.delete(sessionId);
         this.jobsBySession.delete(sessionId);
         if (!durableSubagent)
             this.projectionStores.delete(sessionId);
@@ -676,19 +612,26 @@ export class SessionManager {
     }
     /**
      * Repair one re-established Host-event generation with queryable baselines.
+     * Discard old projection cuts before new queries, including cold Sessions
+     * absent from the process-local control baseline.
      * Opened Session follow streams resume independently through API Gateway.
      */
     handleConnected() {
+        for (const store of this.projectionStores.values())
+            store.clear();
+        this.listMutations = null;
+        this.listInflight = null;
         void this.refreshList();
-        const selectedAddress = this.selected === undefined ? undefined : this.addresses.get(this.selected);
-        if (selectedAddress !== undefined)
-            void this.refreshSubagents(selectedAddress.parentSessionId);
-        if (this.selected !== undefined)
-            void this.refreshSubagents(this.selected);
-        for (const parentSessionId of this.openCatalogs)
+        const parents = new Set(this.openCatalogs);
+        for (const id of this.sessions.keys()) {
+            const address = this.addresses.get(id);
+            if (address !== undefined)
+                parents.add(address.parentSessionId);
+        }
+        for (const parentSessionId of parents)
             void this.refreshSubagents(parentSessionId);
     }
-    /** Debounce membership refetches while one parent catalog is selected or open. */
+    /** Debounce membership refetches for an explicitly consumed catalog. */
     scheduleCatalogRefresh(parentSessionId) {
         if (this.catalogDebounce.has(parentSessionId))
             return;
@@ -764,41 +707,6 @@ export class SessionManager {
             };
         });
     }
-    /**
-     * Reconcile completion reminders against the latest summaries, eagerly after
-     * every mutation and pull (a snapshot-build-time pass would collapse
-     * consecutive status frames into one observation). A running→idle edge of a
-     * non-selected session arms its reminder; running disarms it; removal drops
-     * it. First observation only records the running bit — sessions already
-     * idle at load get no reminder.
-     */
-    syncCompletedNotifications() {
-        const seen = new Set();
-        for (const s of this.summaries) {
-            seen.add(s.sessionId);
-            const prev = this.prevRunning.get(s.sessionId);
-            if (prev === undefined) {
-                this.prevRunning.set(s.sessionId, s.running);
-                continue;
-            }
-            if (prev && !s.running) {
-                if (s.sessionId !== this.selected)
-                    this.completedNotifications.add(s.sessionId);
-            }
-            else if (s.running) {
-                this.completedNotifications.delete(s.sessionId);
-            }
-            this.prevRunning.set(s.sessionId, s.running);
-        }
-        for (const id of this.prevRunning.keys()) {
-            if (!seen.has(id))
-                this.prevRunning.delete(id);
-        }
-        for (const id of this.completedNotifications) {
-            if (!seen.has(id))
-                this.completedNotifications.delete(id);
-        }
-    }
     buildListSnapshot() {
         const merged = this.summaries.map((summary) => {
             // List rows read the generic 'title' projection key (host-computed unit
@@ -812,40 +720,33 @@ export class SessionManager {
                 ...(projectionValues === undefined ? {} : { projectionValues }),
             };
         });
-        const fresh = flattenLineage(merged, this.completedNotifications);
+        const fresh = flattenLineage(merged);
         const items = fresh.map((entry) => {
             const prev = this.entryCache.get(entry.sessionId);
             if (prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
                 && prev.blank === entry.blank
                 && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd
                 && prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth
-                && prev.projectionValues === entry.projectionValues
-                && prev.completed === entry.completed)
+                && prev.projectionValues === entry.projectionValues)
                 return prev;
             this.entryCache.set(entry.sessionId, entry);
             return entry;
         });
+        const itemIds = new Set(items.map(entry => entry.sessionId));
         for (const id of this.entryCache.keys()) {
-            if (!items.some(e => e.sessionId === id))
+            if (!itemIds.has(id))
                 this.entryCache.delete(id);
         }
         const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i]);
         if (!sameOrder)
             this.itemsCache = items;
-        const selected = this.selected;
-        const current = selected !== undefined
-            && (items.some(item => item.sessionId === selected) || this.addresses.has(selected))
-            ? selected
-            : undefined;
         return {
             items: this.itemsCache,
-            current,
             state: this.listState,
             phase: this.listPhase,
             error: this.listError,
             subagentsByParent: Object.fromEntries(this.catalogs),
             jobsBySession: Object.fromEntries(this.jobsBySession),
-            currentAddress: current === undefined ? undefined : this.addresses.get(current),
         };
     }
 }

package/lib/types/client/sessions/projection-store.d.ts

@@ -39,9 +39,9 @@ export interface ProjectionsBaseline {
 /**
  * One session's projection values. Framework semantics, uniform across every
  * key: a baseline seeds rows at its cut, a push frame updates one row, and in
- * both paths a lower-or-equal seq loses — a replayed frame cannot regress a
- * value, a stale baseline cannot overwrite a newer frame. A key the store has
- * never seen reads `undefined` (capability absent). Faces are identity-stable
+ * both paths a lower-or-equal seq within the Host generation loses. A replayed
+ * frame cannot regress a value; a stale baseline cannot overwrite a newer
+ * frame. A key the store has never seen reads `undefined` (capability absent). Faces are identity-stable
  * per key (create-on-demand, cached) so the React side binds each exactly
  * once; the store-level channel (`subscribeAny`) serves coarse consumers (the
  * manager's list projection reads the `title` key).
@@ -95,14 +95,8 @@ export declare class ProjectionValueStore {
      * @param baseline - the response's projections block.
      */
     seed(baseline: ProjectionsBaseline): void;
-    /**
-     * Drop rows beyond a replacement control baseline. Such rows describe
-     * process state the Host lost before persisting it and would otherwise
-     * outrank recomputed lower-seq values forever. The caller seeds the new
-     * baseline immediately afterward.
-     * @param lastSeq - highest durable sequence reflected by the baseline.
-     */
-    truncate(lastSeq: SessionSeqCursor): void;
+    /** Discard one Host generation's values and watermarks while preserving subscribed faces. */
+    clear(): void;
     private changed;
     private channel;
 }

package/lib/types/client/sessions/projection-store.js

@@ -2,9 +2,9 @@ import { Notifier } from "./notifier.js";
 /**
  * One session's projection values. Framework semantics, uniform across every
  * key: a baseline seeds rows at its cut, a push frame updates one row, and in
- * both paths a lower-or-equal seq loses — a replayed frame cannot regress a
- * value, a stale baseline cannot overwrite a newer frame. A key the store has
- * never seen reads `undefined` (capability absent). Faces are identity-stable
+ * both paths a lower-or-equal seq within the Host generation loses. A replayed
+ * frame cannot regress a value; a stale baseline cannot overwrite a newer
+ * frame. A key the store has never seen reads `undefined` (capability absent). Faces are identity-stable
  * per key (create-on-demand, cached) so the React side binds each exactly
  * once; the store-level channel (`subscribeAny`) serves coarse consumers (the
  * manager's list projection reads the `title` key).
@@ -89,17 +89,9 @@ export class ProjectionValueStore {
             this.changed(key);
         }
     }
-    /**
-     * Drop rows beyond a replacement control baseline. Such rows describe
-     * process state the Host lost before persisting it and would otherwise
-     * outrank recomputed lower-seq values forever. The caller seeds the new
-     * baseline immediately afterward.
-     * @param lastSeq - highest durable sequence reflected by the baseline.
-     */
-    truncate(lastSeq) {
-        for (const [key, row] of this.rows) {
-            if (row.seq <= lastSeq)
-                continue;
+    /** Discard one Host generation's values and watermarks while preserving subscribed faces. */
+    clear() {
+        for (const key of this.rows.keys()) {
             this.rows.delete(key);
             this.changed(key);
         }