@yeaft/webchat-agent 0.1.1084 → 0.1.1086

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.1084",
+  "version": "0.1.1086",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -22,7 +22,7 @@ import { promises as fsp } from 'fs';
 import { join, resolve as resolvePath } from 'path';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { getRuntimePlatformInfo } from './runtime-platform.js';
-import { LLMContextError, LLMAbortError, LLMRateLimitError, LLMServerError } from './llm/adapter.js';
+import { LLMContextError, LLMAbortError, LLMRateLimitError, LLMServerError, LLMStreamIdleTimeoutError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes } from './sessions/pre-flow.js';
 import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './sessions/project-doc.js';
 import { partitionMessages } from './compact/partition.js';
@@ -300,9 +300,10 @@ export function shouldAllowGroupReflection({
  * @typedef {{ type: 'consolidate', archivedCount: number, extractedCount: number }} ConsolidateEvent
  * @typedef {{ type: 'recall', entryCount: number, cached: boolean }} RecallEvent
  * @typedef {{ type: 'fallback', from: string, to: string, reason: string }} FallbackEvent
- * @typedef {{ type: 'llm_retry', attempt: number, maxRetries: number, delayMs: number, reason: 'rate_limit_retry_after'|'rate_limit_backoff'|'transient_backoff', errorName: string, statusCode: number|null, message: string }} LlmRetryEvent
+ * @typedef {{ type: 'llm_retry', attempt: number, maxRetries: number, delayMs: number, reason: 'rate_limit_retry_after'|'rate_limit_backoff'|'transient_backoff'|'stream_idle_timeout', errorName: string, statusCode: number|null, message: string }} LlmRetryEvent
+ * @typedef {{ type: 'error', error: Error, retryable: boolean, reason?: 'stream_idle_timeout', retryExhausted?: boolean }} ErrorEvent
  *
- * @typedef {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent | ConsolidateEvent | RecallEvent | FallbackEvent | LlmRetryEvent} EngineEvent
+ * @typedef {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent | ConsolidateEvent | RecallEvent | FallbackEvent | LlmRetryEvent | ErrorEvent} EngineEvent
  */
 
 // ─── Engine ──────────────────────────────────────────────────────
@@ -466,6 +467,50 @@ export class Engine {
   /** @type {Array<{content:string|Array, preview:string}>} */
   #pendingUserMessages = [];
 
+  /**
+   * Tasks (background bash, sub-agent spawns) that were launched DURING
+   * the currently-running query() and have NOT terminated yet. The query
+   * loop refuses to finalize end_turn while this set is non-empty — instead
+   * it parks on `#asyncTaskWaiters` until a terminal event or a new user
+   * append wakes it up. Cleared at the top of each query() and again in
+   * the finally block so a stale set never leaks across turns.
+   * @type {Set<string>}
+   */
+  #pendingAsyncTaskIds = new Set();
+
+  /**
+   * Terminal task events that arrived after their producing tool already
+   * returned. Each entry becomes a synthetic user message at the next
+   * adapter boundary. Format mirrors `#pendingUserMessages` so the same
+   * drain path can splice both into `conversationMessages`.
+   * @type {Array<{content:string|Array, preview:string, internal:boolean, taskId?:string}>}
+   */
+  #pendingTaskResultMessages = [];
+
+  /**
+   * Resolvers parked by the main loop while it waits for an async task to
+   * terminate (or a fresh user append to arrive). Wake order is FIFO; every
+   * resolver is invoked exactly once and the queue cleared, so a single
+   * task completion releases every waiter in the same engine and the loop
+   * decides on the next iteration whether to keep waiting.
+   * @type {Array<() => void>}
+   */
+  #asyncTaskWaiters = [];
+
+  /**
+   * External coordinator hooks. `getOrCreateVpEngine` (web-bridge.js)
+   * installs these so the bridge can route a `taskManager` `completed`
+   * event back to THIS engine while it's still running its query() — same
+   * turn, next adapter loop. Unset (null) in non-bridge contexts (tests,
+   * sub-agents without a bridge) — the engine then degrades to "no
+   * coordinator", which still works because tools call back through
+   * `toolCtx.registerAsyncTask` and the engine waits locally; web-bridge
+   * fallback (legacy `scheduleTaskResultReentry` → new turn) handles the
+   * post-run case.
+   * @type {{ onRegister?: (taskId:string, engine:Engine) => void, onUnregister?: (taskId:string) => void } | null}
+   */
+  #asyncTaskCoordinator = null;
+
   /**
    * Per-group "adjust has run at least once this engine lifetime" flag.
    * Keyed by sessionId (or 'default'). The first turn always runs adjust;
@@ -1042,6 +1087,13 @@ export class Engine {
       // can mark "after this batch, end the turn — do NOT call adapter
       // again". Honored at the top of the tool-loop continuation.
       requestEndTurn: vpCtx?.requestEndTurn,
+      // Background-task ownership hook. Tools that produce a TaskManager
+      // task (bash background, agent spawn) call this with the new
+      // `task.id` so the engine keeps the current query parked at end_turn
+      // until the task terminates — its result is then spliced into the
+      // next adapter loop in the SAME turn. Tools that don't produce
+      // async tasks ignore it.
+      registerAsyncTask: (taskId) => this.#registerAsyncTask(taskId),
       // Sub-agent plumbing — Agent tool needs these to spawn a child
       // Engine that inherits the parent's adapter / stores / toolset.
       parentEngineDeps: {
@@ -1065,6 +1117,12 @@ export class Engine {
         // to. Null when the parent has no stats wired (e.g. tests).
         toolStats: this.#toolStats || null,
         taskManager: this.#taskManager || null,
+        // Propagate the async-task coordinator so sub-agents launched
+        // from this engine register their background tasks against the
+        // SAME owner map the bridge uses. Without this, a sub-agent's
+        // background bash terminal event would not find its engine and
+        // would fall through to the legacy rescue path.
+        asyncTaskCoordinator: this.#asyncTaskCoordinator || null,
       },
     };
   }
@@ -1394,16 +1452,28 @@ export class Engine {
     if (this.#pendingUserMessages.length > 0) {
       pending.push(...this.#pendingUserMessages.splice(0));
     }
+    // Task-result re-entries flow through the same drain so the main loop
+    // sees ONE append queue. Each entry carries `internal: true` so the
+    // `user_append` event downstream is tagged correctly (UI hides the
+    // bubble; persistence stamps role=assistant).
+    if (this.#pendingTaskResultMessages.length > 0) {
+      pending.push(...this.#pendingTaskResultMessages.splice(0));
+    }
     return pending
       .map((item) => {
-        if (typeof item === 'string') return { content: item, preview: item };
+        if (typeof item === 'string') return { content: item, preview: item, internal: false };
         if (!item || typeof item !== 'object') return null;
         const content = item.content ?? item.text;
         if (typeof content !== 'string' && !Array.isArray(content)) return null;
         const preview = typeof item.preview === 'string'
           ? item.preview
           : (typeof content === 'string' ? content : '[content blocks]');
-        return { content, preview };
+        return {
+          content,
+          preview,
+          internal: Boolean(item.internal),
+          taskId: typeof item.taskId === 'string' ? item.taskId : undefined,
+        };
       })
       .filter(Boolean);
   }
@@ -1512,6 +1582,27 @@ export class Engine {
       this.#abortReason = null;
       this.#currentThreadId = MAIN_THREAD_ID;
       this.#pendingUserMessages.length = 0;
+      // Hand back any async tasks still on the books to the coordinator so
+      // a late terminal event falls through to the legacy rescue path
+      // (new turn) instead of being silently swallowed. The coordinator
+      // is responsible for keeping its owner map in sync.
+      if (this.#pendingAsyncTaskIds.size > 0) {
+        const leftover = Array.from(this.#pendingAsyncTaskIds);
+        this.#pendingAsyncTaskIds.clear();
+        for (const tid of leftover) {
+          try { this.#asyncTaskCoordinator?.onUnregister?.(tid); } catch { /* ignore */ }
+        }
+      }
+      this.#pendingTaskResultMessages.length = 0;
+      // Release any parked waiters so they don't pin a microtask after
+      // query() returns. The loop has already exited so they're harmless,
+      // but cleanup keeps the promise graph tight.
+      if (this.#asyncTaskWaiters.length > 0) {
+        const waiters = this.#asyncTaskWaiters.splice(0);
+        for (const r of waiters) {
+          try { r(); } catch { /* ignore */ }
+        }
+      }
     }
   }
 
