lark-remote 0.5.8 → 0.5.9

package/dist/bridge/queue-manager.js

@@ -568,7 +568,7 @@ export class QueueManager {
                     ...this.buildQueueActionButtons(cwd, messageId, true),
                 ],
             });
-            await this.updateCard(cardMessageId, card);
+            await this.updateCardWithRetry(cardMessageId, card);
             getLogger().debug(`[queue-manager] queue card updated to executing messageId=${messageId}`);
         }
         catch (err) {
@@ -597,9 +597,9 @@ export class QueueManager {
             taskList.splice(index, 1);
         }
         this.indexRemove(cwd, messageId);
-        // Note: queueCardMessages mapping is NOT deleted here.
-        // The caller (handleQueueCancel) will call updateQueueCardToCancelled
-        // which will clean up the mapping after updating the card.
+        // queueCardMessages mapping 仍不在这里删：卡片更新由 Bridge.removeFromQueue
+        // 统一触发（单一收口），updateQueueCardToCancelled 成功/失败后都会清掉映射。
+        // 直接调 QueueManager.removeFromQueue 的测试/内部用途不会自动更新卡片。
         getLogger().info(`[queue-manager] removed from queue cwd=${cwd} messageId=${messageId}`);
         return true;
     }
@@ -626,7 +626,7 @@ export class QueueManager {
             ],
         });
         try {
-            await this.updateCard(cardMessageId, card);
+            await this.updateCardWithRetry(cardMessageId, card);
             getLogger().debug(`[queue-manager] queue card updated to cancelled, messageId=${messageId}`);
         }
         catch (err) {
@@ -636,6 +636,21 @@ export class QueueManager {
             this.queueCardMessages.delete(messageId);
         }
     }
