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

package/lib/types/index.d.ts

@@ -1,12 +1,13 @@
 /** Session Remote owner: cold reads, explicit Agent commands, and live control state. */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { nativeFileApplications, openNativeFileApplication } from '@deepseek-ai/dsh-native-command';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { type ApiSessionAgentResult } from './agent.ts';
 import { buildModelCatalog } from './catalog.ts';
-import type { ModelCatalog, SessionAttachmentRequest, SessionAttachmentValue, SessionCancelRequest, SessionCancelValue, SessionControlFrame, SessionCreateRequest, SessionCreateValue, SessionFollowFrame, SessionFollowRequest, SessionForkRequest, SessionForkValue, SessionListRequest, SessionListValue, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, SessionPageRequest, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, SessionRenameValue, SessionSearchRequest, SessionSearchValue, SessionSelectModelRequest, SessionSelectModelValue, SessionUpdateQueueRequest, SessionUpdateQueueValue } from './types.ts';
+import type { ModelCatalog, SessionWorkspacePathApplication, SessionAttachmentRequest, SessionAttachmentValue, SessionCancelRequest, SessionCancelValue, SessionControlFrame, SessionCreateRequest, SessionCreateValue, SessionFollowFrame, SessionFollowRequest, SessionForkRequest, SessionForkValue, SessionListRequest, SessionListValue, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, SessionPageRequest, SessionPromptRequest, SessionPromptValue, SessionRenameRequest, SessionRenameValue, SessionSearchRequest, SessionSearchValue, SessionSelectModelRequest, SessionSelectModelValue, SessionProjectionsRequest, SessionProjectionsValue, SessionUpdateQueueRequest, SessionUpdateQueueValue } from './types.ts';
 export type * from './types.ts';
 export { ApiSessionNotFound } from './agent.ts';
 export { SessionFileReferences } from './file-references.ts';
