@poncho-ai/harness 0.50.3 → 0.50.5

package/src/harness.ts

@@ -146,6 +146,14 @@ export interface HarnessOptions {
    * should also be browsable in the VFS. Empty by default.
    */
   systemSkillPaths?: string[];
+  /**
+   * Override the per-run hard wall-clock timeout, in seconds, taking
+   * precedence over the agent definition's `limits.timeout`. Platforms use
+   * this to give background subagents a longer budget than the foreground
+   * agent without forking the agent definition (e.g. a 1h research subagent
+   * vs. a 5-min foreground turn). `0` disables the hard timeout.
+   */
+  runTimeoutSecOverride?: number;
 }
 
 export interface HarnessRunOutput {
@@ -159,6 +167,16 @@ const now = (): number => Date.now();
 const FIRST_CHUNK_TIMEOUT_MS = 90_000; // 90s to receive the first chunk from the model
 const MAX_TRANSIENT_STEP_RETRIES = 1;
 const COMPACTION_CHECK_INTERVAL_STEPS = 3;
+// Injected as a trailing user turn on the final allowed step, with tools
+// disabled, so a step-exhausted run produces a text summary instead of
+// terminating on a dangling tool call (which surfaces to a parent agent as
+// an empty "(no response)" subagent result). See the `isFinalStep` branch in
+// the run loop.
+const FINAL_STEP_SUMMARY_PROMPT =
+  "You have reached the maximum number of steps for this run and cannot call " +
+  "any more tools. Do NOT attempt any tool calls. Using only the work you have " +
+  "already done, write your final response now: summarize what you found or " +
+  "accomplished, include any concrete results, and flag anything left unfinished.";
 const TOOL_RESULT_ARCHIVE_PARAM = "__toolResultArchive";
 const TOOL_RESULT_TRUNCATED_PREFIX = "[TRUNCATED_TOOL_RESULT]";
 const TOOL_RESULT_PREVIEW_CHARS = 700;
@@ -838,6 +856,7 @@ function extractMediaFromToolOutput(output: unknown): {
 export class AgentHarness {
   private readonly workingDir: string;
   private readonly environment: HarnessOptions["environment"];
+  private readonly runTimeoutSecOverride?: number;
   private modelProvider: ModelProviderFactory;
   private readonly modelProviderInjected: boolean;
   private readonly dispatcher = new ToolDispatcher();
@@ -1074,6 +1093,7 @@ export class AgentHarness {
   constructor(options: HarnessOptions = {}) {
     this.workingDir = options.workingDir ?? process.cwd();
     this.environment = options.environment ?? "development";
+    this.runTimeoutSecOverride = options.runTimeoutSecOverride;
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.uploadStore = options.uploadStore;
@@ -2116,7 +2136,9 @@ export class AgentHarness {
     const runId = `run_${randomUUID()}`;
     const start = now();
     const maxSteps = agent.frontmatter.limits?.maxSteps ?? 20;
-    const configuredTimeout = agent.frontmatter.limits?.timeout;
+    // A constructor-level override (e.g. a longer budget for background
+    // subagents) takes precedence over the agent definition's limits.timeout.
+    const configuredTimeout = this.runTimeoutSecOverride ?? agent.frontmatter.limits?.timeout;
     const timeoutMs = this.environment === "development" && configuredTimeout == null
       ? 0 // no hard timeout in development unless explicitly configured
       : (configuredTimeout ?? 300) * 1000;
@@ -2297,14 +2319,61 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
     };
     const isCancelled = (): boolean => input.abortSignal?.aborted === true;
     let cancellationEmitted = false;
+    // The assistant turn for the current step, captured as it streams. The
+    // assistant message + its tool results are only pushed to `messages`
+    // *together*, after the tool batch finishes — so between "model streamed
+    // a tool call" and "tools done" the turn lives only in these locals. If a
+    // cancellation lands in that window we'd otherwise drop the whole turn
+    // from the canonical history, leaving the next request with back-to-back
+    // user messages and a model with no record of what it just said (the user
+    // still sees it, since the display history is built separately). Cleared
+    // once the turn is committed, and reset at the top of every step.
+    let inflightTurn: {
+      text: string;
+      toolCalls: Array<{ id: string; name: string; input: Record<string, unknown> }>;
+    } | null = null;
     const emitCancellation = (): AgentEvent => {
       cancellationEmitted = true;
       // Snapshot the in-flight messages so the orchestrator can persist them
-      // as the canonical history. Drop a trailing assistant tool_use message
-      // that has no matching tool result — sending that to the API on the next
-      // turn would be rejected.
-      const snapshot = trimToValidPrefix([...messages]);
-      return pushEvent({ type: "run:cancelled", runId, messages: snapshot });
+      // as the canonical history.
+      const snapshot: Message[] = [...messages];
+      // Re-attach the in-flight assistant turn (if any). Synthesize a
+      // tool_result for every pending tool_use so the turn is a valid prefix —
+      // an assistant tool_use with no following tool result is rejected by the
+      // API on the next turn, which is exactly why a naive snapshot drops it.
+      if (inflightTurn && (inflightTurn.text.length > 0 || inflightTurn.toolCalls.length > 0)) {
+        const hasToolCalls = inflightTurn.toolCalls.length > 0;
+        const assistantContent = hasToolCalls
+          ? JSON.stringify({
+              text: inflightTurn.text,
+              tool_calls: inflightTurn.toolCalls.map((tc) => ({
+                id: tc.id,
+                name: tc.name,
+                input: tc.input,
+              })),
+            })
+          : inflightTurn.text;
+        snapshot.push({
+          role: "assistant",
+          content: assistantContent,
+          metadata: { timestamp: now(), id: randomUUID(), runId },
+        });
+        if (hasToolCalls) {
+          const cancelledResults = inflightTurn.toolCalls.map((tc) => ({
+            type: "tool_result" as const,
+            tool_use_id: tc.id,
+            tool_name: tc.name,
+            content: "Tool execution cancelled by user.",
+          }));
+          snapshot.push({
+            role: "tool",
+            content: JSON.stringify(cancelledResults),
+            metadata: { timestamp: now(), id: randomUUID(), runId },
+          });
+        }
+      }
+      // Defensive: drop any trailing dangling tool_use we didn't pair above.
+      return pushEvent({ type: "run:cancelled", runId, messages: trimToValidPrefix(snapshot) });
     };
 
     const resolvedModelName = agent.frontmatter.model?.name ?? "claude-opus-4-5";
@@ -2424,6 +2493,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
     let convertedUpTo = 0;
 
     for (let step = 1; step <= maxSteps; step += 1) {
+      inflightTurn = null;
       try {
         yield* drainBrowserEvents();
         if (isCancelled()) {
@@ -2883,12 +2953,24 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
 
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
 
+        // On the last permitted step, force a closing text turn: strip the
+        // tools so the model cannot start another tool call it has no step
+        // left to resolve, and append a one-shot nudge instructing it to
+        // summarize. This is what keeps a step-exhausted run (very common in
+        // subagents) from ending on a dangling tool call that a parent would
+        // see as an empty result. The nudge is appended only to this model
+        // request — it is never written into `messages`/history.
+        const isFinalStep = step === maxSteps;
+        const toolsForStep = isFinalStep ? {} : tools;
+        const messagesForStep: ModelMessage[] = isFinalStep
+          ? [...finalMessages, { role: "user", content: FINAL_STEP_SUMMARY_PROMPT }]
+          : finalMessages;
 
         const result = await streamText({
           model: modelInstance,
           ...(useStaticCache ? {} : { system: systemPrompt }),
-          messages: finalMessages,
-          tools,
+          messages: messagesForStep,
+          tools: toolsForStep,
           temperature,
           abortSignal: input.abortSignal,
           ...(typeof maxTokens === "number" ? { maxTokens } : {}),
@@ -3026,6 +3108,11 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
           return;
         }
 
+        // The model finished streaming this step's text. Capture it so a
+        // cancellation from here on persists what the user already saw; the
+        // tool calls are attached once they're parsed below.
+        inflightTurn = { text: fullText, toolCalls: [] };
+
         if (isCancelled()) {
           yield emitCancellation();
           return;
@@ -3135,6 +3222,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         name: tc.toolName,
         input: (tc as any).input as Record<string, unknown>,
       }));
+      if (inflightTurn) inflightTurn.toolCalls = toolCalls;
 
       if (toolCalls.length === 0) {
         // Detect silent empty responses — likely an SDK or model
@@ -3593,6 +3681,9 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         content: JSON.stringify(toolResultsForModel),
         metadata: toolMsgMeta as Message["metadata"],
       });
+      // Turn is now committed to `messages`; a later cancellation must not
+      // re-append it from the in-flight holder.
+      inflightTurn = null;
 
       // Post-tool-execution soft deadline: long-running tool batches (e.g.
       // multiple web_search calls) can push past the deadline. Checkpoint

package/src/isolate/polyfills.ts

@@ -610,50 +610,79 @@ const POLYFILL_FETCH_STUB = `
 
 const POLYFILL_TIMERS = `
 // --- Timers polyfill ---
+//
+// The isolate has no host event loop, so real wall-clock delays can't be
+// honoured. What we *can* do is drain pending timers on the microtask queue
+// (which isolated-vm does pump while resolving the run's promise), firing
+// them in order of their requested delay against a virtual clock. This makes
+// the overwhelmingly common pattern — \`await new Promise(r => setTimeout(r, n))\`
+// as a sleep — actually resolve instead of hanging the whole run forever.
+// Delays collapse to "as soon as possible, in delay order"; that's the right
+// trade for a sandbox with no real time. A runaway setInterval is bounded by
+// __MAX_FIRES here and, ultimately, by the host-side wall-clock timeout.
 (function() {
   let __timerId = 0;
-  const __timers = new Map();
+  const __timers = new Map();   // id -> { fn, due, type }
+  const __intervals = new Set(); // ids that should reschedule
+  let __vclock = 0;             // virtual clock (ms)
+  let __draining = false;
+  let __fired = 0;
+  const __MAX_FIRES = 1000000;  // backstop against a runaway interval
+
+  function __schedule(fn, delayMs, type, id) {
+    __timers.set(id, { fn, due: __vclock + delayMs, type });
+    if (!__draining) __drain();
+    return id;
+  }
+
+  function __drain() {
+    __draining = true;
+    const step = function() {
+      if (__timers.size === 0) { __draining = false; return; }
+      // Pick the earliest-due timer (ties broken by insertion id for FIFO).
+      let pick = null;
+      for (const [id, t] of __timers) {
+        if (pick === null || t.due < pick.t.due || (t.due === pick.t.due && id < pick.id)) {
+          pick = { id, t };
+        }
+      }
+      __timers.delete(pick.id);
+      if (pick.t.due > __vclock) __vclock = pick.t.due;
+      __fired++;
+      try { pick.t.fn(); } catch (e) { /* host timers swallow callback throws */ }
+      if (__fired > __MAX_FIRES) { __draining = false; return; }
+      Promise.resolve().then(step);
+    };
+    Promise.resolve().then(step);
+  }
 
   globalThis.setTimeout = function(fn, delay) {
     const id = ++__timerId;
     const ms = Math.max(0, Number(delay) || 0);
-    const start = Date.now();
-    __timers.set(id, { fn, ms, start, type: "timeout" });
-    // In the isolate, setTimeout returns the id but the callback is
-    // executed via a polling mechanism in the async wrapper.
-    // For simple cases (delay=0), we can use a microtask.
-    if (ms === 0) {
-      Promise.resolve().then(() => {
-        if (__timers.has(id)) {
-          __timers.delete(id);
-          fn();
-        }
-      });
-    }
-    return id;
+    return __schedule(typeof fn === "function" ? fn : function() {}, ms, "timeout", id);
   };
 
   globalThis.clearTimeout = function(id) {
     __timers.delete(id);
+    __intervals.delete(id);
   };
 
   globalThis.setInterval = function(fn, delay) {
     const id = ++__timerId;
     const ms = Math.max(1, Number(delay) || 1);
-    const wrapper = () => {
-      if (!__timers.has(id)) return;
-      fn();
-      if (__timers.has(id)) {
-        globalThis.setTimeout(wrapper, ms);
+    __intervals.add(id);
+    const tick = function() {
+      if (!__intervals.has(id)) return;
+      try { fn(); } finally {
+        if (__intervals.has(id)) __schedule(tick, ms, "interval", id);
       }
     };
-    __timers.set(id, { fn: wrapper, ms, type: "interval" });
-    globalThis.setTimeout(wrapper, ms);
-    return id;
+    return __schedule(tick, ms, "interval", id);
   };
 
   globalThis.clearInterval = function(id) {
     __timers.delete(id);
+    __intervals.delete(id);
   };
 
   // queueMicrotask if not available

package/src/isolate/runtime.ts

@@ -153,6 +153,14 @@ export function createIsolateRuntime(config: {
       const t0 = performance.now();
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       let context: any;
+      // Wall-clock guard. isolated-vm's `timeout` option only bounds the
+      // *synchronous* portion of an eval; when the script returns a promise
+      // (which ours always does — it's an async IIFE) a never-settling promise
+      // would hang here forever (e.g. `await new Promise(() => {})`, or a
+      // bound host call that never resolves). Race the eval against a host
+      // timer that disposes the isolate, so `timeLimit` bounds total execution.
+      let timedOut = false;
+      let wallTimer: ReturnType<typeof setTimeout> | undefined;
       try {
         context = await isolate.createContext();
         const jail = context.global;
@@ -197,12 +205,35 @@ export function createIsolateRuntime(config: {
         // (context.eval + promise option handles Reference.apply resolution
         // correctly, unlike compileScript().run())
         const wrapped = `(async () => {\n${code}\n})()`;
-        const rawResult = await context.eval(wrapped, {
+        const evalPromise = context.eval(wrapped, {
           filename: "<user-code>",
           promise: true,
           copy: true,
           timeout: config.timeout,
         });
+        const rawResult =
+          config.timeout > 0
+            ? await Promise.race([
+                evalPromise,
+                new Promise((_resolve, reject) => {
+                  wallTimer = setTimeout(() => {
+                    timedOut = true;
+                    // Disposing rejects the pending eval; this reject is the
+                    // one that wins the race when the promise never settles.
+                    try {
+                      isolate.dispose();
+                    } catch {
+                      /* already disposed */
+                    }
+                    reject(new Error("Execution timed out"));
+                  }, config.timeout);
+                }),
+              ])
+            : await evalPromise;
+        if (wallTimer) {
+          clearTimeout(wallTimer);
+          wallTimer = undefined;
+        }
 
         // Read captured stdout/stderr from isolate
         const stdout = (await context.eval("__stdout.join('\\n')", { copy: true })) as string;
@@ -237,6 +268,18 @@ export function createIsolateRuntime(config: {
           };
         }
 
+        if (timedOut) {
+          return {
+            stdout: "",
+            stderr: "",
+            error: {
+              message: `Execution timed out after ${config.timeout}ms`,
+              name: "TimeoutError",
+            },
+            executionTimeMs: elapsed,
+          };
+        }
+
         // Try to recover stdout/stderr captured before the error
         let stdout = "";
         let stderr = "";
@@ -258,6 +301,7 @@ export function createIsolateRuntime(config: {
           executionTimeMs: elapsed,
         };
       } finally {
+        if (wallTimer) clearTimeout(wallTimer);
         if (abortHandler && signal) {
           signal.removeEventListener("abort", abortHandler);
         }

package/src/orchestrator/index.ts

@@ -46,6 +46,9 @@ export {
 
 export {
   AgentOrchestrator,
+  lastAssistantText,
+  realResponseText,
+  abnormalEndResponse,
   type ActiveConversationRun,
   type EventSink,
   type OrchestratorHooks,

package/src/orchestrator/orchestrator.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, Message } from "@poncho-ai/sdk";
+import { getTextContent, type AgentEvent, type Message } from "@poncho-ai/sdk";
 import type { Conversation, ConversationStore, PendingSubagentResult } from "../state.js";
 import type { AgentHarness } from "../harness.js";
 import type { TelemetryEmitter } from "../telemetry.js";
@@ -28,6 +28,78 @@ import {
   STALE_SUBAGENT_THRESHOLD_MS,
 } from "./subagents.js";
 
+// ── Subagent result extraction ──
+
+/**
+ * Pull the human-readable text out of a single assistant message.
+ *
+ * Beyond the `string | ContentPart[]` shapes `getTextContent` handles, the
+ * harness serializes an assistant turn that ALSO made tool calls as a JSON
+ * string `{"text":"...","tool_calls":[...]}` (see the run loop's
+ * `assistantContent`). A naive `typeof content === "string"` read would hand
+ * that raw JSON blob back as the "response"; here we unwrap it to its `.text`.
+ */
+const assistantMessageText = (message: Message): string => {
+  const raw = getTextContent(message).trim();
+  if (raw.startsWith("{") && raw.includes("\"tool_calls\"")) {
+    try {
+      const parsed = JSON.parse(raw) as { text?: unknown };
+      if (typeof parsed.text === "string") return parsed.text.trim();
+    } catch {
+      // Not the envelope we expected — fall through to the raw string.
+    }
+  }
+  return raw;
+};
+
+/**
+ * Find the last non-empty assistant text in a subagent transcript. Walking
+ * backwards (rather than reading only the final message) means a subagent
+ * that ended on a tool-call turn still yields the prose it produced just
+ * before — instead of surfacing to the parent as an empty result.
+ */
+export const lastAssistantText = (messages: Message[]): string => {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i].role !== "assistant") continue;
+    const text = assistantMessageText(messages[i]);
+    if (text) return text;
+  }
+  return "";
+};
+
+/**
+ * The run loop stuffs a synthetic `[Error: ...]` placeholder into the draft /
+ * persisted assistant text when a run ends on `run:error` (e.g. a timeout).
+ * That placeholder is not real model output — strip it so we don't surface it
+ * to the parent as the subagent's "response".
+ */
+export const realResponseText = (text: string | undefined): string => {
+  const t = (text ?? "").trim();
+  return t.startsWith("[Error:") ? "" : t;
+};
+
+/**
+ * Build the result text delivered to the parent when a subagent ended
+ * abnormally (timeout / error) with no RunResult. We never drop the work it
+ * gathered, and the parent is told it didn't finish — e.g. it may not have
+ * written its output files — plus how to recover (use what's here, send a
+ * write-only follow-up, or read the full transcript).
+ */
+export const abnormalEndResponse = (opts: {
+  subagentId: string;
+  gathered: string;
+  runError?: { code?: string; message?: string };
+}): string => {
+  const timedOut = opts.runError?.code === "TIMEOUT";
+  const head = timedOut
+    ? "[Subagent hit its time limit before finishing — it may not have written its output files.]"
+    : `[Subagent ended before finishing${opts.runError?.message ? `: ${opts.runError.message}` : ""}.]`;
+  const recover = opts.gathered
+    ? "Partial work it gathered is below — write the files yourself from it, or send a tight write-only follow-up with message_subagent."
+    : `Use read_subagent("${opts.subagentId}", mode:"full") to recover what it gathered.`;
+  return opts.gathered ? `${head} ${recover}\n\n${opts.gathered}` : `${head} ${recover}`;
+};
+
 // ── Types ──
 
 export type ActiveConversationRun = {
@@ -723,6 +795,7 @@ export class AgentOrchestrator {
     const draft = createTurnDraftState();
     let latestRunId = "";
     let runResult: { status: "completed" | "error" | "cancelled"; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runError: { code?: string; message?: string } | undefined;
 
     try {
       const conversation = await this.conversationStore.getWithArchive(childConversationId);
@@ -872,6 +945,7 @@ export class AgentOrchestrator {
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(childConversationId, event);
@@ -922,7 +996,17 @@ export class AgentOrchestrator {
           return;
         }
 
-        conv.subagentMeta = { ...conv.subagentMeta!, status: "completed" };
+        // No runResult means the run ended on run:error (timeout / model
+        // error) rather than run:completed — flag the subagent accordingly
+        // instead of faking "completed".
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta!,
+          status: abnormalEnd ? "error" : "completed",
+          ...(abnormalEnd
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
+        };
         await this.conversationStore.update(conv);
       }
 
@@ -933,21 +1017,36 @@ export class AgentOrchestrator {
         conversationId: childConversationId,
       });
 
-      let subagentResponse = runResult?.response ?? draft.assistantResponse;
-      if (!subagentResponse) {
+      // Recover the subagent's real output: prefer the run response, then the
+      // streamed draft, then walk the transcript — discarding the synthetic
+      // "[Error: ...]" placeholder at each step.
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(childConversationId);
-        if (freshSubConv) {
-          const lastAssistant = [...freshSubConv.messages].reverse().find(m => m.role === "assistant");
-          if (lastAssistant && typeof lastAssistant.content === "string") {
-            subagentResponse = lastAssistant.content;
-          }
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+
+      // On an abnormal end (timeout / error) there is no runResult; don't drop
+      // the work — deliver what it gathered, tagged so the parent knows it
+      // didn't finish, and build a result so it never renders as "(no result)".
+      const abnormal = !runResult;
+      const subagentResponse = abnormal
+        ? abnormalEndResponse({ subagentId: childConversationId, gathered, runError })
+        : gathered;
       const pendingResult: PendingSubagentResult = {
         subagentId: childConversationId,
         task,
-        status: "completed",
-        result: runResult ? { status: runResult.status, response: subagentResponse, steps: runResult.steps, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult.duration } : undefined,
+        status: abnormal ? "error" : "completed",
+        result: {
+          status: runResult?.status ?? "error",
+          response: subagentResponse,
+          steps: runResult?.steps ?? 0,
+          tokens: { input: 0, output: 0, cached: 0 },
+          duration: runResult?.duration ?? 0,
+        },
+        ...(abnormal
+          ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+          : {}),
         timestamp: Date.now(),
       };
       await this.conversationStore.appendSubagentResult(parentConversationId, pendingResult);
@@ -1040,8 +1139,16 @@ export class AgentOrchestrator {
     conversation.subagentCallbackCount = callbackCount;
 
     for (const pr of pendingResults) {
+      // An empty response is recoverable, not a dead end: the subagent's work
+      // lives in its transcript even when it produced no closing summary (e.g.
+      // it ran out of steps mid-task). Hand the parent an actionable pointer
+      // instead of a silent "(no response)" it can't act on.
+      const responseText = (pr.result?.response ?? "").trim();
+      const responseLine = responseText
+        || `(subagent produced no final summary after ${pr.result?.steps ?? 0} step(s); its work may be incomplete. `
+          + `Call read_subagent with subagent_id "${pr.subagentId}" and mode "assistant" to retrieve what it did.)`;
       const resultBody = pr.result
-        ? `Status: ${pr.result.status}\nResponse: ${pr.result.response ?? "(no response)"}\nSteps: ${pr.result.steps}, Duration: ${pr.result.duration}ms`
+        ? `Status: ${pr.result.status}\nResponse: ${responseLine}\nSteps: ${pr.result.steps}, Duration: ${pr.result.duration}ms`
         : pr.error
           ? `Error: ${pr.error.message}`
           : "(no result)";
@@ -1227,7 +1334,8 @@ export class AgentOrchestrator {
     this.activeSubagentRuns.set(conversationId, { abortController: childAbortController, harness: childHarness, parentConversationId });
 
     const draft = createTurnDraftState();
-    let runResult: { status: string; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runResult: { status: "completed" | "error" | "cancelled"; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runError: { code?: string; message?: string } | undefined;
 
     try {
       const recallParams = this.hooks?.buildRecallParams?.({ ownerId, tenantId: conversation.tenantId, excludeConversationId: conversationId }) ?? {};
@@ -1262,6 +1370,7 @@ export class AgentOrchestrator {
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(conversationId, event);
@@ -1311,7 +1420,14 @@ export class AgentOrchestrator {
           return;
         }
 
-        conv.subagentMeta = { ...conv.subagentMeta!, status: "completed" };
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta!,
+          status: abnormalEnd ? "error" : "completed",
+          ...(abnormalEnd
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
+        };
         await this.conversationStore.update(conv);
       }
 
@@ -1322,24 +1438,26 @@ export class AgentOrchestrator {
         conversationId,
       });
 
-      let subagentResponse = runResult?.response ?? draft.assistantResponse;
-      if (!subagentResponse) {
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(conversationId);
-        if (freshSubConv) {
-          const lastAssistant = [...freshSubConv.messages].reverse().find(m => m.role === "assistant");
-          if (lastAssistant) {
-            subagentResponse = typeof lastAssistant.content === "string" ? lastAssistant.content : "";
-          }
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+      const abnormal = !runResult;
+      const subagentResponse = abnormal
+        ? abnormalEndResponse({ subagentId: conversationId, gathered, runError })
+        : gathered;
 
       const parentConv = await this.conversationStore.get(parentConversationId);
       if (parentConv) {
         const result: PendingSubagentResult = {
           subagentId: conversationId,
           task,
-          status: "completed",
-          result: { status: "completed", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          status: abnormal ? "error" : "completed",
+          result: { status: runResult?.status ?? "error", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          ...(abnormal
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
           timestamp: Date.now(),
         };
         await this.conversationStore.appendSubagentResult(parentConversationId, result);