dsh-bot-team 1.1.0 → 1.3.0

package/host/execution.js

@@ -1,4 +1,5 @@
-/** Read one Bot message's immutable execution reference through session-query. */
+/** Read Bot executions and group-owned Session history through session-query. */
+import { conversationIdOf } from './conversations.js';
 const ID = /^[A-Za-z0-9_-]{1,256}$/;
 const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
 const ACTIVE = new Set(['pending', 'streaming', 'running', 'queued']);
@@ -57,18 +58,6 @@ function clone(value, ancestors = new Set()) {
   }
 }
 
-function pick(value, keys) {
-  const result = {};
-  if (!record(value)) return result;
-  for (const key of keys) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, key);
-    if (!descriptor || !own(descriptor, 'value')) continue;
-    const copied = clone(descriptor.value);
-    if (copied !== undefined) result[key] = copied;
-  }
-  return result;
-}
-
 function reference(message) {
   const raw = message.meta?.execution;
   if (raw === undefined || raw === null) return { legacy: true, execution: null };
@@ -112,16 +101,36 @@ function response(message, afterSeq, availability, execution, extra = {}) {
   };
 }
 
+function validateExecutionOwnership(repo, message, execution) {
+  if (!repo.getGroup(message.groupId)?.activeConversationId || !execution?.sessionId) return;
+  const conversationId = conversationIdOf(repo, message);
+  const binding = repo.sessionBindingFor?.(execution.sessionId);
+  if (!conversationId || (binding && (binding.groupId !== message.groupId ||
+      binding.conversationId !== conversationId || binding.membershipId !== message.author.membershipId ||
+      binding.botId !== message.author.botId))) fail('invalid-input', 'Execution Session does not belong to this message');
+}
+
 function legacyResponse(repo, message, afterSeq) {
   const member = repo.getMember?.(message.author.membershipId);
-  const fallback = typeof message.author.botId === 'string' && ID.test(message.author.botId) &&
-    typeof message.author.membershipId === 'string' && ID.test(message.author.membershipId) &&
-    member && member.groupId === message.groupId &&
-    member.membershipId === message.author.membershipId && member.botId === message.author.botId &&
-    typeof member.sessionId === 'string' && SESSION_ID.test(member.sessionId);
+  const validAuthor = typeof message.author.botId === 'string' && ID.test(message.author.botId) &&
+    typeof message.author.membershipId === 'string' && ID.test(message.author.membershipId);
+  let fallbackSessionId;
+  if (repo.getGroup(message.groupId)?.activeConversationId) {
+    // A legacy message cannot borrow a newer member Session. Only a unique,
+    // committed binding for this message's own conversation proves a fallback.
+    const conversationId = conversationIdOf(repo, message);
+    const bindings = conversationId && validAuthor ? (repo.sessionBindingsOf?.(message.groupId, conversationId) || []) : [];
+    const candidates = new Set(bindings.filter(binding =>
+      binding.groupId === message.groupId && binding.conversationId === conversationId &&
+      binding.membershipId === message.author.membershipId && binding.botId === message.author.botId &&
+      typeof binding.sessionId === 'string' && SESSION_ID.test(binding.sessionId)).map(binding => binding.sessionId));
+    if (candidates.size === 1) fallbackSessionId = [...candidates][0];
+  } else if (validAuthor && member && member.groupId === message.groupId &&
+      member.membershipId === message.author.membershipId && member.botId === message.author.botId &&
+      typeof member.sessionId === 'string' && SESSION_ID.test(member.sessionId)) fallbackSessionId = member.sessionId;
   return response(message, afterSeq, 'legacy-unlinked', null, {
     reason: 'legacy-message-has-no-execution-reference',
-    ...(fallback ? { fallbackSessionId: member.sessionId } : {}),
+    ...(fallbackSessionId ? { fallbackSessionId } : {}),
   });
 }
 
