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

package/lib/index.js

@@ -1,14 +1,16 @@
 import { hostname } from "node:os";
+import { isAbsolute, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { AssistantStreamAccumulator, ReasoningEffortId, assistantStreamChunks, createUserMessage, errorChain, freezeMessage } from "@deepseek-ai/dsh-llm";
-import { canOpenNativePath, nativeFileManager, openNativePath, revealNativePath } from "@deepseek-ai/dsh-native-command";
+import { canOpenNativePath, nativeFileApplications, nativeFileManager, openNativeAssociatedPath, openNativeFileApplication, revealNativePath } from "@deepseek-ai/dsh-native-command";
+import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { Remote, RemoteError, TypertRemoteService, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
 import { mkdir } from "node:fs/promises";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
-import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { randomUUID } from "node:crypto";
 import { brandString } from "@deepseek-ai/dsh-brand";
 import { AttachmentError } from "@deepseek-ai/dsh-attachment";
+import { buildForkSeed } from "@deepseek-ai/dsh-session/fork";
 import { SessionLogOffset, SessionSeq, isAppendSurfaceEvent } from "@deepseek-ai/dsh-session";
 import { SessionTitleInvalidError } from "@deepseek-ai/dsh-session-title";
 import { canonicalClientTimeZone } from "@deepseek-ai/dsh-util-time";
@@ -16,7 +18,6 @@ import { assertNever } from "@deepseek-ai/dsh-util-values";
 import { Deque } from "@deepseek-ai/dsh-deque";
 import { z as z$1 } from "zod";
 import { isUserInvocable } from "@deepseek-ai/dsh-skill";
-import { isAbsolute } from "node:path";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import mime from "mime-types";
 //#region lib/types/agent.js
@@ -550,6 +551,20 @@ var __disposeResources$3 = (function(SuppressedError) {
 function hasPromptContent(content) {
 	return content.some((part) => part.type !== "text" || part.text.trim().length > 0);
 }
+/**
+* Resolve the omitted-`atSeq` default to the latest completed-turn prefix,
+* including standalone events before the next turn begins.
+*/
+function latestCompletedPrefixBoundary(events) {
+	const lastTurnEnd = events.findLast((event) => event.type === "turn/end");
+	if (lastTurnEnd === void 0) return void 0;
+	let boundary = lastTurnEnd.seq;
+	for (const next of events.slice(boundary + 1)) {
+		if (next.type === "turn/start" || next.type === "user/message" && next.surfaceOp === "append" || next.type === "agent/inbox/spliced") break;
+		boundary = next.seq;
+	}
+	return boundary;
+}
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 var SessionCommandController = class {
 	ctx;
@@ -655,8 +670,10 @@ var SessionCommandController = class {
 		}
 	}
 	/**
-	* Create a new ordinary Session from one completed-turn prefix.
-	* @param request - source Session and optional event anchor.
+	* Create a new ordinary Session from an exact event prefix. An explicit
+	* `atSeq` is the inclusive cut; an omitted value selects the latest
+	* completed-turn prefix. An open cut receives synthetic fork closers.
+	* @param request - source Session and optional exact event boundary.
 	* @returns the new Session identity.
 	*/
 	async fork(request) {
@@ -680,10 +697,9 @@ var SessionCommandController = class {
 				throw new RemoteError("gateway/internal", `fork source unavailable for session "${request.sessionId}": ${String(error)}`, {});
 			}
 			const source = __addDisposableResource$3(env_1, observed, false);
-			const lastSeq = source.events.at(-1)?.seq ?? -1;
-			const boundary = (atSeq === void 0 ? void 0 : source.events.find((event) => event.type === "turn/end" && event.seq >= atSeq)) ?? (atSeq === void 0 || atSeq > lastSeq ? source.events.findLast((event) => event.type === "turn/end") : void 0);
-			if (boundary === void 0) throw new RemoteError("session/fork-unavailable", atSeq !== void 0 && atSeq <= lastSeq ? `session "${request.sessionId}" has not completed the turn containing event ${String(atSeq)}` : `session "${request.sessionId}" has no completed turn to fork from`, { sessionId: request.sessionId });
-			const cut = SessionLogOffset(boundary.seq + 1);
+			const boundary = atSeq ?? latestCompletedPrefixBoundary(source.events);
+			if (boundary === void 0 || source.events[boundary]?.seq !== boundary) throw new RemoteError("session/fork-unavailable", request.atSeq === void 0 ? `session "${request.sessionId}" has no completed turn to fork from` : `event ${String(request.atSeq)} does not exist in session "${request.sessionId}" (last seq: ${String(source.events.at(-1)?.seq ?? "none")})`, { sessionId: request.sessionId });
+			const seed = buildForkSeed(source.events, boundary);
 			let workspace;
 			try {
 				workspace = await this.forkWorkspace(source.header);
@@ -696,8 +712,8 @@ var SessionCommandController = class {
 				const { provider, model } = this.ctx.agentDefaultModel.currentSelection();
 				await this.ctx.agents.create({
 					sessionId: childId,
-					seed: source.events.slice(0, cut),
-					inheritedEventCount: cut,
+					seed,
+					inheritedEventCount: SessionLogOffset(boundary + 1),
 					meta: {
 						...source.header.cwd === void 0 ? {} : { cwd: source.header.cwd },
 						parentSession: source.header.id,
@@ -891,6 +907,7 @@ var SessionCommandController = class {
 	}
 	rejectCreation(sessionId, error) {
 		if (remoteErrorOf(error) !== void 0) 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,
@@ -966,23 +983,39 @@ function imageBlockIn(content, match) {
 			const ref = block.attachment;
 			if (match(ref)) return ref;
 		}
-		if (block.type === "tool-result") {
-			const nested = imageBlockIn(block.content, match);
-			if (nested !== void 0) return nested;
-		}
 	}
 }
+/** Read only first-party declared content fields; unknown event payloads stay opaque. */
 function imageInEvent(event, match) {
 	const data = event.data;
-	const direct = imageBlockIn(data.content, match);
-	if (direct !== void 0) return direct;
-	const message = imageBlockIn(data.message?.content, match);
-	if (message !== void 0) return message;
-	for (const inserted of data.inserted ?? []) {
-		const found = imageBlockIn(inserted.content, match);
-		if (found !== void 0) return found;
+	switch (event.type) {
+		case "user/message":
+		case "tool/ptc-dispatch": return imageBlockIn(data.content, match);
+		case "system/message":
+		case "developer/message":
+		case "tool/result":
+		case "team/message/queued": return imageBlockIn(data.message?.content, match);
+		case "agent/inbox/spliced": {
+			const messages = data.inserted;
+			if (!Array.isArray(messages)) return void 0;
+			for (const message of messages) {
+				if (typeof message !== "object" || message === null || Array.isArray(message)) continue;
+				const found = imageBlockIn(message.content, match);
+				if (found !== void 0) return found;
+			}
+			return;
+		}
+		case "compaction/summary": return imageBlockIn(data.summary, match) ?? imageBlockIn(data.rawOutput, match);
+		case "assistant/message": {
+			const found = imageBlockIn(data.message?.content, match);
+			if (found !== void 0) return found;
+			break;
+		}
+		case "assistant/attempt": break;
+		default: return;
 	}
-	if (event.type === "assistant/message" || event.type === "assistant/attempt") for (const chunk of assistantStreamChunks(event.data.stream, "block-end")) {
+	const assistant = event;
+	for (const chunk of assistantStreamChunks(assistant.data.stream, "block-end")) {
 		const found = imageBlockIn([chunk.block], match);
 		if (found !== void 0) return found;
 	}
@@ -998,12 +1031,12 @@ function routeServed(ctx, provider) {
 }
 //#endregion
 //#region lib/types/control.js
-/** Live Session jobs and projection state with reconnect baselines. */
+/** Live Session projection state with reconnect baselines. */
 /** Owns the Host-wide Session control stream. */
 var SessionControlController = class {
 	ctx;
 	streams = /* @__PURE__ */ new Set();
-	/** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+	/** @param ctx - Host context carrying live Agent and projection services. */
 	constructor(ctx) {
 		this.ctx = ctx;
 		ctx.sessionProjections.onChanged((session, key, value, seq) => {
@@ -1015,19 +1048,6 @@ var SessionControlController = class {
 				seq
 			});
 		});
-		ctx.inject(["jobs"], (jobsCtx) => {
-			jobsCtx.jobs.onJobsChanged((owner) => {
-				this.onJobsChanged(owner);
-			});
-		});
-		ctx.on("session/created", (session) => {
-			const jobs = this.jobsFor(this.ctx.agents.get(session.id));
-			if (jobs.length > 0) this.broadcast({
-				type: "jobs",
-				sessionId: session.id,
-				jobs
-			});
-		});
 		ctx.effect(() => () => {
 			for (const stream of this.streams) stream.end();
 			this.streams.clear();
@@ -1055,15 +1075,7 @@ var SessionControlController = class {
 	}
 	baseline() {
 		const sessions = this.ctx.sessions.list();
-		const jobs = Object.create(null);
-		for (const session of sessions) {
-			const agent = this.ctx.agents.get(session.id);
-			jobs[session.id] = this.jobsFor(agent);
-		}
-		return {
-			jobs,
-			projections: this.projectionBaseline(sessions)
-		};
+		return { projections: this.projectionBaseline(sessions) };
 	}
 	projectionBaseline(sessions) {
 		const blocks = Object.create(null);
@@ -1076,25 +1088,6 @@ var SessionControlController = class {
 		}
 		return blocks;
 	}
-	onJobsChanged(owner) {
-		if (owner !== void 0) {
-			this.broadcast({
-				type: "jobs",
-				sessionId: owner.id,
-				jobs: this.jobsFor(owner)
-			});
-			return;
-		}
-		for (const session of this.ctx.sessions.list()) this.broadcast({
-			type: "jobs",
-			sessionId: session.id,
-			jobs: this.jobsFor(this.ctx.agents.get(session.id))
-		});
-	}
-	jobsFor(agent) {
-		const jobs = this.ctx.get("jobs");
-		return jobs === void 0 ? [] : jobs.list(agent).map(jobView);
-	}
 	broadcast(frame) {
 		for (const stream of this.streams) stream.push(frame);
 	}
@@ -1140,17 +1133,6 @@ var ControlQueue = class {
 		}
 	}
 };
-function jobView(job) {
-	return {
-		id: job.id,
-		kind: job.kind,
-		label: job.label,
-		status: job.status,
-		...job.detail === void 0 ? {} : { detail: job.detail },
-		startedAt: job.startedAt,
-		...job.finishedAt === void 0 ? {} : { finishedAt: job.finishedAt }
-	};
-}
 //#endregion
 //#region lib/types/assistant-stream.js
 /** Process-local assistant state retained for reconnecting Web followers. */
@@ -1347,7 +1329,7 @@ var SessionHistoryController = class {
 			if (throughSeq > sourceCursor) throw new RemoteError("gateway/bad-request", `session page through seq ${String(throughSeq)} is past cursor ${String(sourceCursor)}`, {});
 			/* v8 ignore next -- Session and persistence validation guarantee a dense zero-based event prefix. */
 			if (throughSeq >= 0 && sourceLog[throughSeq]?.seq !== throughSeq) throw new RemoteError("gateway/internal", `session log does not contain through seq ${String(throughSeq)}`, {});
-			const page = paginate(sourceLog, beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, throughSeq);
+			const page = paginate(sourceLog, beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, throughSeq, request.turnWindow);
 			return {
 				records: pageRecords(page.events),
 				hasMore: page.hasMore
@@ -1366,7 +1348,7 @@ var SessionHistoryController = class {
 	* @returns a complete opening snapshot followed by gap-free durable events and opted-in assistant frames.
 	*/
 	async *follow(request, signal) {
-		validateFollowRequest(request);
+		validateHistoryWindow(request);
 		const { address } = request;
 		const target = addressId(address);
 		const buffered = new Deque();
@@ -1426,7 +1408,7 @@ var SessionHistoryController = class {
 				signal.throwIfAborted();
 				const cursor = source.cursor;
 				snapshotCursor = cursor;
-				const page = paginate(events, void 0, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
+				const page = paginate(events, void 0, request.maxMessages ?? DEFAULT_MAX_MESSAGES, cursor, request.turnWindow);
 				const assistantStream = request.assistantStream === true ? this.assistantStreams.get(target)?.snapshot() ?? { revision: 0 } : void 0;
 				const assistantStreamOrdinalCut = assistantStreamOrdinal;
 				yield {
@@ -1533,10 +1515,15 @@ function projectionBlock(snapshot) {
 function validatePageRequest(request) {
 	if (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1 || Object.is(request.throughSeq, -0)) throw new RemoteError("gateway/bad-request", "throughSeq must be an integer greater than or equal to -1", {});
 	if (request.beforeSeq !== void 0 && (!Number.isSafeInteger(request.beforeSeq) || request.beforeSeq < 0 || Object.is(request.beforeSeq, -0))) throw new RemoteError("gateway/bad-request", "beforeSeq must be a non-negative safe integer", {});
-	if (request.maxMessages !== void 0 && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) throw new RemoteError("gateway/bad-request", "maxMessages must be a positive safe integer", {});
+	validateHistoryWindow(request);
 }
-function validateFollowRequest(request) {
+function validateHistoryWindow(request) {
 	if (request.maxMessages !== void 0 && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) throw new RemoteError("gateway/bad-request", "maxMessages must be a positive safe integer", {});
+	const window = request.turnWindow;
+	if (window !== void 0) {
+		if (!Number.isSafeInteger(window.minMessages) || window.minMessages <= 0 || window.minMessages > (request.maxMessages ?? DEFAULT_MAX_MESSAGES)) throw new RemoteError("gateway/bad-request", "turnWindow.minMessages must be a positive safe integer no greater than maxMessages", {});
+		if (!Number.isSafeInteger(window.minTurns) || window.minTurns <= 0) throw new RemoteError("gateway/bad-request", "turnWindow.minTurns must be a positive safe integer", {});
+	}
 }
 function addressId(address) {
 	return address.kind === "session" ? address.sessionId : address.childSessionId;
@@ -1558,7 +1545,7 @@ function validateAddress(address, header, inheritedEventCount, projections) {
 		childSessionId: address.childSessionId,
 		reason: "unsupported"
 	});
-	if (identity.mode !== address.mode) throw new RemoteError("subagent/unauthorized", "subagent mode does not match the supplied address", { childSessionId: address.childSessionId });
+	if (address.mode !== "unknown" && identity.mode !== address.mode) throw new RemoteError("subagent/unauthorized", "subagent mode does not match the supplied address", { childSessionId: address.childSessionId });
 }
 function rejectNotFound(address) {
 	if (address.kind === "session") throw new RemoteError("session/not-found", `session "${address.sessionId}" not found`, { sessionId: address.sessionId });
@@ -1567,12 +1554,20 @@ function rejectNotFound(address) {
 		childSessionId: address.childSessionId
 	});
 }
-function paginate(events, beforeSeq, maxMessages, throughSeq = events.at(-1)?.seq ?? -1) {
+function paginate(events, beforeSeq, maxMessages, throughSeq, turnWindow) {
 	const end = SessionLogOffset(Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1));
 	let count = 0;
+	let turns = 0;
 	let cut = SessionLogOffset(0);
 	for (let index = end - 1; index >= 0; index--) {
 		const event = events[index];
+		if (turnWindow !== void 0 && event.type === "turn/start") {
+			turns++;
+			if (count >= turnWindow.minMessages && turns >= turnWindow.minTurns) {
+				cut = SessionLogOffset(index);
+				break;
+			}
+		}
 		if (!MESSAGE_TYPES$1.has(event.type) || !isAppendSurfaceEvent(event)) continue;
 		count++;
 		const sources = event.sourceEventSeqs;
@@ -1783,6 +1778,7 @@ var ApiSessionList = class {
 		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),
@@ -1819,6 +1815,7 @@ var ApiSessionList = class {
 		return {
 			sessionId: header.id,
 			updatedAt: updatedAt(header, metadata),
+			agentAvailable: false,
 			running: false,
 			blank: metadata?.blank ?? false,
 			...listFields(header),
@@ -1915,18 +1912,29 @@ var ApiSessionList = class {
 	}
 	projectionsFor(header, session) {
 		try {
+			if (session !== void 0) return hintsOf("sequenced", this.ctx.sessionProjections.cachedSnapshot(session));
 			const cache = this.ctx.get("sessionProjectionCache");
-			const block = session === void 0 ? header.isSeeded ? void 0 : cache?.cachedSnapshot(header, SessionLogOffset(0)) ?? cache?.cachedPredecessorTitle(header, SessionLogOffset(0)) : this.ctx.sessionProjections.cachedSnapshot(session);
-			return block !== void 0 && Object.keys(block.values).length > 0 ? {
-				asOfSeq: block.asOfSeq,
-				values: block.values
-			} : void 0;
+			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)}`);
 			return;
 		}
 	}
 };
+/**
+* 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 === void 0 || Object.keys(block.values).length === 0) return void 0;
+	return {
+		kind,
+		asOfSeq: block.asOfSeq,
+		values: block.values
+	};
+}
 function normalizeSearchQuery(query) {
 	const normalized = query.trim();
 	if (normalized.length === 0) throw new RemoteError("gateway/bad-request", "session search query must not be empty", {});
@@ -2211,59 +2219,71 @@ let SessionSkillCatalog = (() => {
 		* @throws RemoteError when the Session cannot be inspected or no registry can serve it.
 		*/
 		async list(request, 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
-				};
+				const { sessionId } = request;
+				let cwd;
+				let agentPreset;
 				try {
-					const observation = __addDisposableResource$1(env_1, await this.ctx.sessionQuery.observeSession(sessionId), false);
-					if (observation.projections === void 0) throw new Error("skill catalog requires a projected Session observation");
-					cwd = observation.header.cwd;
-					agentPreset = observation.projections.values.agentPreset ?? void 0;
-				} catch (e_1) {
-					env_1.error = e_1;
-					env_1.hasError = true;
-				} finally {
-					__disposeResources$1(env_1);
+					const env_2 = {
+						stack: [],
+						error: void 0,
+						hasError: false
+					};
+					try {
+						const observation = __addDisposableResource$1(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
+						if (observation.projections === void 0) throw new Error("skill catalog requires a projected Session observation");
+						cwd = observation.header.cwd;
+						agentPreset = observation.projections.values.agentPreset ?? void 0;
+					} catch (e_1) {
+						env_2.error = e_1;
+						env_2.hasError = true;
+					} finally {
+						__disposeResources$1(env_2);
+					}
+				} 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)}`, {});
 				}
-			} 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)}`, {});
-			}
-			if (cwd === void 0) 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 skillRegistry = (live === void 0 ? void 0 : presets?.serviceFor(live, "skills")) ?? this.ctx.get("skills");
-			if (skillRegistry === void 0) 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 {
-				return { skills: (await skillRegistry.list({
-					cwd,
-					scope
-				})).filter(isUserInvocable).map((skill) => ({
-					name: skill.name,
-					...skill.path === void 0 ? {} : { path: skill.path },
-					description: skill.description,
-					...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse },
-					modelInvocable: skill.invocation.modelInvocable
-				})) };
-			} catch (error) {
-				throw new RemoteError("gateway/internal", `skill listing failed: ${String(error)}`, {});
+				if (cwd === void 0) 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 skillRegistry = (live === void 0 ? void 0 : presets?.serviceFor(live, "skills")) ?? this.ctx.get("skills");
+				if (skillRegistry === void 0) 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$1(env_1, live === void 0 ? await this.scopeFor(agentPreset) : void 0, true);
+				const scope = live ?? lease?.key;
+				try {
+					return { skills: (await skillRegistry.list({
+						cwd,
+						scope
+					})).filter(isUserInvocable).map((skill) => ({
+						name: skill.name,
+						...skill.path === void 0 ? {} : { path: skill.path },
+						description: skill.description,
+						...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse },
+						modelInvocable: skill.invocation.modelInvocable
+					})) };
+				} catch (error) {
+					throw new RemoteError("gateway/internal", `skill listing failed: ${String(error)}`, {});
+				}
+			} catch (e_2) {
+				env_1.error = e_2;
+				env_1.hasError = true;
+			} finally {
+				const result_1 = __disposeResources$1(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 !== void 0) return live;
+		async scopeFor(agentPreset) {
 			const presets = this.ctx.get("agentPresets");
 			if (presets === void 0) return void 0;
 			try {
-				return await presets.standingKeyFor(agentPreset);
+				return await presets.acquireScope(agentPreset);
 			} catch {
 				return;
 			}
@@ -2344,6 +2364,58 @@ const SessionMediaReferences = {
 	}
 };
 //#endregion
+//#region lib/types/archived-session-gate.js
+/**
+* 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.
+*/
+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.
+*/
+function underArchivedSession(ctx, agent) {
+	const archived = ctx.workspaceRegistry.archivedSessionIds;
+	let header = agent.session.header;
+	const visited = /* @__PURE__ */ new Set();
+	while (!visited.has(header.id)) {
+		if (archived.includes(header.id)) return true;
+		visited.add(header.id);
+		if (header.origin !== "subagent" || header.parentSession === void 0) return false;
+		const parent = ctx.sessions.get(header.parentSession);
+		if (parent === void 0) return archived.includes(header.parentSession);
+		header = parent.header;
+	}
+	return false;
+}
+//#endregion
 //#region lib/types/index.js
 /** Session Remote owner: cold reads, explicit Agent commands, and live control state. */
 var __runInitializers = function(thisArg, initializers, value) {
@@ -2453,6 +2525,7 @@ let SessionController = (() => {
 	let _modelCatalog_decorators;
 	let _canOpenWorkspacePath_decorators;
 	let _openWorkspacePath_decorators;
+	let _workspacePathApplications_decorators;
 	let _rename_decorators;
 	let _fork_decorators;
 	let _prompt_decorators;
@@ -2461,6 +2534,7 @@ let SessionController = (() => {
 	let _cancel_decorators;
 	let _page_decorators;
 	let _follow_decorators;
+	let _projections_decorators;
 	let _control_decorators;
 	return class SessionController extends _classSuper {
 		static {
@@ -2472,6 +2546,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")];
@@ -2480,6 +2555,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",
@@ -2558,6 +2634,17 @@ let SessionController = (() => {
 				},
 				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",
@@ -2646,6 +2733,17 @@ let SessionController = (() => {
 				},
 				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",
@@ -2669,6 +2767,7 @@ let SessionController = (() => {
 			"agents",
 			"attachments",
 			"fileUploads",
+			"fs",
 			"llm",
 			"sessions",
 			"sessionProjections",
@@ -2683,6 +2782,8 @@ let SessionController = (() => {
 		history;
 		listState;
 		openPath;
+		fileApplications;
+		openFileApplication;
 		revealPath;
 		canOpenPath;
 		promotions = /* @__PURE__ */ new Set();
@@ -2709,18 +2810,26 @@ let SessionController = (() => {
 				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 !== void 0 || canOpenNativePath()));
 			ctx.plugin(SessionFileReferences);
 			ctx.plugin(SessionMediaReferences);
 			ctx.plugin(SessionSkillCatalog);
+			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");
 			});
@@ -2846,24 +2955,53 @@ let SessionController = (() => {
 			};
 		}
 		/**
-		* 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 {
-				if (request.action === "reveal") await this.revealPath(request.path, signal);
-				else await this.openPath(request.path, signal);
+				const path = await this.verifyDesktopPath(request.path, signal);
+				if (request.action === "reveal") await this.revealPath(path, signal);
+				else if (request.application !== void 0) await this.openFileApplication(path, request.application, signal);
+				else 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 === void 0 || 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.
 		* @param request - Session identity and proposed title.
@@ -2873,8 +3011,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) {
@@ -2934,6 +3074,41 @@ let SessionController = (() => {
 			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 projections = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId, { signal }), false).projections;
+					if (projections === void 0) 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.
 		* @returns one complete baseline followed by live replacement frames.