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

package/README.i18n.yaml

@@ -15,8 +15,8 @@
   en: 1fdf707322fb6996
   zh: 0204f7e9d4aa3cce
 /session-controller/use-this-package:
-  en: 77552723167e5d8e
-  zh: 1d77a657c707190a
+  en: d26a58a8f2406cd5
+  zh: 82135eceb9adb628
 /session-controller/client-references:
   en: 41bdda1ac32df558
   zh: aa5d0e325924066b

package/README.md

@@ -31,7 +31,9 @@ History pages and follow opening snapshots carry one `{ type: 'event', event: Se
 
 The Client journal validates current Session event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provider metadata, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host.
 
-Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` reads one complete baseline through a live-preferred Session observation without activating an Agent. It returns null for a missing Session and serves any registered projection keys. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Initial reads and live projection frames use the same sequence ordering.
+Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent's effective working directory and scoped registry when present. Cold listing uses the projected current directory, falling back to the recorded origin and then the configured directory default. It retains the preset standing scope without activating an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` normally reads an exact baseline, including current-format cold logs, and returns `kind: sequenced`. Only a read requiring migration returns `kind: migration-required` hints without `asOfSeq`; missing keys remain absent. It returns null for a missing Session. Fork callers may set `allowMigration: false` to receive `session/migration-required` instead of starting source migration; omission retains automatic migration. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Sequenced reads and live projection frames use the same sequence ordering; cached reads fill hints without replacing sequenced values.
+
+List rows carry `formatStatus` when available, so Clients can identify migration-required Sessions without requesting their projections.
 
 Host list generation yields between complete rows only when its configured work slice is exhausted; cheap remaining work returns without a forced yield. Request cancellation is checked per row and after each yield and rejects without partial results. Each row is synchronous; the list does not promise one cross-Session snapshot. A Session already queued as cold remains a cached row if it attaches during a yield: Client in-flight mutation replay corrects its availability, and sequenced projections supersede cached hints.
 

package/README.zh.md

@@ -31,7 +31,9 @@ kind: "package-reference"
 
 Client journal 在发布 follow 快照、live entry 或历史页之前验证当前 Session 事件 envelope。它复用浏览器安全的 Session validator，检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 提供方元数据、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败，不删除字段或归一化；范围成员与来源存在性仍由 Host 的持久日志检查。
 
-每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 通过一次 live-preferred Session observation 读取完整基线，不激活 Agent。Session 不存在时返回 null，并可提供任意已注册的 projection key。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。初始读取与实时 projection 帧使用相同的序号排序规则。
+每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent 的有效工作目录与限定范围内的注册表。冷态列表使用投影中的当前目录，依次回退到记录的起始目录与配置的默认目录。它保留 preset 常驻 scope，不会激活 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 正常读取准确基线，包括当前格式的冷日志，返回 `kind: sequenced`。只有需要迁移时才返回不带 `asOfSeq` 的 `kind: migration-required` 提示，缺少的键保持缺席。Session 不存在时返回 null。Fork 调用者可设置 `allowMigration: false`，在源历史需要迁移时收到 `session/migration-required`；省略则保持自动迁移。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。有序读取与实时 projection 帧使用相同的序号排序规则；缓存读取只补充提示，不替换有序值。
+
+列表行在状态可用时携带 `formatStatus`，Client 无需请求其投影即可识别需要迁移的 Session。
 
 Host 仅在配置的工作时间片耗尽时，于完整条目之间让出事件循环；剩余工作较少时直接返回，不强制让出。每行及每次让出之后检查请求取消，取消时拒绝返回部分结果。每行同步计算；列表不承诺跨 Session 的统一快照。已经进入冷态队列的 Session 若在让出期间接入，仍返回缓存行：Client 对进行中请求的变更重放会纠正其可用性，带序号的投影会覆盖缓存提示。
 

package/lib/client.js

@@ -193,6 +193,7 @@ window.__ModuleLoader__.load({
 			"turn/start",
 			"user/message",
 			"web/deepseek-search-llm-request",
+			"working-directory/change",
 			"workspace/changes"
 		]);
 		//#endregion