@@ -140,11 +149,16 @@ function observationEvents(observation, sessionId) {
   if (!observation || observation.header?.id !== sessionId || typeof observation[Symbol.dispose] !== 'function') {
     fail('execution-log-corrupt', 'Session observation identity or lease is invalid');
   }
-  const events = observation.events;
-  const cursor = observation.cursor;
+  return validatedEvents(observation.events, observation.cursor);
+}
+
+function validatedEvents(events, cursor) {
   if (!Array.isArray(events) || !Number.isSafeInteger(cursor) || cursor < -1) fail('execution-log-corrupt', 'Invalid session snapshot');
-  if (events.length !== cursor + 1 || events.some((event, index) => !record(event) || event.seq !== index || typeof event.type !== 'string')) {
-    fail('execution-log-corrupt', 'Session log is not a contiguous snapshot');
+  if (events.length !== cursor + 1) fail('execution-log-corrupt', 'Session log is not a contiguous snapshot');
+  for (const [index, event] of events.entries()) {
+    if (!record(event) || event.seq !== index || typeof event.type !== 'string') {
+      fail('execution-log-corrupt', 'Session log is not a contiguous snapshot');
+    }
   }
   return events;
 }
@@ -236,115 +250,164 @@ function resolveSpan(events, execution) {
   return { span };
 }
 
-function errorInfo(value) {
-  return typeof value === 'string' ? value : pick(value, ['name', 'code', 'message', 'retryable', 'status', 'statusCode', 'providerRetryAfterMs']);
-}
-
-function userMessage(data) {
-  const result = pick(data, ['id', 'role']);
-  result.source = pick(data?.source, ['kind']);
-  result.content = Array.isArray(data?.content) ? data.content.filter((block) =>
-    block && ['text', 'image', 'image-url', 'file', 'audio'].includes(block.type) && block.hidden !== true && block.internal !== true,
-  ).map((block) => block.type === 'text' ? pick(block, ['type', 'text']) : clone(block)) : [];
-  return result;
-}
-
-/** Explicit observable vocabulary: no request envelopes, inbox copies or opaque streams. */
-function project(event, inputMessageId) {
-  const data = record(event.data) ? event.data : {};
-  let projected;
-  switch (event.type) {
-    case 'user/message':
-      if (event.surfaceOp && event.surfaceOp !== 'append') return null;
-      if (data.id !== inputMessageId && data.source?.kind !== 'user') return null;
-      projected = userMessage(data);
-      break;
-    case 'turn/start':
-    case 'step/start':
-    case 'step/end':
-    case 'assistant/attempt':
-      projected = pick(data, ['turn', 'step']);
-      break;
-    case 'turn/end':
-      projected = pick(data, ['turn']);
-      projected.reason = pick(data.reason, ['kind']);
-      if (data.reason?.reason) projected.reason.reason = pick(data.reason.reason, ['kind']);
-      if (data.reason?.error) projected.reason.error = errorInfo(data.reason.error);
-      break;
-    case 'assistant/message': {
-      if (event.surfaceOp && event.surfaceOp !== 'append') return null;
-      const content = Array.isArray(data.message?.content) ? data.message.content
-        .filter((block) => block?.type === 'text' && typeof block.text === 'string' && block.hidden !== true && block.internal !== true && block.visibility !== 'hidden')
-        .map((block) => ({ type: 'text', text: block.text })) : [];
-      if (content.length === 0) return null;
-      projected = pick(data, ['turn', 'step', 'interrupted', 'usage']);
-      projected.message = { ...pick(data.message, ['id', 'role']), content, source: pick(data.message?.source, ['provider', 'model']) };
-      break;
-    }
-    case 'tool/call':
-      projected = pick(data, ['turn', 'step', 'callId', 'name', 'arguments']);
-      break;
-    case 'tool/result':
-      if (event.surfaceOp && event.surfaceOp !== 'append') return null;
-      projected = pick(data, ['turn', 'step', 'meta']);
-      projected.message = pick(data.message, ['id', 'role', 'toolCallId', 'isError', 'content']);
-      projected.message.source = pick(data.message?.source, ['kind', 'callId']);
-      if (data.error !== undefined) projected.error = errorInfo(data.error);
-      break;
-    case 'tool/ptc-dispatch-start':
-    case 'tool/ptc-dispatch':
-    case 'tool/ptc-dispatch-end':
-      projected = pick(data, ['turn', 'step', 'rootCallId', 'parentCallId', 'subCallId', 'name', 'arguments', 'isError', 'content', 'meta']);
-      if (data.error !== undefined) projected.error = errorInfo(data.error);
-      break;
-    case 'approval/asked':
-      projected = pick(data, ['id', 'toolName', 'callId', 'reason']);
-      break;
-    case 'approval/decided':
-      projected = pick(data, ['id', 'outcome']);
-      break;
-    case 'llm/retry':
-    case 'llm/retry-started':
-      projected = pick(data, ['turn', 'step', 'retryId', 'retry', 'provider', 'mode', 'maxRetries', 'delayMs']);
-      if (data.failure !== undefined) projected.failure = errorInfo(data.failure);
-      break;
-    case 'compaction/start':
-    case 'compaction/summary':
-    case 'compaction/end':
-    case 'compaction/prune':
-      // The summary/rawOutput can repeat prompts, reasoning and adjacent turns.
-      projected = pick(data, ['turn', 'compactionId', 'sourceCommandId', 'shadowedRange', 'shadowedSeqs', 'shadowedTokenCount', 'provider', 'model', 'maxTokens', 'usage', 'prunedSeqs']);
-      if (data.error !== undefined) projected.error = errorInfo(data.error);
-      break;
-    default:
-      return null;
-  }
-  return { seq: event.seq, time: clone(event.time) ?? null, type: event.type, data: projected };
-}
-
-function page(events, span, execution, afterSeq, limit) {
-  const visible = [];
+/** Keep the SDK event envelope and payload intact, including future event types. */
+function page(events, span, afterSeq, limit) {
+  const selected = [];
   let nextSeq = afterSeq;
   for (const event of events) {
     if (event.seq < span.startSeq || event.seq > span.lastSeq || event.seq <= afterSeq) continue;
-    const item = project(event, execution.inputMessageId);
-    if (item && visible.length === limit) return { events: visible, nextSeq, hasMore: true };
+    if (selected.length === limit) return { events: selected, nextSeq, hasMore: true };
+    selected.push(clone(event));
     nextSeq = event.seq;
-    if (item) visible.push(item);
   }
-  return { events: visible, nextSeq, hasMore: false };
+  return { events: selected, nextSeq, hasMore: false };
+}
+
+function sessionDescriptor(header) {
+  return {
+    id: header.id,
+    ...(header.origin === undefined ? {} : { origin: clone(header.origin) }),
+    native: header.origin !== 'subagent',
+  };
 }
 
 function failureReason(error) {
-  if (error?.code === 'SESSION_QUERY_SESSION_NOT_FOUND' || error?.code === 'ENOENT') return 'session-log-missing';
+  if (error?.code === 'SESSION_QUERY_SESSION_NOT_FOUND' || error?.code === 'ENOENT' || error?.name === 'SessionPersistenceNotFoundError') return 'session-log-missing';
+  if (error?.name === 'SessionPersistenceCorruptionError') return 'session-log-corrupt';
+  if (error?.name === 'SessionFormatUnsupportedError') return 'session-log-format-unsupported';
   if (['SESSION_QUERY_CORRUPT_SESSION', 'SESSION_QUERY_INVALID_SURFACE', 'execution-log-corrupt'].includes(error?.code)) return 'session-log-corrupt';
   if (error?.code === 'SESSION_QUERY_SOURCE_CONFLICT') return 'session-reference-mismatch';
   return 'session-log-read-failed';
 }
 
+/** Resolve group-owned references before any Session lookup, including historical Bots. */
+function sessionReferences(repo, groupId, sessionId) {
+  const group = repo.getGroup(groupId);
+  if (!group || group.groupId !== groupId) fail('not-found', 'Group not found');
+  const validId = (value) => typeof value === 'string' && ID.test(value);
+  const binding = repo.sessionBindingFor?.(sessionId) || repo.sessionBindingsOf?.(groupId).find(candidate => candidate.sessionId === sessionId);
+  if (binding && binding.groupId !== groupId) fail('invalid-input', 'Session does not belong to this group');
+  const bound = binding && validId(binding.membershipId) && validId(binding.botId) &&
+    typeof binding.conversationId === 'string' && conversationIdOf(repo, binding) === binding.conversationId;
+  const current = !group.activeConversationId && repo.membersOf(groupId).some((member) =>
+    member?.groupId === groupId && validId(member.membershipId) && validId(member.botId) && member.sessionId === sessionId,
+  );
+  const references = [];
+  for (const message of repo.messagesOf(groupId)) {
+    if (message?.groupId !== groupId || !validId(message.messageId) || message.author?.type !== 'bot' ||
+        !validId(message.author.membershipId) || !validId(message.author.botId)) continue;
+    const parsed = reference(message);
+    if (parsed.execution?.sessionId === sessionId && (!group.activeConversationId ||
+        (conversationIdOf(repo, message) && (!binding || conversationIdOf(repo, message) === binding.conversationId)))) {
+      references.push(parsed.execution);
+    }
+  }
+  if (!bound && !current && references.length === 0) fail('invalid-input', 'Session does not belong to this group');
+  return references;
+}
+
+/** Read all raw events of a verified Bot Session without creating or resuming an Agent. */
+export async function readBotSessionHistory({ ctx, repo, groupId, sessionId, afterSeq, limit, signal } = {}) {
+  if (typeof groupId !== 'string' || !ID.test(groupId) || typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+    fail('invalid-input', 'groupId and sessionId must be valid identifiers');
+  }
+  afterSeq = integerParam(afterSeq, -1, -1, 'afterSeq');
+  limit = Math.min(integerParam(limit, 100, 1, 'limit'), 300);
+  abort(signal);
+  sessionReferences(repo, groupId, sessionId);
+  const result = (availability, extra = {}) => ({
+    ok: true, groupId, sessionId, availability, events: [], nextSeq: afterSeq, hasMore: false, ...extra,
+  });
+  let observation;
+  try {
+    const query = typeof ctx?.get === 'function' ? ctx.get('sessionQuery') : ctx?.sessionQuery;
+    if (typeof query?.observeSession !== 'function') return result('unavailable', { reason: 'session-query-unavailable' });
+    observation = await query.observeSession(sessionId, { signal, projectionMode: 'none' });
+    abort(signal);
+    // Group removal or membership rotation may have raced the asynchronous read.
+    const references = sessionReferences(repo, groupId, sessionId);
+    const raw = observationEvents(observation, sessionId);
+    const last = raw.at(-1);
+    // Only a recorded end for this exact tail protects it from cold-repair removal.
+    // An earlier turn's durable end must not legitimize a later synthetic suffix.
+    const end = references.find((ref) => ref.endSeq === last?.seq && (ref.turn === null || ref.turn === last.data?.turn));
+    const events = withoutColdRepairs(raw, observation, { endSeq: end?.endSeq ?? null });
+    const span = { startSeq: 0, lastSeq: events.at(-1)?.seq ?? -1 };
+    const response = result('available', { session: sessionDescriptor(observation.header), ...page(events, span, afterSeq, limit) });
+    abort(signal);
+    return response;
+  } catch (error) {
+    if (isAbort(error, signal)) throw error;
+    if (error?.code === 'invalid-input' || error?.code === 'not-found') throw error;
+    sessionReferences(repo, groupId, sessionId);
+    return result('unavailable', { reason: failureReason(error) });
+  } finally {
+    if (typeof observation?.[Symbol.dispose] === 'function') observation[Symbol.dispose]();
+  }
+}
+
+/**
+ * Read a group-owned committed log for native JSONL export. A prepared query
+ * observation is never an export source: it can contain unpersisted repairs.
+ * Flush only a Session already attached to the store; never open/resume an Agent.
+ * Returns { ok, groupId, sessionId, availability, header, events, session?, reason? }.
+ */
+export async function readBotSessionLog({ ctx, repo, groupId, sessionId, signal } = {}) {
+  if (typeof groupId !== 'string' || !ID.test(groupId) || typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+    fail('invalid-input', 'groupId and sessionId must be valid identifiers');
+  }
+  abort(signal);
+  sessionReferences(repo, groupId, sessionId);
+  const result = (availability, extra = {}) => ({
+    ok: true, groupId, sessionId, availability, header: null, events: [], ...extra,
+  });
+  try {
+    const service = (name) => typeof ctx?.get === 'function' ? ctx.get(name) : ctx?.[name];
+    const persistence = service('sessionPersistence');
+    if (typeof persistence?.open !== 'function') return result('unavailable', { reason: 'session-persistence-unavailable' });
+    const sessions = service('sessions');
+    const live = sessions?.get?.(sessionId);
+    if (live !== undefined) {
+      if (typeof sessions.flush !== 'function') return result('unavailable', { reason: 'session-flush-unavailable' });
+      await sessions.flush(live);
+      abort(signal);
+      sessionReferences(repo, groupId, sessionId);
+    }
+    const options = signal === undefined ? {} : { signal };
+    let handle;
+    let header;
+    let events;
+    try {
+      handle = await persistence.open(sessionId, 'read', options);
+      abort(signal);
+      sessionReferences(repo, groupId, sessionId);
+      if (!handle || handle.header?.id !== sessionId || typeof handle.read !== 'function' || typeof handle.close !== 'function') {
+        fail('execution-log-corrupt', 'Session persistence identity or read handle is invalid');
+      }
+      const snapshot = await handle.read(0, undefined, options);
+      abort(signal);
+      sessionReferences(repo, groupId, sessionId);
+      header = clone(handle.header);
+      if (header?.id !== sessionId) fail('execution-log-corrupt', 'Session persistence identity changed during read');
+      events = validatedEvents(snapshot?.events, snapshot?.events?.length - 1).map((event) => clone(event));
+    } finally {
+      if (typeof handle?.close === 'function') await handle.close();
+    }
+    abort(signal);
+    sessionReferences(repo, groupId, sessionId);
+    return result('available', { header, events, session: sessionDescriptor(header) });
+  } catch (error) {
+    abort(signal);
+    if (isAbort(error, signal)) throw error;
+    if (error?.code === 'invalid-input' || error?.code === 'not-found') throw error;
+    sessionReferences(repo, groupId, sessionId);
+    return result('unavailable', { reason: failureReason(error) });
+  }
+}
+
 /**
- * afterSeq is exclusive; nextSeq is the last examined raw seq (including hidden
- * records). Bounds in execution are inclusive. hasMore describes this captured
+ * afterSeq is exclusive; nextSeq is the last returned raw seq.
+ * Bounds in execution are inclusive. hasMore describes this captured
  * snapshot only; callers may poll again while status is pending/streaming.
  */
 export async function readMessageExecution({ ctx, repo, groupId, messageId, afterSeq, limit, signal } = {}) {
@@ -359,10 +422,14 @@ export async function readMessageExecution({ ctx, repo, groupId, messageId, afte
   if (parsed.legacy) return legacyResponse(repo, message, afterSeq);
   if (parsed.reason) return response(message, afterSeq, 'unavailable', null, { reason: parsed.reason });
   let execution = parsed.execution;
+  validateExecutionOwnership(repo, message, execution);
   if (!execution.sessionId) return response(message, afterSeq, ACTIVE.has(message.status) ? 'preparing' : 'unavailable', execution, { reason: 'execution-session-not-recorded' });
   let observation;
   try {
-    const query = ctx?.sessionQuery ?? ctx?.get?.('sessionQuery');
+    // Cordis rejects property reads for services outside the plugin's inject
+    // list. sessionQuery is optional: resolve it through get before touching
+    // the property used by plain-context adapters.
+    const query = typeof ctx?.get === 'function' ? ctx.get('sessionQuery') : ctx?.sessionQuery;
     if (typeof query?.observeSession !== 'function') return response(message, afterSeq, 'unavailable', execution, { reason: 'session-query-unavailable' });
     observation = await query.observeSession(execution.sessionId, { signal, projectionMode: 'none' });
     abort(signal);
@@ -373,15 +440,18 @@ export async function readMessageExecution({ ctx, repo, groupId, messageId, afte
       return response(message, afterSeq, 'unavailable', parsed.execution, { reason: 'execution-reference-changed' });
     }
     execution = parsed.execution;
+    validateExecutionOwnership(repo, message, execution);
     const events = withoutColdRepairs(observationEvents(observation, execution.sessionId), observation, execution);
+    const session = sessionDescriptor(observation.header);
     const resolved = resolveSpan(events, execution);
-    if (!resolved.span) return response(message, afterSeq, resolved.pending && ACTIVE.has(message.status) ? 'preparing' : 'unavailable', execution, { reason: resolved.reason });
+    if (!resolved.span) return response(message, afterSeq, resolved.pending && ACTIVE.has(message.status) ? 'preparing' : 'unavailable', execution, { session, reason: resolved.reason });
     const { span } = resolved;
     execution = { ...execution, turn: span.turn, startSeq: span.startSeq };
     if (execution.endSeq === null && span.end && span.end.data?.reason?.kind !== 'interrupted') execution.endSeq = span.end.seq;
     const incomplete = !span.end || execution.endSeq === null;
     const result = response(message, afterSeq, 'available', execution, {
-      ...page(events, span, execution, afterSeq, limit),
+      session,
+      ...page(events, span, afterSeq, limit),
       ...(incomplete ? { reason: 'execution-log-incomplete' } : {}),
     });
     abort(signal);
@@ -392,6 +462,7 @@ export async function readMessageExecution({ ctx, repo, groupId, messageId, afte
     // A failed read can race terminal lifecycle updates too.
     message = target(repo, groupId, messageId);
     execution = reference(message).execution;
+    validateExecutionOwnership(repo, message, execution);
     // Do not return SDK exception text: storage errors can include private paths.
     return response(message, afterSeq, 'unavailable', execution, { reason: failureReason(error) });
   } finally {

package/host/native-activity.js

@@ -0,0 +1,225 @@
+/** Native activity is queried through public host services; no Agent is resumed. */
+function service(ctx, name) {
+  // Cordis guards property access with inject declarations, even for absent
+  // optional services. get() safely reads the store and may return undefined.
+  return typeof ctx?.get === 'function' ? ctx.get(name) : ctx?.[name];
+}
+function adapterOf(ctx) { return service(ctx, 'botTeamNativeActivity'); }
+
+/** Explicit adapters support isolated embedders/fixtures without fake idle states. */
+export function nativeConversationCapability({ ctx, pool } = {}) {
+  const adapter = adapterOf(ctx);
+  if (adapter) {
+    try {
+      const capability = typeof adapter.capability === 'function' ? adapter.capability({ ctx, pool }) : adapter.capability;
+      if (capability?.supported === true && typeof adapter.collect === 'function') return { ...capability, missing: capability.missing || [] };
+      return { supported: false, missing: capability?.missing || ['adapter'], reason: capability?.reason || '原生活动适配器不可用' };
+    } catch (error) { return { supported: false, missing: ['adapter'], reason: String(error?.message || error) }; }
+  }
+  const requirements = { agents: ['get', 'list', 'roots', 'isOwnedBy'], jobs: ['list'], goals: ['get'],
+    subagents: ['listDescendants', 'drainDescendants'], sessionQuery: ['observeSession'] };
+  const missing = [];
+  for (const [name, methods] of Object.entries(requirements)) {
+    const host = service(ctx, name);
+    for (const method of methods) if (typeof host?.[method] !== 'function') missing.push(name + '.' + method);
+  }
+  return { supported: missing.length === 0, missing,
+    ...(missing.length ? { reason: '宿主缺少可验证的原生活动查询能力：' + missing.join(', ') } : {}) };
+}
+
+// Installed rc.3 ApprovalService.setPolicy emits exactly this annotation via
+// agent.inject(...): next-step, wakeup=false. It carries no work to execute.
+// Keep every next-turn entry and every unrecognized next-step source blocking.
+function policyAnnotation(message) {
+  return message?.role === 'user' && message.source?.kind === 'user-approval' &&
+    Object.keys(message.source).length === 1 && message.content?.length === 1 &&
+    message.content[0]?.type === 'text' &&
+    /^The approval policy changed from "(ask|never)" to "(ask|never)" [(]changed by the user[)][.]$/.test(message.content[0].text);
+}
+
+function inboxSize(nextTurn, nextStep, annotations = false) {
+  return nextTurn.length + nextStep.filter(message => !annotations || !policyAnnotation(message)).length;
+}
+
+function persistedInbox(events, annotations = false) {
+  const lanes = { 'next-turn': [], 'next-step': [] };
+  for (const event of events) {
+    if (event.type !== 'agent/inbox/spliced') continue;
+    const data = event.data;
+    const lane = lanes[data?.target];
+    const removed = data?.removedCount ?? 0;
+    if (!lane || !Number.isSafeInteger(data.start) || data.start < 0 || data.start > lane.length ||
+      !Number.isSafeInteger(removed) || removed < 0 || data.start + removed > lane.length || !Array.isArray(data.inserted)) {
+      throw new Error('原生 inbox 历史无效');
+    }
+    lane.splice(data.start, removed, ...data.inserted);
+  }
+  return inboxSize(lanes['next-turn'], lanes['next-step'], annotations);
+}
+
+const missingSession = error => ['SESSION_QUERY_SESSION_NOT_FOUND', 'SESSION_QUERY_NOT_FOUND'].includes(error?.code);
+const terminalJob = status => ['completed', 'failed', 'killed'].includes(status);
+
+/**
+ * Async because the installed host's durable descendant catalog and cold
+ * Session observations are async. List.activity is deliberately ignored:
+ * external activations have no local Session and may misleadingly be inactive.
+ * Returns only blockers. Unknown observations fail closed, with a concrete cause.
+ */
+export async function collectNativeConversationBlockers({ ctx, repo, pool, groupId, interactions } = {}) {
+  const adapter = adapterOf(ctx);
+  const capability = nativeConversationCapability({ ctx, pool });
+  const blockers = [];
+  const add = (kind, message, extra = {}) => blockers.push({ code: 'conversation-busy', kind, groupId, message, ...extra });
+  if (!capability.supported) {
+    add('native-unsupported', capability.reason, { missing: capability.missing });
+    return blockers;
+  }
+  if (adapter) {
+    try {
+      const result = await adapter.collect({ ctx, repo, pool, groupId, interactions });
+      if (!Array.isArray(result)) throw new Error('原生活动适配器未返回阻塞列表');
+      return result;
+    } catch (error) {
+      add('native-unknown', '无法确认原生活动：' + String(error?.message || error));
+      return blockers;
+    }
+  }
+  const agents = service(ctx, 'agents');
+  const jobs = service(ctx, 'jobs');
+  const goals = service(ctx, 'goals');
+  const subagents = service(ctx, 'subagents');
+  const query = service(ctx, 'sessionQuery');
+  const roots = new Map();
+  const root = (sessionId, member) => { if (sessionId && !roots.has(sessionId)) roots.set(sessionId, member); };
+  for (const member of repo.members?.values() || []) if (member.groupId === groupId) {
+    root(member.sessionId, member);
+    for (const id of member.previousSessionIds || []) root(id, member);
+  }
+  for (const binding of repo.sessionBindings?.values() || []) if (binding.groupId === groupId) root(binding.sessionId, binding);
+  for (const [agent, owned] of pool?.owned || []) {
+    const member = repo.getMember?.(owned.membershipId);
+    if (member?.groupId === groupId) root(agent.id, member);
+  }
+  const ids = new Set(roots.keys());
+  const observed = new Map();
+  const checkLive = (agent, member, isRoot = false) => {
+    const details = { sessionId: agent.id, membershipId: member?.membershipId };
+    if (isRoot && (!agents.roots().includes(agent) || !pool?.owns?.(agent))) {
+      add('native-borrowed', '原生会话由其他所有者持有，无法关闭独立输入', details);
+    }
+    if (agent.status !== 'idle') add('native-agent', agent.status === 'running' ? '原生 Agent 仍在运行' : '无法确认原生 Agent 已空闲', details);
+    try {
+      const inbox = agent.inbox;
+      if (!Array.isArray(inbox?.nextTurn) || !Array.isArray(inbox?.nextStep)) throw new Error('缺少 inbox 查询');
+      if (inboxSize(inbox.nextTurn, inbox.nextStep, isRoot && pool?.owns?.(agent))) add('native-inbox', '原生 inbox 仍有待执行输入', details);
+    } catch (error) { add('native-unknown', '无法确认原生 inbox：' + String(error?.message || error), details); }
+    try {
+      const goal = goals.get(agent);
+      if (goal?.phase === 'active' && goal.activation === 'armed') add('native-goal', '原生目标仍获授权自动续跑', { ...details, goalId: goal.id });
+      else if (goal?.phase === 'active' && goal.activation !== 'disarmed') add('native-unknown', '无法确认原生目标的续跑授权', details);
+    } catch (error) { add('native-unknown', '无法读取原生目标：' + String(error?.message || error), details); }
+  };
+  for (const [sessionId, member] of roots) {
+    const live = agents.get(sessionId);
+    let absent = false;
+    observed.set(sessionId, live);
+    if (live) checkLive(live, member, true);
+    else {
+      let observation;
+      try {
+        observation = await query.observeSession(sessionId, { projectionMode: 'none' });
+        if (observation.header?.id !== sessionId || !Array.isArray(observation.events)) throw new Error('无效的原生 Session 观察');
+        if (persistedInbox(observation.events, true)) add('native-inbox', '历史原生 inbox 仍有未执行输入', { sessionId, membershipId: member?.membershipId });
+      } catch (error) {
+        if (missingSession(error)) absent = true; // Allocated ids need not have a log yet.
+        else {
+          add('native-unknown', '无法读取原生会话活动：' + String(error?.message || error), { sessionId });
+          continue;
+        }
+      } finally { observation?.[Symbol.dispose]?.(); }
+    }
+    try {
+      const descendants = await subagents.listDescendants(sessionId);
+      if (!Array.isArray(descendants)) throw new Error('无效的子代理列表');
+      for (const child of descendants) {
+        ids.add(child.id);
+        const details = { sessionId: child.id, parentSessionId: child.parentId, rootSessionId: sessionId, membershipId: member?.membershipId };
+        if (child.kind !== 'child' || child.mode === 'external' || child.mode === 'unknown') {
+          // Exact owned teardown has awaited the manager's complete forest.
+          if (!live && pool?.drainedSessions?.has(sessionId)) continue;
+          add('native-descendant-unknown', '无法证明子代理已停止：' + (child.reason || child.mode || '未知类型'), details);
+          continue;
+        }
+        const agent = agents.get(child.id);
+        observed.set(child.id, agent);
+        if (agent) checkLive(agent, member);
+        else if (child.activity === 'running') add('native-descendant-unknown', '子代理 Session 仍驻留，但无法读取其 Agent 活动', details);
+        else {
+          let observation;
+          try {
+            observation = await query.observeSession(child.id, { projectionMode: 'none' });
+            if (observation.header?.id !== child.id || !Array.isArray(observation.events)) throw new Error('无效的子代理 Session 观察');
+            if (persistedInbox(observation.events)) add('native-inbox', '子代理 inbox 仍有未执行输入', details);
+          } catch (error) {
+            if (!missingSession(error)) add('native-descendant-unknown', '无法读取子代理 inbox：' + String(error?.message || error), details);
+          } finally { observation?.[Symbol.dispose]?.(); }
+        }
+      }
+    } catch (error) {
+      if (!absent || !missingSession(error)) add('native-unknown', '无法读取原生子代理：' + String(error?.message || error), { sessionId });
+    }
+  }
+  // Registry ownership also covers live children before their durable catalog
+  // publication; iterate to include descendants of every exact observed owner.
+  let grew;
+  do {
+    grew = false;
+    for (const agent of agents.list()) {
+      if (ids.has(agent.id)) continue;
+      const parent = [...ids].map(id => agents.get(id)).find(owner => owner && agents.isOwnedBy(agent.id, owner));
+      // A manager-owned child can survive a missing root writer/catalog. Its
+      // immutable parentSession still ties that live activity to this group.
+      const parentSession = agent.session?.header?.parentSession;
+      const parentId = typeof parentSession === 'string' ? parentSession : parentSession?.id;
+      if (!parent && !ids.has(parentId)) continue;
+      ids.add(agent.id);
+      observed.set(agent.id, agent);
+      checkLive(agent);
+      grew = true;
+    }
+  } while (grew);
+  for (const sessionId of ids) {
+    try {
+      const listed = jobs.list(sessionId);
+      if (!Array.isArray(listed)) throw new Error('无效的后台作业列表');
+      for (const job of listed) if (job.owner === sessionId && !terminalJob(job.status)) add('native-job', '原生后台作业尚未结束', { sessionId, jobId: job.id, status: job.status });
+    } catch (error) { add('native-unknown', '无法读取原生后台作业：' + String(error?.message || error), { sessionId }); }
+  }
+  // status intentionally reports idle during native maintenance. whenIdle is
+  // public and includes its activityDone promise; a one-turn probe distinguishes
+  // settled idle from ongoing maintenance without waiting for work to finish.
+  for (const [sessionId, agent] of observed) if (agent?.status === 'idle') {
+    try {
+      if (typeof agent.whenIdle !== 'function') throw new Error('缺少 whenIdle 查询');
+      let immediate;
+      const idle = await Promise.race([
+        Promise.resolve(agent.whenIdle()).then(() => true),
+        new Promise(resolve => { immediate = setImmediate(() => resolve(false)); }),
+      ]).finally(() => clearImmediate(immediate));
+      if (!idle) add('native-agent', '原生 Agent 仍有维护或待收尾活动', { sessionId });
+    } catch (error) { add('native-unknown', '无法确认原生 Agent 已完成活动：' + String(error?.message || error), { sessionId }); }
+  }
+  for (const [sessionId, initial] of observed) {
+    const current = agents.get(sessionId);
+    if (current !== initial) add('native-changed', '检查期间原生 Agent 已变更，请重试', { sessionId });
+    else if (current) checkLive(current, roots.get(sessionId), roots.has(sessionId));
+  }
+  if (pool?.isPreparingGroup?.(groupId)) add('native-preparing', '原生 Agent 或输入正在准备');
+  const pendingInteractions = new Set([...(interactions?.entries?.values() || []), ...(interactions?.responding || [])]);
+  for (const entry of pendingInteractions) if (entry.view?.groupId === groupId && (entry.busy || !['done', 'settled'].includes(entry.view.state))) {
+    add('native-interaction', entry.busy ? '原生交互回答正在提交' : '原生交互尚未完成', { sessionId: entry.view.sessionId, interactionId: entry.view.interactionId });
+  }
+  const unique = new Map(blockers.map(value => [[value.kind, value.sessionId, value.jobId, value.interactionId, value.goalId].join(':'), value]));
+  return [...unique.values()];
+}