minimal-agent 0.18.6 → 0.18.8

package/src/loop.ts

@@ -28,6 +28,11 @@
  */
 
 import crypto from 'node:crypto';
+import { answerPreparationNotice } from './runtime/answerPreparation.js';
+import { finalAnswerMessages } from './runtime/finalAnswer.js';
+import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.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 +105,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 +416,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,12 +443,15 @@ 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;
   let presentedResultUnverified = false;
   let deliveryCorrectionAttempted = false;
   let askCorrectionAttempted = false;
+  let diagramPreparationAttempted = false;
+  const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
   const subagents = await configService.subagents();
   await hydrateSessionWorktree({
     sessionState,
@@ -449,9 +460,21 @@ export async function* runQuery(
     cwd: runtimeContext.cwd,
   });
   const toolCallContext: ToolCallContext = {
+    output,
+    availableToolNames: () => currentEffectiveToolSet.names,
     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',
@@ -516,6 +539,7 @@ export async function* runQuery(
     const parts = [
       transientFor(activeTools),
       coordinationText,
+      diagramPreparationAttempted ? visualPresentation(output) : '',
       delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
       askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
@@ -910,7 +934,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 +955,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，
@@ -942,7 +973,7 @@ export async function* runQuery(
       for await (const ev of chatFn({
         provider,
         messages: modelMessages,
-        tools: currentEffectiveToolSet.tools,
+        tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'preparation'),
         signal,
         conversationMode: runtimeContext.conversationMode ?? 'private',
         promptCache: options.promptCache,
@@ -956,12 +987,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 +1028,9 @@ export async function* runQuery(
         }
       }
     } catch (e) {
+      trace('model_error');
       if ((e as Error).name === 'AbortError') {
+        yield* retireDraft('interrupted');
         yield interruption();
         return;
       }
@@ -1026,6 +1054,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 +1086,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 +1095,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 +1118,26 @@ 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 = '';
+    }
+    // Count the calls that survived review scheduling, including failed loads.
+    for (const call of toolCallsByIndex) {
+      if (call.function.name !== 'Skill') continue;
+      try {
+        if (JSON.parse(call.function.arguments).name === 'dynamic-ui') diagramPreparationAttempted = true;
+      } catch { /* Ordinary tool validation reports malformed arguments. */ }
+    }
     const assistantMsg: Message = {
       role: 'assistant',
       content: assistantText.length > 0 ? assistantText : null,
@@ -1098,12 +1150,26 @@ export async function* runQuery(
       ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
     };
     // 4. 没有工具调用 → 整轮交互结束
-    if (toolCallsByIndex.length === 0) {
+    finalResponse: if (toolCallsByIndex.length === 0) {
+      // Repair only private preparation, through the ordinary tool pipeline.
+      // One attempt per turn, including missing/failed skills; never rewind a reply.
+      if (!diagramPreparationAttempted && !options.responseFormat
+        && runtimeContext.profile === 'main' && output.diagrams.length > 0
+        && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
+        && needsDiagramPreparation(assistantText, userInput)) {
+        diagramPreparationAttempted = true;
+        toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+          name: 'Skill', arguments: JSON.stringify({ name: 'dynamic-ui' }),
+        } });
+        assistantMsg.content = null;
+        assistantMsg.tool_calls = toolCallsByIndex;
+        break finalResponse;
+      }
       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 +1178,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 +1196,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 +1226,103 @@ 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'
+          && output.finalDelivery === 'stream') {
+          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, output);
+            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: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), 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') {
+                // Final expression is live generation, not an exact-copy replay.
+                // Once visible, text is never replaced or joined with a different draft.
+                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('最终表达未返回正文。');
+          } catch (error) {
+            publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || (error as Error)?.name === 'AbortError';
+            publicationError = error;
+          }
+          if (publicationError && !publicationInterrupted && !publishedText) {
+            yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
+            yield { type: 'text', delta: candidate };
+            streamed = true;
+            publishedText = candidate;
+            lastFinishReason = candidateFinishReason;
+            publicationError = undefined;
+          }
+          assistantText = publishedText;
+          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 +1374,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 +1398,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 +1632,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 +1961,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/memory/fileStore.js

@@ -1,12 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import lockfile from 'proper-lockfile';
 import { chmod, mkdir, open, readFile, rename, rm, stat, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 import { agentStateDir } from '../context/agentHome.js';
 import { CATEGORY_DIR, MEMORY_ID_PATTERN } from './constants.js';
-const LOCK_STALE_MS = 120_000;
-const LOCK_WAIT_MS = 15_000;
 let mutationQueue = Promise.resolve();
 export function memoryRootDir() {
     return join(agentStateDir(), 'memory');
@@ -54,36 +51,7 @@ export async function pathExists(path) {
 export async function acquireFileLock(path, signal) {
     signal?.throwIfAborted();
     await ensurePrivateDir(dirname(path));
-    const deadline = Date.now() + LOCK_WAIT_MS;
-    while (true) {
-        signal?.throwIfAborted();
-        try {
-            // Do not steal old-version file locks. Restart old hosts before upgrading;
-            // their locks must be reviewed rather than aged out under a live writer.
-            const legacy = await stat(`${path}.lock`).catch(error => {
-                if (error.code === 'ENOENT')
-                    return null;
-                throw error;
-            });
-            if (legacy?.isFile())
-                throw new Error('MEMORY_LEGACY_LOCK：请停止旧版本宿主并检查遗留记忆锁');
-            const release = await lockfile.lock(path, {
-                realpath: false, retries: 0, stale: LOCK_STALE_MS, update: 10_000,
-            });
-            if (signal?.aborted) {
-                await release();
-                signal.throwIfAborted();
-            }
-            return release;
-        }
-        catch (error) {
-            if (error.code !== 'ELOCKED')
-                throw error;
-            if (Date.now() >= deadline)
-                throw new Error('等待记忆文件锁超时');
-            await delay(40, undefined, { signal });
-        }
-    }
+    return acquireStateFileLock(path, { signal, label: 'MEMORY' });
 }
 export async function atomicWriteFile(path, content) {
     await ensurePrivateDir(dirname(path));

package/src/memory/fileStore.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from 'node:crypto';
-import lockfile from 'proper-lockfile';
 import {
   chmod,
   mkdir,
@@ -10,14 +9,12 @@ import {
   stat,
 } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 
 import { agentStateDir } from '../context/agentHome.js';
 import { CATEGORY_DIR, MEMORY_ID_PATTERN } from './constants.js';
 import type { MemoryRecord, MemoryScope } from './types.js';
 
-const LOCK_STALE_MS = 120_000;
-const LOCK_WAIT_MS = 15_000;
 let mutationQueue: Promise<void> = Promise.resolve();
 
 export function memoryRootDir(): string {
@@ -84,28 +81,7 @@ export async function acquireFileLock(
 ): Promise<() => Promise<void>> {
   signal?.throwIfAborted();
   await ensurePrivateDir(dirname(path));
-  const deadline = Date.now() + LOCK_WAIT_MS;
-  while (true) {
-    signal?.throwIfAborted();
-    try {
-      // Do not steal old-version file locks. Restart old hosts before upgrading;
-      // their locks must be reviewed rather than aged out under a live writer.
-      const legacy = await stat(`${path}.lock`).catch(error => {
-        if (error.code === 'ENOENT') return null;
-        throw error;
-      });
-      if (legacy?.isFile()) throw new Error('MEMORY_LEGACY_LOCK：请停止旧版本宿主并检查遗留记忆锁');
-      const release = await lockfile.lock(path, {
-        realpath: false, retries: 0, stale: LOCK_STALE_MS, update: 10_000,
-      });
-      if (signal?.aborted) { await release(); signal.throwIfAborted(); }
-      return release;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ELOCKED') throw error;
-      if (Date.now() >= deadline) throw new Error('等待记忆文件锁超时');
-      await delay(40, undefined, { signal });
-    }
-  }
+  return acquireStateFileLock(path, { signal, label: 'MEMORY' });
 }
 
 export async function atomicWriteFile(

package/src/prompts/policyRegistry.js

@@ -1,6 +1,7 @@
 import { CODE_REVIEW_RUBRIC } from './codeReview.js';
 import { capabilityForToolName, } from '../tools/capabilities.js';
 import { skillInvokeInstruction } from './skillList.js';
+import { visualPresentation } from './visualPresentation.js';
 export function capabilitiesForTools(tools) {
     const result = new Set();
     for (const tool of tools) {
@@ -193,10 +194,13 @@ 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, output, toolNames }) => [
+            visualPresentation(output ?? surface),
+            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 +250,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

@@ -6,6 +6,8 @@ import {
   type CapabilityId,
 } from '../tools/capabilities.js';
 import { skillInvokeInstruction } from './skillList.js';
+import { visualPresentation } from './visualPresentation.js';
+import type { OutputContract } from '../runtime/outputContract.js';
 
 export type PromptPolicyLayer =
   | 'authority'
@@ -31,6 +33,7 @@ export type { CapabilityId } from '../tools/capabilities.js';
 export interface StablePromptContext {
   profile: AgentProfile;
   surface: AgentSurface;
+  output?: OutputContract;
   cwd: string;
   capabilities: ReadonlySet<CapabilityId>;
   toolNames: ReadonlySet<string>;
@@ -240,10 +243,13 @@ 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, output, toolNames }) => [
+      visualPresentation(output ?? surface),
+      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 +299,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',