@@ -26,6 +27,10 @@ export interface Config {
 export interface SessionControllerInternals {
     /** Native default-application handoff. */
     readonly openPath?: (path: string, signal: AbortSignal) => Promise<void>;
+    /** Native file-association query. */
+    readonly fileApplications?: typeof nativeFileApplications;
+    /** Explicit registered-application handoff. */
+    readonly openFileApplication?: typeof openNativeFileApplication;
     /** Native file-manager handoff. */
     readonly revealPath?: (path: string, signal: AbortSignal) => Promise<void>;
     /** Native handoff availability probe. */
@@ -41,6 +46,8 @@ export declare class SessionController extends TypertRemoteService {
     private readonly history;
     private readonly listState;
     private readonly openPath;
+    private readonly fileApplications;
+    private readonly openFileApplication;
     private readonly revealPath;
     private readonly canOpenPath;
     private readonly promotions;
@@ -110,13 +117,24 @@ export declare class SessionController extends TypertRemoteService {
         fileManager: 'finder' | 'explorer' | 'directory' | null;
     };
     /**
-     * Open one path prepared by a Session-aware caller on the Host desktop.
+     * Verify one path through the composed filesystem and open it on the Host desktop.
      * @param request - path after best-effort Session workspace resolution.
      * @param signal - caller lifetime; abort terminates the native command.
      * @returns confirmation after the native opener accepts the path.
-     * @throws RemoteError when the request is invalid, cancelled, or the opener fails.
+     * @throws RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.
      */
     openWorkspacePath(request: SessionOpenWorkspacePathRequest, signal: AbortSignal): Promise<SessionOpenWorkspacePathValue>;
+    /**
+     * Query current file handlers on the serving desktop without activating an Agent.
+     * @param request - file path in Host filesystem syntax.
+     * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+     * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+     * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+     */
+    workspacePathApplications(request: {
+        readonly path: string;
+    }, signal: AbortSignal): Promise<readonly SessionWorkspacePathApplication[]>;
+    private verifyDesktopPath;
     /**
      * Rename one Session after explicitly resuming it.
      * @param request - Session identity and proposed title.
@@ -124,8 +142,10 @@ export declare class SessionController extends TypertRemoteService {
      */
     rename(request: SessionRenameRequest): Promise<SessionRenameValue>;
     /**
-     * Fork one cold-readable completed-turn prefix into a new Session.
-     * @param request - source Session and optional event anchor.
+     * 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.
      * @returns the new Session identity.
      */
     fork(request: SessionForkRequest): Promise<SessionForkValue>;
@@ -169,6 +189,13 @@ export declare class SessionController extends TypertRemoteService {
      *   frames and optional cursorless assistant-stream frames.
      */
     follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
+    /**
+     * Read all registered projections without activating an Agent.
+     * @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.
+     */
+    projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise<SessionProjectionsValue>;
     /**
      * Stream a complete live-control baseline followed by replacement frames.
      * @param signal - cancellation owned by the Remote stream carrier.

package/lib/types/index.js

@@ -86,9 +86,11 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { hostname } from 'node:os';
+import { resolve } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { errorChain } from '@deepseek-ai/dsh-llm';
-import { canOpenNativePath, nativeFileManager, openNativePath, revealNativePath } from '@deepseek-ai/dsh-native-command';
+import { canOpenNativePath, nativeFileManager, nativeFileApplications, openNativeFileApplication, openNativeAssociatedPath, revealNativePath } from '@deepseek-ai/dsh-native-command';
+import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { ApiSessionAgentController, inspectApiSession, } from "./agent.js";
 import { SessionCommandController } from "./commands.js";
@@ -100,6 +102,7 @@ import { buildModelCatalog } from "./catalog.js";
 import { installModelSelectionProjection } from "./model-selection-projection.js";
 import { SessionSkillCatalog } from "./skill-catalog.js";
 import { SessionMediaReferences } from "./media-references.js";
+import { ArchivedSessionGate } from "./archived-session-gate.js";
 export { ApiSessionNotFound } from "./agent.js";
 export { SessionFileReferences } from "./file-references.js";
 export { SessionSkillCatalog } from "./skill-catalog.js";
@@ -114,6 +117,7 @@ let SessionController = (() => {
     let _modelCatalog_decorators;
     let _canOpenWorkspacePath_decorators;
     let _openWorkspacePath_decorators;
+    let _workspacePathApplications_decorators;
     let _rename_decorators;
     let _fork_decorators;
     let _prompt_decorators;
@@ -122,6 +126,7 @@ let SessionController = (() => {
     let _cancel_decorators;
     let _page_decorators;
     let _follow_decorators;
+    let _projections_decorators;
     let _control_decorators;
     return class SessionController extends _classSuper {
         static {
@@ -133,6 +138,7 @@ let SessionController = (() => {
             _modelCatalog_decorators = [Remote('modelCatalog')];
             _canOpenWorkspacePath_decorators = [Remote];
             _openWorkspacePath_decorators = [Remote('openWorkspacePath')];
+            _workspacePathApplications_decorators = [Remote('workspacePathApplications')];
             _rename_decorators = [Remote('rename')];
             _fork_decorators = [Remote('fork')];
             _prompt_decorators = [Remote('prompt')];
@@ -141,6 +147,7 @@ let SessionController = (() => {
             _cancel_decorators = [Remote('cancel')];
             _page_decorators = [Remote('page')];
             _follow_decorators = [Remote({ mode: 'stream' })];
+            _projections_decorators = [Remote('projections')];
             _control_decorators = [Remote({ mode: 'stream' })];
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _search_decorators, { kind: "method", name: "search", static: false, private: false, access: { has: obj => "search" in obj, get: obj => obj.search }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -149,6 +156,7 @@ let SessionController = (() => {
             __esDecorate(this, null, _modelCatalog_decorators, { kind: "method", name: "modelCatalog", static: false, private: false, access: { has: obj => "modelCatalog" in obj, get: obj => obj.modelCatalog }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _canOpenWorkspacePath_decorators, { kind: "method", name: "canOpenWorkspacePath", static: false, private: false, access: { has: obj => "canOpenWorkspacePath" in obj, get: obj => obj.canOpenWorkspacePath }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _openWorkspacePath_decorators, { kind: "method", name: "openWorkspacePath", static: false, private: false, access: { has: obj => "openWorkspacePath" in obj, get: obj => obj.openWorkspacePath }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _workspacePathApplications_decorators, { kind: "method", name: "workspacePathApplications", static: false, private: false, access: { has: obj => "workspacePathApplications" in obj, get: obj => obj.workspacePathApplications }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _rename_decorators, { kind: "method", name: "rename", static: false, private: false, access: { has: obj => "rename" in obj, get: obj => obj.rename }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _fork_decorators, { kind: "method", name: "fork", static: false, private: false, access: { has: obj => "fork" in obj, get: obj => obj.fork }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _prompt_decorators, { kind: "method", name: "prompt", static: false, private: false, access: { has: obj => "prompt" in obj, get: obj => obj.prompt }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -157,6 +165,7 @@ let SessionController = (() => {
             __esDecorate(this, null, _cancel_decorators, { kind: "method", name: "cancel", static: false, private: false, access: { has: obj => "cancel" in obj, get: obj => obj.cancel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _page_decorators, { kind: "method", name: "page", static: false, private: false, access: { has: obj => "page" in obj, get: obj => obj.page }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _follow_decorators, { kind: "method", name: "follow", static: false, private: false, access: { has: obj => "follow" in obj, get: obj => obj.follow }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _projections_decorators, { kind: "method", name: "projections", static: false, private: false, access: { has: obj => "projections" in obj, get: obj => obj.projections }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _control_decorators, { kind: "method", name: "control", static: false, private: false, access: { has: obj => "control" in obj, get: obj => obj.control }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
@@ -165,6 +174,7 @@ let SessionController = (() => {
             'agents',
             'attachments',
             'fileUploads',
+            'fs',
             'llm',
             'sessions',
             'sessionProjections',
@@ -181,6 +191,8 @@ let SessionController = (() => {
         history;
         listState;
         openPath;
+        fileApplications;
+        openFileApplication;
         revealPath;
         canOpenPath;
         promotions = new Set();
@@ -208,19 +220,32 @@ let SessionController = (() => {
             }, 'session-controller.promotions');
             this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation); });
             this.listState = new ApiSessionList(ctx);
-            this.openPath = internals.openPath ?? openNativePath;
+            this.fileApplications = internals.fileApplications ?? nativeFileApplications;
+            this.openFileApplication = internals.openFileApplication ?? openNativeFileApplication;
+            this.openPath = internals.openPath ?? openNativeAssociatedPath;
             this.revealPath = internals.revealPath ?? revealNativePath;
             this.canOpenPath = internals.canOpenPath
                 ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()));
             ctx.plugin(SessionFileReferences);
             ctx.plugin(SessionMediaReferences);
             ctx.plugin(SessionSkillCatalog);
+            // An archived Session, or a subagent descendant of one, runs no model step
+            // until it is restored; what it still runs is stopped by the owners that
+            // answer the Workspace registry's archive-admission events.
+            ctx.plugin(ArchivedSessionGate);
             ctx.on('session/created', (session) => {
                 ctx.emit('api-session/added', this.listState.summaryFor(session));
             });
             ctx.on('session/disposed', (session) => {
                 ctx.emit('api-session/removed', session.id);
             });
+            const publishAgentAvailability = ({ agent }) => {
+                if (ctx.sessions.get(agent.id) === agent.session) {
+                    ctx.emit('api-session/added', this.listState.summaryFor(agent.session));
+                }
+            };
+            ctx.on('agent/created', publishAgentAvailability);
+            ctx.on('agent/disposed', publishAgentAvailability);
             ctx.on('agent/status', ({ agent, status }) => {
                 ctx.emit('api-session/status', agent.id, status === 'running');
             });
@@ -344,29 +369,65 @@ let SessionController = (() => {
             return { name: hostname(), available: fileManager !== null && this.canOpenPath(), fileManager };
         }
         /**
-         * Open one path prepared by a Session-aware caller on the Host desktop.
+         * Verify one path through the composed filesystem and open it on the Host desktop.
          * @param request - path after best-effort Session workspace resolution.
          * @param signal - caller lifetime; abort terminates the native command.
          * @returns confirmation after the native opener accepts the path.
-         * @throws RemoteError when the request is invalid, cancelled, or the opener fails.
+         * @throws RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.
          */
         async openWorkspacePath(request, signal) {
-            if (request.path.length === 0) {
-                throw new RemoteError('gateway/bad-request', 'session.openWorkspacePath requires a non-empty path', {});
-            }
-            signal.throwIfAborted();
             try {
+                const path = await this.verifyDesktopPath(request.path, signal);
                 if (request.action === 'reveal')
-                    await this.revealPath(request.path, signal);
+                    await this.revealPath(path, signal);
+                else if (request.application !== undefined)
+                    await this.openFileApplication(path, request.application, signal);
                 else
-                    await this.openPath(request.path, signal);
+                    await this.openPath(path, signal);
                 return { opened: true };
             }
             catch (error) {
                 if (signal.aborted)
                     throw new RemoteError('gateway/cancelled', 'path open was aborted', {});
-                throw new RemoteError('gateway/internal', `path open failed: ${error instanceof Error ? error.message : String(error)}`, {});
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'path open failed', {}, { cause: error });
+            }
+        }
+        /**
+         * Query current file handlers on the serving desktop without activating an Agent.
+         * @param request - file path in Host filesystem syntax.
+         * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+         * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+         * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+         */
+        async workspacePathApplications(request, signal) {
+            if (!this.canOpenPath())
+                return [];
+            try {
+                const path = await this.verifyDesktopPath(request.path, signal);
+                return await this.fileApplications(path, signal);
             }
+            catch (error) {
+                if (signal.aborted)
+                    throw new RemoteError('gateway/cancelled', 'application query was aborted', {});
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'file application query failed', {}, { cause: error });
+            }
+        }
+        async verifyDesktopPath(path, signal) {
+            if (path.length === 0)
+                throw new RemoteError('gateway/bad-request', 'A non-empty file path is required', {});
+            signal.throwIfAborted();
+            const hostPath = resolve(path);
+            const { fs } = this.ctx;
+            const mapped = fs.processPathFromHostPath(hostPath);
+            if (mapped === undefined || fs.processPath(await fs.resolve(mapped, { signal })) !== hostPath) {
+                throw new RemoteError('gateway/bad-request', 'Path has no verified Host path', {});
+            }
+            signal.throwIfAborted();
+            return hostPath;
         }
         /**
          * Rename one Session after explicitly resuming it.
@@ -377,8 +438,10 @@ let SessionController = (() => {
             return this.commands.rename(request);
         }
         /**
-         * Fork one cold-readable completed-turn prefix into a new Session.
-         * @param request - source Session and optional event anchor.
+         * 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.
          * @returns the new Session identity.
          */
         fork(request) {
@@ -437,6 +500,47 @@ let SessionController = (() => {
         follow(request, signal) {
             return this.history.follow(request, signal);
         }
+        /**
+         * Read all registered projections without activating an Agent.
+         * @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.
+         */
+        async projections(request, signal) {
+            const { sessionId } = request;
+            if (sessionId.length === 0) {
+                throw new RemoteError('gateway/bad-request', 'sessionId must not be empty', {});
+            }
+            try {
+                const env_2 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const observation = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId, { signal }), false);
+                    const projections = observation.projections;
+                    if (projections === undefined) {
+                        throw new RemoteError('session/projections-unavailable', 'Session projections are unavailable', {});
+                    }
+                    return { asOfSeq: projections.asOfSeq, values: projections.values };
+                }
+                catch (e_2) {
+                    env_2.error = e_2;
+                    env_2.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_2);
+                }
+            }
+            catch (error) {
+                if (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND')
+                    return null;
+                if (signal.aborted
+                    || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) {
+                    throw new RemoteError('gateway/cancelled', 'Session projection read was cancelled', {}, { cause: error });
+                }
+                if (error instanceof RemoteError)
+                    throw error;
+                throw new RemoteError('gateway/internal', 'Session projection read failed', {}, { cause: error });
+            }
+        }
         /**
          * Stream a complete live-control baseline followed by replacement frames.
          * @param signal - cancellation owned by the Remote stream carrier.

package/lib/types/list.js

@@ -1,5 +1,4 @@
 /** Cold-safe Session list and search projection. */
-import { SessionLogOffset } from '@deepseek-ai/dsh-session';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
 import { z } from 'zod';
@@ -90,6 +89,7 @@ export class ApiSessionList {
         return {
             sessionId: session.id,
             updatedAt: updatedAt(session.header, metadata),
+            agentAvailable: this.ctx.agents.get(session.id)?.session === session,
             running: this.ctx.agents.get(session.id)?.status === 'running',
             blank: metadata?.blank ?? session.seq === 0,
             ...listFields(session.header),
@@ -128,6 +128,7 @@ export class ApiSessionList {
         return {
             sessionId: header.id,
             updatedAt: updatedAt(header, metadata),
+            agentAvailable: false,
             running: false,
             // A large, metadata-less, or inaccessible cache miss remains unknown and visible.
             blank: metadata?.blank ?? false,
@@ -246,21 +247,16 @@ export class ApiSessionList {
     }
     projectionsFor(header, session) {
         try {
+            if (session !== undefined) {
+                // The live registry computed the block for this Session: its watermark
+                // shares the sequence space of the Session's baselines and frames.
+                return hintsOf('sequenced', this.ctx.sessionProjections.cachedSnapshot(session));
+            }
+            // A cold row reads the persisted cache by header alone; the cache serves
+            // seeded and unseeded lifecycles alike because a listing never seeds a
+            // fold. The watermark is the stored record's own.
             const cache = this.ctx.get('sessionProjectionCache');
-            const block = session === undefined
-                ? header.isSeeded
-                    ? undefined
-                    : cache?.cachedSnapshot(header, SessionLogOffset(0))
-                        ?? cache?.cachedPredecessorTitle(header, SessionLogOffset(0))
-                : this.ctx.sessionProjections.cachedSnapshot(session);
-            return block !== undefined && Object.keys(block.values).length > 0
-                ? {
-                    asOfSeq: block.asOfSeq,
-                    // Listing hints contain every currently cached wire value but remain
-                    // partial: missing cells and cache rows are never materialized here.
-                    values: block.values,
-                }
-                : undefined;
+            return hintsOf('cached', cache?.cachedSnapshot(header) ?? cache?.cachedPredecessorTitle(header));
         }
         catch (error) {
             this.ctx.logger.warn(`api-session.list: projection column for "${header.id}" failed; serving the row without it: ${String(error)}`);
@@ -268,6 +264,19 @@ export class ApiSessionList {
         }
     }
 }
+/**
+ * Wrap one projection block as Session-list hints of the named sequence space.
+ * @param kind - which sequence space the block's watermark belongs to.
+ * @param block - the block, or `undefined` when no source served one.
+ * @returns the hints, or `undefined` when the block is absent or carries no value.
+ */
+function hintsOf(kind, block) {
+    if (block === undefined || Object.keys(block.values).length === 0)
+        return undefined;
+    // Listing hints contain every wire value the source currently holds but
+    // remain partial: missing cells and cache rows are never materialized here.
+    return { kind, asOfSeq: block.asOfSeq, values: block.values };
+}
 function normalizeSearchQuery(query) {
     const normalized = query.trim();
     if (normalized.length === 0) {

package/lib/types/skill-catalog.js

@@ -114,72 +114,82 @@ let SessionSkillCatalog = (() => {
          * @throws RemoteError when the Session cannot be inspected or no registry can serve it.
          */
         async list(request, signal) {
-            void signal;
-            const { sessionId } = request;
-            let cwd;
-            let agentPreset;
+            const env_1 = { stack: [], error: void 0, hasError: false };
             try {
-                const env_1 = { stack: [], error: void 0, hasError: false };
+                void signal;
+                const { sessionId } = request;
+                let cwd;
+                let agentPreset;
                 try {
-                    const observation = __addDisposableResource(env_1, await this.ctx.sessionQuery.observeSession(sessionId), false);
-                    if (observation.projections === undefined) {
-                        throw new Error('skill catalog requires a projected Session observation');
+                    const env_2 = { stack: [], error: void 0, hasError: false };
+                    try {
+                        const observation = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
+                        if (observation.projections === undefined) {
+                            throw new Error('skill catalog requires a projected Session observation');
+                        }
+                        cwd = observation.header.cwd;
+                        agentPreset = observation.projections.values.agentPreset ?? undefined;
+                    }
+                    catch (e_1) {
+                        env_2.error = e_1;
+                        env_2.hasError = true;
+                    }
+                    finally {
+                        __disposeResources(env_2);
                     }
-                    cwd = observation.header.cwd;
-                    agentPreset = observation.projections.values.agentPreset ?? undefined;
                 }
-                catch (e_1) {
-                    env_1.error = e_1;
-                    env_1.hasError = true;
+                catch (error) {
+                    if (error instanceof SessionQueryError
+                        && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
+                        throw new RemoteError('session/not-found', `session "${sessionId}" not found`, { sessionId });
+                    }
+                    throw new RemoteError('gateway/internal', `session "${sessionId}" could not be inspected: ${String(error)}`, {});
                 }
-                finally {
-                    __disposeResources(env_1);
+                if (cwd === undefined) {
+                    throw new RemoteError('gateway/internal', `session "${sessionId}" has no project cwd`, {});
                 }
-            }
-            catch (error) {
-                if (error instanceof SessionQueryError
-                    && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
-                    throw new RemoteError('session/not-found', `session "${sessionId}" not found`, { sessionId });
+                const live = this.ctx.agents.get(sessionId);
+                const presets = this.ctx.get('agentPresets');
+                const scoped = live === undefined ? undefined : presets?.serviceFor(live, 'skills');
+                const skillRegistry = scoped ?? this.ctx.get('skills');
+                if (skillRegistry === undefined) {
+                    throw new RemoteError('gateway/internal', 'skill registry is absent: neither this session\'s agent preset nor the host composition mounts @deepseek-ai/dsh-skill', {});
+                }
+                const lease = __addDisposableResource(env_1, live === undefined ? await this.scopeFor(agentPreset) : undefined, true);
+                const scope = live ?? lease?.key;
+                try {
+                    const skills = (await skillRegistry.list({ cwd, scope })).filter(isUserInvocable);
+                    return {
+                        skills: skills.map(skill => ({
+                            name: skill.name,
+                            ...skill.path === undefined ? {} : { path: skill.path },
+                            description: skill.description,
+                            ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+                            modelInvocable: skill.invocation.modelInvocable,
+                        })),
+                    };
+                }
+                catch (error) {
+                    throw new RemoteError('gateway/internal', `skill listing failed: ${String(error)}`, {});
                 }
-                throw new RemoteError('gateway/internal', `session "${sessionId}" could not be inspected: ${String(error)}`, {});
-            }
-            if (cwd === undefined) {
-                throw new RemoteError('gateway/internal', `session "${sessionId}" has no project cwd`, {});
-            }
-            const live = this.ctx.agents.get(sessionId);
-            const presets = this.ctx.get('agentPresets');
-            const scoped = live === undefined ? undefined : presets?.serviceFor(live, 'skills');
-            const skillRegistry = scoped ?? this.ctx.get('skills');
-            if (skillRegistry === undefined) {
-                throw new RemoteError('gateway/internal', 'skill registry is absent: neither this session\'s agent preset nor the host composition mounts @deepseek-ai/dsh-skill', {});
             }
-            const scope = await this.scopeFor(sessionId, agentPreset);
-            try {
-                const skills = (await skillRegistry.list({ cwd, scope })).filter(isUserInvocable);
-                return {
-                    skills: skills.map(skill => ({
-                        name: skill.name,
-                        ...skill.path === undefined ? {} : { path: skill.path },
-                        description: skill.description,
-                        ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
-                        modelInvocable: skill.invocation.modelInvocable,
-                    })),
-                };
+            catch (e_2) {
+                env_1.error = e_2;
+                env_1.hasError = true;
             }
-            catch (error) {
-                throw new RemoteError('gateway/internal', `skill listing failed: ${String(error)}`, {});
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
             }
         }
         /** Resolve a live or standing preset scope without creating an Agent. */
-        async scopeFor(sessionId, agentPreset) {
-            const live = this.ctx.agents.get(sessionId);
-            if (live !== undefined)
-                return live;
+        async scopeFor(agentPreset) {
             const presets = this.ctx.get('agentPresets');
             if (presets === undefined)
                 return undefined;
             try {
-                return await presets.standingKeyFor(agentPreset);
+                return await presets.acquireScope(agentPreset);
             }
             catch {
                 // An unknown or unusable recorded preset falls back to the global registry.