@xmanrui/dsh-im 4.34.1 → 4.35.0

package/src/channels/feishu/feishu-channel.mjs

@@ -80,12 +80,13 @@ function abortReason(signal) {
 }
 
 function operationTimeout(stage) {
-  const error = new Error(`Feishu file ${stage} timed out.`);
+  const error = new Error(`Feishu ${stage} timed out.`);
   error.code = 'provider-timeout';
   return error;
 }
 
-function waitForFileOperation(operation, { signal, timeoutMs, stage }) {
+// Bound the caller's wait even when the SDK does not honor cancellation.
+export function waitForFeishuOperation(operation, { signal, timeoutMs, stage = 'request' }) {
   signal?.throwIfAborted();
   const deadline = new AbortController();
   const operationSignal = signal
@@ -108,7 +109,10 @@ function waitForFileOperation(operation, { signal, timeoutMs, stage }) {
     const timer = setTimeout(() => deadline.abort(), timeoutMs);
     operationSignal.addEventListener('abort', onAbort, { once: true });
 
-    Promise.resolve().then(() => operation(operationSignal)).then(
+    Promise.resolve().then(() => {
+      operationSignal.throwIfAborted();
+      return operation(operationSignal);
+    }).then(
       (value) => finish(resolve, value),
       (error) => finish(reject, error),
     );
@@ -116,6 +120,10 @@ function waitForFileOperation(operation, { signal, timeoutMs, stage }) {
   });
 }
 
+function waitForFileOperation(operation, { stage, ...options }) {
+  return waitForFeishuOperation(operation, { ...options, stage: `file ${stage}` });
+}
+
 function deliveryUuid(file, chatId, messageType) {
   const seed = `${file.deliveryKey}\u0000${chatId}`;
   const digest = createHash('sha256')

package/src/channels/feishu/feishu-runtime.mjs

@@ -2,7 +2,7 @@ import { createConnectionDiagnostics, atConnectionStage } from '../shared/connec
 import { randomUUID } from 'node:crypto';
 import { FeishuHarnessBridge } from './bridge.mjs';
 import { cardActionProbeCard } from './feishu-cards.mjs';
-import { VerifiedFeishuChannel } from './feishu-channel.mjs';
+import { VerifiedFeishuChannel, waitForFeishuOperation } from './feishu-channel.mjs';
 import { normalizeFeishuGroupResponseMode } from './group-response-mode.mjs';
 import { normalizeFeishuStepPushMode } from './step-push-mode.mjs';
 import { createVoice } from './voice.mjs';
@@ -367,6 +367,7 @@ export class FeishuRuntime {
         voice: this.#voice,
         sessionSyncTargetsFor: this.#sessionSyncTargetsFor,
         repair: this.#repair,
+        requestTimeoutMs: this.#requestTimeoutMs,
         replyTimeoutMs: this.#replyTimeoutMs,
         // Interaction cards (approval/question buttons) are on by default.
         // Set DSH_IM_INTERACTION_CARDS=0 to fall back to plain-text replies.
@@ -674,7 +675,7 @@ export class FeishuRuntime {
     });
   }
 
-  async sendProactiveText(target, text, { signal, format = 'plain' } = {}) {
+  async sendProactiveText(target, text, { signal, format = 'plain', receipt = false } = {}) {
     if (!this.#status.ready || !this.#client) {
       const error = new Error('飞书机器人尚未连接');
       error.code = 'bot-not-connected';
@@ -697,26 +698,40 @@ export class FeishuRuntime {
       error.code = 'bad-request';
       throw error;
     }
+    if (typeof receipt !== 'boolean' || (receipt && target.kind !== 'group'))
+      throw Object.assign(new Error('capability-unavailable'), { code: 'capability-unavailable' });
     signal?.throwIfAborted();
     // Use the same native Markdown element as chat, without opening a stream
     // or retrying as plain text after a possibly accepted delivery.
     const content = format === 'markdown'
       ? { schema: '2.0', body: { elements: [{ tag: 'markdown', content: text }] } }
       : { text };
-    const response = await this.#client.im.v1.message.create({
+    const activeSignal = signal
+      ? AbortSignal.any([signal, this.#abortController.signal])
+      : this.#abortController.signal;
+    const response = await waitForFeishuOperation(() => this.#client.im.v1.message.create({
       params: { receive_id_type: receiveIdType },
       data: {
         receive_id: receiveId,
         msg_type: format === 'markdown' ? 'interactive' : 'text',
         content: JSON.stringify(content),
       },
+    }), {
+      signal: activeSignal,
+      timeoutMs: this.#requestTimeoutMs,
+      stage: `proactive text send (${this.#requestTimeoutMs}ms)`,
     });
     if (response?.code && response.code !== 0) {
       const error = new Error(`Feishu proactive delivery failed: ${response.msg || response.code}`);
       error.code = 'target-rejected';
       throw error;
     }
-    return { sent: true };
+    if (!receipt) return { sent: true };
+    const messageId = response?.data?.message_id;
+    const conversationId = response?.data?.chat_id;
+    if (typeof messageId !== 'string' || !messageId || messageId.length > 512 || conversationId !== receiveId)
+      throw Object.assign(new Error('send-result-unknown'), { code: 'send-result-unknown' });
+    return { sent: true, receipt: { version: 1, messageId, conversationId } };
   }
 
   /**

package/src/channels/feishu/multi-bot-controller.mjs

@@ -594,7 +594,7 @@ export class MultiBotDshFeishuController {
       this.#assertOpen('capability-unavailable');
       return { version: 1, botId, channel: 'feishu', account,
         connected: isConnected(connectionStatus(this.#runtimes.get(botId))),
-        capabilities: ['proactive-text-checked'] };
+        capabilities: ['proactive-text-checked', 'proactive-receipt-checked'] };
     });
   }
 

package/src/channels/qq/qq-bridge.mjs

@@ -75,6 +75,7 @@ import {
 } from './qq-menu.mjs';
 import { withSessionBindingLock } from '../shared/session-binding-lock.mjs';
 import { t } from '../shared/i18n.mjs';
+import { isQqMessageAddressed, normalizeQqMentions } from './qq-mention.mjs';
 
 function interactionResolvedText() {
   return t('这个问题已在其他客户端处理，无需再次回答。');
@@ -408,7 +409,7 @@ async function sendQqFile(
 function canClaimInteractionReply(message, pending) {
   return pending.questions[pending.index]
     && nonEmptyString(message?.senderId) === pending.actor
-    && (message.kind !== 'group' || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE')
+    && isQqMessageAddressed(message)
     && !hasQqImageAttachments(message)
     && !hasQqFileAttachments(message)
     && nonEmptyString(safeText(message));
@@ -506,9 +507,9 @@ export class QqHarnessBridge {
       || !['c2c', 'group'].includes(message?.kind)
       || this.#state.hasSeen(messageId)
       || this.#acceptedMessageIds.has(messageId)) return Promise.resolve();
+    message = normalizeQqMentions(message, new Set([this.#bot.appId]));
     const key = conversationKey(message);
-    const addressed = message.kind !== 'group'
-      || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE';
+    const addressed = isQqMessageAddressed(message);
     const commandText = safeText(message);
     const menuTextOnly = !hasQqImageAttachments(message) && !hasQqFileAttachments(message)
       && !qqReplyReference(message);
@@ -634,7 +635,7 @@ export class QqHarnessBridge {
       actor: sender,
       messageId,
       text: hasQqImageAttachments(message) || hasQqFileAttachments(message) ? '' : safeText(message),
-      addressed: message.kind !== 'group' || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE',
+      addressed,
       hasPendingQuestion: Boolean(pending),
       questionCompletion: pending?.submitting || pending?.claimedReplyMessageId
         ? pending.queue
@@ -689,8 +690,7 @@ export class QqHarnessBridge {
     alreadyRecorded = false,
     batchSubmission = null,
   } = {}) {
-    const addressed = message.kind !== 'group'
-      || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE';
+    const addressed = isQqMessageAddressed(message);
     const preparedMessage = addressed
       ? prefetchInboundFiles(
           qqInboundMessage(message, { fetchImpl: this.#fetchImpl }),
@@ -984,7 +984,7 @@ export class QqHarnessBridge {
       await this.#state.markSeen(messageId);
       messageRecorded = true;
     };
-    if (message.kind === 'group' && message.rawEventType !== 'GROUP_AT_MESSAGE_CREATE') return;
+    if (!isQqMessageAddressed(message)) return;
 
     const target = message.replyTarget;
     const promptMessage = preparedMessage
@@ -1245,7 +1245,7 @@ export class QqHarnessBridge {
     this.#status.messagesReceived += 1;
     this.#status.lastMessageAt = new Date().toISOString();
 
-    if (message.kind === 'group' && message.rawEventType !== 'GROUP_AT_MESSAGE_CREATE') return;
+    if (!isQqMessageAddressed(message)) return;
     const text = nonEmptyString(safeText(message));
     if (!text || hasQqImageAttachments(message) || hasQqFileAttachments(message)) {
       await this.#bot.sendText(message.replyTarget, t('请用文字回答当前问题。'));

package/src/channels/qq/qq-mention.mjs

@@ -0,0 +1,37 @@
+// Keep the decision after the SDK sanitizes the mention out of the content.
+const addressedToBot = Symbol('qq.addressedToBot');
+
+function selfMentions(message) {
+  return Array.isArray(message?.mentions)
+    ? message.mentions.filter((mention) => mention?.is_you === true)
+    : [];
+}
+
+export function isQqMessageAddressed(message) {
+  return Boolean(message) && (message.kind !== 'group'
+    || message[addressedToBot] === true
+    || message.rawEventType === 'GROUP_AT_MESSAGE_CREATE'
+    || selfMentions(message).length > 0);
+}
+
+/** botIds belongs to one runtime; only platform-marked self mentions add IDs. */
+export function normalizeQqMentions(message, botIds = new Set()) {
+  if (message?.kind !== 'group') return message;
+  for (const mention of selfMentions(message)) {
+    for (const id of [mention.id, mention.user_openid, mention.member_openid]) {
+      if (typeof id === 'string' && id.trim()) botIds.add(id.trim());
+    }
+  }
+  const marker = /<@!?([^<>\s]+)>/gu;
+  const content = typeof message.content === 'string' ? message.content : '';
+  // raw.content is still the current message, never the quoted message snapshot.
+  const rawContent = typeof message.raw?.content === 'string' ? message.raw.content : '';
+  const mentioned = isQqMessageAddressed(message)
+    || [...`${content}\n${rawContent}`.matchAll(marker)].some((match) => botIds.has(match[1]));
+  // Match the SDK sanitizer's in-place contract: later sender enrichment must
+  // remain visible to the existing queued message and source-context capture.
+  message[addressedToBot] = mentioned;
+  message.content = content.replace(/<@!?([^<>\s]+)>[ \t]*/gu,
+    (match, id) => botIds.has(id) ? '' : match).trim();
+  return message;
+}

package/src/channels/qq/qq-runtime.mjs

@@ -8,6 +8,7 @@ import {
 import { t } from '../shared/i18n.mjs';
 import { evaluateInboundAccess } from '../shared/inbound-access.mjs';
 import { createQqBridgeStatus, QqHarnessBridge } from './qq-bridge.mjs';
+import { isQqMessageAddressed, normalizeQqMentions } from './qq-mention.mjs';
 
 function timeoutError() {
   const error = new Error('QQ WebSocket did not become ready in time');
@@ -178,6 +179,11 @@ export class QqRuntime {
       replyTimeoutMs: this.#replyTimeoutMs,
       signal: controller.signal,
     });
+    const botMentionIds = new Set([this.#config.appId]);
+    bot.use(async (ctx, next) => {
+      ctx.message = normalizeQqMentions(ctx.message, botMentionIds);
+      await next();
+    });
     // QQ delivers emoji/face messages as opaque `<faceType=..,faceId="..",ext="..">`
     // tags. Parse them into readable text so the Harness sees what the sender
     // actually meant instead of an unusable markup fragment.
@@ -186,8 +192,7 @@ export class QqRuntime {
       keepAlive: true,
       predicate: (ctx) => {
         const message = ctx?.message;
-        if (!message || (message.kind === 'group'
-          && message.rawEventType !== 'GROUP_AT_MESSAGE_CREATE')) return false;
+        if (!isQqMessageAddressed(message)) return false;
         if (!this.#accessPolicy) {
           return message.kind === 'group'
             || this.#config.ownerUserOpenid === '*'
@@ -207,7 +212,10 @@ export class QqRuntime {
       readyResolve = resolve;
       readyReject = reject;
     });
-    const onReady = () => {
+    const onReady = (data) => {
+      if (typeof data?.user?.id === 'string' && data.user.id.trim()) {
+        botMentionIds.add(data.user.id.trim());
+      }
       const now = Date.now();
       this.#status.ready = true;
       this.#status.qqConnectionState = 'connected';

package/src/channels/shared/bot-workspace-store.mjs

@@ -1709,6 +1709,7 @@ export function createBotWorkspaceScope(
         };
       }
       if ((property === 'listWorkspaces'
+        || property === 'listWorkspaceEntries'
         || property === 'listWorkspaceSessions'
         || property === 'listModels')
         && typeof target[property] === 'function') {

package/src/channels/shared/connection-error.mjs

@@ -6,7 +6,7 @@ import { t } from './i18n.mjs';
 const reported = new WeakMap();
 const lastReport = new WeakMap();
 const stages = new WeakMap();
-const OWNED_REASONS = { 'connect-timeout': 'timeout', 'telegram-timeout': 'timeout', 'cli-timeout': 'timeout', 'telegram-response-invalid': 'invalid-response', 'office-protocol-mismatch': 'invalid-response' };
+const OWNED_REASONS = { 'connect-timeout': 'timeout', 'telegram-timeout': 'timeout', 'cli-timeout': 'timeout', 'provider-timeout': 'timeout', 'telegram-response-invalid': 'invalid-response', 'office-protocol-mismatch': 'invalid-response' };
 const STANDARD_NAMES = new Set(['Error', 'TypeError', 'SyntaxError', 'AggregateError', 'DOMException', 'AxiosError', 'TimeoutError', 'AbortError']);
 const KNOWN_MESSAGES = {
   'discord-401': 'Discord Bot Token 无效，请重新填写。',
@@ -37,18 +37,24 @@ export function extractConnectionEvidence(error) {
   const { chain, truncated } = connectionErrorChain(error);
   const errors = chain.map(e => ({
     type: STANDARD_NAMES.has(e.name) ? e.name : 'Error',
+    // Host RPC adapters carry safe diagnostic facts without the original Error graph.
     ...normalizeDiagnosticDetails({
-      reason: OWNED_REASONS[e.code] ?? e.code ?? (e.name === 'TimeoutError' ? 'timeout' : e instanceof SyntaxError ? 'invalid-json' : undefined),
+      reason: e.details?.reason, reasons: e.details?.reasons,
+      httpStatus: e.details?.httpStatus, providerCode: e.details?.providerCode,
+    }),
+    ...normalizeDiagnosticDetails({
+      // DOMException TimeoutError has a numeric legacy code; its name is authoritative.
+      reason: OWNED_REASONS[e.code] ?? (e.name === 'TimeoutError' ? 'timeout' : e.code ?? (e instanceof SyntaxError ? 'invalid-json' : undefined)),
       httpStatus: e.status ?? e.statusCode ?? e.response?.status,
       providerCode: e.providerCode,
     }),
     hasCause: Boolean(e.cause && typeof e.cause === 'object'),
     hasErrors: Array.isArray(e.errors),
   }));
-  const allReasons = [...new Set(errors.map(e => e.reason).filter(r => r && !['unknown', 'multiple-causes'].includes(r)))];
+  const allReasons = [...new Set(errors.flatMap(e => e.reason === 'multiple-causes' ? e.reasons ?? [] : [e.reason]).filter(r => r && !['unknown', 'multiple-causes'].includes(r)))];
   const precise = allReasons.filter(r => !['timeout', 'http-error', 'provider-rejected', 'invalid-response'].includes(r));
   const reasons = precise.length ? precise : allReasons;
-  const first = field => chain.map(e => normalizeDiagnosticDetails({ [field]: e[field] })[field]).find(v => v !== undefined);
+  const first = field => chain.map(e => normalizeDiagnosticDetails({ [field]: e[field] ?? e.details?.[field] })[field]).find(v => v !== undefined);
   return {
     chain, errors,
     details: normalizeDiagnosticDetails({

package/src/channels/shared/harness-client.mjs

@@ -242,10 +242,12 @@ function turnStoppedError() {
   return error;
 }
 
-function workspacePaths(value) {
+function workspaceEntries(value) {
   if (!Array.isArray(value?.items)) return [];
   return value.items.flatMap((item) => (
-    typeof item?.path === 'string' && isAbsolute(item.path) ? [item.path] : []
+    typeof item?.path === 'string' && isAbsolute(item.path)
+      ? [{ path: item.path, title: typeof item.title === 'string' ? item.title : '' }]
+      : []
   ));
 }
 
@@ -1081,8 +1083,12 @@ export class HarnessClient {
   }
 
   async listWorkspaces(options = {}) {
+    return (await this.listWorkspaceEntries(options)).map((item) => item.path);
+  }
+
+  async listWorkspaceEntries(options = {}) {
     await this.ensureRunning(options);
-    return workspacePaths(await this.rpc('workspace.list', {}, 30_000, options));
+    return workspaceEntries(await this.rpc('workspace.list', {}, 30_000, options));
   }
 
   async listWorkspaceSessions(workspacePath, options = {}) {

package/src/channels/shared/i18n-en/shared-a.mjs

@@ -104,6 +104,10 @@ export default {
     'This message contains an image or file that cannot be processed. Adjust it and send it again.',
   '任务未完成，暂时无法确定原因。请重试；若持续发生，请将参考号提供给管理员。':
     'The task did not finish and the cause could not be determined. Try again; if it persists, give the reference ID to an administrator.',
+  '请求超时，当前操作结果尚未确认。请先检查任务状态或聊天记录，不要立即重复提交。':
+    'The request timed out and its outcome is unconfirmed. Check the task status or chat history before submitting it again.',
+  '网络请求失败，当前操作结果尚未确认。请先检查任务状态或聊天记录，不要立即重复提交。':
+    'The network request failed and its outcome is unconfirmed. Check the task status or chat history before submitting it again.',
   '错误码：{code}；参考号：{referenceId}': 'Error code: {code}; reference: {referenceId}',
   '{label}机器人': '{label} bot',
   '目前支持文字和图片消息。': 'Only text and image messages are supported at the moment.',

package/src/channels/shared/message-failure.mjs

@@ -1,4 +1,4 @@
-import { extractConnectionEvidence } from './connection-error.mjs';
+import { connectionHint, extractConnectionEvidence } from './connection-error.mjs';
 import { diagnosticFields } from './diagnostic-details.mjs';
 import { randomUUID } from 'node:crypto';
 
@@ -90,6 +90,10 @@ const FAILURE_MESSAGES = Object.freeze({
     '回复已经生成，但当前渠道暂时无法发送。请稍后重试。',
   INPUT_INVALID:
     '当前消息包含无法处理的图片或文件。请调整后重新发送。',
+  REQUEST_TIMEOUT:
+    '请求超时，当前操作结果尚未确认。请先检查任务状态或聊天记录，不要立即重复提交。',
+  NETWORK_ERROR:
+    '网络请求失败，当前操作结果尚未确认。请先检查任务状态或聊天记录，不要立即重复提交。',
   INTERNAL_UNKNOWN:
     '任务未完成，暂时无法确定原因。请重试；若持续发生，请将参考号提供给管理员。',
 });
@@ -156,16 +160,30 @@ function failureCode(error) {
     return 'CHANNEL_RATE_LIMIT';
   }
   if (['channel-delivery-uncertain', 'delivery-uncertain', 'artifact-delivery-uncertain']
-    .includes(code)) {
+    .includes(code) || error?.deliveryOutcome === 'unknown') {
     return 'CHANNEL_DELIVERY_UNCERTAIN';
   }
   if (code === 'channel-delivery-failed' || code.startsWith('artifact-')
-    || ['network-error', 'timeout'].includes(code)) {
+    || code === 'network-error') {
     return 'CHANNEL_DELIVERY';
   }
   return 'INTERNAL_UNKNOWN';
 }
 
+// Only refine the unknown fallback, using the same allowlisted evidence as the UI.
+// Mixed unrelated causes and cancellation do not establish a network diagnosis.
+function transportFailureCode(error, details) {
+  if (error?.name === 'AbortError' || error?.code === 'cancelled') return 'INTERNAL_UNKNOWN';
+  const reasons = details.reason === 'multiple-causes' ? details.reasons : [details.reason];
+  const timeout = reason => reason === 'timeout' || reason === 'ETIMEDOUT' || /_TIMEOUT$/u.test(reason);
+  if (reasons?.length && reasons.every(timeout)) return 'REQUEST_TIMEOUT';
+  const network = reason => timeout(reason) || [
+    'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET',
+    'ENETUNREACH', 'EHOSTUNREACH', 'ERR_NETWORK_ACCESS_DENIED', 'ERR_PROXY_CONNECTION_FAILED',
+  ].includes(reason) || /CERT|TLS|SSL|ISSUER|SIGNATURE/u.test(reason);
+  return reasons?.length && reasons.every(network) ? 'NETWORK_ERROR' : 'INTERNAL_UNKNOWN';
+}
+
 function safeReferenceId(value) {
   return typeof value === 'string' && /^[A-Z0-9-]{6,40}$/u.test(value)
     ? value
@@ -185,13 +203,17 @@ export function classifyMessageFailure(error, {
 } = {}) {
   const safeReason = safeFailureReason(reason);
   const classifiedCode = failureCode(error);
-  const code = classifiedCode === 'INTERNAL_UNKNOWN'
+  const businessCode = classifiedCode === 'INTERNAL_UNKNOWN'
     && safeReason
     && typeof userMessage === 'string'
     && userMessage.trim()
     ? 'INPUT_INVALID'
     : classifiedCode;
   const details = extractConnectionEvidence(error).details;
+  const code = businessCode === 'INTERNAL_UNKNOWN'
+    ? transportFailureCode(error, details)
+    : businessCode;
+  if (code === 'REQUEST_TIMEOUT' || code === 'NETWORK_ERROR') details.hint = connectionHint(details);
   return Object.freeze({
     ...(code === 'INTERNAL_UNKNOWN' || details.reason !== 'unknown' || details.httpStatus || details.providerCode ? { details } : {}),
     code,

package/src/channels/shared/text-harness-bridge.mjs

@@ -936,12 +936,12 @@ export class TextHarnessBridge {
       const finalDeliveryUnknown = textReceipt?.deliveryOutcome === 'unknown';
       if (textReceipt?.deliveryOutcome === 'failed') {
         textDeliveryError = channelDeliveryFailure(
-          new Error(`Final text delivery failed (${textReceipt.reason ?? 'unknown'})`),
+          Object.assign(new Error('Final text delivery failed'), { code: textReceipt.reason }),
           { uncertain: false },
         );
       } else if (finalDeliveryUnknown) {
         textDeliveryError = channelDeliveryFailure(
-          new Error(`Final text delivery outcome is unknown (${textReceipt.reason ?? 'unknown'})`),
+          Object.assign(new Error('Final text delivery outcome is unknown'), { code: textReceipt.reason }),
         );
       }
       // A failed final text must not discard an already registered result file.

package/src/channels/shared/workspace-command.mjs

@@ -62,17 +62,19 @@ export function parseSessionListArgument(value) {
   return { selector: '', limit };
 }
 
+async function existingWorkspacePath(value) {
+  const workspace = normalizedWorkspacePath(value);
+  if (!workspace) return null;
+  try {
+    if (!(await stat(workspace)).isDirectory()) return null;
+    return normalizedWorkspacePath(await realpath(workspace));
+  } catch {
+    return null;
+  }
+}
+
 async function existingWorkspacePaths(values) {
-  const checked = await Promise.all(values.map(async (value) => {
-    const workspace = normalizedWorkspacePath(value);
-    if (!workspace) return null;
-    try {
-      if (!(await stat(workspace)).isDirectory()) return null;
-      return normalizedWorkspacePath(await realpath(workspace));
-    } catch {
-      return null;
-    }
-  }));
+  const checked = await Promise.all(values.map(existingWorkspacePath));
   return [...new Set(checked.filter(Boolean))];
 }
 
@@ -109,16 +111,26 @@ async function selectedWorkspacePath(value) {
   }
 }
 
-export async function workspacePathSnapshot(harness, options = {}) {
-  const listed = await harness.listWorkspaces(options);
+export async function workspacePathSnapshot(harness, { includeTitles = false, ...options } = {}) {
+  const withEntries = includeTitles && typeof harness.listWorkspaceEntries === 'function';
+  const listed = await (withEntries ? harness.listWorkspaceEntries(options) : harness.listWorkspaces(options));
   const currentValue = typeof harness?.currentWorkspace === 'function'
     ? harness.currentWorkspace()
     : null;
-  const [current] = currentValue ? await existingWorkspacePaths([currentValue]) : [];
-  const registered = await existingWorkspacePaths(Array.isArray(listed) ? listed : []);
-  const paths = [...new Set([...(current ? [current] : []), ...registered])];
+  const current = await existingWorkspacePath(currentValue);
+  const entries = await Promise.all((Array.isArray(listed) ? listed : []).map(async (item) => ({
+    path: await existingWorkspacePath(withEntries ? item?.path : item),
+    title: withEntries ? safeDisplayText(item?.title) : '',
+  })));
+  const paths = [...new Set([...(current ? [current] : []), ...entries.map((item) => item.path).filter(Boolean)])];
+  const titles = {};
+  if (includeTitles) {
+    for (const item of entries) {
+      if (item.path && item.title && !titles[item.path]) titles[item.path] = item.title;
+    }
+  }
   harness.assertWorkspaceScope?.();
-  return { current: current ?? null, paths };
+  return { current: current ?? null, paths, ...(includeTitles ? { titles } : {}) };
 }
 
 export function splitWorkspaceCommandMessage(message) {