@@ -1616,7 +1617,7 @@ window.__ModuleLoader__.load({
 				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
@@ -3011,20 +3012,28 @@ window.__ModuleLoader__.load({
 			}
 			/**
 			* 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);
 				if (retained !== void 0) return retained;
 				for (const parentSessionId of this.projectionStores.keys()) {
 					const child = this.projectionStores.get(parentSessionId)?.values().subagentCatalog?.find((entry) => entry.id === sessionId);
-					if (child !== void 0) return {
+					if (child !== void 0 && child.mode !== "external") return {
 						parentSessionId,
 						childSessionId: sessionId,
 						mode: child.mode
 					};
 				}
+				const summary = this.summaries.find((summary) => summary.sessionId === sessionId);
+				if (summary?.origin !== "subagent" || summary.parentSessionId === void 0) return void 0;
+				return {
+					parentSessionId: summary.parentSessionId,
+					childSessionId: sessionId,
+					mode: "unknown"
+				};
 			}
 			/**
 			* Withdraw an exact Client instance before running its teardown callbacks.
@@ -3090,7 +3099,8 @@ window.__ModuleLoader__.load({
 						session.handleRunning(summary.running);
 					} else {
 						const address = this.addresses.get(sessionId);
-						if ((address === void 0 ? void 0 : this.projectionStores.get(address.parentSessionId)?.values().subagentCatalog?.find((entry) => entry.id === sessionId)) !== void 0) {
+						const child = address === void 0 ? void 0 : this.projectionStores.get(address.parentSessionId)?.values().subagentCatalog?.find((entry) => entry.id === sessionId);
+						if (child !== void 0 && child.mode !== "external") {
 							session.handleBlank(false);
 							session.handleRunning(false);
 						} else session.handleBlank(true);
@@ -3158,7 +3168,7 @@ window.__ModuleLoader__.load({
 				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.
 			*/
@@ -3179,13 +3189,22 @@ window.__ModuleLoader__.load({
 						const result = await this.remote.session.projections({ sessionId }, controller.signal);
 						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) store.clear();
 							this.projectionLoads.set(sessionId, {
-								state: "ready",
+								state: value?.kind === "migration-required" ? "migration-required" : "ready",
 								error: null
 							});
 						} else this.projectionLoads.set(sessionId, {
@@ -3340,14 +3359,15 @@ window.__ModuleLoader__.load({
 			* 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) {
 				const source = this.summaries.find((s) => s.sessionId === opts.sessionId);
 				const result = await this.remote.session.fork({
 					sessionId: opts.sessionId,
-					...opts.atSeq === void 0 ? {} : { atSeq: opts.atSeq }
+					...opts.atSeq === void 0 ? {} : { atSeq: opts.atSeq },
+					...opts.allowMigration === void 0 ? {} : { allowMigration: opts.allowMigration }
 				});
 				const childId = result.ok ? result.value.sessionId : workspaceAttachSessionId(result.error);
 				if (childId !== void 0) this.recordMutation({
@@ -3572,7 +3592,7 @@ window.__ModuleLoader__.load({
 					};
 				})).map((entry) => {
 					const prev = this.entryCache.get(entry.sessionId);
-					if (prev !== void 0 && prev.updatedAt === entry.updatedAt && prev.running === entry.running && prev.blank === entry.blank && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd && prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth && prev.projectionValues === entry.projectionValues) return prev;
+					if (prev !== void 0 && prev.updatedAt === entry.updatedAt && prev.running === entry.running && prev.blank === entry.blank && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd && prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth && prev.formatStatus === entry.formatStatus && prev.projectionValues === entry.projectionValues) return prev;
 					this.entryCache.set(entry.sessionId, entry);
 					return entry;
 				});
@@ -3605,13 +3625,14 @@ window.__ModuleLoader__.load({
 						blank: existing.blank && mutation.summary.blank,
 						...mutation.kind === "upsert" ? {
 							agentAvailable: mutation.summary.agentAvailable,
-							running: mutation.summary.running
+							running: mutation.summary.running,
+							...mutation.summary.formatStatus === void 0 ? {} : { formatStatus: mutation.summary.formatStatus }
 						} : {},
 						...existing.cwd === void 0 && mutation.summary.cwd !== void 0 ? { cwd: mutation.summary.cwd } : {},
 						...existing.parentSessionId === void 0 && mutation.summary.parentSessionId !== void 0 ? { parentSessionId: mutation.summary.parentSessionId } : {},
 						...existing.origin === void 0 && mutation.summary.origin !== void 0 ? { origin: mutation.summary.origin } : {}
 					};
-					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) return [...summaries];
+					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.formatStatus === existing.formatStatus) return [...summaries];
 					return summaries.map((summary) => summary.sessionId === mutation.summary.sessionId ? filled : summary);
 				}
 				case "remove": return summaries.filter((summary) => summary.sessionId !== mutation.sessionId);
@@ -3861,13 +3882,13 @@ window.__ModuleLoader__.load({
 			* 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) {
@@ -3957,7 +3978,7 @@ window.__ModuleLoader__.load({
 			*   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.
@@ -3966,7 +3987,8 @@ window.__ModuleLoader__.load({
 				const sourceTitle = opts.increaseTitle ? this.list.getSnapshot().byId[opts.sessionId]?.title : void 0;
 				const result = await this.manager.fork({
 					sessionId: opts.sessionId,
-					...opts.atSeq === void 0 ? {} : { atSeq: SessionSeq(opts.atSeq) }
+					...opts.atSeq === void 0 ? {} : { atSeq: SessionSeq(opts.atSeq) },
+					...opts.allowMigration === void 0 ? {} : { allowMigration: opts.allowMigration }
 				});
 				if (!result.ok) throw new SessionForkError(result.error, opts.sessionId);
 				this.projectList();
@@ -4130,6 +4152,7 @@ window.__ModuleLoader__.load({
 						retainedBy: this.retentionSnapshot(entry.sessionId).retainedBy,
 						blank: entry.blank,
 						updatedAt: entry.updatedAt,
+						formatStatus: entry.formatStatus,
 						...entry.projectionValues === void 0 ? {} : { projectionValues: entry.projectionValues },
 						...entry.title !== void 0 ? { title: entry.title } : {},
 						...entry.cwd !== void 0 ? { cwd: entry.cwd } : {},
@@ -4138,6 +4161,7 @@ window.__ModuleLoader__.load({
 					};
 				}
 				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/index.js

@@ -1881,6 +1881,7 @@ var ApiSessionList = class {
 			sessionId: session.id,
 			updatedAt: updatedAt(session.header, metadata),
 			agentAvailable: this.ctx.agents.get(session.id)?.session === session,
+			formatStatus: "current",
 			running: this.ctx.agents.get(session.id)?.status === "running",
 			blank: metadata?.blank ?? session.seq === 0,
 			...listFields(session.header),
@@ -1903,16 +1904,16 @@ var ApiSessionList = class {
 			signal?.throwIfAborted();
 			const live = this.ctx.sessions.get(record.header.id);
 			if (live !== void 0) items.push(this.summaryFor(live));
-			else if (record.header.cwd !== void 0) cold.push(record.header);
+			else if (record.header.cwd !== void 0) cold.push(record);
 			if (performance.now() >= yieldDeadline) {
 				await scheduler.yield();
 				signal?.throwIfAborted();
 				yieldDeadline = performance.now() + this.workSliceMs;
 			}
 		}
-		for (const header of cold) {
+		for (const record of cold) {
 			signal?.throwIfAborted();
-			items.push(this.summarizeCold(header));
+			items.push(this.summarizeCold(record));
 			if (performance.now() >= yieldDeadline) {
 				await scheduler.yield();
 				signal?.throwIfAborted();
@@ -1923,13 +1924,14 @@ var ApiSessionList = class {
 		items.sort((left, right) => right.updatedAt - left.updatedAt);
 		return items;
 	}
-	summarizeCold(header) {
+	summarizeCold({ header, formatStatus }) {
 		const projections = this.projectionsFor(header, void 0);
 		const metadata = projections?.values.sessionListMetadata;
 		return {
 			sessionId: header.id,
 			updatedAt: updatedAt(header, metadata),
 			agentAvailable: false,
+			...formatStatus === void 0 ? {} : { formatStatus },
 			running: false,
 			blank: metadata?.blank ?? false,
 			...listFields(header),
@@ -2261,7 +2263,8 @@ let SessionSkillCatalog = (() => {
 		static inject = [
 			"agents",
 			"sessionQuery",
-			"typert"
+			"typert",
+			"workingDirectory"
 		];
 		/** @param ctx - Host context carrying Session reads and optional skill/preset services. */
 		constructor(ctx) {
@@ -2294,8 +2297,10 @@ let SessionSkillCatalog = (() => {
 					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;
+						cwd = observation.projections.values.workingDirectory ?? observation.header.cwd ?? this.ctx.workingDirectory.defaultDirectory;
 						agentPreset = observation.projections.values.agentPreset ?? void 0;
+						const live = this.ctx.agents.get(sessionId);
+						if (live !== void 0) cwd = await this.ctx.workingDirectory.ensure(live, signal);
 					} catch (e_1) {
 						env_2.error = e_1;
 						env_2.hasError = true;
@@ -2306,7 +2311,6 @@ let SessionSkillCatalog = (() => {
 					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");
@@ -3104,10 +3108,13 @@ let SessionController = (() => {
 		* 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) {
+		async fork(request) {
+			if (request.allowMigration === false && this.ctx.sessions.get(request.sessionId) === void 0) {
+				if ((await this.ctx.get("sessionPersistence")?.stat(request.sessionId))?.formatStatus === "migration-required" && this.ctx.sessions.get(request.sessionId) === void 0) throw new RemoteError("session/migration-required", "Open the source Session to complete migration before forking", { sessionId: request.sessionId });
+			}
 			return this.commands.fork(request);
 		}
 		/**
@@ -3164,10 +3171,10 @@ let SessionController = (() => {
 			return this.history.follow(request, signal);
 		}
 		/**
-		* 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.
 		*/
 		async projections(request, signal) {
 			const { sessionId } = request;
@@ -3179,9 +3186,22 @@ let SessionController = (() => {
 					hasError: false
 				};
 				try {
+					signal.throwIfAborted();
+					const live = this.liveProjections(sessionId);
+					if (live !== void 0) return live;
+					const stored = await this.ctx.get("sessionPersistence")?.stat(sessionId, { signal });
+					signal.throwIfAborted();
+					const attached = this.liveProjections(sessionId);
+					if (attached !== void 0) return attached;
+					if (stored === void 0) return null;
+					if (stored.formatStatus === "migration-required") return {
+						kind: "migration-required",
+						values: { ...(this.ctx.get("sessionProjectionCache")?.cachedSnapshot(stored.header))?.values }
+					};
 					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 {
+						kind: "sequenced",
 						asOfSeq: projections.asOfSeq,
 						values: projections.values
 					};
@@ -3192,12 +3212,22 @@ let SessionController = (() => {
 					__disposeResources(env_2);
 				}
 			} catch (error) {
-				if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") return null;
+				if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") return this.liveProjections(sessionId) ?? 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 });
 			}
 		}
+		liveProjections(sessionId) {
+			const session = this.ctx.sessions.get(sessionId);
+			if (session === void 0) return void 0;
+			const snapshot = this.ctx.sessionProjections.snapshot(session);
+			return {
+				kind: "sequenced",
+				asOfSeq: snapshot.asOfSeq,
+				values: snapshot.values
+			};
+		}
 		/**
 		* Stream a complete live-control baseline followed by replacement frames.
 		* @param signal - cancellation owned by the Remote stream carrier.