@yeaft/webchat-agent 1.0.567 → 1.0.569

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.567",
+  "version": "1.0.569",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -17,7 +17,7 @@
  * Reference: yeaft-yeaft-implementation-plan.md §3.1, §4 (Phase 2)
  */
 
-import { randomUUID } from 'crypto';
+import { randomUUID, createHash } from 'crypto';
 import { promises as fsp } from 'fs';
 import { join, resolve as resolvePath } from 'path';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
@@ -50,6 +50,13 @@ import { perfNowMs, recordAgentPerfTrace } from './perf-trace.js';
 // Default thread marker for legacy / non-group flows. Group VP runtime may
 // pass a real threadId per (sessionId, vpId, threadId) engine instance.
 const MAIN_THREAD_ID = 'main';
+
+function foldingMessageKey(message) {
+  return message?._persistedMessageId || message?.id || createHash('sha256').update(JSON.stringify([
+    message?.role, message?.toolCallId, message?.toolCalls, message?.content,
+  ])).digest('hex');
+}
+
 import { pickEffort, parseEffortPrefix, snapshotEffortDecision } from './effort.js';
 import { bindProviderState } from './llm/provider-state.js';
 import {
@@ -1666,9 +1673,9 @@ export class Engine {
     return this.#conversationStore.append(this.#conversationRecord(message, context));
   }
 
-  #persistFoldedRange(messages, startIdx, endIdx, reflection, context = {}) {
+  #persistFoldedRange(foldedMessages, reflection, context = {}) {
     if (!this.#canPersistConversation() || typeof this.#conversationStore?.foldMessages !== 'function') return null;
-    const persistedRows = (messages || []).slice(startIdx, endIdx + 1)
+    const persistedRows = (foldedMessages || [])
       .map(message => message?._persistedMessageId || message?.id)
       .filter(id => typeof id === 'string' && id)
       .map(id => ({ id }));
@@ -4101,6 +4108,10 @@ export class Engine {
               assistantText,
               language: this.#config.language,
               signal,
+              onComplete: diagnostic => this.#trace.log?.('tool_reflection', {
+                sessionId: runtimeSessionId, turnId: queryTurnId,
+                trigger: 't2', model: this.#config.model, ...diagnostic,
+              }),
             });
             // Detach: never await. The promise outlives this query() and
             // the next call will pick it up (or use the fallback stub if
@@ -4111,6 +4122,12 @@ export class Engine {
             const info = {
               promise,
               loopRange: [arcStart, arcEnd],
+              // Absolute indexes do not survive history-window reconstruction.
+              arcKeys: conversationMessages.slice(arcStart, arcEnd + 1).map(foldingMessageKey),
+              arcRows: conversationMessages.slice(arcStart, arcEnd + 1).map(message => ({
+                role: message.role, id: message.id, _persistedMessageId: message._persistedMessageId,
+                toolCallId: message.toolCallId, toolCalls: message.toolCalls?.map(call => ({ id: call.id })),
+              })),
               count: pairs.length,
               originalUserMsg: prompt,
               originatingTurnId: queryTurnId,
@@ -4904,24 +4921,25 @@ export class Engine {
             assistantText,
             language: this.#config.language,
             signal,
+            onComplete: diagnostic => this.#trace.log?.('tool_reflection', {
+              sessionId: runtimeSessionId, turnId: queryTurnId,
+              trigger: 't1', model: this.#config.model, ...diagnostic,
+            }),
           });
-          const next = collapseRangeToReflection(
+          const { messages: next, reflection: reflectionMessage, foldedMessages } = collapseRangeToReflection(
             conversationMessages, batchStart, batchEnd, content,
           );
-          const reflectionMessage = next[batchStart];
-          const durableRowsInRange = conversationMessages
-            .slice(batchStart, batchEnd + 1)
+          const durableRowsInRange = foldedMessages
             .some(message => message?._persistedMessageId || message?.id);
           const persistedReflection = this.#persistFoldedRange(
-            conversationMessages,
-            batchStart,
-            batchEnd,
+            foldedMessages,
             reflectionMessage,
             { sessionId: runtimeSessionId, model: currentModel, executionOrigin },
           );
           if (durableRowsInRange && !persistedReflection) {
             throw new Error('T1 reflection could not publish its durable range replacement');
           }
