@deepseek-ai/dsh-api-session-controller 0.1.6-alpha.1 → 0.1.7-alpha.1

package/lib/types/agent.d.ts

@@ -29,7 +29,7 @@ export declare class ApiSessionPresetConflict extends Error {
     constructor(sessionId: SessionId, requestedPreset: string, existingPreset: string | undefined);
 }
 /** Failures produced while resolving one ordinary Session identity to its live Agent. */
-export type ApiSessionAgentError = RemoteError<'session/not-found' | 'session/agent-busy' | 'gateway/internal'>;
+export type ApiSessionAgentError = RemoteError<'session/not-found' | 'session/agent-busy' | 'session/writer-held' | 'gateway/internal'>;
 /** Result of resolving one ordinary Session identity to its live Agent. */
 export type ApiSessionAgentResult = {
     readonly agent: Agent;

package/lib/types/agent.js

@@ -219,7 +219,11 @@ export class ApiSessionAgentController {
             this.resumes.set(sessionId, resume);
         }
         try {
-            return { agent: await resume };
+            const agent = await resume;
+            // A shared resume can publish an identity that subagent routing adopts
+            // before every waiter observes it; apply the live ownership policy again.
+            const published = this.liveAgent(sessionId);
+            return published ?? { agent };
         }
         catch (error) {
             if (error instanceof ApiSessionNotFound) {
@@ -235,6 +239,9 @@ export class ApiSessionAgentController {
             if (racedSession !== undefined && hasApiSessionSubagentOwner(this.ctx, racedSession, undefined)) {
                 return { error: apiSessionSubagentOwnershipError(sessionId) };
             }
+            if (error instanceof Error && error.name === 'SessionAlreadyOwnedError') {
+                return { error: new RemoteError('session/writer-held', error.message, { sessionId }) };
+            }
             return {
                 error: new RemoteError('gateway/internal', `resume failed for session "${sessionId}": ${String(error)}`, {}),
             };

package/lib/types/archived-session-gate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The controller's admission gate for archived Sessions: an archived
+ * Session, or a subagent descendant of one, must not run a model step until
+ * it is restored. The work a Session still runs is reported and stopped by
+ * its owners — the Agent registry (`turn`), the job registry seam (`job`),
+ * the Subagent runtime (`subagent`), and the Schedule plugin (`schedule`) —
+ * through the Workspace registry's archive-admission events.
+ */
+import type { Context, Plugin } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/**
+ * The gate as a plugin for `ctx.plugin(...)`: it loads once the Agent
+ * registry, Session store, and Workspace registry are available and unwinds
+ * with the plugin's fiber. A late waking delivery to an archived Session — a
+ * subagent settlement, a queued follow-up — proposes a step the gate rejects,
+ * which the loop ends as `blocked` without a request; unarchiving lifts the
+ * gate for the whole lineage.
+ */
+export declare const ArchivedSessionGate: Plugin.Object<void>;
+/**
+ * Whether the Agent's Session, or a Session above it in its subagent lineage,
+ * is archived. Lineage follows the durable header fields through
+ * subagent-origin Sessions only: a fork of an archived Session is an
+ * independent conversation.
+ * @param ctx - Host context.
+ * @param agent - the Agent proposing a step.
+ * @returns whether an archived Session owns the step.
+ */
+export declare function underArchivedSession(ctx: Context, agent: Agent): boolean;
+//# sourceMappingURL=archived-session-gate.d.ts.map

package/lib/types/archived-session-gate.js

@@ -0,0 +1,52 @@
+/**
+ * The controller's admission gate for archived Sessions: an archived
+ * Session, or a subagent descendant of one, must not run a model step until
+ * it is restored. The work a Session still runs is reported and stopped by
+ * its owners — the Agent registry (`turn`), the job registry seam (`job`),
+ * the Subagent runtime (`subagent`), and the Schedule plugin (`schedule`) —
+ * through the Workspace registry's archive-admission events.
+ */
+/**
+ * The gate as a plugin for `ctx.plugin(...)`: it loads once the Agent
+ * registry, Session store, and Workspace registry are available and unwinds
+ * with the plugin's fiber. A late waking delivery to an archived Session — a
+ * subagent settlement, a queued follow-up — proposes a step the gate rejects,
+ * which the loop ends as `blocked` without a request; unarchiving lifts the
+ * gate for the whole lineage.
+ */
+export const ArchivedSessionGate = {
+    name: 'archived-session-gate',
+    inject: ['agents', 'sessions', 'workspaceRegistry'],
+    apply(ctx) {
+        ctx.on('agent/pre-step', (payload, next) => underArchivedSession(ctx, payload.agent)
+            ? Promise.resolve({ kind: 'reject' })
+            : next());
+    },
+};
+/**
+ * Whether the Agent's Session, or a Session above it in its subagent lineage,
+ * is archived. Lineage follows the durable header fields through
+ * subagent-origin Sessions only: a fork of an archived Session is an
+ * independent conversation.
+ * @param ctx - Host context.
+ * @param agent - the Agent proposing a step.
+ * @returns whether an archived Session owns the step.
+ */
+export function underArchivedSession(ctx, agent) {
+    const archived = ctx.workspaceRegistry.archivedSessionIds;
+    let header = agent.session.header;
+    const visited = new Set();
+    while (!visited.has(header.id)) {
+        if (archived.includes(header.id))
+            return true;
+        visited.add(header.id);
+        if (header.origin !== 'subagent' || header.parentSession === undefined)
+            return false;
+        const parent = ctx.sessions.get(header.parentSession);
+        if (parent === undefined)
+            return archived.includes(header.parentSession);
+        header = parent.header;
+    }
+    return false;
+}
+//# sourceMappingURL=archived-session-gate.js.map

package/lib/types/client/contract/session.d.ts

@@ -127,6 +127,8 @@ export interface ISession {
      * turn-jump loader. Repeated calls while a jump is paging lower its shared
      * target and return the in-flight completion; `snapshot.loadingOlder` is
      * the busy signal for the whole jump.
+     * Older pages publish together at completion, including successful pages
+     * before a later failure; live events remain independently visible.
      * @param seq - durable event seq the window must reach (a turn's `turn/start` seq).
      * @returns completion once covered, exhausted, superseded, or failed soft.
      */

package/lib/types/client/contract/sessions.d.ts

@@ -14,11 +14,58 @@ import type { SessionSearchResultItem } from '../sessions/manager.ts';
 import type { SessionBinding, SessionListState } from '../sessions/service.ts';
 import type { SessionFace } from './session.ts';
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { SessionReferenceSource } from '../index.ts';
 export type { AgentContext } from '../scope.ts';
+/** Known Session identity or durable direct-parent subagent address; an address owns no lifetime. */
+export type SessionTarget = SessionId | SubagentAddress;
+/** One independent use of an exact Client generation, without Host Agent ownership. */
+export interface SessionReference extends Disposable {
+    readonly sessionId: SessionId;
+    /** Shared binding; access fails after reference release or generation disposal. */
+    readonly binding: SessionBinding;
+    /** This reference's cancellable wait for the shared initial `Session.open()` attempt to settle. */
+    readonly ready: Promise<SessionBinding>;
+    /** Release once; the final reference starts local scope and history teardown. */
+    release(): void;
+}
+/** Consumer identity and optional cancellation of one acquisition waiter. */
+export interface SessionRetainOptions {
+    readonly source: SessionReferenceSource;
+    readonly signal?: AbortSignal | undefined;
+}
+/** Local ownership counts, independent of catalog membership and never persisted. */
+export interface SessionRetainInfo {
+    readonly referenceCount: number;
+    /** Positive source counts only; a source without references is absent. */
+    readonly retainedBy: Readonly<Partial<Record<SessionReferenceSource, number>>>;
+}
 /** The sessions-service face injected as `ctx.sessions`. */
 export interface ISessions {
-    /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
+    /** Host catalog and local reference-source counts; navigation belongs to view owners. */
     readonly list: ObservableSnapshot<SessionListState>;
+    /**
+     * Retain an exact Client generation and start its shared initial history opening.
+     * @param target - known identity or durable direct-parent address.
+     * @param options - required consumer source and optional independent waiter cancellation.
+     * @returns an owned reference immediately; await `reference.ready` when the initial open attempt must settle first.
+     */
+    retain(target: SessionTarget, options: SessionRetainOptions): SessionReference;
+    /**
+     * Hold one reference through callback settlement, including synchronous and asynchronous failures.
+     * @param target - Session to acquire.
+     * @param options - source and acquisition cancellation.
+     * @param operation - callback using the reference only until its returned value or Promise settles.
+     * @returns the callback result after release; acquisition and callback failures propagate unchanged.
+     */
+    using<T>(target: SessionTarget, options: SessionRetainOptions, operation: (reference: SessionReference) => T | Promise<T>): Promise<T>;
+    /**
+     * Observe local reference counts without retaining, creating a scope, or opening history.
+     * The returned source keeps stable identity across same-id generations and remains allocated
+     * until the Client root is disposed, even after its final subscriber leaves.
+     * @param id - explicit Session identity; Host existence is not implied.
+     * @returns a stable read-only source across same-id generations, with zero counts when none is live.
+     */
+    retainInfo(id: SessionId): ObservableSnapshot<SessionRetainInfo>;
     /**
      * The `session.search` result bound the wire schema fixes, exposed to
      * presentation as injected data. Not per-connection state: every transport
@@ -28,43 +75,25 @@ export interface ISessions {
     /**
      * Create or adopt a Session on the Host.
      * @param opts - target workspace, directory, and optional preallocated identity.
-     * @returns the Session identity after its local binding is addressable.
+     * @returns the catalogued identity; retain it before borrowing its binding.
      */
     create(opts?: {
         workspaceId?: WorkspaceId;
         cwd?: string;
         sessionId?: SessionId;
     }): Promise<SessionId>;
-    /**
-     * Select a session as current.
-     * @param id - session id (must exist in the list; unknown ids fail loud).
-     */
-    open(id: SessionId): void;
-    /**
-     * Open a healthy catalog child through its exact direct-parent address.
-     * @param address - catalog-derived parent and child ids.
-     */
-    openSubagent(address: SubagentAddress): void;
     /**
      * Resolve an already discovered direct-parent address without opening it.
      * @param id - possible addressed child id.
-     * @returns the retained address, when present.
+     * @returns a retained or loaded-catalog address, without retaining a new selection or scope.
      */
     subagentAddress(id: SessionId): SubagentAddress | undefined;
     /**
-     * Mark whether a catalog menu is consuming live membership updates.
-     * @param parentSessionId - catalog owner.
-     * @param open - current menu state.
-     */
-    setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
-    /**
-     * Refresh one direct-child catalog.
-     * @param parentSessionId - catalog owner.
+     * Load all Session projections once per connection; retry an unsuccessful initial read.
+     * @param sessionId - Session to inspect without opening its conversation.
      * @returns completion of the current or newly started refresh.
      */
-    refreshSubagents(parentSessionId: SessionId): Promise<void>;
-    /** Clear the current selection into the no-session view state. */
-    clear(): void;
+    refreshProjections(sessionId: SessionId): Promise<void>;
     /**
      * Refresh the Host-authoritative Session list.
      * @returns completion of the current or newly started Session-list refresh.
@@ -82,12 +111,13 @@ export interface ISessions {
         hasMore: boolean;
     }>>;
     /**
-     * Fork a session from a completed-turn prefix of the source; on resolution
-     * the child is in the list store and `open()` can target it.
-     * @param opts - source session id, the optional event seq anchoring the
-     *   cut (the boundary is the first turn/end at or after it; an in-log
-     *   anchor in an open turn is unavailable rather than clipped backward),
-     *   and whether to increment an inherited durable title before resolving.
+     * Fork a session from an exact inclusive prefix of the source; on
+     * resolution the child is catalogued and can be explicitly retained.
+     * @param opts - source session id, the optional exact inclusive boundary
+     *   seq (a real event seq the caller already knows; a cut inside an open
+     *   turn is balanced Host-side with synthetic closers, and omission selects
+     *   the latest completed-turn prefix), and whether to increment an
+     *   inherited durable title before resolving.
      * @returns the child session id.
      * @throws when the fork fails, or when a requested child-title rename fails after creation.
      */
@@ -97,9 +127,9 @@ export interface ISessions {
         increaseTitle?: boolean;
     }): Promise<SessionId>;
     /**
-     * Resolve an Agent-scoped context view (use-and-discard).
+     * Borrow an already-retained Agent-scoped Context without extending its lifetime.
      * @param id - session id.
-     * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+     * @returns the live scoped Context, or undefined without a retained generation.
      */
     scope(id: SessionId): AgentContext | undefined;
     /**
@@ -112,13 +142,13 @@ export interface ISessions {
     /**
      * Resolve the session face behind an Agent-scoped context.
      * @param ctx - an Agent-scoped context.
-     * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
+     * @returns the matching live Session, or undefined for an untagged, foreign, or ended generation.
      */
     sessionOf(ctx: Context): SessionFace | undefined;
     /**
-     * Resolve the stable session binding (scope-addressed assembly feed).
+     * Borrow an already-retained Session binding without extending its lifetime.
      * @param id - session id.
-     * @returns binding, or undefined for a session neither listed nor already scoped.
+     * @returns the live binding, or undefined without a retained generation.
      */
     binding(id: SessionId): SessionBinding | undefined;
 }

package/lib/types/client/contract/snapshot.d.ts

@@ -1,22 +1,9 @@
 /** Session-owned observable state excluding Conversation target data. */
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
 import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment';
-import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client';
 import type { RemoteFailure } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionRequestId } from '../../types.ts';
-/** One transient inbox occurrence from the authoritative queue snapshot. */
-export interface QueuedMessage {
-    readonly id: MessageId;
-    readonly messageId: MessageId;
-    readonly placement: 'queued' | 'steering' | 'context';
-    /** Prompt-RPC identity of a browser-submitted occurrence; correlates the local submission echo. */
-    readonly rpcId?: SessionRequestId;
-    readonly content: readonly ContentBlock[];
-    readonly preview: string;
-    readonly text: string | null;
-}
 /** One image displayed by a local submission echo before durable admission. */
 export interface PendingSubmissionImage {
     /** Browser-owned preview URL; its lifecycle belongs to the submitter, never this snapshot. */
@@ -70,7 +57,6 @@ export interface PromptError {
 /** Immutable Session lifecycle and control snapshot. */
 export interface SessionSnapshot {
     readonly sessionId: SessionId;
-    readonly queue: readonly QueuedMessage[];
     /** Local prompt-submission echoes not yet observed as durable events or queue occurrences. */
     readonly pendingSubmissions: readonly PendingSubmission[];
     readonly running: boolean;

package/lib/types/client/index.d.ts

@@ -6,14 +6,23 @@ export { createScope, scopeOf } from './scope.ts';
 export type { AgentContext, AgentScopeHandle } from './scope.ts';
 export { SessionCreateError, SessionForkError } from './sessions/service.ts';
 export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts';
-export type { SessionListPhase, SessionListSnapshot, SessionSearchResultItem, SubagentCatalogSnapshot, } from './sessions/manager.ts';
+export type { SessionListPhase, SessionListSnapshot, SessionSearchResultItem, SessionProjectionSnapshot, } from './sessions/manager.ts';
 export type { Session } from './sessions/session.ts';
 export type { ProjectionsBaseline, ProjectionValueStore, SessionProjectionMap, UseProjection, } from './sessions/projection-store.ts';
 export type { BeginSubmissionInput, ISession, PendingSubmissionRetirement, ProjectionsFace, SessionFace, SubmissionHandle, } from './contract/session.ts';
-export type { ISessions } from './contract/sessions.ts';
+export type { ISessions, SessionReference, SessionRetainInfo, SessionRetainOptions, SessionTarget, } from './contract/sessions.ts';
 export { MutableSessionEventSource } from './contract/events.ts';
 export type { AssistantLiveChunkEvent, SessionAssistantSettlementEntry, SessionEventChange, SessionEventLike, SessionEventLikeEntry, SessionEventSource, SessionEventWindow, SessionLiveEventEntry, SessionTransientEventEntry, } from './contract/events.ts';
-export type { OpenState, PendingSubmission, PendingSubmissionAttachment, PendingSubmissionFileAttachment, PendingSubmissionImage, PendingSubmissionImageAttachment, PendingSubmissionPlacement, PromptError, QueuedMessage, SessionSnapshot, } from './contract/snapshot.ts';
+export type { OpenState, PendingSubmission, PendingSubmissionAttachment, PendingSubmissionFileAttachment, PendingSubmissionImage, PendingSubmissionImageAttachment, PendingSubmissionPlacement, PromptError, SessionSnapshot, } from './contract/snapshot.ts';
+/** Consumer-owned reference labels; extend this map through the package's canonical /client entry. */
+export interface SessionReferenceSourceMap {
+    /** Temporary Client Controller work, including fork-title preparation. */
+    controllerOperation: unknown;
+    /** A Client Gateway invocation's synchronous Context ownership. */
+    gateway: unknown;
+}
+/** Declaration-merge-extensible labels carried by independent Client references. */
+export type SessionReferenceSource = Extract<keyof SessionReferenceSourceMap, string>;
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Client Session object layer and Agent scope owner. */

package/lib/types/client/index.js

@@ -1,4 +1,5 @@
 /** Client Session object layer, Agent scopes, and Remote lifecycle wiring. */
+import { typertOwnedValue } from '@deepseek-ai/dsh-typert-protocol';
 import { createSessionControlStream } from "./transport.js";
 import { ClientSessions } from "./sessions/service.js";
 export { createSessionControlStream, SessionEventStream, SESSION_SEARCH_RESULT_LIMIT, SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS, } from "./transport.js";
@@ -21,6 +22,7 @@ export const inject = [
  */
 export function apply(ctx) {
     const remotes = ctx.remote;
+    const connection = ctx.get('connection');
     const sessions = new ClientSessions(ctx, remotes);
     ctx.remote.$on('api-session/added', (summary) => { sessions.handleSessionAdded(summary); });
     ctx.remote.$on('api-session/removed', (sessionId) => { sessions.handleSessionRemoved(sessionId); });
@@ -37,13 +39,22 @@ export function apply(ctx) {
         accept: (frame) => { sessions.handleControlFrame(frame); },
         failed: (error) => { console.error('[session-controller] control stream failed:', error); },
     });
-    control.start();
-    ctx.on('connection/reset', () => { sessions.handleConnected(); });
-    if (ctx.remote.$host.home !== undefined)
+    const connected = () => {
+        if (connection.generation.getSnapshot() === undefined)
+            return;
+        // A ready control baseline may arrive before Cordis delivers connection/reset.
         sessions.handleConnected();
+        control.restart();
+        control.start();
+    };
+    ctx.effect(() => connection.generation.subscribe(connected), 'session-controller.client.generation');
+    connected();
     ctx.typert.contexts.registerClient('agent', {
-        identity: candidate => sessions.scopeOf(candidate),
-        resolve: sessionId => sessions.resolveAgentScope(sessionId),
+        identity: candidate => sessions.sessionOf(candidate)?.sessionId,
+        resolve: (sessionId) => {
+            const reference = sessions.retainAgentScope(sessionId);
+            return typertOwnedValue(reference.binding.ctx, () => { reference.release(); });
+        },
     });
     ctx.effect(() => async () => { await control.dispose(); }, 'session-controller.client.control');
 }

package/lib/types/client/scope.d.ts

@@ -6,11 +6,14 @@ import type { TypertRemoteScopeApi } from '@deepseek-ai/dsh-typert-protocol';
 export type AgentContext = Omit<Context, 'remote'> & {
     readonly remote: ClientRemote & TypertRemoteScopeApi<'agent'>;
 };
+interface ScopeIdentity {
+    readonly sessionId: SessionId;
+}
 /** A minted Agent scope and its disposal boundary. */
 export interface AgentScopeHandle {
     /**
      * Tagged context: scope-owned registrations and scoped dispatch both go
-     * through it (passing it as the dispatch subject routes to this agent's
+     * through it (passing it as the dispatch subject routes to this generation's
      * tagged listeners plus every untagged one).
      */
     ctx: AgentContext;
@@ -20,10 +23,10 @@ export interface AgentScopeHandle {
 /**
  * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
  * carries the agent tag and the dispatch filter — untagged listeners are
- * admitted globally, tagged listeners only for a matching agent.
+ * admitted globally, tagged listeners only for the same Client generation.
  * Registrations through the returned ctx dispose with the fiber.
  * @param ctx - client root context the scope fiber mounts under.
- * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @param key - durable Session identity carried by this generation.
  * @returns the tagged context and its backing fiber.
  */
 export declare function createScope(ctx: Context, key: SessionId): AgentScopeHandle;
@@ -33,4 +36,11 @@ export declare function createScope(ctx: Context, key: SessionId): AgentScopeHan
  * @returns its agent identity (the session id), or undefined for root contexts.
  */
 export declare function scopeOf(ctx: Context): SessionId | undefined;
+/**
+ * Read the exact generation identity inherited by a Client Context.
+ * @param ctx - scoped or root Client Context.
+ * @returns the generation identity, or undefined for an unscoped Context.
+ */
+export declare function scopeIdentityOf(ctx: Context): ScopeIdentity | undefined;
+export {};
 //# sourceMappingURL=scope.d.ts.map

package/lib/types/client/scope.js

@@ -1,20 +1,4 @@
-/**
- * Client Agent-scope primitive: mint a Cordis context tagged with the owning
- * Agent's identity. The mechanism mirrors the host `dsh-scope` architecture
- * (no-op plugin fiber + context tag + `Context.filter` routing predicate);
- * the shape deliberately diverges: the filter lives on the actx itself
- * instead of a separate carrier object, so scoped dispatch is plain cordis —
- * `actx.bail(actx, event, payload)` / `actx.emit(actx, ...)` — with no
- * wrapper. The host needs a detached carrier because its dispatch subject is
- * the business Agent object; client scope events carry only ids, so the
- * actx is the natural subject. The second divergence stands: the scope key
- * is the branded `SessionId` (value compared), not an object identity — the
- * agent and its session share one id (1:1, same axis; no separate AgentId
- * brand), and a client scope's identity IS that wire id. Third divergence,
- * deliberate: the client scopes the Agent IDENTITY, not a live Agent object
- * — a cold session's host Agent is already disposed while its client actx
- * stays alive for history viewing.
- */
+/** Client scope generations route local events independently of Host Agent residency. */
 import { Context as CordisContext } from '@deepseek-ai/cordis';
 /** Context tag written by {@link createScope}. */
 const kScope = Symbol('dsh.client.scope');
@@ -23,19 +7,20 @@ function agentScope() { }
 /**
  * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
  * carries the agent tag and the dispatch filter — untagged listeners are
- * admitted globally, tagged listeners only for a matching agent.
+ * admitted globally, tagged listeners only for the same Client generation.
  * Registrations through the returned ctx dispose with the fiber.
  * @param ctx - client root context the scope fiber mounts under.
- * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @param key - durable Session identity carried by this generation.
  * @returns the tagged context and its backing fiber.
  */
 export function createScope(ctx, key) {
     const fiber = ctx.plugin(agentScope);
+    const identity = { sessionId: key };
     const scoped = fiber.ctx.extend({
-        [kScope]: key,
+        [kScope]: identity,
         [CordisContext.filter](listenerCtx) {
-            const tag = scopeOf(listenerCtx);
-            return tag === undefined || tag === key;
+            const tag = scopeIdentityOf(listenerCtx);
+            return tag === undefined || tag === identity;
         },
     });
     return {
@@ -49,6 +34,14 @@ export function createScope(ctx, key) {
  * @returns its agent identity (the session id), or undefined for root contexts.
  */
 export function scopeOf(ctx) {
+    return scopeIdentityOf(ctx)?.sessionId;
+}
+/**
+ * Read the exact generation identity inherited by a Client Context.
+ * @param ctx - scoped or root Client Context.
+ * @returns the generation identity, or undefined for an unscoped Context.
+ */
+export function scopeIdentityOf(ctx) {
     return ctx[kScope];
 }
 //# sourceMappingURL=scope.js.map

package/lib/types/client/sessions/lineage.d.ts

@@ -13,7 +13,10 @@ export interface SessionListEntry {
     title?: string;
     updatedAt: number;
     running: boolean;
-    /** Empty-log bit mirrored from the summary; lists hide blank sessions (filtering stays with the consumer). */
+    /**
+     * New Session presentation and reuse eligibility, reconciled with
+     * `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer).
+     */
     blank: boolean;
     parentSessionId?: SessionId;
     /** Coarse durable origin for navigation filtering; not a continuation capability. */
@@ -21,8 +24,6 @@ export interface SessionListEntry {
     cwd?: string;
     /** Current host-computed projection values for list consumers. */
     projectionValues?: Readonly<Partial<SessionProjectionMap>>;
-    /** Finished running while not selected and not yet opened — the sidebar's green "done" reminder (clears on select or the next run). */
-    completed: boolean;
     /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
     depth: number;
 }
@@ -31,8 +32,7 @@ export interface SessionListEntry {
  * follows the established input order; this projection never re-sorts a
  * hydrated list from mutable timestamps.
  * @param summaries - the host's session.list items.
- * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
  * @returns display rows in render order.
  */
-export declare function flattenLineage(summaries: readonly TitledSessionSummary[], completed?: ReadonlySet<SessionId>): SessionListEntry[];
+export declare function flattenLineage(summaries: readonly TitledSessionSummary[]): SessionListEntry[];
 //# sourceMappingURL=lineage.d.ts.map

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

@@ -6,10 +6,9 @@
  * follows the established input order; this projection never re-sorts a
  * hydrated list from mutable timestamps.
  * @param summaries - the host's session.list items.
- * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
  * @returns display rows in render order.
  */
-export function flattenLineage(summaries, completed) {
+export function flattenLineage(summaries) {
     const byId = new Map();
     for (const s of summaries)
         byId.set(s.sessionId, s);
@@ -33,9 +32,9 @@ export function flattenLineage(summaries, completed) {
             return;
         }
         visited.add(s.sessionId);
+        const { agentAvailable: _agentAvailable, ...row } = s;
         out.push({
-            ...s,
-            completed: completed?.has(s.sessionId) ?? false,
+            ...row,
             depth,
         });
         const kids = children.get(s.sessionId);