@@ -2232,12 +2323,13 @@ export class Engine {
           }
         }
 
-        // ─── Rate-limit / transient retry ─────────────────
+        // ─── Rate-limit / transient / stream-idle retry ───
         // Honour server-supplied Retry-After for 429/529; fall back to
-        // exponential backoff for 5xx and transport failures wrapped as
-        // LLMServerError. Counts against retryPolicy.maxRetries; on
-        // exhaustion we fall through to the fallback-model path (and
-        // ultimately the error event) without further waiting.
+        // exponential backoff for 5xx, transport failures, and stream-idle
+        // timeouts wrapped as LLMServerError. Counts against
+        // retryPolicy.maxRetries; on exhaustion we fall through to the
+        // fallback-model path (and ultimately the error event) without
+        // further waiting.
         const isRateLimit = err instanceof LLMRateLimitError;
         const isTransient = err instanceof LLMServerError;
         if (isRateLimit || isTransient) {
@@ -2259,7 +2351,9 @@ export class Engine {
               reason = 'rate_limit_backoff';
             } else {
               delayMs = computeBackoffDelay(retryPolicy, consecutiveRetryableErrors - 1);
-              reason = 'transient_backoff';
+              reason = err instanceof LLMStreamIdleTimeoutError
+                ? 'stream_idle_timeout'
+                : 'transient_backoff';
             }
             yield {
               type: 'llm_retry',
@@ -2286,7 +2380,7 @@ export class Engine {
         // ─── Fallback model ──────────────────────────────
         const fallbackModel = this.#config.fallbackModel;
         if (fallbackModel && fallbackModel !== currentModel &&
-            (err.name === 'LLMRateLimitError' || err.name === 'LLMServerError')) {
+            (err instanceof LLMRateLimitError || err instanceof LLMServerError)) {
           yield { type: 'fallback', from: currentModel, to: fallbackModel, reason: err.message };
           currentModel = fallbackModel;
           consecutiveRetryableErrors = 0; // new model, fresh retry budget
@@ -2294,11 +2388,17 @@ export class Engine {
           continue; // retry with fallback model
         }
 
-        yield {
+        const isRetryableError = err instanceof LLMRateLimitError || err instanceof LLMServerError;
+        const errorEvent = {
           type: 'error',
           error: err,
-          retryable: err.name === 'LLMRateLimitError' || err.name === 'LLMServerError',
+          retryable: isRetryableError,
         };
+        if (err instanceof LLMStreamIdleTimeoutError) {
+          errorEvent.reason = 'stream_idle_timeout';
+          errorEvent.retryExhausted = consecutiveRetryableErrors >= retryPolicy.maxRetries;
+        }
+        yield errorEvent;
         yield { type: 'turn_end', turnNumber, stopReason: 'error', threadId };
         break;
       }
@@ -2460,6 +2560,80 @@ export class Engine {
         continue;
       }
 
+      // If no tool calls, we're done — UNLESS we still own a pending
+      // async task. The user-facing semantic: a turn that launched a
+      // background bash / sub-agent stays "live" until those tasks
+      // terminate (or the user appends, or abort). The model already
+      // said end_turn; we just defer finalization by parking on the
+      // wait queue, then splice the synthetic task-result message in
+      // and run one more adapter loop. This matches the contract the
+      // bridge documents for `formatTaskResultForVp`: "Consume it now:
+      // tell the user the outcome or continue the work. Do not wait
+      // for another user turn."
+      if ((stopReason !== 'tool_use' || toolCalls.length === 0)
+          && this.#pendingAsyncTaskIds.size > 0
+          && !signal?.aborted) {
+        // Drop into a wait loop. The loop wakes on (a) any task
+        // terminal event delivered via `notifyAsyncTaskCompleted`, (b)
+        // a fresh user append (which is honored as a higher priority
+        // user input), or (c) abort. On wake we re-check: if either
+        // queue has content, drain + splice + continue the outer loop.
+        // If both queues are empty AND we still have pending tasks AND
+        // we're not aborted, we just keep waiting. This is the only
+        // place query() can block on something other than the LLM stream.
+        yield {
+          type: 'async_task_wait_start',
+          turnId: queryTurnId,
+          loopNumber: turnNumber,
+          threadId,
+          pendingTaskIds: Array.from(this.#pendingAsyncTaskIds),
+        };
+        // Race-safe wait: a `notifyAsyncTaskCompleted` callback that
+        // arrives synchronously between `yield` and the `await` below
+        // (e.g. the bridge handles a task event in the same microtask
+        // as the wait_start event) will already have populated the
+        // queues, so #waitForAsyncWake resolves immediately on its
+        // fast-path check. Drain BEFORE deciding to continue so we
+        // never "fall through" with content sitting in either queue.
+        while (!signal?.aborted
+               && this.#pendingTaskResultMessages.length === 0
+               && this.#pendingUserMessages.length === 0) {
+          if (this.#pendingAsyncTaskIds.size === 0) break;
+          await this.#waitForAsyncWake(signal);
+        }
+        yield {
+          type: 'async_task_wait_end',
+          turnId: queryTurnId,
+          loopNumber: turnNumber,
+          threadId,
+          aborted: Boolean(signal?.aborted),
+          remainingTaskIds: Array.from(this.#pendingAsyncTaskIds),
+        };
+        if (!signal?.aborted) {
+          const appendedAfterAsyncWait = this.#drainPendingUserMessages(drainPendingUserMessages);
+          if (appendedAfterAsyncWait.length > 0) {
+            for (const item of appendedAfterAsyncWait) {
+              conversationMessages.push({ role: 'user', content: item.content });
+              yield {
+                type: 'user_append',
+                turnId: queryTurnId,
+                loopNumber: turnNumber,
+                threadId,
+                preview: String(item.preview || '').slice(0, 200),
+                internal: Boolean(item.internal),
+                taskId: typeof item.taskId === 'string' ? item.taskId : undefined,
+              };
+            }
+            yield { type: 'turn_end', turnNumber, stopReason: 'async_task_continue', threadId };
+            continue;
+          }
+        }
+        // If we fall through here, either abort fired or the wait
+        // exited with no payload (all tasks released themselves via
+        // engine teardown / unregister with no notification). Drop into
+        // the regular end_turn path.
+      }
+
       // If no tool calls, we're done
       if (stopReason !== 'tool_use' || toolCalls.length === 0) {
         if (pendingSubAgentNotifs.length > 0) {
@@ -3109,9 +3283,134 @@ export class Engine {
     if (typeof content === 'string' && !content.trim()) return false;
     const preview = typeof content === 'string' ? content : '[content blocks]';
     this.#pendingUserMessages.push({ content, preview });
+    // Wake the async-task wait loop too. A user typing while the engine
+    // is parked on a background task should release the loop immediately
+    // so the user's words get spliced into the next iteration.
+    this.#wakeAsyncTaskWaiters();
+    return true;
+  }
+
+  /**
+   * Install the coordinator that lets an external dispatcher (web-bridge)
+   * route a background task's terminal event back to THIS engine while
+   * its query() is still running. Pass `null` to detach.
+   * @param {{ onRegister?: (taskId:string, engine:Engine) => void, onUnregister?: (taskId:string) => void } | null} coord
+   */
+  setAsyncTaskCoordinator(coord) {
+    this.#asyncTaskCoordinator = (coord && typeof coord === 'object') ? coord : null;
+  }
+
+  /**
+   * True iff the currently-running query is holding pending async tasks.
+   * Used by external probes (web-bridge fallback dispatcher) to decide
+   * whether a task terminal event should be injected into the same turn
+   * or fall back to the legacy "open a new turn" rescue path.
+   * @returns {boolean}
+   */
+  hasPendingAsyncTasks() {
+    return this.#pendingAsyncTaskIds.size > 0;
+  }
+
+  /**
+   * True iff THIS engine has registered the given taskId as belonging to
+   * the currently-running query. Web-bridge calls this before
+   * `notifyAsyncTaskCompleted` so a terminal event for a task that wasn't
+   * launched from this turn (or whose engine already finished) falls
+   * through to the legacy rescue path.
+   * @param {string} taskId
+   * @returns {boolean}
+   */
+  ownsPendingAsyncTask(taskId) {
+    return typeof taskId === 'string' && this.#pendingAsyncTaskIds.has(taskId);
+  }
+
+  /**
+   * Deliver a terminal task event into the currently-running query. Drops
+   * the task from the pending set, queues a synthetic user message with
+   * the rendered task result, and wakes the wait loop. Returns true iff
+   * the engine accepted ownership (the bridge should NOT fall back to the
+   * legacy rescue path). Returns false when the engine was never holding
+   * this taskId — caller should fall through to its rescue path.
+   *
+   * @param {string} taskId
+   * @param {string|Array} content — pre-formatted task result body
+   * @param {{ preview?: string }} [opts]
+   * @returns {boolean}
+   */
+  notifyAsyncTaskCompleted(taskId, content, opts = {}) {
+    if (!this.ownsPendingAsyncTask(taskId)) return false;
+    if (typeof content !== 'string' && !Array.isArray(content)) return false;
+    if (typeof content === 'string' && !content.trim()) return false;
+    // Defensive: an empty content-block array would splice as a wire-valid
+    // but semantically empty user message, which the adapter would happily
+    // forward and bill for. Production callers (formatTaskResultForVp)
+    // always emit a non-empty string today; this guards future refactors.
+    if (Array.isArray(content) && content.length === 0) return false;
+    this.#pendingAsyncTaskIds.delete(taskId);
+    try { this.#asyncTaskCoordinator?.onUnregister?.(taskId); } catch { /* coord must not throw into engine */ }
+    const preview = typeof opts.preview === 'string'
+      ? opts.preview
+      : (typeof content === 'string' ? content.slice(0, 200) : '[task result]');
+    this.#pendingTaskResultMessages.push({
+      content,
+      preview,
+      internal: true,
+      taskId,
+    });
+    this.#wakeAsyncTaskWaiters();
     return true;
   }
 
+  /**
+   * Register a background task as belonging to the current query. Called
+   * from tools (bash background, agent spawn) via `toolCtx.registerAsyncTask`.
+   * @param {string} taskId
+   * @returns {void}
+   */
+  #registerAsyncTask(taskId) {
+    if (typeof taskId !== 'string' || !taskId) return;
+    this.#pendingAsyncTaskIds.add(taskId);
+    try { this.#asyncTaskCoordinator?.onRegister?.(taskId, this); } catch { /* coord must not throw into tools */ }
+  }
+
+  #wakeAsyncTaskWaiters() {
+    if (this.#asyncTaskWaiters.length === 0) return;
+    const waiters = this.#asyncTaskWaiters.splice(0);
+    for (const resolve of waiters) {
+      try { resolve(); } catch { /* never break the loop on a stray callback */ }
+    }
+  }
+
+  /**
+   * Wait for *any* of: an async task terminal event, a fresh user append,
+   * or signal abort. Resolves immediately if any of those is already
+   * pending. The loop re-evaluates conditions on wake — multiple
+   * concurrent tasks all wake the same waiter once, then the loop drains
+   * everything in one iteration and decides whether to keep waiting.
+   * @param {AbortSignal|null|undefined} signal
+   * @returns {Promise<void>}
+   */
+  #waitForAsyncWake(signal) {
+    return new Promise((resolve) => {
+      // Fast paths — anything already pending releases instantly. This is
+      // the common case when a task finished between adapter loops.
+      if (this.#pendingTaskResultMessages.length > 0) return resolve();
+      if (this.#pendingUserMessages.length > 0) return resolve();
+      if (signal?.aborted) return resolve();
+      this.#asyncTaskWaiters.push(resolve);
+      if (signal && typeof signal.addEventListener === 'function') {
+        // Best-effort abort wakeup; the loop re-checks signal.aborted.
+        const onAbort = () => {
+          // Splice the resolver out of the wait queue so it can't double-fire.
+          const idx = this.#asyncTaskWaiters.indexOf(resolve);
+          if (idx >= 0) this.#asyncTaskWaiters.splice(idx, 1);
+          try { resolve(); } catch { /* ignore */ }
+        };
+        try { signal.addEventListener('abort', onAbort, { once: true }); } catch { /* old runtimes */ }
+      }
+    });
+  }
+
   /** @returns {string|null} */
   get yeaftDir() { return this.#yeaftDir; }
 

package/yeaft/sub-agent/runner.js

@@ -156,6 +156,12 @@ export function startSubAgent(agent, deps = {}) {
     toolStats: deps.toolStats || null,
     taskManager: deps.taskManager || null,
   });
+  // Same-turn async-task plumbing: inherit the parent's coordinator so a
+  // background bash launched FROM this sub-agent registers itself against
+  // the shared owner map and its terminal event reaches the sub-engine.
+  if (deps.asyncTaskCoordinator && typeof subEngine.setAsyncTaskCoordinator === 'function') {
+    subEngine.setAsyncTaskCoordinator(deps.asyncTaskCoordinator);
+  }
 
   agent.subEngine = subEngine;
   agent.engineMessages = agent.engineMessages || [];

package/yeaft/tools/agent.js

@@ -427,7 +427,14 @@ use it as the default workflow or call it repeatedly in a loop.`,
           runtime: { subAgentId: agentId, name, cwd: agent.cwd },
           source: { threadId: callerScope.parentThreadId || ctx?.threadId || 'main' },
         });
-        if (task?.id) agent.taskId = task.id;
+        if (task?.id) {
+          agent.taskId = task.id;
+          // Same-turn parking — see tools/bash.js for the contract. The
+          // sub-agent runs in its own engine but reports completion
+          // through the same TaskManager event, so the spawning turn
+          // stays parked until the sub-agent finishes.
+          try { ctx.registerAsyncTask?.(task.id); } catch { /* coord errors must not block spawn */ }
+        }
         startSubAgent(agent, deps);
       } catch (err) {
         agent.status = STATUS.FAILED;

package/yeaft/tools/bash.js

@@ -246,6 +246,12 @@ Guidelines:
             threadId: ctx.threadId || 'main',
           },
         });
+        // Same-turn parking: tell the engine "this turn has an async
+        // task in flight". The engine refuses to finalize end_turn
+        // while the set is non-empty and will splice the task result
+        // into the next adapter loop when it terminates. No-op when
+        // the engine didn't wire the hook (legacy callers / tests).
+        try { ctx.registerAsyncTask?.(task.id); } catch { /* never block tool return on coord errors */ }
         return `Started background task ${task.id}.\nStatus: ${task.status}\nLog: ${task.log?.path || ''}\nUse ListTasks, ReadTaskLog, or CancelTask to inspect or control it.`;
       } catch (err) {
         return JSON.stringify({ error: err?.message || String(err) });

package/yeaft/web-bridge.js

@@ -258,6 +258,42 @@ const vpDrivers = new Map();
 const vpEngines = new Map();
 /** @type {Map<string, AbortController>} */
 const vpAborts = new Map();
+
+/**
+ * Owner index for background tasks currently parked on a running engine.
+ * Populated by the per-engine async-task coordinator at register time;
+ * cleared at notify time or when the engine teardown unregisters whatever
+ * it didn't get to deliver. Used by `scheduleTaskResultReentry` to pick
+ * "same-turn injection" over the legacy "new turn" rescue path when the
+ * engine is still live.
+ * @type {Map<string, import('./engine.js').Engine>}
+ */
+const asyncTaskOwners = new Map();
+
+/**
+ * Build a coordinator for a freshly-constructed engine. The coordinator
+ * keeps `asyncTaskOwners` in sync so a `taskManager` `completed` event
+ * can find the engine that launched it in O(1).
+ *
+ * Defined as a factory (not a single shared object) so each engine's
+ * `onRegister` callback closes over its own engine reference — sub-agents
+ * inherit a coordinator that still associates their tasks with the
+ * sub-engine, not the parent.
+ *
+ * @returns {{ onRegister: (taskId: string, engine: import('./engine.js').Engine) => void, onUnregister: (taskId: string) => void }}
+ */
+function buildAsyncTaskCoordinator() {
+  return {
+    onRegister(taskId, engine) {
+      if (typeof taskId !== 'string' || !taskId) return;
+      asyncTaskOwners.set(taskId, engine);
+    },
+    onUnregister(taskId) {
+      if (typeof taskId !== 'string' || !taskId) return;
+      asyncTaskOwners.delete(taskId);
+    },
+  };
+}
 /**
  * Per-(sessionId, vpId) current TodoWrite list. Each VP in a group keeps
  * its own todo state so two VPs in the same group can independently
@@ -956,6 +992,15 @@ function getOrCreateVpEngine(sessionId, vpId, threadId = 'main') {
     sessionId,
     vpId,
   });
+  // Install the async-task coordinator so background tasks launched
+  // from this engine register against the shared owner map and
+  // `scheduleTaskResultReentry` can deliver terminal events back into
+  // the same query() instead of opening a fresh turn.
+  try {
+    if (typeof eng.setAsyncTaskCoordinator === 'function') {
+      eng.setAsyncTaskCoordinator(buildAsyncTaskCoordinator());
+    }
+  } catch { /* coordinator is best-effort plumbing, never block engine creation */ }
   vpEngines.set(key, eng);
   return eng;
 }
@@ -1053,6 +1098,36 @@ function scheduleTaskResultReentry(event) {
   const vpId = task.ownerVpId || null;
   if (!sessionId || !vpId) return;
   const threadId = task.source?.threadId || task.runtime?.threadId || 'main';
+  const formatted = formatTaskResultForVp(task);
+
+  // Same-turn fast path: when the engine that launched this task is
+  // still running its query() AND has parked on the wait queue, hand
+  // the result straight in — it splices into the very next adapter
+  // loop with no new turn / new VP envelope. Falls through to the
+  // legacy "open a new turn" rescue path when:
+  //   - the engine already finished (typical orphan / late completion),
+  //   - the engine was torn down between register and complete, or
+  //   - the task wasn't registered with the engine in the first place
+  //     (e.g. legacy `taskManager.startTask` callers that bypass tools).
+  const ownerEngine = asyncTaskOwners.get(task.id);
+  if (ownerEngine
+      && typeof ownerEngine.ownsPendingAsyncTask === 'function'
+      && ownerEngine.ownsPendingAsyncTask(task.id)
+      && typeof ownerEngine.notifyAsyncTaskCompleted === 'function') {
+    try {
+      const accepted = ownerEngine.notifyAsyncTaskCompleted(task.id, formatted, {
+        preview: `task ${task.kind || 'tool'} ${task.status}`,
+      });
+      if (accepted) {
+        asyncTaskOwners.delete(task.id);
+        return;
+      }
+    } catch {
+      // Same-turn delivery is best-effort. Fall through to the legacy
+      // rescue path so we never drop a terminal event on the floor.
+    }
+  }
+
   const msgId = `task_result_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
   queueMicrotask(() => {
     enqueueForVp(sessionId, vpId, {
@@ -1064,7 +1139,7 @@ function scheduleTaskResultReentry(event) {
         id: msgId,
         from: 'tool',
         role: 'assistant',
-        text: formatTaskResultForVp(task),
+        text: formatted,
         meta: {
           injectedBy: 'task_result',
           taskId: task.id,
@@ -1399,6 +1474,7 @@ export async function __testResetVpState() {
   vpInboxes.clear();
   vpDrivers.clear();
   vpEngines.clear();
+  asyncTaskOwners.clear();
   vpAborts.clear();
   sessionContexts.clear();
   vpCurrentTodos.clear();
@@ -2345,8 +2421,9 @@ function handleEngineEvent(event, hctx) {
 
     case 'llm_retry':
       // Engine paused before re-issuing the same turn because the LLM
-      // returned a retryable error (rate limit / 5xx / transient network).
-      // Surface to the client so the UI can show "retrying in Xs (1/3)"
+      // returned a retryable error (rate limit / 5xx / transient network /
+      // stream idle timeout). Surface to the client so the UI can show
+      // "retrying in Xs (1/3)"
       // instead of looking frozen mid-turn.
       sendSessionEvent({
         type: 'llm_retry',
@@ -2456,6 +2533,37 @@ function handleEngineEvent(event, hctx) {
       }, envelope);
       break;
 
+    // Same-turn async-task wait. Engine parks at end_turn while a
+    // background bash / sub-agent is still running and re-enters the
+    // same turn when the terminal event arrives (see engine.js
+    // `#runQuery` wait block). Bridge forwards both edges so the debug
+    // panel (and any other in-process subscriber) can render the park
+    // window with the live list of pending taskIds. Wire types stay
+    // namespaced under `vp_async_task_*` to match the existing
+    // `vp_thread_*` / `vp_typing_*` event family.
+    case 'async_task_wait_start':
+      sendSessionEvent({
+        type: 'vp_async_task_wait_start',
+        turnId: event.turnId,
+        threadId: event.threadId,
+        loopNumber: event.loopNumber,
+        pendingTaskIds: Array.isArray(event.pendingTaskIds) ? event.pendingTaskIds : [],
+        ts: Date.now(),
+      }, envelope);
+      break;
+
+    case 'async_task_wait_end':
+      sendSessionEvent({
+        type: 'vp_async_task_wait_end',
+        turnId: event.turnId,
+        threadId: event.threadId,
+        loopNumber: event.loopNumber,
+        aborted: Boolean(event.aborted),
+        remainingTaskIds: Array.isArray(event.remainingTaskIds) ? event.remainingTaskIds : [],
+        ts: Date.now(),
+      }, envelope);
+      break;
+
     case 'loop':
       // feat-6af5f9f1 PR B: replaces the old `debug_turn` event. Same
       // payload shape plus turnId + loopNumber + usage.totalTokens.
@@ -2482,6 +2590,14 @@ function handleEngineEvent(event, hctx) {
 
     case 'error': {
       const errMsg = event.error?.message || 'Unknown error';
+      sendSessionEvent({
+        type: 'error',
+        message: errMsg,
+        errorName: event.error?.name || null,
+        retryable: !!event.retryable,
+        ...(event.reason ? { reason: event.reason } : {}),
+        ...(event.retryExhausted !== undefined ? { retryExhausted: !!event.retryExhausted } : {}),
+      }, envelope);
       if (isPermissionErrorMsg(errMsg)) {
         if (!_permissionDiagnosticSent) {
           _permissionDiagnosticSent = true;
@@ -4160,6 +4276,7 @@ export function handleYeaftModelSwitch(msg) {
   // Engines would otherwise keep the old effective config and drop newly
   // selected effort values until process restart.
   vpEngines.clear();
+  asyncTaskOwners.clear();
 
   sendSessionEvent({
     type: 'model_switched',
@@ -4501,6 +4618,7 @@ export async function resetYeaftSession() {
   vpInboxes.clear();
   vpDrivers.clear();
   vpEngines.clear();
+  asyncTaskOwners.clear();
   sessionContexts.clear();
   vpCurrentTodos.clear();
   threadClassifier = defaultClassifyThread;