@yeaft/webchat-agent 1.0.633 → 1.0.635

package/yeaft/query-progress.js

@@ -0,0 +1,201 @@
+/**
+ * Query-local loop evidence. Activity is not completion: only changed observations
+ * (including new negative reads) count as evidence. No transcript, arguments or
+ * result bodies escape this object. Polling/waiting is neutral, not stagnation or progress.
+ */
+import { createHash } from 'node:crypto';
+import { argsHashOf } from './tool-folding/exec-log.js';
+
+const MAX_ENTRIES = 1024;
+const WARNING_BATCHES = 4;
+const RECOVERY_BATCHES = 8;
+const REPORT_BATCHES = 12;
+const FAILURE_LIMIT = 3;
+const NEUTRAL_TOOLS = new Set([
+  'AskUser', 'WaitAgent', 'ListAgents', 'WaitTask', 'ListTasks', 'ReadTaskLog',
+  'PromptAgent', 'UpdateAgent', 'CloseAgent', 'PresentResponse',
+]);
+
+function boundedSet(map, key, value) {
+  map.delete(key);
+  map.set(key, value);
+  if (map.size > MAX_ENTRIES) map.delete(map.keys().next().value);
+}
+function resultHash(output) {
+  return createHash('sha256').update(typeof output === 'string' ? output : JSON.stringify(output) || '').digest('hex');
+}
+
+function failureKind(output, call, readOnly) {
+  const text = typeof output === 'string' ? output : JSON.stringify(output) || '';
+  const errorText = text.replace(/^Error:\s*/, '');
+  let contract;
+  // MCP and legacy tools throw JSON envelopes; Engine prefixes their messages
+  // with "Error: ". Preserve that contract for classification without changing
+  // the raw persisted/UI tool output.
+  try { contract = typeof output === 'string' ? JSON.parse(errorText) : output; } catch { /* legacy text errors */ }
+  // Confirmed nonzero exit is not rollback evidence. It is, however, a finished
+  // command that can be revalidated after an edit or new input, unlike a timeout
+  // or an operation whose lifecycle is still unknown.
+  if (call.name === 'Bash' && contract?.code === 'bash_exit_nonzero'
+      && contract.failureType === 'exit_nonzero' && contract.terminationConfirmed === true
+      && contract.timedOut === false && Number.isInteger(contract.exitCode)) return 'terminated_command';
+  if (contract?.errorEffect === 'unknown' || contract?.replaySafe === false) return 'uncertain';
+  // Match the registry's explicit pre-execution validation contract, not words
+  // in arbitrary messages or file paths such as /schema/validation/*.json.
+  if (contract?.code === 'invalid_arguments' && contract.errorEffect === 'none') return 'validation';
+  // A dispatched mutation without an explicit no-effect contract is unsafe to
+  // replay regardless of whether its message happens to mention a timeout.
+  if (!readOnly && contract?.errorEffect !== 'none') return 'uncertain';
+  const message = typeof contract?.error === 'string' ? contract.error : errorText;
+  if (['EPERM', 'EACCES'].includes(contract?.code)
+      || /^(?:Failed to read file:\s*)?(?:EPERM\b|EACCES\b|permission denied\b|access denied\b|forbidden\b)/i.test(message)) return 'permission';
+  // Known negative filesystem observations contain paths, not lifecycle data.
+  // Names such as /timeout/schema/ are domain evidence, never timeout signals.
+  if (readOnly && (/^(?:File not found:|ENOENT\b|Path is a directory:|Cannot read binary file:|File too large:)/i.test(message)
+      || contract?.code === 'ENOENT')) return resultHash(output);
+  if (/timed?\s*out|timeout|ECONNRESET|disconnect|socket hang up|connection closed/i.test(message)) return 'uncertain';
+  return resultHash(output);
+}
+
+export class QueryProgress {
+  #results = new Map();
+  #mutations = new Map();
+  #failures = new Map();
+  #batch = { evidence: false, repeated: false, failed: false };
+  #revision = 0;
+  #state = {
+    modelRequests: 0, toolExecutions: 0, reusedCalls: 0, repeatedCalls: 0,
+    failedCalls: 0, stage: 'running', reason: null, lastEvidenceAt: null, stagnantBatches: 0,
+  };
+
+  requestStarted() { this.#state.modelRequests += 1; }
+
+  /** Caller feedback/new owned task results may invalidate prior observations. */
+  resetEvidence() {
+    this.#results.clear();
+    this.#mutations.clear();
+    // New instructions/results do not prove a timed-out mutation was rolled back.
+    for (const [key, failure] of this.#failures) {
+      if (failure.readOnly || failure.kind !== 'uncertain') this.#failures.delete(key);
+    }
+    this.#state.stagnantBatches = 0;
+    this.#state.stage = 'running';
+    this.#state.reason = null;
+    this.#batch = { evidence: false, repeated: false, failed: false };
+  }
+
+  /** Limit unchanged failures; never automatically replay an uncertain mutation. */
+  blocked(call) {
+    const failure = this.#failures.get(`${call.name}:${argsHashOf(call.input)}`);
+    // A possibly committed mutation must be verified before even the first replay.
+    if (!failure || (failure.count < FAILURE_LIMIT
+        && !(['uncertain', 'terminated_command'].includes(failure.kind) && !failure.readOnly))) return null;
+    return `Blocked unchanged failed call to ${call.name} after ${failure.count} equivalent failures. This call was NOT executed. Use the earlier error to correct the arguments or choose a different supported path. If an earlier operation timed out or disconnected, its side effects may already have happened: verify the target state before retrying. Otherwise report the concrete blocker. Previous failed call: ${failure.callId}.`;
+  }
+
+  observe({ call, output, isError = false, readOnly = false, executed = true, reused = false, skipped = false, policy = 'warn' }) {
+    if (skipped) return;
+    if (executed) this.#state.toolExecutions += 1;
+    if (reused) this.#state.reusedCalls += 1;
+    if (isError) this.#state.failedCalls += 1;
+    const key = `${call.name}:${argsHashOf(call.input)}`;
+    const hash = resultHash(output);
+    if (isError) {
+      const prior = this.#failures.get(key);
+      const kind = failureKind(output, call, readOnly);
+      if (executed && !readOnly) {
+        // A partial mutation may have changed even a previously unreadable
+        // resource. Permit verification, never a replay of the mutation itself.
+        this.#results.clear();
+        for (const [failedKey, failure] of this.#failures) {
+          if (failure.readOnly) this.#failures.delete(failedKey);
+        }
+      }
+      // A blocked result is synthetic; do not replace the original failure.
+      if (executed) boundedSet(this.#failures, key, {
+        kind, readOnly, count: prior?.kind === kind ? prior.count + 1 : 1, callId: call.id,
+      });
+      const repeated = !executed || prior?.kind === kind;
+      // A first negative observation for a distinct read narrows the search.
+      // Validation/permission failures are blockers, not domain evidence.
+      if (readOnly && !repeated && !['validation', 'permission', 'uncertain'].includes(kind)) {
+        this.#batch.evidence = true;
+        this.#state.lastEvidenceAt = Date.now();
+      } else {
+        this.#batch.failed = true;
+      }
+      if (repeated) {
+        this.#batch.repeated = true;
+        this.#state.repeatedCalls += 1;
+      }
+      return;
+    }
+    this.#failures.delete(key);
+    if (NEUTRAL_TOOLS.has(call.name) || policy === 'allow') return;
+    if (!readOnly && executed && !reused) {
+      // New mutations invalidate read observations, so edit/verify loops remain
+      // useful. An identical mutation/acknowledgement is not itself evidence
+      // of another change; never cache or replay it, merely count repetition.
+      if (this.#mutations.get(key) === hash) {
+        this.#batch.repeated = true;
+        this.#state.repeatedCalls += 1;
+      } else {
+        boundedSet(this.#mutations, key, hash);
+        this.#results.clear();
+        // Reads and confirmed, finished commands may now succeed after an
+        // edit. Unknown/timeout side effects still require explicit verification.
+        for (const [failedKey, failure] of this.#failures) {
+          if (failure.readOnly || failure.kind === 'terminated_command') this.#failures.delete(failedKey);
+        }
+        this.#batch.evidence = true;
+        this.#state.lastEvidenceAt = Date.now();
+      }
+      return;
+    }
+    // Different ranges/pages are independent observations. A changed result for
+    // the same call is fresh evidence even when it returns to an older value.
+    const prior = this.#results.get(key);
+    if (prior?.hash === hash || reused || !executed) {
+      this.#state.repeatedCalls += 1;
+      this.#batch.repeated = true;
+      return readOnly && prior?.hash === hash ? prior.callId : null;
+    } else {
+      boundedSet(this.#results, key, { hash, callId: call.id });
+      this.#batch.evidence = true;
+      this.#state.lastEvidenceAt = Date.now();
+    }
+  }
+
+  /** Called only AFTER every tool result is paired and persisted. */
+  finishBatch() {
+    const previousStage = this.#state.stage;
+    if (this.#batch.evidence) {
+      this.#state.stagnantBatches = 0;
+      this.#state.stage = 'running';
+      this.#state.reason = null;
+    } else if (this.#batch.repeated || this.#batch.failed) {
+      this.#state.stagnantBatches += 1;
+      this.#state.reason = this.#batch.failed ? 'repeated_failure' : 'repeated_results';
+      const count = this.#state.stagnantBatches;
+      this.#state.stage = count >= REPORT_BATCHES ? 'stopped'
+        : count >= RECOVERY_BATCHES ? 'recovering'
+          : count >= WARNING_BATCHES ? 'warning' : 'running';
+    }
+    this.#batch = { evidence: false, repeated: false, failed: false };
+    if (previousStage === this.#state.stage || this.#state.stage === 'running') return null;
+    if (this.#state.stage === 'stopped') return 'report';
+    return this.#state.stage;
+  }
+
+  snapshot(identity = {}) {
+    return { type: 'query_progress', ...identity, revision: ++this.#revision, ...this.#state };
+  }
+}
+
+export function progressReminder(action, reason) {
+  const failureHint = reason === 'repeated_failure'
+    ? 'The same execution paths are failing. A timeout does not prove an operation did not happen; verify state before retrying any side effect.'
+    : 'Recent tool batches repeat results already available; re-reading or restating a plan is not new evidence.';
+  if (action === 'report') return `[system note] Investigation stopped after repeated non-progress batches despite recovery guidance. ${failureHint} Do not claim the user task is complete. Using only existing evidence, give a concise handoff: completed artifacts, unfinished requirements, concrete blocker, and a safe next step. No further tools are available for this one reporting response.`;
+  return `[system note] Query progress ${action === 'recovering' ? 'recovery required' : 'warning'}: ${failureHint} Reuse prior results. Execute a concrete next step toward the requested deliverable, obtain genuinely missing evidence, or explain the blocker. Do not spawn another review of the same baseline or search for your own promises. Long-running useful work and legitimate waits remain allowed.`;
+}

package/yeaft/sub-agent/prompt-queue.js

@@ -11,6 +11,9 @@ import { snapshotEffortDecision } from '../effort.js';
  * @param {{ projectSessionIds?: string[], projectLabel?: string, projectInstruction?: string }} projectContext
  */
 export function enqueueSubAgentPrompt(agent, prompt, projectContext = {}) {
+  // Reserve the original delegation identity, but stop reusing its mutable
+  // evidence as soon as follow-up work is accepted (even before it runs).
+  agent.delegationSuperseded = true;
   if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
   agent.pendingPrompts.push({
     prompt,

package/yeaft/sub-agent/result-reference.js

@@ -0,0 +1,13 @@
+import { createHash } from 'crypto';
+
+/** Reference to the agent's current reply, not its initial delegation; liveness/status alone do not change it. */
+export function getAgentResultRef(agent) {
+  const evidence = JSON.stringify({
+    result: agent.result ?? null,
+    preview: agent.lastResult || '',
+    finalReport: agent.finalReport || null,
+    error: agent.error || null,
+  });
+  const hash = createHash('sha256').update(evidence).digest('hex').slice(0, 16);
+  return `${agent.id}:${agent.resultRevision || 0}:${hash}`;
+}

package/yeaft/sub-agent/runner.js

@@ -171,9 +171,10 @@ export function startSubAgent(agent, deps = {}) {
     agent.subEngine = subEngine;
     agent.engineMessages = agent.engineMessages || [];
     agent.liveness = agent.liveness || makeLiveness();
-    agent.parentVpId = deps.parentVpId || null;
-    agent.parentSessionId = deps.parentSessionId || null;
-    agent.parentThreadId = deps.parentThreadId || 'main';
+    // Preserve tool-boundary ownership when host deps omit caller identifiers.
+    agent.parentVpId = agent.parentVpId || deps.parentVpId || null;
+    agent.parentSessionId = agent.parentSessionId || deps.parentSessionId || null;
+    agent.parentThreadId = agent.parentThreadId || deps.parentThreadId || 'main';
     outputLog = createOutputLog(agent.id, deps.subAgentLogDir);
     agent.outputLog = outputLog;
     agent.outputFile = outputLog.path;
@@ -187,7 +188,7 @@ export function startSubAgent(agent, deps = {}) {
       parentName: deps.parentName || 'parent',
       parentVpId: deps.parentVpId || null,
       agentName: agent.name,
-      mission: agent.mission || agent.task || '',
+      mission: (agent.mission || agent.task || '') + (agent.baseline ? `\n\nWorkspace baseline: ${agent.baseline}` : ''),
       expectedOutput: agent.expected_output,
       presetPrompt: (agent.personaData || getPersona(agent.persona))?.systemPrompt,
       budget: agent.budget,
@@ -457,6 +458,9 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         continue;
       }
 
+      // Every actual query is a new evidence revision, even if its reply text
+      // happens to equal the previous reply. PromptAgent must stay collectable.
+      agent.resultRevision = (agent.resultRevision || 0) + 1;
       // Partial evidence belongs to this query, never a previous follow-up.
       agent.partial_output = '';
       agent.lastResult = '';
@@ -495,8 +499,9 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
           // Liveness — update first so even listener throws don't lose
           // the bump.
           bumpLivenessFromEvent(agent.liveness, evt);
-          // Hidden provider progress is liveness only, never a log/task/UI event.
-          if (evt?.type === 'provider_activity') continue;
+          // Provider activity and UI-only query counters are liveness only here:
+          // never persist them in the child log or churn task notifications.
+          if (evt?.type === 'provider_activity' || evt?.type === 'query_progress') continue;
 
           // Mirror every raw event to the durable log. We still keep
           // `sub_agent_event` text_delta suppressed so the inline transcript

package/yeaft/sub-agent/task-identity.js

@@ -0,0 +1,46 @@
+import { createHash } from 'crypto';
+import path from 'path';
+import { realpathSync } from 'fs';
+
+function canonicalJSON(value) {
+  if (Array.isArray(value)) return value.map(canonicalJSON);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonicalJSON(value[key])]));
+  }
+  return value;
+}
+
+/** Resolve relative child paths against the caller workspace, not the process cwd. */
+export function resolveAgentCwd(cwd, parentCwd) {
+  return path.resolve(parentCwd || process.cwd(), cwd || '.');
+}
+
+function canonicalWorkspace(cwd) {
+  let resolved = resolveAgentCwd(cwd);
+  try { resolved = realpathSync(resolved); } catch { /* non-existent paths keep lexical identity */ }
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+/**
+ * Exact, query-local delegation identity. Names are labels, not task identity.
+ * No queryTurnId means a legacy caller: do not infer a scope or deduplicate it.
+ * The owner is checked separately with agentBelongsToScope before reuse.
+ * Keep this initial identity reserved across continuations; their latest mutable
+ * evidence must not be returned for an original-spec retry.
+ */
+export function buildDelegationIdentity(input, spec, grants, ctx = {}) {
+  const queryTurnId = typeof ctx?.queryTurnId === 'string' ? ctx.queryTurnId.trim() : '';
+  if (!queryTurnId) return null;
+  const workspace = canonicalWorkspace(ctx.cwd);
+  const taskSpec = {
+    mission: spec.mission,
+    persona: spec.persona,
+    cwd: canonicalWorkspace(resolveAgentCwd(input.cwd, ctx.cwd)),
+    baseline: input.baseline ?? null,
+    expected_output: spec.expected_output,
+    allow_tools: [...grants].sort(),
+    budget: spec.budget,
+  };
+  const specHash = createHash('sha256').update(JSON.stringify(canonicalJSON(taskSpec))).digest('hex');
+  return { queryTurnId, workspace, taskKey: input.taskKey?.trim() || null, specHash };
+}

package/yeaft/tools/agent.js

@@ -33,6 +33,8 @@ import { STATUS, isTerminalAgentStatus } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness, makeLiveness } from '../sub-agent/liveness.js';
 import { TASK_RESULT_DELIVERY } from '../tasks/store.js';
 import { captureParentEffortDecision } from '../effort.js';
+import { buildDelegationIdentity, resolveAgentCwd } from '../sub-agent/task-identity.js';
+import { getAgentResultRef } from '../sub-agent/result-reference.js';
 
 /** In-memory sub-agent registry. */
 const agents = new Map();
@@ -95,6 +97,11 @@ export function validateSpec(input) {
     return { ok: false, error: 'spec must be an object' };
   }
   const { name, task, mission, expected_output, persona, budget } = input;
+  for (const key of ['taskKey', 'baseline', 'cwd']) {
+    if (input[key] !== undefined && !cleanString(input[key])) {
+      return { ok: false, error: `${key} must be a non-empty string` };
+    }
+  }
   if (!cleanString(name)) {
     return { ok: false, error: 'name is required' };
   }
@@ -237,6 +244,7 @@ Pick a preset persona to pre-wire a tool subset and model tier:
 
 Guidelines:
 - Give a clear, focused mission — what "done" looks like
+- Exact spec retries in the same parent query/workspace reuse the existing agent (even renamed or terminal), unless follow-up work superseded its original evidence; that retry is rejected, not respawned. Use a new taskKey for an intentional independent run; taskKey conflicts require a new key, not a changed spec.
 - Use expected_output when the return shape matters
 - Delegate one clear result with the workspace/base and completion evidence. Let the child choose its steps; do simple work directly. Split unrelated goals, not individual reads.
 - Usually omit budget so the child can finish. Add a budget only when the task actually needs a hard lifetime ceiling; tool exhaustion reserves one tool-free handoff and unfinished work stays budget_exceeded.
@@ -261,6 +269,7 @@ stops or finalizes work no longer needed.`,
 
 使用指南：
 - 给出清晰聚焦的 mission——"完成"是什么样子
+- 同一父级 query/workspace 内完全相同的规格重试会复用已有 Agent（含改名或已结束任务）；若后续工作已替代原任务证据，则拒绝重试，不自动重建。需要独立执行时使用新的 taskKey；同 key 规格冲突不能通过修改规格重试解决。
 - 当返回结构重要时使用 expected_output
 - 一次只委派一个明确结果，提供工作目录/基线和完成证据，让子 Agent 自主选择步骤；简单工作直接做。拆分不相关目标，不要拆成逐个读取任务。
 - 通常省略 budget，让子 Agent 完成工作；仅当任务确实需要硬性累计上限时才设置。不要给多文件 review 人为设置极小额度。工具额度耗尽后保留一次无工具交付机会，未完成仍返回 budget_exceeded。
@@ -279,6 +288,20 @@ stops or finalizes work no longer needed.`,
           zh: '子 Agent 的描述性名称（如 "test-writer"、"refactor-auth"）',
         },
       },
+      taskKey: {
+        type: 'string',
+        description: {
+          en: 'Optional exact task identity within this parent query/workspace. Retries reuse the agent even after completion, but are rejected after follow-up work supersedes its original evidence. Changing the spec under this key is an error. Use a new key for an intentional independent run.',
+          zh: '可选的父级 query/workspace 内精确任务标识；重试复用原 Agent（含已结束任务），后续工作替代原证据后则拒绝复用；同 key 修改任务规格会报冲突。明确需要独立执行时使用新 key。',
+        },
+      },
+      baseline: {
+        type: 'string',
+        description: {
+          en: 'Optional immutable workspace baseline (e.g. commit SHA); included in task identity and passed to the child.',
+          zh: '可选不可变 workspace 基线（如 commit SHA）；纳入任务身份并传给子 Agent。',
+        },
+      },
       task: {
         type: 'string',
         description: {
@@ -360,6 +383,9 @@ stops or finalizes work no longer needed.`,
   // tools. A parent query therefore cannot safely reuse filesystem snapshots
   // after a SpawnAgent call returns.
   mayMutateWorkspaceAfterReturn: () => true,
+  // Execute retries through the identity check, never cache an old status.
+  cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input, ctx) {
     // NB: every envelope below puts `next_steps` (or `error_next_steps`) at
     // the FIRST position because `agent/yeaft/tools/registry.js` caps tool
@@ -377,8 +403,49 @@ stops or finalizes work no longer needed.`,
     const spec = validation.spec;
     const grants = validateToolGrants(input.allow_tools === undefined ? [] : input.allow_tools, ctx?.parentEngineDeps?.parentToolRegistry);
     if (!grants.ok) return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: grants.error });
-    const { name, cwd } = input;
+    const { name } = input;
     const callerScope = getCallerAgentScope(ctx);
+    const identity = buildDelegationIdentity(input, spec, grants.tools, ctx);
+    if (identity) {
+      for (const agent of agents.values()) {
+        const prior = agent.delegationIdentity;
+        if (!prior || !agentBelongsToScope(agent, callerScope)
+          || prior.queryTurnId !== identity.queryTurnId || prior.workspace !== identity.workspace) continue;
+        const sameIdentity = identity.taskKey !== null
+          ? prior.taskKey === identity.taskKey
+          : prior.taskKey === null && prior.specHash === identity.specHash;
+        if (!sameIdentity) continue;
+        if (prior.specHash !== identity.specHash) {
+          return JSON.stringify({
+            next_steps: ERROR_NEXT_STEPS,
+            error: `Task identity conflict: taskKey "${identity.taskKey}" already has a different spec. Use a new taskKey for independent work.`,
+            agentId: agent.id,
+          });
+        }
+        // Identity stays reserved, but the mutable record no longer owns the
+        // original evidence after a continuation. Check accepted follow-up and
+        // finalization controls before the runner starts; revisions are a fallback.
+        if (agent.delegationSuperseded || agent.finalizationRequested || agent.resultRevision > 1) {
+          return JSON.stringify({
+            next_steps: 'Do not use this agent\'s latest reply as the original delegation evidence. Reuse the original reply if already collected; otherwise inspect the original turn in the agent log. Use a new taskKey only for intentional independent work.',
+            error: 'Delegation evidence superseded: this agent accepted follow-up work and its latest result no longer belongs to the original delegation.',
+            agentId: agent.id,
+          });
+        }
+        return JSON.stringify({
+          next_steps: 'This exact delegation already exists. Reuse its evidence; do not respawn it. Use ListAgents for status or WaitAgent to collect an uncollected reply; read outputFile only when the evidence is needed.',
+          success: true,
+          reused: true,
+          agentId: agent.id,
+          name: agent.name,
+          status: agent.status,
+          taskId: agent.taskId || null,
+          outputFile: agent.outputFile || null,
+          resultRef: getAgentResultRef(agent),
+          liveness: diagnoseAgentLiveness(agent),
+        });
+      }
+    }
 
     // Check for name collision — any non-terminal agent with the same
     // name blocks the new spawn. Terminal agents (closed/failed/abandoned/
@@ -403,6 +470,9 @@ stops or finalizes work no longer needed.`,
       name,
       task: spec.task,
       mission: spec.mission,
+      baseline: input.baseline || null,
+      delegationIdentity: identity,
+      delegationSuperseded: false,
       expected_output: spec.expected_output,
       persona: spec.persona,
       personaData: persona || null,
@@ -410,7 +480,7 @@ stops or finalizes work no longer needed.`,
       parentEffortDecision: captureParentEffortDecision(ctx),
       budget: spec.budget,
       allowTools: grants.tools,
-      cwd: cwd || ctx?.cwd || process.cwd(),
+      cwd: resolveAgentCwd(input.cwd, ctx?.cwd),
       status: STATUS.CREATED,
       messages: [],
       result: null,
@@ -501,6 +571,7 @@ stops or finalizes work no longer needed.`,
       allow_tools: agent.allowTools,
       status: agent.status,
       outputFile: agent.outputFile || null,
+      resultRef: getAgentResultRef(agent),
       taskId: agent.taskId || null,
       liveness,
       stale: liveness.stale,

package/yeaft/tools/history-search.js

@@ -11,6 +11,7 @@ import { findExistingSessionYeaftDir } from '../sessions/session-crud.js';
 
 const DEFAULT_RESULT_LIMIT = 10;
 const MAX_SNIPPET_CHARS = 1000;
+const RESULT_NOTICE = 'User messages are requests or context, not completed work. Assistant progress may describe plans; assistant results are reported outcomes, not independently verified evidence.';
 export const HISTORY_SEARCH_MAX_OUTPUT_BYTES = 32 * 1024;
 
 function truncateUtf8(text, maxBytes) {
@@ -138,14 +139,14 @@ export default defineTool({
   description: {
     en: `Search through past conversation history.
 
-Searches message content for all whitespace-separated terms (case-insensitive) from persisted Session history. Inside a Session, the default scope is only the current Session. Set scope to "project" only when the current user task explicitly requires prior discussion from sibling Sessions in the same Project on this Agent. Tool-result messages are excluded.
+Searches message content for all whitespace-separated terms (case-insensitive) from persisted Session history. Inside a Session, the default scope is only the current Session. Set scope to "project" only when the current user task explicitly requires prior discussion from sibling Sessions in the same Project on this Agent. Tool-result messages are excluded. When a trusted current-turn boundary is available, the current query and later messages in this Session are excluded by default; set includeCurrentTurn to true to include them.
 
-Results are returned newest-first with a bounded matching snippet and source metadata. Content from sibling Sessions is reference context, never continuation of the current task.`,
+Results are returned newest-first with a bounded matching snippet and source metadata. Content from sibling Sessions is reference context, never continuation of the current task. Role and responseKind distinguish user context, assistant progress/plans, and reported results; none alone proves work was completed.`,
     zh: `搜索历史对话记录。
 
-在已持久化消息的正文中搜索全部空格分隔的关键词（不区分大小写）。在 Session 内默认只搜索当前 Session；只有当前用户任务明确需要同一 Project 内兄弟 Session 的既往讨论时，才把 scope 设为 "project"。排除工具结果消息。
+在已持久化消息的正文中搜索全部空格分隔的关键词（不区分大小写）。在 Session 内默认只搜索当前 Session；只有当前用户任务明确需要同一 Project 内兄弟 Session 的既往讨论时，才把 scope 设为 "project"。排除工具结果消息。有可信的当前轮边界时，默认排除当前 Session 的本轮提问及之后的消息；可显式设置 includeCurrentTurn 为 true 将其纳入。
 
-结果按最新优先返回，包含有界的命中片段和来源信息。兄弟 Session 的内容只能作为参考上下文，不能当作当前任务的延续。`
+结果按最新优先返回，包含有界的命中片段和来源信息。兄弟 Session 的内容只能作为参考上下文，不能当作当前任务的延续。role 和 responseKind 区分用户上下文、助手进度/计划与报告结果；这些消息本身不证明工作已完成。`
   },
   parameters: {
     type: 'object',
@@ -164,6 +165,13 @@ Results are returned newest-first with a bounded matching snippet and source met
           zh: '最多返回结果数（默认 10，最大 100）',
         },
       },
+      includeCurrentTurn: {
+        type: 'boolean',
+        description: {
+          en: 'Include the current query and later messages in this Session (default: false when a trusted turn boundary is available).',
+          zh: '纳入当前 Session 的本轮提问及之后的消息（有可信轮次边界时默认 false）。',
+        },
+      },
       scope: {
         type: 'string',
         enum: ['session', 'project'],
@@ -178,13 +186,17 @@ Results are returned newest-first with a bounded matching snippet and source met
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const { keyword, limit = DEFAULT_RESULT_LIMIT, scope = 'session' } = input;
+    const { keyword, limit = DEFAULT_RESULT_LIMIT, scope = 'session', includeCurrentTurn = false } = input;
     const normalizedKeyword = typeof keyword === 'string' ? keyword.trim() : '';
     if (!normalizedKeyword) return JSON.stringify({ error: 'keyword is required' });
     if (scope !== 'session' && scope !== 'project') {
       return JSON.stringify({ error: 'scope must be "session" or "project"' });
     }
 
+    if (typeof includeCurrentTurn !== 'boolean') {
+      return JSON.stringify({ error: 'includeCurrentTurn must be a boolean' });
+    }
+
     const yeaftDir = ctx?.yeaftDir;
     if (!yeaftDir) {
       return JSON.stringify({ error: 'Yeaft directory not configured — no conversation history available' });
@@ -214,6 +226,11 @@ Results are returned newest-first with a bounded matching snippet and source met
           const messages = searchMessages(storeDir, normalizedKeyword, limit, {
             telemetry: scanTelemetry,
             sessionIds: [sessionId],
+            ...(!includeCurrentTurn && sessionId === ctx.sessionId ? {
+              boundarySessionId: ctx.sessionId,
+              beforeSeq: ctx.historyBeforeSeq,
+              beforeMessageId: ctx.historyBeforeMessageId,
+            } : {}),
           });
           telemetry.scannedSessions = (telemetry.scannedSessions || 0) + 1;
           telemetry.scannedFiles = (telemetry.scannedFiles || 0) + (scanTelemetry.scannedFiles || 0);
@@ -224,6 +241,7 @@ Results are returned newest-first with a bounded matching snippet and source met
               messageId: message.id || null,
               sessionId: message.sessionId || sessionId,
               role: message.role,
+              responseKind: message.responseKind || null,
               content: buildSnippet(message.content || '', normalizedKeyword),
               mode: message.mode || null,
               time: message.time || message.timestamp || null,
@@ -242,6 +260,7 @@ Results are returned newest-first with a bounded matching snippet and source met
           messageId: msg.id || null,
           sessionId: msg.sessionId || null,
           role: msg.role,
+          responseKind: msg.responseKind || null,
           content: buildSnippet(msg.content, normalizedKeyword),
           mode: msg.mode,
           time: msg.time || msg.timestamp || null,
@@ -277,6 +296,7 @@ Results are returned newest-first with a bounded matching snippet and source met
           results: [],
           scope: ctx?.sessionId ? scope : 'legacy-global',
           message: `No matches found for "${normalizedKeyword}"`,
+          notice: RESULT_NOTICE,
           telemetry: searchTelemetry,
         });
       }
@@ -286,9 +306,9 @@ Results are returned newest-first with a bounded matching snippet and source met
         totalResults: results.length,
         keyword: normalizedKeyword,
         scope: ctx?.sessionId ? scope : 'legacy-global',
-        ...(scope === 'project' && ctx?.sessionId
-          ? { notice: 'Sibling Session results are reference context, not continuation of the current task.' }
-          : {}),
+        notice: RESULT_NOTICE + (scope === 'project' && ctx?.sessionId
+          ? ' Sibling Session results are reference context, not continuation of the current task.'
+          : ''),
         telemetry: searchTelemetry,
       });
     } catch (err) {

package/yeaft/tools/types.js

@@ -25,6 +25,8 @@
  * @property {(input: {query:string, cursor?:number, maxResults?:number}) => Promise<object>|object} [discoverTools] — page through hidden registered tool capabilities and activate returned entries for the next provider loop
  * @property {import('../tasks/manager.js').TaskManager} [taskManager] — Session task manager
  * @property {string} [sessionId] — current Session id
+ * @property {string} [queryTurnId] — unique identity of the owning Engine query
+ * @property {number} [historyBeforeSeq] — durable current-user boundary; default history recall excludes this sequence and later
  * @property {string[]} [projectSessionIds] — same-Agent sibling Session ids in the current Project
  * @property {string} [threadId] — current Session thread id
  * @property {string} [currentVpId] — R6: VP id of the caller (set in multi-VP groups)

package/yeaft/tools/wait-agent.js

@@ -36,6 +36,7 @@ import { isTerminalAgentStatus, STATUS } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
 import { describeAgentLifecycle, describeAgentOutcome } from '../sub-agent/outcome.js';
+import { getAgentResultRef } from '../sub-agent/result-reference.js';
 
 /**
  * Build the status-specific next-step guidance the LLM reads after a wait.
@@ -203,7 +204,19 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     env.truncated = Boolean(agent.finalReport?.truncated);
     env.partial_output = resultText;
   }
-  env.result = resultText;
+  env.resultRef = getAgentResultRef(agent);
+  const settled = !timedOut && (status === STATUS.IDLE || isTerminalAgentStatus(status));
+  if (settled && agent.collectedResultRef === env.resultRef) {
+    env.alreadyCollected = true;
+    env.next_steps = 'This unchanged reply was already collected. Reuse resultRef; read outputFile only if you need the original evidence. Do not wait again for this reply. PromptAgent queues new work; CloseAgent finalizes idle work.';
+    // Preserve lifecycle/outcome and live diagnostics, not duplicate evidence.
+    if (env.error) env.error = env.error.slice(0, 400);
+    delete env.partial_output;
+    delete env.final_report;
+  } else {
+    env.result = resultText;
+    if (settled) agent.collectedResultRef = env.resultRef;
+  }
   return env;
 }
 
@@ -235,6 +248,10 @@ wait loop but does not cancel or prove failure: inspect outputFile before decidi
 For ordinary SpawnAgent background work, use ListAgents or later completion
 notifications instead of repeatedly re-waiting.
 
+An unchanged reply already collected by WaitAgent returns alreadyCollected=true and
+resultRef instead of repeating result text. PromptAgent starts a new collectable revision,
+even when its reply text is identical. Lifecycle and liveness remain current.
+
 The default wait is a bounded 5000ms poll; callers may request up to 300000ms
 (5 minutes). This caps one WaitAgent call only, not the sub-agent lifetime.`,
     zh: `等待子 Agent 的下一次状态变更（turn 结束、终止或等待超时）并获取状态信封。
@@ -256,6 +273,9 @@ PromptAgent 后若非 stale/stalled 的有界等待超时，必须在同一父
 若信封显示 stale/stalled，应停止盲目等待并检查 outputFile；它只是诊断，不会取消任务，也不能证明
 provider 或工具已经卡死。仅在确实要取消时使用 CloseAgent。
 
+WaitAgent 已收集且未变化的回复仅返回 alreadyCollected=true 和 resultRef，不重印结果。
+PromptAgent 会产生新的可收集 revision，即使回复文本相同；生命周期和 liveness 仍实时返回。
+
 普通 SpawnAgent 异步流程仍用 ListAgents 做非阻塞状态检查，并依赖后续 completion
 notification；默认 5000ms、最大 300000ms 仅限制单次 WaitAgent 调用，不限制子 Agent 生命周期。`
   },

package/yeaft/tools/web-fetch.js

@@ -79,6 +79,13 @@ Guidelines:
           zh: '最大内容长度，单位字符（默认 50000）',
         },
       },
+      polling: {
+        type: 'boolean',
+        description: {
+          en: 'Set true only for user-requested live status polling while waiting for external work. Not for repeatedly reading documents, schemas or static API responses. Does not change response formatting.',
+          zh: '仅在用户要求等待外部任务并轮询实时状态时设为 true，不用于重复读取文档、schema 或静态 API 响应；不改变响应格式。',
+        },
+      },
       raw: {
         type: 'boolean',
         description: {
@@ -91,6 +98,8 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  // Live waiting is explicit; raw formatting alone never exempts static reads.
+  duplicateCallPolicy: (input) => input?.polling === true ? 'allow' : 'warn',
   async execute(input, ctx) {
     const { url, max_length = 50000, raw = false } = input;
     if (!url) return JSON.stringify({ error: 'url is required' });