@deepseek-ai/dsh-api-session-controller 0.2.1-alpha.1 → 0.2.1-alpha.3

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

@@ -78,8 +78,9 @@ export class SessionManager {
     }
     /**
      * Resolve an address for breadcrumb navigation without retaining transport authority.
-     * @param sessionId - possible child id in an already-loaded catalog.
-     * @returns A retained or catalog-derived direct-parent address.
+     * @param sessionId - possible child id in received Session metadata.
+     * @returns A retained address, then a catalog address, then an unknown-mode address
+     *   from a listed subagent header; undefined without that evidence.
      */
     subagentAddress(sessionId) {
         const retained = this.addresses.get(sessionId);
@@ -88,7 +89,7 @@ export class SessionManager {
         for (const parentSessionId of this.projectionStores.keys()) {
             const child = this.projectionStores.get(parentSessionId)?.values().subagentCatalog
                 ?.find(entry => entry.id === sessionId);
-            if (child !== undefined) {
+            if (child !== undefined && child.mode !== 'external') {
                 return {
                     parentSessionId,
                     childSessionId: sessionId,
@@ -96,7 +97,14 @@ export class SessionManager {
                 };
             }
         }
-        return undefined;
+        const summary = this.summaries.find(summary => summary.sessionId === sessionId);
+        if (summary?.origin !== 'subagent' || summary.parentSessionId === undefined)
+            return undefined;
+        return {
+            parentSessionId: summary.parentSessionId,
+            childSessionId: sessionId,
+            mode: 'unknown',
+        };
     }
     // ---- Instance management ----
     /**
@@ -169,7 +177,7 @@ export class SessionManager {
                 const address = this.addresses.get(sessionId);
                 const child = address === undefined ? undefined : this.projectionStores.get(address.parentSessionId)?.values().subagentCatalog
                     ?.find(entry => entry.id === sessionId);
-                if (child !== undefined) {
+                if (child !== undefined && child.mode !== 'external') {
                     // A catalogued child exists only after its delegated session has
                     // durable history, even though child rows do not carry `blank`.
                     session.handleBlank(false);
@@ -252,7 +260,7 @@ export class SessionManager {
         return store;
     }
     /**
-     * Load a complete projection baseline once per connection; retry unsuccessful reads.
+     * Read projections without starting migration; retry failed or migration-deferred reads.
      * @param sessionId - Session to inspect without opening its conversation.
      * @returns completion of the current or newly started read.
      */
@@ -273,14 +281,27 @@ export class SessionManager {
                 if (controller.signal.aborted)
                     return;
                 if (result.ok) {
-                    if (result.value !== null) {
-                        store.seed({ ...result.value, asOfSeq: sessionSeqCursor(result.value.asOfSeq) });
+                    const value = result.value;
+                    if (value !== null) {
+                        switch (value.kind) {
+                            case 'sequenced':
+                                store.seed({ values: value.values, asOfSeq: sessionSeqCursor(value.asOfSeq) });
+                                break;
+                            case 'migration-required':
+                                store.applyCached(value.values);
+                                break;
+                            default:
+                                assertNever(value, 'session projections result');
+                        }
                     }
                     else if (store.values() === initialValues) {
                         // A later frame proves existence independently of an earlier missing read.
                         store.clear();
                     }
-                    this.projectionLoads.set(sessionId, { state: 'ready', error: null });
+                    this.projectionLoads.set(sessionId, {
+                        state: value?.kind === 'migration-required' ? 'migration-required' : 'ready',
+                        error: null,
+                    });
                 }
                 else {
                     this.projectionLoads.set(sessionId, { state: 'error', error: result.error });
@@ -416,11 +437,14 @@ export class SessionManager {
      * Contract session.create; on success merge into summaries immediately (no
      * wait for the next refresh). A created session is blank by definition
      * (entity birth precedes the first message).
-     * @param opts - target workspace or working directory, plus an optional caller-owned id.
-     * @returns the create result.
+     * @param opts - target workspace or working directory, an optional blank Session to reuse, and an optional Agent preset.
+     * @returns the create result, naming the Session the Host created or reused.
     */
     async create(opts = {}) {
-        const shared = opts.sessionId === undefined ? {} : { sessionId: opts.sessionId };
+        const shared = {
+            ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }),
+            ...(opts.agentPreset === undefined ? {} : { agentPreset: opts.agentPreset }),
+        };
         const payload = opts.workspaceId !== undefined
             ? { workspaceId: opts.workspaceId, ...shared }
             : { ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }), ...shared };
@@ -454,7 +478,7 @@ export class SessionManager {
      * preserve it or lower it after an exact cut before the first `turn/start`;
      * lineage rides parentSessionId. A child published before Workspace
      * attachment fails is also reconciled into the list.
-     * @param opts - source session and the optional exact inclusive boundary seq.
+     * @param opts - source session, optional exact inclusive boundary seq, and permission to start migration.
      * @returns the fork result (the child session id).
      */
     async fork(opts) {
@@ -462,6 +486,7 @@ export class SessionManager {
         const result = await this.remote.session.fork({
             sessionId: opts.sessionId,
             ...opts.atSeq === undefined ? {} : { atSeq: opts.atSeq },
+            ...opts.allowMigration === undefined ? {} : { allowMigration: opts.allowMigration },
         });
         const childId = result.ok
             ? result.value.sessionId
@@ -691,6 +716,7 @@ export class SessionManager {
                 && 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.formatStatus === entry.formatStatus
                 && prev.projectionValues === entry.projectionValues)
                 return prev;
             this.entryCache.set(entry.sessionId, entry);
@@ -732,6 +758,7 @@ function applyMutation(summaries, mutation) {
                 ...(mutation.kind === 'upsert' ? {
                     agentAvailable: mutation.summary.agentAvailable,
                     running: mutation.summary.running,
+                    ...(mutation.summary.formatStatus === undefined ? {} : { formatStatus: mutation.summary.formatStatus }),
                 } : {}),
                 ...(existing.cwd === undefined && mutation.summary.cwd !== undefined ? { cwd: mutation.summary.cwd } : {}),
                 ...(existing.parentSessionId === undefined && mutation.summary.parentSessionId !== undefined
@@ -741,7 +768,8 @@ function applyMutation(summaries, mutation) {
             };
             if (filled.cwd === existing.cwd && filled.parentSessionId === existing.parentSessionId
                 && filled.origin === existing.origin && filled.blank === existing.blank
-                && filled.agentAvailable === existing.agentAvailable && filled.running === existing.running)
+                && filled.agentAvailable === existing.agentAvailable && filled.running === existing.running
+                && filled.formatStatus === existing.formatStatus)
                 return [...summaries];
             return summaries.map(summary => summary.sessionId === mutation.summary.sessionId ? filled : summary);
         }

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

@@ -6,8 +6,8 @@
  * (`{ value, seq }`) comes from the connected Host — a follow opening
  * baseline, a Session Controller `projection` frame, a list block the Host
  * computed for an attached Session — and merges under **higher seq wins**
- * against other sequenced rows. A `cached` row (`{ value }`) comes from the
- * session list's view of the persisted checkpoint, carries no comparable
+ * against other sequenced rows. A `cached` row (`{ value }`) comes from
+ * a Host view of the persisted checkpoint, carries no comparable
  * seq, and yields to every sequenced write. No client-side domain folding
  * exists: a domain ships projection support with zero client code. Per-key
  * bare observable faces feed `useProjection` (ui-renderer binds them).
@@ -101,7 +101,7 @@ export declare class ProjectionValueStore {
      */
     apply(key: string, value: unknown, seq: SessionSeqCursor): void;
     /**
-     * Fill keys from a session-list block the Host labeled `cached`: a zero-I/O
+     * Fill keys from a Host block labeled `cached`: a zero-I/O
      * view of the persisted checkpoint. A cached value lands only where no
      * sequenced row exists: a connected Session has already answered for such
      * a key, and the list's view of the persisted checkpoint cannot be newer

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

@@ -82,7 +82,7 @@ export class ProjectionValueStore {
         this.changed(key);
     }
     /**
-     * Fill keys from a session-list block the Host labeled `cached`: a zero-I/O
+     * Fill keys from a Host block labeled `cached`: a zero-I/O
      * view of the persisted checkpoint. A cached value lands only where no
      * sequenced row exists: a connected Session has already answered for such
      * a key, and the list's view of the persisted checkpoint cannot be newer

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

@@ -12,6 +12,7 @@ import type { AgentContext, ISessions, SessionReference, SessionRetainInfo, Sess
 import { SessionManager } from './manager.ts';
 import type { SessionRemotes } from './remotes.ts';
 import type { SessionListPhase, SessionSearchResultItem, SessionProjectionSnapshot } from './manager.ts';
+import type { SessionListEntry } from './lineage.ts';
 /** Session list row projected from the host list RPC plus live stream increments. */
 export interface SessionSummary {
     id: SessionId;
@@ -23,6 +24,8 @@ export interface SessionSummary {
     parentId?: SessionId;
     /** Coarse durable origin for navigation filtering; not a continuation capability. */
     origin?: 'subagent';
+    /** Format classification supplied by the Host list, when available. */
+    formatStatus?: SessionListEntry['formatStatus'];
     /** Host running state for `ids` members; a display fallback for other rows. */
     running: boolean;
     /** Local ownership counts; Host metadata refreshes cannot overwrite them. */
@@ -30,7 +33,7 @@ export interface SessionSummary {
     /**
      * New Session presentation and reuse eligibility, derived from the Host
      * summary, `sessionListMetadata`, and client acceptance/running observations.
-     * New Session reuses a blank one targeting the same workspace. Filtering
+     * Workspace reconnection may reuse a blank in the same workspace. Filtering
      * stays with the consumer: the store carries every row, while the Workspace
      * browser shows only the selected blank entry.
      */
@@ -113,11 +116,11 @@ export declare class ClientSessions implements ISessions {
      * Resolve an already discovered direct-parent address without opening it.
      * Feature plugins use this to avoid Agent-bound RPCs in persisted child views.
      * @param id - possible addressed child id.
-     * @returns A retained or loaded-catalog address, without retaining a new selection or scope.
+     * @returns A retained, catalog-derived, or unknown-mode listed address, without retaining a new selection or scope.
      */
     subagentAddress(id: SessionId): SubagentAddress | undefined;
     /**
-     * Load all Session projections once per connection; retry an unsuccessful initial read.
+     * Read projections without starting migration; retry failed or migration-deferred reads.
      * @param sessionId - Session to inspect without opening its conversation.
      */
     refreshProjections(sessionId: SessionId): Promise<void>;
@@ -172,14 +175,15 @@ export declare class ClientSessions implements ISessions {
     /**
      * Create a Host Session and publish its catalog row before resolving.
      * Callers retain the returned identity before borrowing its binding.
-     * @param opts - target workspace or directory and an optional preallocated id.
-     * @returns the new session id.
+     * @param opts - target workspace or directory, an optional blank Session to reuse, and an optional Agent preset.
+     * @returns the created or reused session id.
      * @throws {SessionCreateError} with the requested id.
      */
     create(opts?: {
         workspaceId?: WorkspaceId;
         cwd?: string;
         sessionId?: SessionId;
+        agentPreset?: string;
     }): Promise<SessionId>;
     /**
      * Fork a session from an exact inclusive prefix of the source (same
@@ -189,7 +193,7 @@ export declare class ClientSessions implements ISessions {
      *   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.
+     *   inherited durable title before resolving, plus permission to start source migration.
      * @returns the child session id.
      * @throws {SessionForkError} with the source id.
      * @throws {Error} when a requested child-title rename fails after creation.
@@ -199,6 +203,7 @@ export declare class ClientSessions implements ISessions {
         atSeq?: number;
         increaseTitle?: boolean;
         onCreated?: (childId: SessionId) => void;
+        allowMigration?: boolean;
     }): Promise<SessionId>;
     /**
      * Borrow an already-retained Agent-scoped Context.

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

@@ -234,13 +234,13 @@ export class ClientSessions {
      * Resolve an already discovered direct-parent address without opening it.
      * Feature plugins use this to avoid Agent-bound RPCs in persisted child views.
      * @param id - possible addressed child id.
-     * @returns A retained or loaded-catalog address, without retaining a new selection or scope.
+     * @returns A retained, catalog-derived, or unknown-mode listed address, without retaining a new selection or scope.
      */
     subagentAddress(id) {
         return this.manager.subagentAddress(id);
     }
     /**
-     * Load all Session projections once per connection; retry an unsuccessful initial read.
+     * Read projections without starting migration; retry failed or migration-deferred reads.
      * @param sessionId - Session to inspect without opening its conversation.
      */
     refreshProjections(sessionId) {
@@ -312,8 +312,8 @@ export class ClientSessions {
     /**
      * Create a Host Session and publish its catalog row before resolving.
      * Callers retain the returned identity before borrowing its binding.
-     * @param opts - target workspace or directory and an optional preallocated id.
-     * @returns the new session id.
+     * @param opts - target workspace or directory, an optional blank Session to reuse, and an optional Agent preset.
+     * @returns the created or reused session id.
      * @throws {SessionCreateError} with the requested id.
      */
     async create(opts = {}) {
@@ -331,7 +331,7 @@ export class ClientSessions {
      *   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.
+     *   inherited durable title before resolving, plus permission to start source migration.
      * @returns the child session id.
      * @throws {SessionForkError} with the source id.
      * @throws {Error} when a requested child-title rename fails after creation.
@@ -343,6 +343,7 @@ export class ClientSessions {
         const result = await this.manager.fork({
             sessionId: opts.sessionId,
             ...(opts.atSeq === undefined ? {} : { atSeq: SessionSeq(opts.atSeq) }),
+            ...(opts.allowMigration === undefined ? {} : { allowMigration: opts.allowMigration }),
         });
         if (!result.ok)
             throw new SessionForkError(result.error, opts.sessionId);
@@ -502,6 +503,7 @@ export class ClientSessions {
                 retainedBy: this.retentionSnapshot(entry.sessionId).retainedBy,
                 blank: entry.blank,
                 updatedAt: entry.updatedAt,
+                formatStatus: entry.formatStatus,
                 ...(entry.projectionValues === undefined
                     ? {}
                     : { projectionValues: entry.projectionValues }),
@@ -513,6 +515,8 @@ export class ClientSessions {
         }
         for (const [parentId, projection] of Object.entries(projectionsBySession)) {
             for (const child of projection.values.subagentCatalog ?? []) {
+                if (child.mode === 'external')
+                    continue;
                 const childId = child.id;
                 const summary = byId[childId];
                 const projectionValues = summary?.projectionValues ?? this.manager.projectionValues(childId);

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

@@ -202,7 +202,7 @@ export class Session {
             // wire type is used; this array is not filtered or reordered.
             const routedContent = content;
             const routed = await this.remote.subagents.prompt({
-                requestId: randomUUID(),
+                requestId: requestId ?? randomUUID(),
                 parentSessionId: this.address.parentSessionId,
                 childSessionId: this.address.childSessionId,
                 mode: 'continuable',

package/lib/types/commands.d.ts

@@ -1,7 +1,17 @@
 /** Session commands whose activation policy is explicit at each Remote method. */
 import type { Context } from '@deepseek-ai/cordis';
+import type { MessageSource } from '@deepseek-ai/dsh-llm';
 import { ApiSessionAgentController } from './agent.ts';
 import type { SessionAttachmentRequest, SessionAttachmentValue, SessionCancelRequest, SessionCancelValue, SessionCreateRequest, SessionCreateValue, SessionForkRequest, SessionForkValue, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, SessionRenameValue, SessionSelectModelRequest, SessionSelectModelValue, SessionUpdateQueueRequest, SessionUpdateQueueValue } from './types.ts';
+type PromptContentCandidate = SessionPromptRequest['content'][number] | Extract<SessionUpdateQueueRequest['action'], {
+    readonly kind: 'edit';
+}>['content'][number];
+/**
+ * Whether prompt content carries non-whitespace text or an attachment.
+ * @param content - submitted or edited prompt parts.
+ * @returns false for content the Agent must not receive.
+ */
+export declare function hasPromptContent(content: readonly PromptContentCandidate[]): boolean;
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 export declare class SessionCommandController {
     private readonly ctx;
@@ -14,9 +24,10 @@ export declare class SessionCommandController {
      */
     constructor(ctx: Context, agents: ApiSessionAgentController, defaultCwd: string);
     /**
-     * Create or idempotently adopt one ordinary Session.
-     * @param request - requested identity, location, and Agent preset.
-     * @returns the Session identity and resolved preset when configured.
+     * Create one ordinary Session for a new conversation, reusing the named
+     * blank Session while it is an unarchived member of the requested Workspace.
+     * @param request - optional blank Session to reuse, location, and Agent preset.
+     * @returns the created or reused Session identity and its preset when configured.
      */
     create(request: SessionCreateRequest): Promise<SessionCreateValue>;
     /**
@@ -40,11 +51,13 @@ export declare class SessionCommandController {
      */
     fork(request: SessionForkRequest): Promise<SessionForkValue>;
     /**
-     * Reject empty content, then admit one prompt after Agent and attachment validation.
-     * @param request - Session identity, prompt content, source metadata, and delivery mode.
+     * Admit one prompt after Agent and attachment validation; the Remote method
+     * has already validated the content and built the durable message source.
+     * @param request - Session identity, prompt content, and delivery mode.
+     * @param source - the `user-rpc` source recorded on the accepted message.
      * @returns acknowledgement that the Agent accepted the prompt.
      */
-    prompt(request: SessionPromptRequest): Promise<SessionPromptValue>;
+    prompt(request: SessionPromptRequest, source: MessageSource): Promise<SessionPromptValue>;
     private requireModel;
     /**
      * Read one durable image after proving the Session log references it.
@@ -69,4 +82,5 @@ export declare class SessionCommandController {
     private readSessionState;
     private forkWorkspace;
 }
+export {};
 //# sourceMappingURL=commands.d.ts.map

package/lib/types/commands.js

@@ -60,11 +60,15 @@ import { buildForkSeed } from '@deepseek-ai/dsh-session/fork';
 import { SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title';
-import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time';
 import { assertNever } from '@deepseek-ai/dsh-util-values';
 import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol';
 import { ApiSessionCwdConflict, ApiSessionNotFound, ApiSessionPresetConflict, ApiSessionSubagentOwnership, apiSessionSubagentOwnershipError, hasApiSessionSubagentOwner, inspectApiSession, } from "./agent.js";
-function hasPromptContent(content) {
+/**
+ * Whether prompt content carries non-whitespace text or an attachment.
+ * @param content - submitted or edited prompt parts.
+ * @returns false for content the Agent must not receive.
+ */
+export function hasPromptContent(content) {
     return content.some(part => part.type !== 'text' || part.text.trim().length > 0);
 }
 /**
@@ -100,15 +104,15 @@ export class SessionCommandController {
         this.defaultCwd = defaultCwd;
     }
     /**
-     * Create or idempotently adopt one ordinary Session.
-     * @param request - requested identity, location, and Agent preset.
-     * @returns the Session identity and resolved preset when configured.
+     * Create one ordinary Session for a new conversation, reusing the named
+     * blank Session while it is an unarchived member of the requested Workspace.
+     * @param request - optional blank Session to reuse, location, and Agent preset.
+     * @returns the created or reused Session identity and its preset when configured.
      */
     async create(request) {
         if (request.workspaceId !== undefined && request.cwd !== undefined) {
             throw new RemoteError('gateway/bad-request', 'session.create accepts workspaceId or cwd, not both', {});
         }
-        const sessionId = request.sessionId ?? brandString(`session-${randomUUID()}`);
         let workspace;
         if (request.workspaceId !== undefined) {
             workspace = this.ctx.workspaceRegistry.get(request.workspaceId);
@@ -119,13 +123,20 @@ export class SessionCommandController {
             }
         }
         const cwd = workspace?.path ?? request.cwd ?? this.defaultCwd;
-        let adopted;
+        let created;
         try {
-            adopted = await this.agents.ensureSession(sessionId, cwd, request.sessionId !== undefined, request.agentPreset);
+            created = await this.agents.createSession({
+                ...(request.sessionId === undefined ? {} : { sessionId: request.sessionId }),
+                cwd,
+                ...(request.agentPreset === undefined ? {} : { agentPreset: request.agentPreset }),
+                reusable: sessionId => !this.ctx.workspaceRegistry.archivedSessionIds.includes(sessionId)
+                    && (workspace === undefined || workspace.sessionIds.includes(sessionId)),
+            });
         }
         catch (error) {
-            this.rejectCreation(sessionId, error);
+            this.rejectCreation(error);
         }
+        const sessionId = created.agent.id;
         if (workspace !== undefined) {
             try {
                 await workspace.attachSession(sessionId);
@@ -134,8 +145,7 @@ export class SessionCommandController {
                 throw new RemoteError('session/workspace-attach-failed', `session "${sessionId}" was created but could not attach to workspace "${workspace.id}": ${String(error)}`, { sessionId, workspaceId: workspace.id });
             }
         }
-        const agentPreset = this.agents.presetForSession(adopted.session);
-        return { sessionId, ...(agentPreset === undefined ? {} : { agentPreset }) };
+        return { sessionId, ...(created.agentPreset === undefined ? {} : { agentPreset: created.agentPreset }) };
     }
     /**
      * Validate and install one Session-local model selection; save the default in the background.
@@ -283,28 +293,16 @@ export class SessionCommandController {
         }
     }
     /**
-     * Reject empty content, then admit one prompt after Agent and attachment validation.
-     * @param request - Session identity, prompt content, source metadata, and delivery mode.
+     * Admit one prompt after Agent and attachment validation; the Remote method
+     * has already validated the content and built the durable message source.
+     * @param request - Session identity, prompt content, and delivery mode.
+     * @param source - the `user-rpc` source recorded on the accepted message.
      * @returns acknowledgement that the Agent accepted the prompt.
      */
-    async prompt(request) {
-        if (!hasPromptContent(request.content)) {
-            throw new RemoteError('gateway/bad-request', 'prompt content must include non-whitespace text or an attachment', {});
-        }
-        const clientTimeZone = request.clientTimeZone === undefined
-            ? undefined
-            : canonicalClientTimeZone(request.clientTimeZone);
-        if (request.clientTimeZone !== undefined && clientTimeZone === undefined) {
-            throw new RemoteError('session/invalid-time-zone', 'clientTimeZone must be UTC or a valid IANA Area/Location name', { value: request.clientTimeZone });
-        }
+    async prompt(request, source) {
         const agent = await this.resolveAgent(request.sessionId);
         if (hasPromptRequest(agent, request.requestId))
             return { accepted: true };
-        const source = {
-            kind: 'user',
-            rpcId: request.requestId,
-            ...(clientTimeZone === undefined ? {} : { clientTimeZone }),
-        };
         const hasImage = request.content.some(part => part.type === 'image');
         const admit = async () => {
             try {
@@ -482,17 +480,13 @@ export class SessionCommandController {
             throw found.error;
         return found.agent;
     }
-    rejectCreation(sessionId, error) {
+    rejectCreation(error) {
         if (remoteErrorOf(error) !== undefined)
             throw error;
-        if (error instanceof Error && error.name === 'SessionAlreadyOwnedError') {
-            throw new RemoteError('session/writer-held', error.message, { sessionId });
-        }
         if (error instanceof ApiSessionPresetConflict) {
             throw new RemoteError('agent-preset/conflict', error.message, {
                 sessionId: error.sessionId,
                 requestedPreset: error.requestedPreset,
-                ...(error.existingPreset === undefined ? {} : { existingPreset: error.existingPreset }),
             });
         }
         if (error instanceof ApiSessionCwdConflict) {
@@ -505,7 +499,7 @@ export class SessionCommandController {
         if (error instanceof ApiSessionSubagentOwnership) {
             throw apiSessionSubagentOwnershipError(error.sessionId);
         }
-        throw new RemoteError('gateway/internal', `failed to create session "${sessionId}": ${String(error)}`, {});
+        throw new RemoteError('gateway/internal', `failed to create session: ${String(error)}`, {});
     }
     async readSessionState(sessionId) {
         const attached = this.ctx.sessions.get(sessionId);

package/lib/types/index.d.ts

@@ -85,16 +85,18 @@ export declare class SessionController extends TypertRemoteService {
      */
     list(_request: SessionListRequest, signal: AbortSignal): Promise<SessionListValue>;
     /**
-     * Search visible Session content without resuming an Agent.
+     * Search visible Session content without resuming an Agent. A non-owner
+     * receives only the hits whose Session `allows()` admits; `hasMore`
+     * describes the bounded result before that filtering.
      * @param request - literal message-content query.
      * @param signal - cancellation for list and search reads.
      * @returns authorized bounded Session search results.
      */
     search(request: SessionSearchRequest, signal: AbortSignal): Promise<SessionSearchValue>;
     /**
-     * Create or idempotently adopt one ordinary Session.
-     * @param request - requested identity, location, and Agent preset.
-     * @returns the Session identity and resolved preset when configured.
+     * Create one ordinary Session for a new conversation, reusing the named blank Session while it is reusable.
+     * @param request - optional blank Session to reuse, location, and Agent preset.
+     * @returns the created or reused Session identity and its preset when configured.
      */
     create(request: SessionCreateRequest): Promise<SessionCreateValue>;
     /**
@@ -156,7 +158,7 @@ export declare class SessionController extends TypertRemoteService {
      * Fork one cold-readable exact event prefix into a new Session. An omitted
      * boundary selects the latest completed-turn prefix; an open cut receives
      * synthetic fork closers.
-     * @param request - source Session and optional exact inclusive event boundary.
+     * @param request - source Session, optional exact inclusive event boundary, and migration preflight choice.
      * @returns the new Session identity.
      */
     fork(request: SessionForkRequest): Promise<SessionForkValue>;
@@ -201,12 +203,13 @@ export declare class SessionController extends TypertRemoteService {
      */
     follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
     /**
-     * Read all registered projections without activating an Agent.
+     * Read exact projections, returning cached hints only when migration is required.
      * @param request - Session whose current values are required.
-     * @param signal - cancellation for the Session observation.
-     * @returns complete baseline, or null when the Session does not exist.
+     * @param signal - cancellation for the Session read.
+     * @returns a sequenced baseline, cached hints when migration is deferred, or null when absent.
      */
     projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise<SessionProjectionsValue>;
+    private liveProjections;
     /**
      * Stream a complete live-control baseline followed by replacement frames.
      * @param signal - cancellation owned by the Remote stream carrier.