lark-remote 0.5.8 → 0.5.10

package/dist/router/index.js

@@ -783,9 +783,8 @@ export class CommandRouter {
         const { cwd, messageId } = payload;
         const removed = this.bridge.removeFromQueue(cwd, messageId);
         if (removed) {
-            // Update the queue card in-place to "cancelled" state
-            await this.bridge.updateQueueCardToCancelled(cwd, messageId);
-            // Send a brief confirmation (user can see the card has been updated)
+            // 队列卡的「已撤销」更新由 removeFromQueue 统一触发（单一收口）；
+            // 这里只负责给点击者一个即时反馈。
             await this.bridge.sendResult({ text: '✅ 已从队列中撤销' }, ctx);
         }
         else {
@@ -823,134 +822,143 @@ export class CommandRouter {
             await this.bridge.sendResult({ text: '⚠️ 正在压缩会话，消息将在压缩完成后按顺序执行。' }, ctx);
             return;
         }
-        // 1.5. If the user edited the message, the original closure (captured at
-        // enqueue time with stale content) must NOT run. Register a one-shot
-        // replacement closure on the task's EXISTING queue slot BEFORE any await:
-        // interruptCurrentRun / markQueueCardExecuting can let the chain advance to
-        // this task's begin, and begin consumes the replacement at that point — a
-        // registration after those awaits would arrive too late (the stale closure
-        // runs and the replacement leaks as a permanent dead closure). Registering
-        // on the existing slot (instead of removeFromQueue + re-enqueue) preserves
-        // the queue position: enqueue can only append to the promise chain tail,
-        // which would put the edited task behind tasks queued after it.
-        if (targetTask.editedMessage) {
-            const editedContent = targetTask.editedMessage;
-            ///Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
-            // cwdOverride（lane cwd 同源）。否则编辑后重新执行的 run 会丢 cwd 与绑定。
-            this.bridge.setTaskReplacement(cwd, messageId, async () => {
-                await this.handle(editedContent, ctx, {
-                    cwdOverride: cwd,
-                    binding: targetTask.binding,
+        // 1.4. Hold the target's run-card start until this handler has sent its
+        // final feedback. The queue chain can advance during the awaits below
+        // (interruptCurrentRun / the queue-card PATCH): the target may begin and
+        // call forwardToClaude before the toast is sent. Without this hold the
+        // run card would land first, leaving the toast as the newest message —
+        // the chat list then previews the toast instead of the run card's title
+        // (which is how the user follows a run without opening the conversation).
+        // Registered before any await, released in finally on every exit path;
+        // forwardToClaude waits for it before creating the run card.
+        const releaseRunStart = this.bridge.holdQueueTaskRun(cwd, messageId);
+        try {
+            // 1.5. If the user edited the message, the original closure (captured at
+            // enqueue time with stale content) must NOT run. Register a one-shot
+            // replacement closure on the task's EXISTING queue slot BEFORE any await:
+            // interruptCurrentRun / markQueueCardExecuting can let the chain advance to
+            // this task's begin, and begin consumes the replacement at that point — a
+            // registration after those awaits would arrive too late (the stale closure
+            // runs and the replacement leaks as a permanent dead closure). Registering
+            // on the existing slot (instead of removeFromQueue + re-enqueue) preserves
+            // the queue position: enqueue can only append to the promise chain tail,
+            // which would put the edited task behind tasks queued after it.
+            if (targetTask.editedMessage) {
+                const editedContent = targetTask.editedMessage;
+                ///Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
+                // cwdOverride（lane cwd 同源）。否则编辑后重新执行的 run 会丢 cwd 与绑定。
+                this.bridge.setTaskReplacement(cwd, messageId, async () => {
+                    await this.handle(editedContent, ctx, {
+                        cwdOverride: cwd,
+                        binding: targetTask.binding,
+                    });
                 });
+            }
+            // 2. Stop current running process
+            // (Note: queue executing count is reset inside Bridge.interruptCurrentRun
+            //  so all stop paths — /stop, /t, card stop, queue.immediate — are covered.)
+            const interrupt = await this.bridge.interruptCurrentRunDetailed({
+                userId: ctx.userId,
+                chatId: ctx.chatId,
+                cwd,
             });
-        }
-        // 2. Stop current running process
-        // (Note: queue executing count is reset inside Bridge.interruptCurrentRun
-        //  so all stop paths — /stop, /t, card stop, queue.immediate — are covered.)
-        const interrupt = await this.bridge.interruptCurrentRunDetailed({
-            userId: ctx.userId,
-            chatId: ctx.chatId,
-            cwd,
-        });
-        const stopped = interrupt.stopped;
-        // A remote (DSH) stop is only a request; when it cannot be confirmed the
-        // target must not be promised "immediate" execution — its prompt would sit
-        // behind the still-running turn with no visible progress.
-        const stopUnconfirmed = interrupt.stop?.status === 'unconfirmed';
-        getLogger().info(`[router] queue.immediate: stopped=${stopped} unconfirmed=${stopUnconfirmed}`);
-        // 3. Remove all tasks BEFORE this one (by position in the current queue).
-        // The target may have begun while interruptCurrentRun was awaiting (the chain
-        // advances concurrently): then it is already out of the snapshot and every
-        // remaining queued task is BEHIND it — clearing must stop, not run off the
-        // end and delete tasks queued after the target.
-        const tasks = this.bridge.getQueuedTasks(cwd);
-        const targetIdx = tasks.findIndex((t) => t.messageId === messageId);
-        let removedCount = 0;
-        const removedIds = [];
-        // Phase 1: remove synchronously. The queue chain advances on any await
-        // (card PATCH round trips included), so every task before the target must
-        // be removed before yielding to the event loop — otherwise a task the user
-        // asked to clear can begin executing while its cancellation card is still
-        // in flight.
-        for (let i = 0; i < targetIdx; i++) {
-            const task = tasks[i];
-            if (this.bridge.removeFromQueue(cwd, task.messageId)) {
-                removedCount++;
-                removedIds.push(task.messageId);
+            const stopped = interrupt.stopped;
+            // A remote (DSH) stop is only a request; when it cannot be confirmed the
+            // target must not be promised "immediate" execution — its prompt would sit
+            // behind the still-running turn with no visible progress.
+            const stopUnconfirmed = interrupt.stop?.status === 'unconfirmed';
+            getLogger().info(`[router] queue.immediate: stopped=${stopped} unconfirmed=${stopUnconfirmed}`);
+            // 3. Remove all tasks BEFORE this one (by position in the current queue).
+            // The target may have begun while interruptCurrentRun was awaiting (the chain
+            // advances concurrently): then it is already out of the snapshot and every
+            // remaining queued task is BEHIND it — clearing must stop, not run off the
+            // end and delete tasks queued after the target.
+            const tasks = this.bridge.getQueuedTasks(cwd);
+            const targetIdx = tasks.findIndex((t) => t.messageId === messageId);
+            let removedCount = 0;
+            // Phase 1: remove synchronously. The queue chain advances on any await
+            // (card PATCH round trips included), so every task before the target must
+            // be removed before yielding to the event loop — otherwise a task the user
+            // asked to clear can begin executing while its cancellation card is still
+            // in flight.
+            for (let i = 0; i < targetIdx; i++) {
+                const task = tasks[i];
+                // 撤销卡片由 removeFromQueue 统一触发（fire-and-forget），保持本循环
+                // 同步推进的既有不变式。
+                if (this.bridge.removeFromQueue(cwd, task.messageId)) {
+                    removedCount++;
+                }
             }
-        }
-        if (targetIdx < 0) {
-            getLogger().debug(`[router] queue.immediate: target no longer queued (began/cancelled), not clearing tasks behind it`);
-        }
-        // Phase 2: update cancelled cards after all removals. All tasks before the
-        // target are already gone, so any chain advance can only reach the target
-        // itself — the card updates may safely run in the background.
-        for (const removedId of removedIds) {
-            void this.bridge.updateQueueCardToCancelled(cwd, removedId);
-        }
-        // 4. DO NOT remove the target task - keep it in queue to execute immediately
-        // The queue will naturally execute it after the current task (which we just stopped)
-        // 4.4. Refresh the replacement with the latest edited content (idempotent:
-        // re-registering over the same slot). Covers the user editing the message
-        // again while interruptCurrentRun was awaiting; skipped automatically once
-        // the task has begun, because getQueuedTask then returns undefined.
-        const latestTask = this.bridge.getQueuedTask(cwd, messageId);
-        if (latestTask?.editedMessage) {
-            const editedContent = latestTask.editedMessage;
-            ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
-            this.bridge.setTaskReplacement(cwd, messageId, async () => {
-                await this.handle(editedContent, ctx, {
-                    cwdOverride: cwd,
-                    binding: latestTask.binding,
+            if (targetIdx < 0) {
+                getLogger().debug(`[router] queue.immediate: target no longer queued (began/cancelled), not clearing tasks behind it`);
+            }
+            // 4. DO NOT remove the target task - keep it in queue to execute immediately
+            // The queue will naturally execute it after the current task (which we just stopped)
+            // 4.4. Refresh the replacement with the latest edited content (idempotent:
+            // re-registering over the same slot). Covers the user editing the message
+            // again while interruptCurrentRun was awaiting; skipped automatically once
+            // the task has begun, because getQueuedTask then returns undefined.
+            const latestTask = this.bridge.getQueuedTask(cwd, messageId);
+            if (latestTask?.editedMessage) {
+                const editedContent = latestTask.editedMessage;
+                ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
+                this.bridge.setTaskReplacement(cwd, messageId, async () => {
+                    await this.handle(editedContent, ctx, {
+                        cwdOverride: cwd,
+                        binding: latestTask.binding,
+                    });
                 });
-            });
-        }
-        // 4.5/6. The target must only be marked executing (and the toast may only
-        // promise immediate execution) when it is really the next task after the
-        // stop. While interruptCurrentRun was awaiting, a task ahead of the target
-        // may have begun and now occupy the cwd — the target is still queued
-        // but is NOT next, so its card must stay queued and the toast must say so.
-        const targetStillQueued = this.bridge.getQueuedTask(cwd, messageId) !== undefined;
-        if (!targetStillQueued) {
-            // The target began or was cancelled while earlier awaits were in flight —
-            // a success toast must never promise execution of a task that will not
-            // run. The two missing-reason states get distinct feedback: a target
-            // that began while the interrupt was in flight is already executing, so
-            // the toast must acknowledge that instead of telling the user nothing
-            // was scheduled; only a target that was actually cancelled (never began)
-            // gets the "未安排执行" wording.
-            if (this.bridge.hasTaskBegan(messageId)) {
-                await this.bridge.sendResult({ text: `ℹ️ 目标消息已开始执行，无需重复操作。已清除 ${removedCount} 条排队消息。` }, ctx);
+            }
+            // 4.5/6. The target must only be marked executing (and the toast may only
+            // promise immediate execution) when it is really the next task after the
+            // stop. While interruptCurrentRun was awaiting, a task ahead of the target
+            // may have begun and now occupy the cwd — the target is still queued
+            // but is NOT next, so its card must stay queued and the toast must say so.
+            const targetStillQueued = this.bridge.getQueuedTask(cwd, messageId) !== undefined;
+            if (!targetStillQueued) {
+                // The target began or was cancelled while earlier awaits were in flight —
+                // a success toast must never promise execution of a task that will not
+                // run. The two missing-reason states get distinct feedback: a target
+                // that began while the interrupt was in flight is already executing, so
+                // the toast must acknowledge that instead of telling the user nothing
+                // was scheduled; only a target that was actually cancelled (never began)
+                // gets the "未安排执行" wording.
+                if (this.bridge.hasTaskBegan(messageId)) {
+                    await this.bridge.sendResult({ text: `ℹ️ 目标消息已开始执行，无需重复操作。已清除 ${removedCount} 条排队消息。` }, ctx);
+                }
+                else {
+                    await this.bridge.sendResult({
+                        text: `⚠️ 目标消息已不在队列中（可能已被撤销），未安排执行。已清除 ${removedCount} 条排队消息。`,
+                    }, ctx);
+                }
+                return;
+            }
+            const workspaceBusy = this.bridge.isBusyFor(cwd);
+            if (stopUnconfirmed) {
+                const name = interrupt.agentKind ? agentDisplayName(interrupt.agentKind) : 'agent';
+                await this.bridge.sendResult({
+                    text: `⚠️ 未能确认 ${name} 的 turn 已停止，它可能仍在后台运行。\n` +
+                        `已清除 ${removedCount} 条排队消息；您的消息已提交，但可能要等该 turn 结束后才开始。`,
+                }, ctx);
+            }
+            else if (!workspaceBusy) {
+                // Normal path: nothing new began during the stop, the target is next.
+                // Mark its own card as executing now so buttons grey out immediately.
+                // Done BEFORE any removal so getQueuedTask still returns the task with
+                // its (possibly edited) messagePreview for the card. The queue callback's
+                // later updateQueueCardToExecuting call becomes a no-op (idempotent).
+                await this.bridge.markQueueCardExecuting(cwd, messageId);
+                const stopPrefix = stopped ? '⚡ 已停止当前任务，' : '';
+                await this.bridge.sendResult({ text: `${stopPrefix}清除了 ${removedCount} 条排队消息。您的消息将立即执行。` }, ctx);
             }
             else {
                 await this.bridge.sendResult({
-                    text: `⚠️ 目标消息已不在队列中（可能已被撤销），未安排执行。已清除 ${removedCount} 条排队消息。`,
+                    text: `⚠️ 排在目标之前的任务已开始执行，目标消息保持排队。已清除 ${removedCount} 条排队消息。`,
                 }, ctx);
             }
-            return;
         }
-        const workspaceBusy = this.bridge.isBusyFor(cwd);
-        if (stopUnconfirmed) {
-            const name = interrupt.agentKind ? agentDisplayName(interrupt.agentKind) : 'agent';
-            await this.bridge.sendResult({
-                text: `⚠️ 未能确认 ${name} 的 turn 已停止，它可能仍在后台运行。\n` +
-                    `已清除 ${removedCount} 条排队消息；您的消息已提交，但可能要等该 turn 结束后才开始。`,
-            }, ctx);
-        }
-        else if (!workspaceBusy) {
-            // Normal path: nothing new began during the stop, the target is next.
-            // Mark its own card as executing now so buttons grey out immediately.
-            // Done BEFORE any removal so getQueuedTask still returns the task with
-            // its (possibly edited) messagePreview for the card. The queue callback's
-            // later updateQueueCardToExecuting call becomes a no-op (idempotent).
-            await this.bridge.markQueueCardExecuting(cwd, messageId);
-            const stopPrefix = stopped ? '⚡ 已停止当前任务，' : '';
-            await this.bridge.sendResult({ text: `${stopPrefix}清除了 ${removedCount} 条排队消息。您的消息将立即执行。` }, ctx);
-        }
-        else {
-            await this.bridge.sendResult({
-                text: `⚠️ 排在目标之前的任务已开始执行，目标消息保持排队。已清除 ${removedCount} 条排队消息。`,
-            }, ctx);
+        finally {
+            releaseRunStart();
         }
     }
     /**
@@ -2491,6 +2499,11 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     '请在 DSH Web UI 检查；需要终止时再发一次 /stop。',
             };
         }
+        // 多个 workspace 并行时 /stop 会停掉全部；把这件事说出来，避免用户以为
+        // 只停了当前那个（旧实现只停一条且无提示）。
+        const count = interrupt.stoppedCount ?? 1;
+        if (count > 1)
+            return { text: `✅ 已停止 ${count} 个运行中的任务` };
         return null;
     }
     async cmdExit() {
@@ -2628,6 +2641,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             activeRun.terminal !== 'error' &&
             activeRun.terminal !== 'interrupted' &&
             activeRun.terminal !== 'idle_timeout' &&
+            activeRun.terminal !== 'goal_continuing' &&
             activeRun.sessionId === sessionId;
         const activeUsage = activeRunUsage(activeRun);
         return {
@@ -3538,9 +3552,10 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         const prefetchCount = Math.min(RESUME_CONTENT_PREFETCH, allSessions.length);
         for (const s of allSessions.slice(0, prefetchCount)) {
             // 行上已经带了服务端投影预览（DSH：title + turnOutline 末条）→ 跳过预取。
-            // DSH 的 readSessionContent 是 3 个 curl 加一次 maxMessages=10000 的
-            // session/page；一页 5 个会话按行预取等于 15 次同步 HTTP，而这些信息
-            // session/list 已经给全了。
+            // DSH 的 readSessionContent 每行走 3 次 unary：`session/list`（cwd 守卫）、
+            // `session/projections`（取 throughSeq）、再 `session/page`（maxMessages=10000，
+            // 拉整段历史）。按前 5 行预取等于 15 次同步 HTTP，而这些信息一次
+            // `session/list` 就已经给全了。
             if (s.title || s.lastUserMessage || s.lastAssistantMessage)
                 continue;
             // 优先走轻量摘要（只取标题/用量，不构造 events）——codex 实现了

package/dist/router/usage-format.d.ts

@@ -52,4 +52,9 @@ export declare function formatUsageStats(usage?: {
 }, options?: {
     showResult?: boolean;
     result?: string;
+    /**
+     * 首行状态文案。默认 `✅ 已完成`；goal 仍 active 的收尾卡必须换掉它——
+     * 本轮 turn 结束不等于任务结束。
+     */
+    completedLabel?: string;
 }): string;

package/dist/router/usage-format.js

@@ -40,7 +40,7 @@ function formatTokenK(n) {
 export function formatUsageStats(usage, options) {
     const lines = [];
     // 1. Success 状态（通用格式，无具体结果值）
-    lines.push('✅ 已完成');
+    lines.push(options?.completedLabel ?? '✅ 已完成');
     // 1.4. 实际生效模型（非空字符串才显示）
     if (usage?.model) {
         lines.push(`Model - ${usage.model}`);

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -147,6 +147,12 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
      *
      * `idleTtlMs: 0` = 不回收（与 claude 会话层的 `armIdleTimer` 同口径；按 0
      * setTimeout 会秒删刚建好的连接，等于每条消息重起一次进程）。
+     *
+     * 定时器回调带 **slot 身份校验**：武装之后 slot 可能已被替换——进程自退走
+     * baseOnClose（删 slot 但不经过 disposeSlot）、或同 cwd 已 acquire 了新连接。
+     * 这两种情况下本定时器都已过期，不得回收「当时恰好挂在该 cwd 上」的连接：
+     * 2026-10-24 线上事故即一条泄漏的过期 TTL 杀掉继任连接的在途 turn，卡片
+     * 误报 "Codex app-server connection closed"。
      */
     notifyIdle(cwd: string): void;
     private createClient;

package/dist/runner/common/jsonrpc/connection-manager.js

@@ -183,18 +183,27 @@ export class ConnectionManager {
      *
      * `idleTtlMs: 0` = 不回收（与 claude 会话层的 `armIdleTimer` 同口径；按 0
      * setTimeout 会秒删刚建好的连接，等于每条消息重起一次进程）。
+     *
+     * 定时器回调带 **slot 身份校验**：武装之后 slot 可能已被替换——进程自退走
+     * baseOnClose（删 slot 但不经过 disposeSlot）、或同 cwd 已 acquire 了新连接。
+     * 这两种情况下本定时器都已过期，不得回收「当时恰好挂在该 cwd 上」的连接：
+     * 2026-10-24 线上事故即一条泄漏的过期 TTL 杀掉继任连接的在途 turn，卡片
+     * 误报 "Codex app-server connection closed"。
      */
     notifyIdle(cwd) {
         if (this.idleTtlMs <= 0)
             return;
         const slot = this.slots.get(cwd);
-        if (slot) {
-            this.clearIdleTimer(slot);
-            slot.idleTimer = setTimeout(() => {
-                getLogger().info(`[${this.logTag}] idle timeout for cwd=${cwd}, releasing connection`);
-                this.disposeSlot(cwd);
-            }, this.idleTtlMs);
-        }
+        if (!slot)
+            return;
+        this.clearIdleTimer(slot);
+        slot.idleTimer = setTimeout(() => {
+            slot.idleTimer = null;
+            if (this.slots.get(cwd) !== slot)
+                return;
+            getLogger().info(`[${this.logTag}] idle timeout for cwd=${cwd}, releasing connection`);
+            this.disposeSlot(cwd);
+        }, this.idleTtlMs);
     }
     // =========================================================================
     // Internal
@@ -222,7 +231,13 @@ export class ConnectionManager {
                 getLogger().info(`[${this.logTag}] connection closed cwd=${cwd}`);
                 // 只清理自己创建的 slot：并发 release + 重新 acquire 后 slot 可能已被
                 // 新连接占据，误删会破坏新连接。
-                if (this.slots.get(cwd)?.client === client) {
+                const current = this.slots.get(cwd);
+                if (current?.client === client) {
+                    // 进程自退（codex app-server 偶发 exit 0，非本程序发起，不经
+                    // disposeSlot）也要撤掉挂在旧 slot 上的 idle TTL：定时器不随 slot
+                    // 删除而取消，到期时会按 cwd 误杀继任连接的在途 turn（2026-10-24
+                    // 线上事故，见 notifyIdle 的身份校验与对应回归测试）。
+                    this.clearIdleTimer(current);
                     this.slots.delete(cwd);
                     this.onConnectionLost?.(cwd);
                 }

package/dist/runner/dsh/client.d.ts

@@ -20,6 +20,7 @@
  * replay, and seq-based dedup.
  */
 import type { DshApprovalStreamItem, DshCommandResult, DshModelCatalogValue, DshModelSelection, DshOpenTurnState, DshPermissionCatalogValue, DshJobView, DshPresetListValue, DshProjectionItem, DshProjectionSnapshot, DshQuestion, DshRemoteEventOutcome, DshSessionPageValue, DshStreamItem, DshTokenUsage } from './types.js';
+import type { GoalView } from '../types.js';
 interface WebSocketMessageEvent {
     data: unknown;
 }
@@ -193,6 +194,20 @@ export declare class DshClient {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<DshProjectionSnapshot | null>;
+    /**
+     * Read the session's current goal (one unary, authoritative at call time).
+     *
+     * 收尾判定必须用宿主状态：本轮 turn 结束不代表任务结束——goal 仍 active 时
+     * driver 会在 quiescence 立刻起下一轮。`known:false` 表示读不到，调用方不得
+     * 据此断言"已完成"（探测失败降级为收尾，正是"任务还在跑却写完成"的来源）。
+     */
+    goalState(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        known: boolean;
+        goal: GoalView | null;
+    }>;
     /**
      * Find this run's prompt if it is still sitting in the host's inbox.
      *

package/dist/runner/dsh/client.js

@@ -24,6 +24,7 @@ import WebSocket from 'ws';
 import { getLogger } from '../../logger/index.js';
 import { DSH_COOKIE_LIFETIME_MS, isDshCredentialsNotFound, mintDshBrowserCookie, readDshBrowserSecret, resolveDshCredentialsFile, } from './auth.js';
 import { DEFAULT_REQUEST_TIMEOUT_MS } from '../common/defaults.js';
+import { goalFromProjection } from './goal-view.js';
 function defaultWebSocketFactory(url, options) {
     const socket = new WebSocket(url, {
         ...(options?.headers ? { headers: options.headers } : {}),
@@ -449,6 +450,32 @@ export class DshClient {
                 : {},
         };
     }
+    /**
+     * Read the session's current goal (one unary, authoritative at call time).
+     *
+     * 收尾判定必须用宿主状态：本轮 turn 结束不代表任务结束——goal 仍 active 时
+     * driver 会在 quiescence 立刻起下一轮。`known:false` 表示读不到，调用方不得
+     * 据此断言"已完成"（探测失败降级为收尾，正是"任务还在跑却写完成"的来源）。
+     */
+    async goalState(sessionId, opts) {
+        let snapshot;
+        try {
+            snapshot = await this.projectionSnapshot(sessionId, opts);
+        }
+        catch (err) {
+            if (opts?.signal?.aborted)
+                throw err;
+            getLogger().warn(`[dsh] goal probe failed session=${sessionId}: ${err.message}`);
+            return { known: false, goal: null };
+        }
+        // 拿不到投影 = 宿主没这个会话的投影，不等于"没有 goal"。
+        if (!snapshot)
+            return { known: false, goal: null };
+        const parsed = goalFromProjection(snapshot.values.goal);
+        if (parsed === undefined)
+            return { known: false, goal: null };
+        return { known: true, goal: parsed };
+    }
     /**
      * Find this run's prompt if it is still sitting in the host's inbox.
      *

package/dist/runner/dsh/goal-view.d.ts

@@ -0,0 +1,36 @@
+/**
+ * DSH `goal` 域 → 卡片用的 {@link GoalView} 解析。
+ *
+ * 两个来源、同一个目标类型：
+ * 1. 投影值：`session/projections` 的 `values.goal` 与 `session/control` 的
+ *    `{key:'goal'}` 帧，宿主状态包一层 `current`（`{current:{goal,roundsStarted
+ *    ,createdAt,updatedAt},seenGoalIds,failure}`）；
+ * 2. 会话事件 `goal/change`：create/edit/pause/resume/complete/block 携带完整
+ *    snapshot + roundsStarted；clear 是墓碑，表示"现在没有 goal"。
+ *
+ * 解析失败返回 `undefined`，表示**读不懂**——它与"没有 goal"（`null`）必须区分：
+ * 把读不懂当成没有 goal，就会在 goal 还在自动续跑时收尾卡片。
+ */
+import type { GoalView } from '../types.js';
+/**
+ * 解析投影里的 goal 状态。
+ *
+ * @returns `GoalView` = 有 goal；`null` = 宿主明确没有 goal；`undefined` = 读不懂。
+ */
+export declare function goalFromProjection(value: unknown): GoalView | null | undefined;
+/**
+ * 解析 `goal/change` 事件 payload。
+ *
+ * @returns `GoalView` = 变更后的 goal；`null` = clear（现在没有 goal）；
+ *   `undefined` = 读不懂。
+ */
+export declare function goalFromChange(data: unknown): GoalView | null | undefined;
+/** 便利构造：把解析结果包成 runner 事件。 */
+export declare function goalStateEvent(goal: GoalView | null, known: boolean): {
+    type: 'goal_state';
+    goal: GoalView | null;
+    known: boolean;
+    timestamp: string;
+};
+/** 两次观测是否等价（用于抑制重复帧，不触发重渲染）。 */
+export declare function sameGoal(a: GoalView | null | undefined, b: GoalView | null | undefined): boolean;

package/dist/runner/dsh/goal-view.js

@@ -0,0 +1,106 @@
+/**
+ * DSH `goal` 域 → 卡片用的 {@link GoalView} 解析。
+ *
+ * 两个来源、同一个目标类型：
+ * 1. 投影值：`session/projections` 的 `values.goal` 与 `session/control` 的
+ *    `{key:'goal'}` 帧，宿主状态包一层 `current`（`{current:{goal,roundsStarted
+ *    ,createdAt,updatedAt},seenGoalIds,failure}`）；
+ * 2. 会话事件 `goal/change`：create/edit/pause/resume/complete/block 携带完整
+ *    snapshot + roundsStarted；clear 是墓碑，表示"现在没有 goal"。
+ *
+ * 解析失败返回 `undefined`，表示**读不懂**——它与"没有 goal"（`null`）必须区分：
+ * 把读不懂当成没有 goal，就会在 goal 还在自动续跑时收尾卡片。
+ */
+const PHASES = new Set(['active', 'paused', 'blocked', 'complete']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonNegativeInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function parseSnapshot(value, roundsStarted) {
+    if (!isRecord(value))
+        return undefined;
+    const phase = value.phase;
+    if (typeof phase !== 'string' || !PHASES.has(phase))
+        return undefined;
+    if (typeof value.objective !== 'string')
+        return undefined;
+    if (typeof value.id !== 'string' || value.id.length === 0)
+        return undefined;
+    const max = nonNegativeInt(value.maxGoalRounds);
+    if (max === undefined)
+        return undefined;
+    const reason = value.blockedReason;
+    const blockedReason = isRecord(reason) && typeof reason.code === 'string' && typeof reason.message === 'string'
+        ? { code: reason.code, message: reason.message }
+        : undefined;
+    return {
+        id: value.id,
+        objective: value.objective,
+        // 上面已按白名单校验，这里收窄回联合类型。
+        phase: phase,
+        roundsStarted: nonNegativeInt(roundsStarted) ?? 0,
+        maxGoalRounds: max,
+        ...(blockedReason ? { blockedReason } : {}),
+    };
+}
+/**
+ * 解析投影里的 goal 状态。
+ *
+ * @returns `GoalView` = 有 goal；`null` = 宿主明确没有 goal；`undefined` = 读不懂。
+ */
+export function goalFromProjection(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    // 宿主状态信封：{current:{goal,roundsStarted,...}, seenGoalIds, failure}
+    if ('current' in value) {
+        const current = value.current;
+        if (current === null)
+            return null;
+        if (!isRecord(current))
+            return undefined;
+        if (current.goal === undefined || current.goal === null)
+            return null;
+        return parseSnapshot(current.goal, current.roundsStarted);
+    }
+    // 兼容直接投递 GoalProjection 的形态：{goal, roundsStarted, ...}
+    if (value.goal === undefined || value.goal === null)
+        return null;
+    return parseSnapshot(value.goal, value.roundsStarted);
+}
+/**
+ * 解析 `goal/change` 事件 payload。
+ *
+ * @returns `GoalView` = 变更后的 goal；`null` = clear（现在没有 goal）；
+ *   `undefined` = 读不懂。
+ */
+export function goalFromChange(data) {
+    if (!isRecord(data))
+        return undefined;
+    if (data.operation === 'clear')
+        return null;
+    if (typeof data.operation !== 'string')
+        return undefined;
+    return parseSnapshot(data.goal, data.roundsStarted);
+}
+/** 便利构造：把解析结果包成 runner 事件。 */
+export function goalStateEvent(goal, known) {
+    return { type: 'goal_state', goal, known, timestamp: new Date().toISOString() };
+}
+/** 两次观测是否等价（用于抑制重复帧，不触发重渲染）。 */
+export function sameGoal(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined)
+        return false;
+    return (a.id === b.id &&
+        a.phase === b.phase &&
+        a.roundsStarted === b.roundsStarted &&
+        a.maxGoalRounds === b.maxGoalRounds &&
+        a.objective === b.objective &&
+        a.blockedReason?.code === b.blockedReason?.code);
+}
+//# sourceMappingURL=goal-view.js.map