+    /**
+     * 卡片 PATCH 带一次重试：一次网络抖动不该让排队卡永久停在旧状态——映射
+     * 会在本次调用结束时被清理，之后没有任何自动修正机会。
+     * 第二次仍失败则向上抛，由调用方 catch 记日志（行为与改前一致）。
+     */
+    async updateCardWithRetry(messageId, card) {
+        try {
+            await this.updateCard(messageId, card);
+            return;
+        }
+        catch (err) {
+            getLogger().warn(`[queue-manager] queue card update failed, retrying once messageId=${messageId}: ${err.message}`);
+        }
+        await this.updateCard(messageId, card);
+    }
     /** Get task metadata from queue. */
     getQueuedTask(cwd, messageId) {
         // O(1) index lookup instead of array `find`.

package/dist/card/card-shared.js

@@ -22,6 +22,8 @@ const TERMINAL_LABELS = {
     idle_timeout: '已超时',
     running: '运行中',
     finalizing: '完成中',
+    // 本轮结束、goal 仍 active：任务没结束，标签不能说"完成"。
+    goal_continuing: '目标继续',
 };
 export function terminalToLabel(terminal) {
     return TERMINAL_LABELS[terminal] ?? '运行中';
@@ -37,6 +39,8 @@ export function terminalToColor(terminal) {
         return 'orange';
     if (terminal === 'finalizing')
         return 'orange';
+    if (terminal === 'goal_continuing')
+        return 'orange';
     if (terminal === 'running')
         return 'blue';
     return 'red';

package/dist/card/run-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { RunState, ToolEntry } from './run-state.js';
+import { type RunState, type ToolEntry } from './run-state.js';
 export interface RunCardRenderOptions {
     /**
      * Agent kind for the run card header title (e.g. "Claude · 思考中").
@@ -12,6 +12,13 @@ export interface RunCardRenderOptions {
      * 无 turn_started → operationKind undefined）同样能拿到按钮。
      */
     compactSupported?: boolean;
+    /**
+     * 卡片没有 `state.sessionId` 时，是否仍有可压缩的会话（bridge 在开跑前从
+     * sessionStore 探到的会话）。`false` 表示「本轮没有 init，之前也没有任何
+     * 会话」——此时 Compact 按钮点了必然反查不到记录，不渲染。缺省（undefined）
+     * 保持原有「按钮可见」语义，供渲染层独立调用方使用。
+     */
+    sessionFallbackAvailable?: boolean;
 }
 type BlockGroup = {
     kind: 'thinking';

package/dist/card/run-renderer.js

@@ -1,10 +1,11 @@
+import { isRunTerminal, } from './run-state.js';
 import { terminalToColor, terminalToLabel, newSessionButton, stopButton, compactButton, cardButton, agentDisplayName, } from './card-shared.js';
 import { collapsibleMarkdownPanel, markdownDiv } from './collapsible.js';
 import { toolBodyMd, toolHeaderText } from './tool-render.js';
 import { truncateMarkdownTables, CARD_BUDGET_BYTES } from './text-truncate.js';
 import { truncateUtf8 } from '../common/truncate.js';
 import { countCardElements, MAX_CARD_ELEMENTS } from './card-budget.js';
-import { displayWidth } from '../common/text-width.js';
+import { displayWidth, truncateToDisplayWidth } from '../common/text-width.js';
 import { isContentFilterFailure } from '../common/turn-failure.js';
 import { formatClock, formatTimestamp } from './time.js';
 import { formatUsageStats } from '../router/usage-format.js';
@@ -45,10 +46,75 @@ function shouldShowCompactButton(state, options) {
         return false;
     if (options.compactSupported === false)
         return false;
-    return (state.terminal === 'done' ||
-        state.terminal === 'error' ||
-        state.terminal === 'interrupted' ||
-        state.terminal === 'idle_timeout');
+    // 没有可反查的会话 = 点了必然失败：「/stop 落在 init 之前」的那类卡
+    // 上会留一个注定回「该任务已结束」的死按钮。本轮 sessionId 优先；没有时看
+    // bridge 在开跑前探到的 store 会话（`sessionFallbackAvailable`，缺省视为可用
+    // 以保持渲染层独立调用方的既有语义）。
+    if (!state.sessionId && options.sessionFallbackAvailable === false)
+        return false;
+    // goal 仍 active = 宿主会自动起下一轮，会话永远不 idle，压缩必被拒（DSH 的
+    // 手动压缩要求 agent 空闲）。给按钮就是给一个注定失败的点击：用户点
+    // compact 只会拿到"还有一轮在跑"。
+    if (state.goal?.phase === 'active')
+        return false;
+    return isRunTerminal(state.terminal);
+}
+/**
+ * goal 区块：目标是什么、跑到第几轮、当前什么状态。
+ *
+ * 为什么放在状态行下面（而不是摘要区）：手机上用户只会扫前两屏。goal 是解释
+ * "这轮为什么结束却没收尾/为什么不能压缩"的唯一线索，必须靠前。
+ *
+ * 窄屏约束：每行一个 div，段间用 ` · `，不做 auto+grow 并排。
+ */
+const GOAL_INLINE_WIDTH = 64;
+const GOAL_FULL_MAX_BYTES = 2_400;
+/** 目标阶段的短标签。 */
+function goalPhaseLabel(goal) {
+    if (goal.phase === 'active')
+        return '目标进行中';
+    if (goal.phase === 'paused')
+        return '目标已暂停';
+    if (goal.phase === 'blocked')
+        return '目标被阻断';
+    return '目标已完成';
+}
+/**
+ * Build the goal block (empty when the session has no goal).
+ *
+ * 状态来源是宿主的 `goal` 投影/`goal/change`，不是桥的推断：把"我这一轮结束
+ * 了"当任务结束，就是"卡片写完成、任务还在跑"那类缺陷的来源。
+ */
+function buildGoalSection(state) {
+    const goal = state.goal;
+    if (!goal)
+        return [];
+    const elements = [];
+    const round = `第 ${goal.roundsStarted}/${goal.maxGoalRounds} 轮`;
+    elements.push(markdownDiv(`🎯 **${goalPhaseLabel(goal)}** · ${round}`));
+    // 目标全文可能有换行/超长：行内压成单行并截断，全文进折叠面板。
+    const singleLine = goal.objective.replace(/\s+/gu, ' ').trim();
+    const inline = displayWidth(singleLine) <= GOAL_INLINE_WIDTH
+        ? singleLine
+        : truncateToDisplayWidth(singleLine, GOAL_INLINE_WIDTH);
+    elements.push(markdownDiv(`目标：${inline}`, 'notation'));
+    if (inline !== singleLine) {
+        elements.push(collapsibleMarkdownPanel({
+            title: '🎯 目标全文',
+            expanded: false,
+            border: 'grey',
+            content: truncateUtf8(goal.objective, GOAL_FULL_MAX_BYTES),
+            textSize: 'notation',
+        }));
+    }
+    if (goal.phase === 'blocked' && goal.blockedReason) {
+        elements.push(markdownDiv(`⛔ 阻断：${goal.blockedReason.code} — ${goal.blockedReason.message}`, 'notation'));
+    }
+    if (goal.phase === 'active' && state.terminal === 'goal_continuing') {
+        // 这句话就是整张卡的核心信息：本轮结束 ≠ 任务结束。
+        elements.push(markdownDiv(`_本轮已结束；DSH 会自动开始第 ${goal.roundsStarted + 1} 轮_`, 'notation'));
+    }
+    return elements;
 }
 /**
  * Wrap text block in a collapsible panel with timestamp in the header.
@@ -397,9 +463,22 @@ function assembleRunCard(state, options, elements) {
             template: headerTemplate(state),
             title: { content: headerTitle(state, options), tag: 'plain_text' },
         },
-        body: { elements },
+        // goal 区块紧随状态行（所有预算档位都以此为第一元素），让"目标是什么/
+        // 第几轮"出现在折叠面板之前；它只有 2–3 个元素，兜底档位也扛得住。
+        body: { elements: insertAfterStatusRow(elements, buildGoalSection(state)) },
     };
 }
+/**
+ * 把目标区块插到状态行之后。所有预算档位的 elements 都以 statusRow 开头；
+ * 空数组时原样返回，避免把 `undefined` 塞进飞书卡片数组。
+ */
+function insertAfterStatusRow(elements, extra) {
+    if (extra.length === 0)
+        return elements;
+    if (elements.length === 0)
+        return extra;
+    return [elements[0], ...extra, ...elements.slice(1)];
+}
 /**
  * Build a budget-fallback tier (degraded or extreme): keep the last N thinking
  * blocks and last N tools, truncate text/thinking per tier, then render in
@@ -964,7 +1043,14 @@ function buildSummaryContent(state, options = {}) {
             model: state.model,
             costUsd: state.costUsd,
             reasoningTokens: state.reasoningTokens,
-        }, { showResult: true, result });
+        }, {
+            showResult: true,
+            result,
+            // 本轮结束但目标继续：不能报"已完成"，也不能说"出错"。
+            ...(state.terminal === 'goal_continuing'
+                ? { completedLabel: '⏳ 本轮结束 · 目标仍在继续' }
+                : {}),
+        });
         elements.push(markdownDiv(usageStatsStr + empty));
         // 后台任务：跨 turn 生命周期，必须显式告知并可逐个停止。
         elements.push(...buildBackgroundJobsSection(state));
@@ -1086,8 +1172,13 @@ function statusTagLabel(terminal) {
 /** CardKit 2.0 header title — agent-aware via options.agentKind. */
 function headerTitle(state, options = {}) {
     const agent = agentDisplayName(options.agentKind ?? 'claude');
-    if (state.terminal === 'done')
-        return `✅ ${agent} · 已完成`;
+    // 本轮 turn 结束但 goal 仍 active：这是"一轮结束"，不是"任务完成"。标题
+    // 必须说清楚，否则用户会以为活儿干完了。
+    if (state.terminal === 'goal_continuing')
+        return `⏳ ${agent} · 本轮结束（目标继续）`;
+    if (state.terminal === 'done') {
+        return state.goal?.phase === 'complete' ? `✅ ${agent} · 目标已完成` : `✅ ${agent} · 已完成`;
+    }
     if (state.terminal === 'error')
         return `⚠️ ${agent} · 出错`;
     if (state.terminal === 'interrupted')

package/dist/card/run-state.d.ts

@@ -1,5 +1,22 @@
-import type { AgentEvent, ApprovalView, ToolHint } from '../runner/index.js';
-export type RunTerminal = 'running' | 'finalizing' | 'done' | 'error' | 'interrupted' | 'idle_timeout';
+import type { AgentEvent, ApprovalView, ToolHint, GoalView } from '../runner/index.js';
+export type RunTerminal = 'running' | 'finalizing' | 'done' | 'error' | 'interrupted' | 'idle_timeout'
+/**
+ * 本轮 turn 已结束，但会话的 goal 仍 active：宿主会自动开始下一轮，任务没有
+ * 完成，卡片不得写"完成"。与 done 的差别只在语义与渲染，
+ * 卡片同样停止更新。
+ */
+ | 'goal_continuing';
+/**
+ * 已收尾的 run 终态集合（卡片不再更新）。
+ *
+ * 单一来源：事件消费守卫、可压缩记账白名单、Compact 按钮可见性三处共用，
+ * 禁止各自再抄一份字面量——三处漂移过一次（goal_continuing 只进白名单不进
+ * 按钮判据），新增终态时必漏一处的风险是结构性的。
+ */
+export declare const RUN_TERMINAL_STATES: readonly ["done", "error", "interrupted", "idle_timeout", "goal_continuing"];
+export type RunFinalTerminal = (typeof RUN_TERMINAL_STATES)[number];
+/** 该状态是否已收尾（非 running/finalizing）。 */
+export declare function isRunTerminal(terminal: RunTerminal): terminal is RunFinalTerminal;
 export type RunFooter = 'thinking' | 'tool_running' | 'streaming' | null;
 /** 中断来源（interrupted 终态的原因），供卡片如实归因。 */
 export type InterruptedReason = 'approval_timeout' | 'user_stop' | 'approval_cancelled';
@@ -161,6 +178,16 @@ export interface RunState {
         status?: string;
         progress?: string;
     }>;
+    /**
+     * 会话级长期目标（DSH goal）。跨 turn 生命周期：goal 仍 active 时，本轮结束
+     * 只是"一轮结束"，宿主会自动续跑，卡片必须显示目标是什么、跑到第几轮。
+     */
+    goal?: GoalView;
+    /**
+     * goal 是否被成功观测过。`false` = 探测失败，渲染层不得据此断言"没有目标/
+     * 已完成"（把读不到当成没有，就退回了"任务在跑、卡片写完成"的旧缺陷）。
+     */
+    goalKnown?: boolean;
 }
 export interface FinishMeta {
     resultSubtype?: 'success' | 'error' | 'interrupted';

package/dist/card/run-state.js

@@ -3,6 +3,24 @@ const MAX_REASONING_CHARS = 4_000;
 const MAX_TEXT_CHARS = 12_000;
 const MAX_TOOL_DETAIL_CHARS = 3_000;
 const MAX_BLOCKS = 24;
+/**
+ * 已收尾的 run 终态集合（卡片不再更新）。
+ *
+ * 单一来源：事件消费守卫、可压缩记账白名单、Compact 按钮可见性三处共用，
+ * 禁止各自再抄一份字面量——三处漂移过一次（goal_continuing 只进白名单不进
+ * 按钮判据），新增终态时必漏一处的风险是结构性的。
+ */
+export const RUN_TERMINAL_STATES = [
+    'done',
+    'error',
+    'interrupted',
+    'idle_timeout',
+    'goal_continuing',
+];
+/** 该状态是否已收尾（非 running/finalizing）。 */
+export function isRunTerminal(terminal) {
+    return RUN_TERMINAL_STATES.includes(terminal);
+}
 export function createInitialRunState(runId) {
     return {
         runId,
@@ -17,16 +35,17 @@ export function reduceRunState(state, event) {
     // 只有终态才阻止事件处理。finalizing 是非终态，
     // 仍需累积 assistant 内容（thinking、text、tool_use、后台任务输出）。
     const terminal = state.terminal;
-    if (terminal === 'done' ||
-        terminal === 'error' ||
-        terminal === 'interrupted' ||
-        terminal === 'idle_timeout') {
+    if (isRunTerminal(terminal)) {
         return state;
     }
     if (event.type === 'system')
         return reduceSystemEvent(state, event);
     if (event.type === 'run_status')
         return reduceRunStatusEvent(state, event);
+    if (event.type === 'goal_state') {
+        // 覆盖写：每次观测都是宿主的整份快照（phase/轮次/目标全文），不做增量。
+        return { ...state, goal: event.goal ?? undefined, goalKnown: event.known };
+    }
     if (event.type === 'background_jobs')
         return reduceBackgroundJobsEvent(state, event);
     if (event.type === 'result')

package/dist/index.js

@@ -532,16 +532,17 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         const content = router.expandAliasMessage(msg.content);
         if (isStopCommand(content)) {
             void (async () => {
-                const stopped = await bridge.interruptCurrentRun({
+                const interrupt = await bridge.interruptCurrentRunDetailed({
                     userId: msg.userId,
                     chatId: msg.chatId,
                 });
-                if (!stopped) {
-                    await bridge.sendResult({ text: '当前没有运行中的进程' }, {
-                        userId: msg.userId,
-                        chatId: msg.chatId,
-                        messageId: msg.messageId,
-                    });
+                const ctx = { userId: msg.userId, chatId: msg.chatId, messageId: msg.messageId };
+                if (!interrupt.stopped) {
+                    await bridge.sendResult({ text: '当前没有运行中的进程' }, ctx);
+                }
+                else if ((interrupt.stoppedCount ?? 1) > 1) {
+                    // 并行 workspace 时 /stop 停全部，必须让用户看到数量。
+                    await bridge.sendResult({ text: `✅ 已停止 ${interrupt.stoppedCount} 个运行中的任务` }, ctx);
                 }
             })().catch((err) => logger.error('[control] /stop failed:', err));
             return;

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 {
@@ -866,7 +865,6 @@ export class CommandRouter {
         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
@@ -874,20 +872,15 @@ export class CommandRouter {
         // 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++;
-                removedIds.push(task.messageId);
             }
         }
         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:
@@ -2491,6 +2484,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 +2626,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 +3537,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/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;