+          if (persistedReflection?.id) reflectionMessage._persistedMessageId = persistedReflection.id;
           // Raw tool rows inside the replacement range are now tombstoned in
           // durable history. Late async completions must follow the folded
           // continuation path rather than appending to those stale rows.
@@ -4934,11 +4952,12 @@ export class Engine {
           }
           conversationMessages.length = 0;
           for (const m of next) conversationMessages.push(m);
-          // After collapse: the just-inserted reflection lives at
-          // index `batchStart`. The next tool arc therefore starts
+          // The preserved users precede the reflection. The next arc starts
           // immediately after it, i.e. at conversationMessages.length
           // (the next assistant message will land here).
           arcStartIdx = conversationMessages.length;
+          // Read hints must not imply raw ranges remain in model context.
+          fileReadObservations.clear();
           lastT1AtLoopCount = completedToolLoops;
           // Bump the success counter — used by the T2 schedule check
           // to decide whether T2 still has work to do at end_turn.
@@ -5180,12 +5199,13 @@ export class Engine {
     this.#pendingT2.clear();
 
     for (const [turnNumber, info] of drained) {
-      const range = info.loopRange;
-      if (!Array.isArray(range) || range.length !== 2) continue;
-      const [startIdx, endIdx] = range;
-      if (startIdx < 0 || endIdx < startIdx || endIdx >= conversationMessages.length) {
-        continue;
-      }
+      const keys = info.arcKeys;
+      if (!Array.isArray(keys) || keys.length === 0) continue;
+      const currentKeys = conversationMessages.map(foldingMessageKey);
+      const startIdx = currentKeys.findIndex((key, index) => key === keys[0]
+        && keys.every((expected, offset) => currentKeys[index + offset] === expected));
+      const endIdx = startIdx + keys.length - 1;
+      const rangePresent = startIdx >= 0;
 
       // PR-L follow-up: deterministic readiness check. The info record
       // carries `ready / result / error` flags that are flipped from the
@@ -5214,15 +5234,13 @@ export class Engine {
       }
 
       // Rewrite history and publish the same logical replacement to disk.
-      const next = collapseRangeToReflection(conversationMessages, startIdx, endIdx, content);
-      const reflectionMessage = next[startIdx];
-      const durableRowsInRange = conversationMessages
-        .slice(startIdx, endIdx + 1)
+      const { messages: next, reflection: reflectionMessage, foldedMessages } = rangePresent
+        ? collapseRangeToReflection(conversationMessages, startIdx, endIdx, content)
+        : collapseRangeToReflection(info.arcRows, 0, info.arcRows.length - 1, content);
+      const durableRowsInRange = foldedMessages
         .some(message => message?._persistedMessageId || message?.id);
       const persistedReflection = this.#persistFoldedRange(
-        conversationMessages,
-        startIdx,
-        endIdx,
+        foldedMessages,
         reflectionMessage,
         {
           ...context,
@@ -5231,26 +5249,31 @@ export class Engine {
         },
       );
       if (durableRowsInRange && !persistedReflection) continue;
+      if (persistedReflection?.id) reflectionMessage._persistedMessageId = persistedReflection.id;
       // T2 replaces this arc in durable and in-memory history just like T1.
       // Forget its raw result handles before a late async task can append to a
       // tombstoned tool row at the next provider boundary.
-      const foldedToolCallIds = conversationMessages
-        .slice(startIdx, endIdx + 1)
+      const foldedToolCallIds = foldedMessages
         .filter(message => message?.role === 'tool' && message.toolCallId)
         .map(message => message.toolCallId);
       for (const toolCallId of foldedToolCallIds) {
         this.#persistedToolMessages.delete(toolCallId);
       }
-      // Mutate in place so caller's reference stays valid.
-      conversationMessages.length = 0;
-      for (const m of next) conversationMessages.push(m);
+      // History may have evicted the old arc. Publish only its original
+      // durable row IDs; never replace unrelated rows at stale indexes.
+      if (rangePresent) {
+        conversationMessages.length = 0;
+        for (const m of next) conversationMessages.push(m);
+      }
 
       yield {
         type: 'reflection',
         turnId: info.originatingTurnId || null,
         trigger,
         status: 'ready',
-        loopRange: [startIdx, endIdx],
+        // Wire identity must match the original pending card, even if the
+        // history window shifted or evicted its internal replacement range.
+        loopRange: info.loopRange,
         toolCount: info.count || 0,
         content,
         durationMs,

package/yeaft/sub-agent/execution-control.js

@@ -64,6 +64,14 @@ export class SubAgentToolRegistry extends ToolRegistry {
     const limit = agent.budget?.max_tool_calls;
     const llmLimit = agent.budget?.max_llm_calls;
     const llmCalls = agent.usage?.llmCalls || 0;
+    if (agent.finalizationRequested) {
+      agent.finalizationStarted = true;
+      return {
+        finalize: true,
+        maxOutputTokens: 4096,
+        prompt: '[Parent wrap-up control] Stop investigating and do not call tools. Return the final task report now using only evidence already collected. State verification, incomplete work, and blockers honestly; do not claim success merely because the lifecycle is ending.',
+      };
+    }
     const reason = limit && stats.toolCalls >= limit ? `max_tool_calls (${limit}) reached`
       : llmLimit && llmCalls >= llmLimit ? `max_llm_calls (${llmLimit}) reached` : null;
     if (reason) {
@@ -112,6 +120,9 @@ export class SubAgentToolRegistry extends ToolRegistry {
     // after cancellation, even when the underlying tool ignores AbortSignal.
     const signal = agent.abortController?.signal;
     if (signal?.aborted) throw new Error(String(signal.reason || 'Sub-agent aborted'));
+    if (agent.finalizationRequested) {
+      throw new Error('Parent requested finalization; no further child tools may execute');
+    }
     const stats = agent.execution || (agent.execution = createExecutionStats());
     const limit = agent.budget?.max_tool_calls;
     if (limit !== undefined && stats.toolCalls >= limit) {

package/yeaft/sub-agent/notifications.js

@@ -104,6 +104,10 @@ export function enqueueTerminalNotification(input) {
     budgetExceeded: Boolean(input.budgetExceeded),
     budgetReason: input.budgetReason || null,
     budgetUsage: input.budgetUsage || null,
+    outcome: input.outcome || (input.budgetExceeded ? 'incomplete' : null),
+    incomplete: Boolean(input.incomplete || input.budgetExceeded),
+    truncated: Boolean(input.truncated),
+    finalReport: input.finalReport || null,
     createdAt: Date.now(),
   };
   const key = bucketKey(scope);
@@ -218,17 +222,29 @@ export function formatNotificationsForPrompt(notifs) {
   );
   for (const n of notifs) {
     parts.push('');
-    parts.push(`<notification agent="${n.agentName}" id="${n.agentId}" status="${n.status}" turns="${n.turns}">`);
+    parts.push(`<notification agent="${n.agentName}" id="${n.agentId}" status="${n.status}" outcome="${n.outcome || 'unknown'}" turns="${n.turns}">`);
     if (n.error) parts.push(`  error: ${n.error}`);
+    if (n.incomplete) {
+      parts.push('  incomplete: true');
+      parts.push('  warning: This is partial evidence, not task success; do not treat verdict text such as APPROVE as a completed review.');
+    }
+    if (n.truncated) parts.push('  truncated: true');
     if (n.budgetExceeded) {
       parts.push('  budgetExceeded: true');
       if (n.budgetReason) parts.push(`  budgetReason: ${n.budgetReason}`);
       if (n.budgetUsage) parts.push(`  budgetUsage: ${JSON.stringify(n.budgetUsage)}`);
     }
     if (n.outputFile) parts.push(`  outputFile: ${n.outputFile}`);
+    if (n.finalReport) {
+      parts.push(`  finalReportReserved: ${Boolean(n.finalReport.reserved)}`);
+      parts.push(`  finalReportReceived: ${Boolean(n.finalReport.received)}`);
+      parts.push(`  finalReportTruncated: ${Boolean(n.finalReport.truncated)}`);
+    }
     if (n.result) {
-      const r = n.result.length > 1500 ? n.result.slice(0, 1500) + '…(truncated)' : n.result;
-      parts.push('  result:');
+      const clipped = n.result.length > 1500;
+      const r = clipped ? n.result.slice(0, 1500) + '…(display truncated)' : n.result;
+      if (clipped) parts.push('  displayTruncated: true');
+      parts.push(n.incomplete ? '  partialOutput:' : '  result:');
       parts.push(`    ${r.split('\n').join('\n    ')}`);
     }
     parts.push('</notification>');

package/yeaft/sub-agent/outcome.js

@@ -0,0 +1,39 @@
+import { STATUS, isTerminalAgentStatus } from './status.js';
+
+/** Lifecycle state and task outcome are separate contracts. */
+export function describeAgentOutcome(agent) {
+  const result = agent?.result;
+  const budgetResult = result && typeof result === 'object'
+    && result.status === 'budget_exceeded' ? result : null;
+  if (budgetResult) {
+    return {
+      status: 'incomplete',
+      complete: false,
+      reason: 'budget_exceeded',
+      truncated: Boolean(budgetResult.truncated || budgetResult.final_report?.truncated),
+    };
+  }
+  if (agent?.finalizationRequested) {
+    return { status: 'incomplete', complete: false, reason: 'parent_requested_finalization',
+      truncated: Boolean(agent.finalReport?.truncated) };
+  }
+  switch (agent?.status) {
+    case STATUS.COMPLETED:
+      return { status: 'succeeded', complete: true, reason: null, truncated: false };
+    case STATUS.FAILED:
+      return { status: 'failed', complete: false, reason: 'execution_failed', truncated: false };
+    case STATUS.CLOSED:
+      return { status: 'cancelled', complete: false, reason: 'closed', truncated: false };
+    case STATUS.ABANDONED:
+      return { status: 'incomplete', complete: false, reason: 'abandoned', truncated: false };
+    default:
+      return { status: 'pending', complete: false, reason: null, truncated: false };
+  }
+}
+
+export function describeAgentLifecycle(agent) {
+  return {
+    status: agent?.status || null,
+    terminal: isTerminalAgentStatus(agent?.status),
+  };
+}

package/yeaft/sub-agent/runner.js

@@ -42,6 +42,7 @@ import { getPersona } from '../personas.js';
 import { RESTRICTED_TOOLS, createChildToolPolicy } from './tool-access.js';
 import { buildSpawnedPreamble } from './spawned-prompt.js';
 import { STATUS, isTerminalAgentStatus } from './status.js';
+import { describeAgentOutcome } from './outcome.js';
 import { createOutputLog } from './output-log.js';
 import { makeLiveness, bumpLivenessFromEvent } from './liveness.js';
 import { consumeNotificationForAgent, enqueueTerminalNotification } from './notifications.js';
@@ -259,6 +260,8 @@ export function startSubAgent(agent, deps = {}) {
 function buildWallTimeBudgetResult(agent, reason) {
   return {
     status: 'budget_exceeded',
+    outcome: 'incomplete',
+    complete: false,
     partial_output: agent.partial_output || agent.lastResult
       || (typeof agent.result === 'string' ? agent.result : agent.result?.partial_output) || '',
     reason,
@@ -343,6 +346,19 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
   };
 
   const dequeueNextUserPrompt = () => {
+    if (agent.finalizationRequested && !agent.finalizationStarted) {
+      agent.finalizationStarted = true;
+      return {
+        // The parent's reason is audit evidence, not a child prompt. The
+        // registry supplies the authenticated control instruction separately.
+        prompt: 'Return the requested evidence-only final report; identify any unchecked scope.',
+        finalization: true,
+        parentEffortDecision: snapshotEffortDecision(agent.parentEffortDecision),
+        projectSessionIds: Array.isArray(deps.projectSessionIds) ? deps.projectSessionIds.slice() : [],
+        projectLabel: typeof deps.projectLabel === 'string' ? deps.projectLabel : '',
+        projectInstruction: typeof deps.projectInstruction === 'string' ? deps.projectInstruction : '',
+      };
+    }
     if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
     const entry = agent.pendingPrompts.shift();
     if (!entry) return null;
@@ -444,7 +460,9 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
       agent.result = '';
       let assistantText = '';
       let budgetReportText = '';
+      let finalReportText = '';
       let endedNormally = false;
+      let outputTruncated = false;
       let streamError = null;
       const priorUsageTokens = agent.usage?.tokens || 0;
       let turnUsageTokens = 0;
@@ -489,6 +507,7 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
           if (evt && evt.type === 'text_delta' && typeof evt.text === 'string') {
             assistantText += evt.text;
             if (agent.budgetReportStarted) budgetReportText += evt.text;
+            if (agent.finalizationStarted) finalReportText += evt.text;
             // Mid-stream visibility: keep lastResult fresh so a parent
             // calling WaitAgent during a long generation sees what the
             // child is currently saying, not stale text from the prior
@@ -509,6 +528,7 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
             streamError = evt.error.message || String(evt.error);
           }
           if (evt && evt.type === 'stop') {
+            if (evt.stopReason === 'max_tokens') outputTruncated = true;
             if (evt.stopReason === 'end_turn' || evt.stopReason === 'stop_sequence') {
               endedNormally = true;
             }
@@ -544,6 +564,13 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         const reason = agent.executionBudgetReason || agent.toolBudgetReason;
         agent.result = buildWallTimeBudgetResult(agent, reason);
         agent.result.reporting = { attempted: !!agent.budgetReportStarted, received: !!budgetReportText.trim() };
+        agent.result.truncated = outputTruncated;
+        agent.result.final_report = {
+          reserved: true,
+          received: !!budgetReportText.trim(),
+          truncated: outputTruncated,
+          text: budgetReportText.trim(),
+        };
         if (streamError) agent.result.reporting.error = streamError;
         agent.usage.turns += 1;
         agent.result.usage = { ...agent.usage };
@@ -553,6 +580,18 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         return;
       }
 
+      if (agent.finalizationRequested) {
+        agent.finalReport = { reserved: true, received: !!finalReportText.trim(),
+          truncated: outputTruncated, text: finalReportText.trim() };
+        agent.result = finalReportText.trim() || assistantText.trim();
+        agent.lastResult = capTail(agent.result, LAST_RESULT_MAX_CHARS);
+        agent.usage.turns += 1;
+        transitionTerminal(agent, STATUS.COMPLETED, {
+          error: streamError, diagnostic: 'parent_requested_finalization', deps,
+        });
+        return;
+      }
+
       if (streamError) {
         transitionTerminal(agent, STATUS.FAILED, {
           error: streamError,
@@ -673,11 +712,13 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
   if (agent.__terminalNotified) return;
   agent.__terminalNotified = true;
 
+  const outcome = describeAgentOutcome(agent);
   const evt = {
     type: 'sub_agent_status',
     agentId: agent.id,
     agentName: agent.name,
     status,
+    outcome: outcome.status,
     error: error || agent.error || null,
     parentSessionId: agent.parentSessionId || deps?.parentSessionId || null,
     parentVpId: agent.parentVpId || deps?.parentVpId || null,
@@ -686,14 +727,17 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
   try { agent.outputLog?.write(evt); } catch { /* ignore */ }
   if (agent.taskId && deps?.taskManager && agent.parentSessionId) {
     const budgetExceeded = agent.result?.status === 'budget_exceeded';
-    const taskStatus = budgetExceeded ? 'failed' : status === STATUS.COMPLETED ? 'succeeded'
+    const taskStatus = outcome.status === 'incomplete' ? 'failed' : status === STATUS.COMPLETED ? 'succeeded'
       : status === STATUS.CLOSED ? 'cancelled'
         : 'failed';
     try {
       deps.taskManager.completeTask(agent.parentSessionId, agent.taskId, {
         status: taskStatus,
-        error: budgetExceeded ? agent.result.reason : (error || agent.error || null),
-        summary: budgetExceeded ? JSON.stringify(agent.result) : status === STATUS.COMPLETED
+        error: outcome.status === 'incomplete' ? (agent.result?.reason || outcome.reason) : (error || agent.error || null),
+        summary: budgetExceeded ? JSON.stringify(agent.result) : agent.finalizationRequested
+          ? JSON.stringify({ outcome: outcome.status, complete: false, reason: outcome.reason,
+            partial_output: agent.result || agent.lastResult || '', final_report: agent.finalReport || null })
+          : status === STATUS.COMPLETED
           ? (typeof agent.result === 'string' ? agent.result : (agent.lastResult || null))
           : null,
       });
@@ -731,6 +775,10 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
         budgetExceeded: !!budgetResult,
         budgetReason: budgetResult?.reason || null,
         budgetUsage: budgetResult?.usage || null,
+        outcome: outcome.status,
+        incomplete: !outcome.complete,
+        truncated: outcome.truncated,
+        finalReport: budgetResult?.final_report || agent.finalReport || null,
       });
     } catch { /* never let the notification queue throw kill the driver */ }
   }
@@ -756,6 +804,9 @@ function waitUntilResumed(agent, idleAbandonMs) {
       if (Array.isArray(agent.pendingPrompts) && agent.pendingPrompts.length > 0) {
         return resolve('prompt');
       }
+      if (agent.finalizationRequested && !agent.finalizationStarted) {
+        return resolve('prompt');
+      }
       if (idleAbandonMs > 0 && Date.now() - start >= idleAbandonMs) {
         return resolve('abandoned');
       }

package/yeaft/sub-agent/status.js

@@ -21,8 +21,8 @@
  * - 'running'   : the sub-engine is processing a prompt.
  * - 'idle'      : the previous turn ended cleanly and the queue is empty.
  *                  The driver is parked in waitUntilResumed().
- * - 'completed' : terminal success — typically set by tickAgent() when a
- *                  budget cutoff is hit cleanly with a partial_output.
+ * - 'completed' : terminal lifecycle state. Inspect the separate outcome;
+ *                  a budget cutoff also ends the lifecycle but is incomplete.
  * - 'failed'    : terminal — driver/adapter/stream raised; agent.error set.
  * - 'closed'    : terminal — CloseAgent called (or driver finally{} reaped
  *                  a cleanly-finishing agent).
@@ -72,7 +72,7 @@ export function describeAgentStatus(status) {
     case STATUS.CREATED:    return 'just spawned';
     case STATUS.RUNNING:    return 'running a turn';
     case STATUS.IDLE:       return 'idle (turn ended, queue empty)';
-    case STATUS.COMPLETED:  return 'completed (terminal)';
+    case STATUS.COMPLETED:  return 'completed lifecycle (terminal; inspect outcome)';
     case STATUS.FAILED:     return 'failed (terminal)';
     case STATUS.CLOSED:     return 'closed (terminal)';
     case STATUS.ABANDONED:  return 'abandoned by idle watchdog (terminal)';

package/yeaft/tasks/manager.js

@@ -66,6 +66,7 @@ export class TaskManager {
     this.active = new Map();
     this.processes = new Map();
     this.cancelEscalationTimers = new Map();
+    this.waiters = new Map();
     this.pendingStartupEvents = [];
     this.#loadPersistedRunningTasks();
   }
@@ -88,6 +89,20 @@ export class TaskManager {
     try { sink?.(event); } catch { /* event sinks must not break tasks */ }
   }
 
+  #taskForOwner(sessionId, taskId, ownerVpId = null) {
+    const task = this.active.get(this.#key(sessionId, taskId)) || this.store.readTask(sessionId, taskId);
+    if (!task) return null;
+    if (ownerVpId && task.ownerVpId !== ownerVpId) return null;
+    return task;
+  }
+
+  #settleWaiters(key, task) {
+    const waiters = this.waiters.get(key);
+    if (!waiters) return;
+    this.waiters.delete(key);
+    for (const settle of [...waiters]) settle(task);
+  }
+
   #emit(event, task, extra = {}, { deferUntilSink = false } = {}) {
     const payload = { type: 'yeaft_task_event', event, task: publicSnapshot(task), ...extra };
     if (!this.onEvent && deferUntilSink) {
@@ -246,12 +261,13 @@ export class TaskManager {
     this.active.delete(key);
     this.processes.delete(key);
     this.#emit('completed', task);
+    this.#settleWaiters(key, task);
     return publicSnapshot(task);
   }
 
-  cancelTask(sessionId, taskId) {
+  cancelTask(sessionId, taskId, ownerVpId = null) {
     const key = this.#key(sessionId, taskId);
-    const task = this.active.get(key) || this.store.readTask(sessionId, taskId);
+    const task = this.#taskForOwner(sessionId, taskId, ownerVpId);
     if (!task) return { ok: false, error: `Unknown task: ${taskId}` };
     if (isTerminalTaskStatus(task.status)) return { ok: true, task: publicSnapshot(task) };
     const runner = this.processes.get(key);
@@ -312,21 +328,77 @@ export class TaskManager {
     return { ok: true, task: publicSnapshot(task), pending: true };
   }
 
-  listActiveTasks(sessionId = null) {
-    const tasks = Array.from(this.active.values()).filter(task => !sessionId || task.sessionId === sessionId);
+  listActiveTasks(sessionId = null, ownerVpId = null) {
+    const tasks = Array.from(this.active.values()).filter(task => (
+      (!sessionId || task.sessionId === sessionId)
+      && (!ownerVpId || task.ownerVpId === ownerVpId)
+    ));
     return tasks.map(publicSnapshot);
   }
 
-  getTask(sessionId, taskId) {
-    return publicSnapshot(this.active.get(this.#key(sessionId, taskId)) || this.store.readTask(sessionId, taskId));
+  getTask(sessionId, taskId, ownerVpId = null) {
+    return publicSnapshot(this.#taskForOwner(sessionId, taskId, ownerVpId));
   }
 
-  readTaskLog(sessionId, taskId, opts = {}) {
-    const task = this.active.get(this.#key(sessionId, taskId)) || this.store.readTask(sessionId, taskId);
+  readTaskLog(sessionId, taskId, opts = {}, ownerVpId = null) {
+    const task = this.#taskForOwner(sessionId, taskId, ownerVpId);
+    if (!task) return null;
     if (task?.log?.path) return this.store.readLogFile(task.log.path, opts);
     return this.store.readLog(sessionId, taskId, opts);
   }
 
+  /** Wait for exactly one task without reading its log into memory. */
+  waitForTask(sessionId, taskId, { timeoutMs = 120_000, signal = null, ownerVpId = null } = {}) {
+    const key = this.#key(sessionId, taskId);
+    const initial = this.#taskForOwner(sessionId, taskId, ownerVpId);
+    if (!initial) return Promise.resolve({ ok: false, error: `Unknown task: ${taskId}` });
+    if (isTerminalTaskStatus(initial.status)) {
+      return Promise.resolve({ ok: true, timedOut: false, task: publicSnapshot(initial) });
+    }
+
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      let settled = false;
+      const waiters = this.waiters.get(key) || new Set();
+      this.waiters.set(key, waiters);
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+        signal?.removeEventListener?.('abort', onAbort);
+        waiters.delete(onComplete);
+        if (waiters.size === 0 && this.waiters.get(key) === waiters) this.waiters.delete(key);
+      };
+      const finish = (value, error = null) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (error) reject(error);
+        else resolve(value);
+      };
+      const onComplete = task => finish({ ok: true, timedOut: false, task: publicSnapshot(task) });
+      const onAbort = () => {
+        const error = new Error('Task wait aborted');
+        error.name = 'AbortError';
+        finish(null, error);
+      };
+      waiters.add(onComplete);
+
+      // Register before the second read so completion cannot be missed.
+      const current = this.#taskForOwner(sessionId, taskId, ownerVpId);
+      if (!current) finish({ ok: false, error: `Unknown task: ${taskId}` });
+      else if (isTerminalTaskStatus(current.status)) onComplete(current);
+      else if (signal?.aborted) onAbort();
+      else {
+        signal?.addEventListener?.('abort', onAbort, { once: true });
+        timer = setTimeout(() => {
+          const latest = this.#taskForOwner(sessionId, taskId, ownerVpId);
+          if (!latest) finish({ ok: false, error: `Unknown task: ${taskId}` });
+          else finish({ ok: true, timedOut: !isTerminalTaskStatus(latest.status), task: publicSnapshot(latest) });
+        }, Math.max(0, Number.isFinite(timeoutMs) ? Math.floor(timeoutMs) : 120_000));
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+    });
+  }
+
   setTaskLogPath(sessionId, taskId, logPath) {
     if (!logPath || typeof logPath !== 'string') return null;
     const key = this.#key(sessionId, taskId);