minimal-agent 0.18.6 → 0.18.7

package/src/loop.ts

@@ -28,6 +28,9 @@
  */
 
 import crypto from 'node:crypto';
+import { answerPreparationNotice } from './runtime/answerPreparation.js';
+import { finalAnswerMessages } from './runtime/finalAnswer.js';
+import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
 import { conciseToolPath } from './runtime/toolDisplay.js';
 import { dirname, resolve } from 'node:path';
 import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
@@ -100,6 +103,7 @@ import {
 } from './advisor/advisorCoordinator.js';
 import { toolEffectFor } from './tools/capabilities.js';
 import { isReadOnlyShellCommand, isVerificationShellCommand } from './tools/bash/semantics.js';
+import { collectReviewContext } from './advisor/reviewContext.js';
 import {
   createAgentRuntimeContext,
   type AgentRuntimeContext,
@@ -410,11 +414,13 @@ export async function* runQuery(
   if (!computerIntent.needed && sessionState) delete sessionState.computerAutomation;
   // DI fallback：测试可传 stub，生产走真实模块单例
   const chatFn = options.chat ?? defaultChat;
+  const trace = createLifecycleTrace('loop');
   const executeToolFn = options.executeTool ?? defaultExecuteTool;
   const explicitFileDeliveryRequested = expectsFormalDelivery(userInput);
   const currentUserMessageId = options.userMessageId ?? crypto.randomUUID();
 
   let currentTransientBundle = options.transientBundle;
+  let advisorContextBundle = currentTransientBundle;
   let modelEnvironmentCwd = runtimeContext.cwd;
   const observedRuleScopes = new Map<string, string>();
   const pendingRuleScopes = new Set<string>();
@@ -435,6 +441,7 @@ export async function* runQuery(
     const selected = availableForBundle >= bundle.diagnostics.usedTokens
       ? bundle
       : resizeContextBundle(bundle, availableForBundle);
+    advisorContextBundle = selected;
     return [selected.text, opaque].filter(Boolean).join('\n\n');
   };
   let resultPresented = false;
@@ -452,6 +459,16 @@ export async function* runQuery(
     executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
     history,
     sessionState,
+    advisorReviewContext: () => ({
+      ...collectReviewContext(advisorContextBundle),
+      constraints: [...collectReviewContext(advisorContextBundle).constraints,
+        { id: 'execution.boundary', authority: 'host', content: JSON.stringify({ cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+          conversationMode: toolCallContext.conversationMode, profile: runtimeContext.profile,
+          availableTools: [...currentEffectiveToolSet.names], invocation: invocationInstructions(options.invocationPolicy) }) }],
+      omittedIds: [...new Set([...(currentTransientBundle?.diagnostics.omittedIds ?? []), ...(advisorContextBundle?.diagnostics.omittedIds ?? [])]),
+        ...(options.transientContext ? ['legacy.transient-context:not-forwarded'] : [])],
+      clippedIds: [...new Set([...(currentTransientBundle?.diagnostics.clippedIds ?? []), ...(advisorContextBundle?.diagnostics.clippedIds ?? [])])],
+    }),
     // Statistics only; consultations have no per-turn quota.
     advisorCalls: { used: 0 },
     advisorInvocation: 'agent',
@@ -910,7 +927,17 @@ export async function* runQuery(
     }
 
     // 3. 调 LLM 并组装 assistant 消息
+    trace('model_start');
     let assistantText = '';
+    // Candidate text is private until the delivery gates allow publication.
+    // Keep the compatibility event as a phase notice, never as a text retraction.
+    function* retireDraft(reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted'): Generator<LoopEvent> {
+      const message: Message = { role: 'system', content: answerPreparationNotice(reason), id: crypto.randomUUID(),
+        timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+      history.push(message);
+      yield { type: 'injected_message', message };
+      if (reason !== 'interrupted') yield { type: 'assistant_draft_discarded', reason, textLength: 0 };
+    }
     /** 按 index 累积 tool_calls（OpenAI 协议下 tool_calls 是分片返回的） */
     const toolCallsByIndex: ToolCall[] = [];
     /**
@@ -921,9 +948,6 @@ export async function* runQuery(
     let reasoningString = '';
     const reasoningDetails: unknown[] = [];
 
-    /** 首个 text_delta 时切到 streaming，再来不重复 yield */
-    let stageStreamingYielded = false;
-
     /**
      * R2：本轮 LLM 流的终止原因（来自 client 的 done.stopReason）。
      * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
@@ -956,12 +980,7 @@ export async function* runQuery(
           : {}),
       })) {
         if (ev.type === 'text_delta') {
-          if (!stageStreamingYielded) {
-            stageStreamingYielded = true;
-            yield { type: 'stage_change', stage: 'streaming' };
-          }
           assistantText += ev.delta;
-          yield { type: 'text', delta: ev.delta };
         } else if (ev.type === 'tool_call_delta') {
           mergeToolCallDelta(toolCallsByIndex, ev);
         } else if (ev.type === 'reasoning_delta') {
@@ -1002,7 +1021,9 @@ export async function* runQuery(
         }
       }
     } catch (e) {
+      trace('model_error');
       if ((e as Error).name === 'AbortError') {
+        yield* retireDraft('interrupted');
         yield interruption();
         return;
       }
@@ -1026,6 +1047,7 @@ export async function* runQuery(
             options.promptCache,
           );
         } catch (error) {
+          yield* retireDraft('interrupted');
           if (signal?.aborted || (error as Error).name === 'AbortError') {
             yield interruption();
             return;
@@ -1057,6 +1079,7 @@ export async function* runQuery(
       }
 
       // code='llm_error'：终结性错误，stop_reason='error'
+      yield* retireDraft('interrupted');
       yield {
         type: 'error',
         error: `LLM 调用失败：${(e as Error).message}`,
@@ -1065,7 +1088,9 @@ export async function* runQuery(
       return;
     }
 
+    trace('model_end');
     if (lastFinishReason === 'aborted' || signal?.aborted || options.hasQueuedInput?.()) {
+      yield* retireDraft('interrupted');
       if (options.hasQueuedInput?.() && !signal?.aborted) {
         pushQueuedInputMarker(history);
         yield { type: 'interrupted', reason: 'queued_input' };
@@ -1086,6 +1111,19 @@ export async function* runQuery(
       }
     }
 
+    // A pending review must run before another solving/publishing attempt.
+    // Read-only diagnosis and human questions remain available while stalled.
+    const pendingReview = options.advisorCheckpoints === false ? undefined : advisorCoordinator.pendingReview();
+    if (pendingReview && turn < maxTurns && toolCallsByIndex.length > 0
+      && !toolCallsByIndex.some(tc => ['Advisor', 'AskUserQuestion'].includes(tc.function.name))
+      && toolCallsByIndex.some(tc => tc.function.name === 'PresentResult'
+        || advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find(t => t.name === tc.function.name), { treatVerificationAsReadOnly: true }).mutatesWorkspace
+        || stallGuard.shouldReject(tc))) {
+      yield* retireDraft('advisor_checkpoint');
+      toolCallsByIndex.splice(0, toolCallsByIndex.length, { id: crypto.randomUUID(), type: 'function',
+        function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) } });
+      assistantText = '';
+    }
     const assistantMsg: Message = {
       role: 'assistant',
       content: assistantText.length > 0 ? assistantText : null,
@@ -1098,12 +1136,12 @@ export async function* runQuery(
       ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
     };
     // 4. 没有工具调用 → 整轮交互结束
-    if (toolCallsByIndex.length === 0) {
+    finalResponse: if (toolCallsByIndex.length === 0) {
       if (!askCorrectionAttempted && runtimeContext.interactiveAsk
         && currentEffectiveToolSet.names.has('AskUserQuestion')
         && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
         askCorrectionAttempted = true;
-        yield { type: 'assistant_draft_discarded', reason: 'interactive_question', textLength: assistantText.length };
+        yield* retireDraft('interactive_question');
         continue;
       }
       const emptyResponse = stripThinkBlocks(assistantText).length === 0;
@@ -1112,12 +1150,11 @@ export async function* runQuery(
       if (pendingDelegations.length && !delegationCorrectionAttempted && turn < maxTurns) {
         delegationCorrectionAttempted = true;
         coordinationText = coordination!.text;
-        yield { type: 'assistant_draft_discarded', reason: 'formal_delivery', textLength: assistantText.length };
+        yield* retireDraft('formal_delivery');
         continue;
       }
       const pendingMessages = [...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext)];
       if (pendingMessages.length) {
-        if (!emptyResponse) history.push(assistantMsg);
         history.push(...pendingMessages);
         continue;
       }
@@ -1131,22 +1168,27 @@ export async function* runQuery(
         && turn < maxTurns
       ) {
         deliveryCorrectionAttempted = true;
-        yield {
-          type: 'assistant_draft_discarded',
-          reason: 'formal_delivery',
-          textLength: assistantText.length,
-        };
+        yield* retireDraft('formal_delivery');
         continue;
       }
-      const deliveryCheckpoint = emptyResponse
+      const deliveryCheckpoint = emptyResponse || options.advisorCheckpoints === false
         ? { allow: true as const }
         : advisorCoordinator.beforeDelivery(assistantText);
+      const fallbackReview = !emptyResponse && options.advisorCheckpoints !== false
+        ? advisorCoordinator.pendingReview(assistantText) : undefined;
+      if (fallbackReview && turn < maxTurns) {
+        yield* retireDraft('advisor_checkpoint');
+        // Reuse the effective tool boundary, permissions, cancellation, events and
+        // persistence. Never call a provider behind the host's tool pipeline.
+        toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+          name: 'Advisor', arguments: JSON.stringify(fallbackReview),
+        } });
+        assistantMsg.content = null;
+        assistantMsg.tool_calls = toolCallsByIndex;
+        break finalResponse;
+      }
       if (!deliveryCheckpoint.allow && turn < maxTurns) {
-        yield {
-          type: 'assistant_draft_discarded',
-          reason: 'advisor_checkpoint',
-          textLength: assistantText.length,
-        };
+        yield* retireDraft('advisor_checkpoint');
         continue;
       }
       if (!emptyResponse) {
@@ -1156,19 +1198,110 @@ export async function* runQuery(
       if (emptyResponse) {
         // A no-tool response is already the model's terminal signal. Do not turn it
         // into another model round, and do not persist/broadcast an empty bubble.
-        yield {
-          type: 'assistant_draft_discarded',
-          reason: 'empty_response',
-          textLength: assistantText.length,
-        };
+        yield* retireDraft('empty_response');
       } else {
+        // Publication is a separate tool-free request. Nothing from preparation
+        // has been streamed, and no gate may retract text after this boundary.
+        let publicationError: unknown;
+        let publicationInterrupted = false;
+        let streamed = false;
+        if (!options.responseFormat && runtimeContext.profile === 'main'
+          && (runtimeContext.surface === 'desktop' || runtimeContext.surface === 'tui')) {
+          const candidate = assistantText;
+          const candidateFinishReason = lastFinishReason;
+          let publishedText = '';
+          let publicationDone = false;
+          yield { type: 'stage_change', stage: 'streaming' };
+          try {
+            const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText);
+            const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
+            if (publicationPlan.overBudget) throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
+            if (signal?.aborted || options.hasQueuedInput?.()) {
+              publicationInterrupted = true;
+              throw new Error('最终发布已取消。');
+            }
+            turnUsage.totalCalls += 1;
+            for await (const event of chatFn({
+              provider,
+              messages: publicationMessages,
+              tools: [], signal,
+              conversationMode: runtimeContext.conversationMode ?? 'private',
+              promptCache: options.promptCache,
+            })) {
+              if (event.type === 'done' && !publicationDone) {
+                publicationDone = true;
+                if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
+                  turnUsage.reportedCalls += 1;
+                  turnUsage.inputTokens += event.promptTokens ?? 0;
+                  turnUsage.outputTokens += event.outputTokens ?? 0;
+                }
+              }
+              if (signal?.aborted || options.hasQueuedInput?.()) {
+                publicationInterrupted = true;
+                break;
+              }
+              if (event.type === 'text_delta') {
+                // Never expose a rewrite of the reviewed candidate. Previously
+                // published chunks are necessarily an exact prefix of it.
+                if (!candidate.startsWith(publishedText + event.delta)) {
+                  throw new Error('发布内容偏离定稿，使用原定稿。');
+                }
+                publishedText += event.delta;
+                streamed = true;
+                yield { type: 'text', delta: event.delta };
+              } else if (event.type === 'tool_call_delta') {
+                throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
+              } else if (event.type === 'done') {
+                publicationDone = true;
+                lastFinishReason = event.stopReason;
+                if (event.stopReason === 'aborted') publicationInterrupted = true;
+              }
+            }
+            if (!publicationDone && !publicationInterrupted) throw new Error('最终答案流未正常结束。');
+            if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length') throw new Error('最终答案流缺少有效的结束状态。');
+            if (!publishedText.trim() && !publicationInterrupted) throw new Error('最终表达未返回正文。');
+            if (!publicationInterrupted && publishedText !== candidate) throw new Error('最终表达未完整传递定稿。');
+          } catch (error) {
+            publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || (error as Error)?.name === 'AbortError';
+            publicationError = error;
+          }
+          if (publicationError && !publicationInterrupted) {
+            yield { type: 'warning', message: '流式发布未完成，已使用原定稿补齐；未重新生成或改写答案。' };
+            const remaining = candidate.slice(publishedText.length);
+            if (remaining) {
+              yield { type: 'text', delta: remaining };
+              streamed = true;
+            }
+            publishedText = candidate;
+            publicationError = undefined;
+          }
+          assistantText = publishedText;
+          if (!publicationInterrupted) lastFinishReason = candidateFinishReason;
+          assistantMsg.content = publishedText || null;
+          if (!publishedText) {
+            if (publicationInterrupted) yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+            else yield { type: 'error', code: 'llm_error', error: `最终答案生成失败：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+            return;
+          }
+        }
+        assistantMsg.presentation = 'final';
+        trace('final_published');
         if (assistantMsg.role === 'assistant') assistantMsg.advisorTaskVersion = advisorCoordinator.versions.taskVersion;
         assistantMsg.advisorCheckpoints = advisorCoordinator.drainDegradations();
         history.push(assistantMsg);
+        // Non-interactive consumers retain atomic output. Interactive hosts
+        // already received real deltas; commit the identical text only once.
+        if (!streamed) yield { type: 'text', delta: assistantText };
         yield {
           type: 'assistant_message',
           message: assistantMsg as Extract<Message, { role: 'assistant' }>,
         };
+        if (publicationInterrupted || publicationError) {
+          yield { type: 'warning', message: '最终答案未完整生成，已保留已输出内容；未撤回或重新生成。' };
+          if (publicationInterrupted) yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+          else yield { type: 'error', code: 'llm_error', error: `最终答案流中断：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+          return;
+        }
       }
       // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
       // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
@@ -1220,7 +1353,11 @@ export async function* runQuery(
         ...turnUsage,
         trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
       };
-      if (pendingDelegations.length) {
+      if (emptyResponse && !resultPresented) {
+        const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+        yield { type: 'warning', message: warning };
+        yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
+      } else if (pendingDelegations.length) {
         const warning = `必要子任务尚未收口：${pendingDelegations.map((r) => r.id).join(', ')}。本轮不能视为全部完成。`;
         yield { type: 'warning', message: warning };
         yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning, usage };
@@ -1240,11 +1377,14 @@ export async function* runQuery(
           usage,
         };
       } else {
-        yield { type: 'turn_done', completionStatus: 'completed', usage };
+        yield { type: 'turn_done', completionStatus: 'completed', usage,
+          ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}) };
       }
       return;
     }
 
+    assistantMsg.presentation = 'progress';
+    trace('progress_published');
     history.push(assistantMsg);
     yield {
       type: 'assistant_message',
@@ -1471,7 +1611,19 @@ export async function* runQuery(
     };
 
     const runOne: typeof runOneImpl = async (tc, reportProgress) => {
+      // Also settle denied/invalid/unavailable calls that never reached the
+      // provider adapter. This records a real attempt, not an ignored reminder.
+      let consultation;
+      if (tc.function.name === 'Advisor') {
+        let reason: import('./types.js').AdvisorReason | undefined;
+        try { reason = JSON.parse(tc.function.arguments).reason; } catch { /* validation handles malformed input */ }
+        consultation = advisorCoordinator.beginConsultation(reason);
+      }
       const outcome = await runOneImpl(tc, reportProgress);
+      if (consultation && outcome.result.metadata?.kind !== 'advisor_consultation'
+        && !( !outcome.result.ok && outcome.result.error === 'aborted')) {
+        outcome.result = { ...outcome.result, metadata: advisorCoordinator.finishConsultation(consultation, outcome.result.ok) };
+      }
       const metadata = outcome.result.metadata;
       if (metadata?.kind === 'advisor_decision' && outcome.result.ok
         || metadata?.kind === 'advisor_consultation') {
@@ -1788,6 +1940,7 @@ export function buildModelMessages(
   transientContext?: string,
   currentUserMessageId?: string,
 ): Message[] {
+  history = history.filter(message => !(message.role === 'system' && message._ephemeral));
   const transient = transientContext?.trim();
   if (!transient) return history;
   let index = currentUserMessageId

package/src/prompts/policyRegistry.js

@@ -193,10 +193,18 @@ const CAPABILITY_POLICIES = [
         render: ({ toolNames }) => `- 需求匹配已安装 Skill 或用户点名时，${skillInvokeInstruction(toolNames.has('Skill'))}；前端开发与交互修复也要主动匹配设计技能，不等用户说“设计”。引用资源按需读取，多阶段按需组合，不预读整个目录或加载无关技能。`,
     },
     {
-        id: 'execution.desktop-diagrams', layer: 'execution', profiles: MAIN_PROFILE, source: 'native',
-        render: ({ surface, toolNames }) => surface === 'desktop'
-            ? `- Desktop 需要架构、流程或关系图时，${toolNames.has('Skill') || toolNames.has('Read') ? '优先加载可用的 dynamic-ui，按规范输出 svg 围栏；' : ''}少用大段 ASCII 框图。简单文字、清晰表格不画图；用户指定 ASCII 或原样代码/目录树除外。图不可用时用文字/表格，保留关键结论，不伪造控件或成果。`
-            : '- 纯文本回复不输出 SVG 源码，改用文字或表格。',
+        id: 'execution.desktop-diagrams', layer: 'execution', profiles: ALL_PROFILES, source: 'native',
+        render: ({ surface, toolNames }) => [
+            '- 按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。',
+            surface === 'desktop'
+                ? '- Desktop/Web 聊天支持 mermaid 和 svg 围栏，不用裸 HTML。'
+                : surface === 'cli' || surface === 'tui'
+                    ? '- CLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。'
+                    : '- 跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。',
+            toolNames.has('Skill') || toolNames.has('Read')
+                ? '- 加载可用的 dynamic-ui。'
+                : '',
+        ].filter(Boolean).join('\n'),
     },
     {
         id: 'capability.session-worktree', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
@@ -246,12 +254,12 @@ const CAPABILITY_POLICIES = [
         requiresTools: ['Advisor'],
         // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
         // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
-        render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：Advisor 是第二意见，主 Agent 自行核实并决定采纳、部分采纳或拒绝；顾问不授予权限，也不替用户验收。
-  咨询条件只有：计划准备执行前（reason=plan_review）、实质结果提交前（delivery_review）、同一问题两次或以上处理失败后（stalled）、用户明显不满意（user_dissatisfaction）、自身非常不确定或无法解决（uncertainty）。只读调查不等于计划执行；按问题与阶段咨询，不因命令字符串、工具切换或每次写入重新咨询。
-  同阶段同问题已有咨询结果就继续执行；仅新出现的实质问题或两次失败触发再咨询，换工具不清零失败次数，无关失败不合并。
+        render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：提供第二意见，由主 Agent 核实取舍；不授予权限、不替用户验收。
+  咨询时机：实质计划执行前（plan_review）、实质交付前（delivery_review）、同一问题两次或以上处理失败后（stalled）、用户明显不满意（user_dissatisfaction）、非常不确定或无法解决（uncertainty）、关键证据冲突无法消解（evidence_conflict）。换工具不清零失败次数，无关失败不合并。
+  文字调研、计算、比较和推荐也是交付；自信、没文件不豁免。自动咨询不再问用户；寒暄、进度、拼写修正无需咨询。
+  同阶段不重复问；成果、假设实质变化或新冲突才重开。questions/note 指明疑点与证据 ID，历史由宿主附带。缺材料先补查，不算验证通过。读完意见再操作；暂缓操作未执行，提醒不算咨询。
   不设咨询配额，每次咨询只尝试一次；失败、空答或超时自行降级继续，不转成人工审批，也不宣称获得验证。
-  依据代码、测试和用户要求判断意见，${toolNames.has('AdvisorDecision') ? '可用 AdvisorDecision 记录 accept/partial/reject；登记失败不阻止执行。' : '直接说明采纳判断。'}证据冲突以实测为准，仅无法判断时复核咨询。
-  提供关键疑点与必要现场，返回后先读结果再决定后续行动；同批暂缓调用不是执行证据，不因此重复咨询。`,
+  以代码、测试和用户要求核实意见，${toolNames.has('AdvisorDecision') ? '可用 AdvisorDecision 记录 accept/partial/reject；登记失败不阻止执行。' : '直接说明采纳判断。'}顾问不是事实来源，冲突以实测为准。`,
     },
     {
         id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',

package/src/prompts/policyRegistry.ts

@@ -240,10 +240,18 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
     render: ({ toolNames }) => `- 需求匹配已安装 Skill 或用户点名时，${skillInvokeInstruction(toolNames.has('Skill'))}；前端开发与交互修复也要主动匹配设计技能，不等用户说“设计”。引用资源按需读取，多阶段按需组合，不预读整个目录或加载无关技能。`,
   },
   {
-    id: 'execution.desktop-diagrams', layer: 'execution', profiles: MAIN_PROFILE, source: 'native',
-    render: ({ surface, toolNames }) => surface === 'desktop'
-      ? `- Desktop 需要架构、流程或关系图时，${toolNames.has('Skill') || toolNames.has('Read') ? '优先加载可用的 dynamic-ui，按规范输出 svg 围栏；' : ''}少用大段 ASCII 框图。简单文字、清晰表格不画图；用户指定 ASCII 或原样代码/目录树除外。图不可用时用文字/表格，保留关键结论，不伪造控件或成果。`
-      : '- 纯文本回复不输出 SVG 源码，改用文字或表格。',
+    id: 'execution.desktop-diagrams', layer: 'execution', profiles: ALL_PROFILES, source: 'native',
+    render: ({ surface, toolNames }) => [
+      '- 按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。',
+      surface === 'desktop'
+        ? '- Desktop/Web 聊天支持 mermaid 和 svg 围栏，不用裸 HTML。'
+        : surface === 'cli' || surface === 'tui'
+          ? '- CLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。'
+          : '- 跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。',
+      toolNames.has('Skill') || toolNames.has('Read')
+        ? '- 加载可用的 dynamic-ui。'
+        : '',
+    ].filter(Boolean).join('\n'),
   },
   {
     id: 'capability.session-worktree', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
@@ -293,12 +301,12 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
     requiresTools: ['Advisor'],
     // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
     // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
-    render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：Advisor 是第二意见，主 Agent 自行核实并决定采纳、部分采纳或拒绝；顾问不授予权限，也不替用户验收。
-  咨询条件只有：计划准备执行前（reason=plan_review）、实质结果提交前（delivery_review）、同一问题两次或以上处理失败后（stalled）、用户明显不满意（user_dissatisfaction）、自身非常不确定或无法解决（uncertainty）。只读调查不等于计划执行；按问题与阶段咨询，不因命令字符串、工具切换或每次写入重新咨询。
-  同阶段同问题已有咨询结果就继续执行；仅新出现的实质问题或两次失败触发再咨询，换工具不清零失败次数，无关失败不合并。
+    render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：提供第二意见，由主 Agent 核实取舍；不授予权限、不替用户验收。
+  咨询时机：实质计划执行前（plan_review）、实质交付前（delivery_review）、同一问题两次或以上处理失败后（stalled）、用户明显不满意（user_dissatisfaction）、非常不确定或无法解决（uncertainty）、关键证据冲突无法消解（evidence_conflict）。换工具不清零失败次数，无关失败不合并。
+  文字调研、计算、比较和推荐也是交付；自信、没文件不豁免。自动咨询不再问用户；寒暄、进度、拼写修正无需咨询。
+  同阶段不重复问；成果、假设实质变化或新冲突才重开。questions/note 指明疑点与证据 ID，历史由宿主附带。缺材料先补查，不算验证通过。读完意见再操作；暂缓操作未执行，提醒不算咨询。
   不设咨询配额，每次咨询只尝试一次；失败、空答或超时自行降级继续，不转成人工审批，也不宣称获得验证。
-  依据代码、测试和用户要求判断意见，${toolNames.has('AdvisorDecision') ? '可用 AdvisorDecision 记录 accept/partial/reject；登记失败不阻止执行。' : '直接说明采纳判断。'}证据冲突以实测为准，仅无法判断时复核咨询。
-  提供关键疑点与必要现场，返回后先读结果再决定后续行动；同批暂缓调用不是执行证据，不因此重复咨询。`,
+  以代码、测试和用户要求核实意见，${toolNames.has('AdvisorDecision') ? '可用 AdvisorDecision 记录 accept/partial/reject；登记失败不阻止执行。' : '直接说明采纳判断。'}顾问不是事实来源，冲突以实测为准。`,
   },
   {
     id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',

package/src/runtime/answerPreparation.js

@@ -0,0 +1,9 @@
+export function answerPreparationNotice(reason) {
+    switch (reason) {
+        case 'advisor_checkpoint': return '交付前复核：正在核查内部候选结论，完成后发布最终答案。';
+        case 'formal_delivery': return '整理交付：正在核对委派结果或补齐正式成果提交。';
+        case 'interactive_question': return '等待关键决策：接下来通过交互问题确认，请在输入区作答。';
+        case 'empty_response': return '本轮未产生可显示的正文，未生成新的最终答复。';
+        case 'interrupted': return '生成未完成，未发布最终答案。';
+    }
+}

package/src/runtime/answerPreparation.ts

@@ -0,0 +1,11 @@
+import type { LoopEvent } from '../types.js';
+
+export function answerPreparationNotice(reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted'): string {
+  switch (reason) {
+    case 'advisor_checkpoint': return '交付前复核：正在核查内部候选结论，完成后发布最终答案。';
+    case 'formal_delivery': return '整理交付：正在核对委派结果或补齐正式成果提交。';
+    case 'interactive_question': return '等待关键决策：接下来通过交互问题确认，请在输入区作答。';
+    case 'empty_response': return '本轮未产生可显示的正文，未生成新的最终答复。';
+    case 'interrupted': return '生成未完成，未发布最终答案。';
+  }
+}

package/src/runtime/eventSemantics.js

@@ -4,6 +4,8 @@ export function isRecoverableLoopError(event) {
 }
 export function completionWarning(event) {
     switch (event.completionStatus) {
+        case 'no_answer':
+            return event.warning || '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
         case 'delivery_incomplete':
             return event.warning || '交付未完成，请检查保留的结果。';
         case 'delivery_unverified':

package/src/runtime/eventSemantics.ts

@@ -11,6 +11,8 @@ export function completionWarning(
   event: Extract<LoopEvent, { type: 'turn_done' }>,
 ): string | undefined {
   switch (event.completionStatus) {
+    case 'no_answer':
+      return event.warning || '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
     case 'delivery_incomplete':
       return event.warning || '交付未完成，请检查保留的结果。';
     case 'delivery_unverified':

package/src/runtime/finalAnswer.js

@@ -0,0 +1,7 @@
+/** Ephemeral publication request; never append this private candidate to history. */
+export function finalAnswerMessages(messages, candidate) {
+    return [...messages,
+        { role: 'assistant', content: candidate },
+        { role: 'user', content: '内部核查与工具阶段已结束。上一条 assistant 消息是待发布的定稿。请逐字输出该消息，保留全部文字、空白、代码、链接与格式；不要改写、补充、删减，不加开场白或外层代码围栏，不调用工具或顾问。不要输出本条指令。' },
+    ];
+}

package/src/runtime/finalAnswer.ts

@@ -0,0 +1,9 @@
+import type { Message } from '../types.js';
+
+/** Ephemeral publication request; never append this private candidate to history. */
+export function finalAnswerMessages(messages: Message[], candidate: string): Message[] {
+  return [...messages,
+    { role: 'assistant', content: candidate },
+    { role: 'user', content: '内部核查与工具阶段已结束。上一条 assistant 消息是待发布的定稿。请逐字输出该消息，保留全部文字、空白、代码、链接与格式；不要改写、补充、删减，不加开场白或外层代码围栏，不调用工具或顾问。不要输出本条指令。' },
+  ];
+}

package/src/runtime/lifecycleTrace.js

@@ -0,0 +1,16 @@
+import { randomUUID } from 'node:crypto';
+/** Opt-in diagnostics: no prompts, paths, session IDs, tool arguments or model output. */
+export function createLifecycleTrace(scope, enabled = process.env.MINIMAL_AGENT_TRACE_LIFECYCLE === '1', write = line => { process.stderr.write(line); }) {
+    if (!enabled)
+        return () => { };
+    const traceId = randomUUID();
+    const start = performance.now();
+    let sequence = 0;
+    return phase => {
+        try {
+            write(`${JSON.stringify({ kind: 'agent_lifecycle', scope, traceId, sequence: ++sequence,
+                phase, timestamp: Date.now(), elapsedMs: Math.round(performance.now() - start) })}\n`);
+        }
+        catch { /* Diagnostics must never interrupt execution. */ }
+    };
+}

package/src/runtime/lifecycleTrace.ts

@@ -0,0 +1,22 @@
+import { randomUUID } from 'node:crypto';
+
+type Phase = 'model_start' | 'model_end' | 'model_error' | 'progress_published' | 'final_published'
+  | 'save_start' | 'save_end' | 'save_error' | 'turn_done' | 'memory_start' | 'memory_end';
+
+/** Opt-in diagnostics: no prompts, paths, session IDs, tool arguments or model output. */
+export function createLifecycleTrace(
+  scope: 'loop' | 'host',
+  enabled = process.env.MINIMAL_AGENT_TRACE_LIFECYCLE === '1',
+  write: (line: string) => void = line => { process.stderr.write(line); },
+): (phase: Phase) => void {
+  if (!enabled) return () => {};
+  const traceId = randomUUID();
+  const start = performance.now();
+  let sequence = 0;
+  return phase => {
+    try {
+      write(`${JSON.stringify({ kind: 'agent_lifecycle', scope, traceId, sequence: ++sequence,
+        phase, timestamp: Date.now(), elapsedMs: Math.round(performance.now() - start) })}\n`);
+    } catch { /* Diagnostics must never interrupt execution. */ }
+  };
+}

package/src/session/runTurn.js

@@ -19,6 +19,7 @@
  * ============================================================
  */
 import { acquireContextLock } from '../context/contextLock.js';
+import { createLifecycleTrace } from '../runtime/lifecycleTrace.js';
 import { loadContext, saveContext } from '../context/persistContext.js';
 import { startTurnJournal } from '../memory/turnJournal.js';
 import { createLearningModel } from '../memory/learningModel.js';
@@ -69,6 +70,7 @@ export async function* runTurn(opts) {
         return null;
     });
     let completedNormally = false;
+    const trace = createLifecycleTrace('host');
     let hostFailed = false;
     try {
         for await (const event of runWithPlugins(opts.userInput, {
@@ -107,8 +109,18 @@ export async function* runTurn(opts) {
             // at stage boundaries so a Runtime restart does not lose the whole workflow.
             if (persist && (['user_message_committed', 'assistant_message', 'compact_start', 'turn_done'].includes(event.type)
                 || (event.type === 'injected_message' && event.message && typeof event.message === 'object' && 'role' in event.message && event.message.role === 'system' && '_uiProgress' in event.message && event.message._uiProgress === true))) {
-                await saveContext(history, opts.sessionFile);
+                trace('save_start');
+                try {
+                    await saveContext(history, opts.sessionFile);
+                    trace('save_end');
+                }
+                catch (error) {
+                    trace('save_error');
+                    throw error;
+                }
             }
+            if (event.type === 'turn_done')
+                trace('turn_done');
             yield event;
         }
         completedNormally = true;
@@ -124,9 +136,11 @@ export async function* runTurn(opts) {
         try {
             if (!completedNormally && !hostFailed)
                 journal?.observe({ type: 'interrupted' });
+            trace('memory_start');
             await journal?.finish(history, historyStart).catch(error => {
                 process.stderr.write(`[minimal-agent memory] 本轮记忆收尾失败，不影响会话落盘：${error.message}\n`);
             });
+            trace('memory_end');
             if (persist)
                 await saveContext(history, opts.sessionFile);
         }