@bacnh85/pi-subagent 0.17.0 → 0.19.2

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 0.19.2 (2026-09-02)
+
+### Fixed
+
+- **Stalled streams now fall back to the next model** — when a provider
+  accepts a request but the stream emits zero events for the entire idle
+  window (known router/provider failure mode, e.g. slow-TTFT models behind
+  omniroute), the run previously died on model #1 with "Idle timeout" and
+  never tried the fallback chain. An IDLE timeout is now treated as a
+  capacity signal (`isRetryableModelResult`): the task retries on the next
+  candidate (each candidate is tried at most once, so worst case is N idle
+  windows). The HARD lifetime cap stays terminal — a task that ran 20 min is
+  genuinely huge, not a stall. Found by live background-task test: trivial
+  20+22 task timed out on glm-5-turbo with zero stream events.
+
+## 0.19.1 (2026-09-02)
+
+### Fixed
+
+- **Model fallback now engages on credential cooldown** — router providers
+  report "All credentials for model X are cooling down" when every key for a
+  model is in its rate-limit window. That message didn't match
+  `RATE_LIMIT_PATTERNS`, so `runWithModelFallback` treated it as a fatal error
+  instead of advancing to the next candidate (e.g. `@fast`
+  glm-5-turbo → gpt-oss-20b → deepseek-v4-flash), aborting subagent and chain
+  runs with "All credentials … are cooling down". Added the cooldown pattern
+  (credential cooldown / cooldown window / cooling down) so capacity signals
+  from the credential layer trigger the same fallback as 429s.
+
+## 0.19.0 (2026-09-02)
+
+### Fixed
+
+- **Reviewer/planner agents no longer abort at the 3-min idle timeout while
+  thinking** — root cause: a `thinking: high` child on a slow model can spend
+  many minutes in one reasoning stretch, and the default 3-min inactivity
+  window kills the run even though it is healthy. Fix: new agent frontmatter
+  field **`timeout: <minutes>`** (1–60) bakes a per-agent idle window; the
+  hard lifetime cap is raised to match so long windows are actually
+  enforceable. Bundled `reviewer` and `planner` agents ship with
+  `timeout: 10`. Per-call `timeout` still overrides. (The idle timer already
+  treats every SDK event — including streaming deltas — as activity; a run
+  that emits no events at all for the window is genuinely hung.)
+  Reported by peer mbp-sao-9915 (review rounds hitting the 180s default).
+
+## 0.18.0 (2026-09-02)
+
+### Fixed
+
+- **Worktree patches now reach the parent model** — `sandbox: worktree` results
+  previously exposed the diff only in TUI details; the tool-result text the
+  parent model reads contained just the child's final message, so the
+  documented "parent merges via apply_patch" flow was impossible in practice.
+  The diff is now appended as a `🌿 worktree patch` block (capped at the
+  per-task output limit) in single, parallel, chain, and background-completion
+  results, and `operation: "status"` reports `Patch: N diff lines`.
+
+### Added
+
+- **`merge: "3way"` per call/item** — with a worktree-sandboxed agent, the
+  captured diff is applied to the parent checkout via `git apply --3way`
+  (temp-file at repo root, applied before worktree removal so the staged blobs
+  are available for 3-way reconstruction). Results carry
+  `mergeStatus: "applied" | "conflict"`; conflicts keep git's markers, report
+  the apply error, and still deliver the patch for manual merging — never
+  silently resolved. Concurrent applies are serialized (OMP `withRepoLock`
+  equivalent) so parallel siblings cannot race the checkout.
+- Applies are mutex-serialized across parallel/background tasks.
+
 ## 0.17.0 (2026-08-31)
 
 ### Added

package/README.md

@@ -166,10 +166,18 @@ two `worker` agents editing the same files can no longer clobber each other —
 each writes into its own checkout.
 
 - All file mutations land in the worktree; the main checkout stays untouched.
-- On completion, a unified diff of the child's changes is returned in the
-  result and shown in the thread viewer as a `🌿 worktree` badge.
-- **Merging is explicit**: the parent receives the diff and applies it via
-  `apply_patch` / cherry-pick / discard. Nothing is auto-merged.
+- On completion, the unified diff of the child's changes is included in the
+  tool result as a `🌿 worktree patch` block (capped at the per-task output
+  limit) and shown in the thread viewer as a `🌿 worktree` badge.
+- **Merging**: by default the parent merges explicitly via `apply_patch` /
+  `git apply` / discard. Pass `merge: "3way"` (per call/item) to have the diff
+  applied automatically to the parent checkout via `git apply --3way` once the
+  child completes — conflicts leave git's conflict markers in place, are
+  reported in the result (`mergeStatus: "conflict"`), and the patch is still
+  delivered for manual merging. Nothing is ever silently resolved. Applies are
+  serialized so parallel siblings cannot race the checkout.
+- Children start from `HEAD`: uncommitted changes in the parent checkout are
+  invisible to the child and will surface as apply conflicts when merging.
 - The worktree is removed on completion (success, error, or abort).
 - Requires git; when the cwd is not a git repo, the agent falls back to
   in-process execution with a warning (`ponytail`: isolation optimization,

package/agent-format.md

@@ -26,6 +26,7 @@ models:                   # Optional ordered fallbacks; comma form also accepted
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 sandbox: read-only        # Optional: read-only | workspace-write | worktree. Auto-derives tool restrictions.
 color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|cyan.
+timeout: 10               # Optional: per-agent inactivity timeout in minutes (1–60). Default 3. For slow-thinking (thinking: high) agents.
 ---
 ```
 
@@ -42,7 +43,7 @@ agent's `thinking` for that match. See README → *Role-based model routing*.
 
 - `read-only`: Restricts tools to the read-only allowlist (`read`, `grep`, `find`, `ls` plus read-only extension tools when inherited — `web_*`, `serena_*`, `munin_*`, `fff*`, …). Overrides any `tools` field.
 - `workspace-write` (default): Uses the agent's `tools` list or defaults to all tools.
-- `worktree`: Runs the agent in an isolated git worktree (`.pi-worktrees/<id>` under the repo root). All file mutations land in the worktree; the main checkout is untouched. On completion, a unified diff of the changes is returned in the result (visible in the thread viewer as a `🌿 worktree` badge) — the parent merges explicitly via `apply_patch`/cherry-pick; nothing is applied automatically. Falls back to in-process execution when the cwd is not a git repo (with a warning). Requires git.
+- `worktree`: Runs the agent in an isolated git worktree (`.pi-worktrees/<id>` under the repo root). All file mutations land in the worktree; the main checkout is untouched. On completion, the unified diff is delivered in the tool result as a `🌿 worktree patch` block; pass `merge: "3way"` to apply it to the parent checkout automatically (`git apply --3way`, conflicts reported as `mergeStatus: "conflict"` with markers left in place). Falls back to in-process execution when the cwd is not a git repo (with a warning). Requires git.
 
 ### `color`
 

package/agents/planner.md

@@ -6,6 +6,7 @@ model: "@smart"
 thinking: high
 color: blue
 sandbox: read-only
+timeout: 10
 ---
 
 You are a senior software planner. Investigate the repository, identify the smallest complete implementation path, and return a concrete plan with file and symbol anchors.

package/agents/reviewer.md

@@ -6,6 +6,7 @@ model: "@smart"
 thinking: high
 color: purple
 sandbox: read-only
+timeout: 10
 ---
 
 You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.

package/extensions/agents.ts

@@ -24,6 +24,8 @@ export interface AgentConfig {
   thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
   sandbox?: "read-only" | "workspace-write" | "worktree";
   color?: AgentColor;
+  /** Per-agent default inactivity timeout in minutes (1–60). Per-call timeout overrides. */
+  timeout?: number;
   systemPrompt: string;
   source: "user" | "project" | "bundled";
   filePath: string;
@@ -224,6 +226,30 @@ function loadAgentsFromDir(
       });
     }
 
+    // Per-agent inactivity timeout (minutes) — lets slow-thinking agents
+    // (thinking: high) raise the 3-min default without per-call params.
+    let timeout: number | undefined;
+    if (frontmatter.timeout !== undefined && typeof frontmatter.timeout !== "boolean" && !Array.isArray(frontmatter.timeout)) {
+      const t = Number(frontmatter.timeout);
+      if (Number.isInteger(t) && t >= 1 && t <= 60) {
+        timeout = t;
+      } else {
+        diagnostics.push({
+          filePath,
+          issue: `Invalid timeout "${frontmatter.timeout}". Must be an integer 1–60 (minutes). Ignoring.`,
+          severity: "warn",
+        });
+      }
+    } else if (frontmatter.timeout !== undefined) {
+      // Booleans/arrays/objects: Number() would coerce (true→1, [10]→10), so
+      // reject up front with the same diagnostic instead of silently accepting.
+      diagnostics.push({
+        filePath,
+        issue: `Invalid timeout "${String(frontmatter.timeout)}". Must be an integer 1–60 (minutes). Ignoring.`,
+        severity: "warn",
+      });
+    }
+
     agents.push({
       name: frontmatter.name,
       description: frontmatter.description,
@@ -239,6 +265,7 @@ function loadAgentsFromDir(
       color: typeof frontmatter.color === "string" && VALID_COLORS.includes(frontmatter.color as any)
         ? frontmatter.color as AgentColor
         : undefined,
+      timeout,
       systemPrompt: body,
       source,
       filePath,

package/extensions/background.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 import type { SubAgentResult, SubAgentProgress } from "./runner.ts";
-import { isFailedResult, getResultOutput, getFinalOutput } from "./runner.ts";
+import { isFailedResult, getResultOutput, getFinalOutput, formatPatchBlock } from "./runner.ts";
 import type { threadStore as ThreadStoreType } from "./threads.ts";
 import type { AgentScope } from "./agents.ts";
 import { parseStructuredResult } from "./result.ts";
@@ -59,6 +59,7 @@ export interface BackgroundDeps {
     onHeartbeatDetails: () => BackgroundDetails,
     onHeartbeat: () => void,
     isReadOnly?: boolean,
+    merge?: "3way",
   ) => Promise<SubAgentResult>;
   threadStore: typeof ThreadStoreType;
 }
@@ -97,7 +98,7 @@ export interface TaskSnapshot {
   completedAt?: number;
   elapsedMs: number;
   threadId: string;
-  result?: { output: string; model?: string; usage?: unknown };
+  result?: { output: string; model?: string; usage?: unknown; patchLines?: number };
 }
 
 export function snapshotTask(task: BackgroundTask, now = Date.now()): TaskSnapshot {
@@ -112,7 +113,7 @@ export function snapshotTask(task: BackgroundTask, now = Date.now()): TaskSnapsh
     elapsedMs: now - task.startedAt,
     threadId: task.threadId,
     result: result
-      ? { output: getResultOutput(result), model: result.model, usage: result.usage }
+      ? { output: getResultOutput(result), model: result.model, usage: result.usage, patchLines: result.patch && result.patch !== "(no changes)" ? result.patch.split("\n").length : undefined }
       : undefined,
   };
 }
@@ -126,6 +127,7 @@ export interface StartBackgroundInput {
   task: string;
   cwd?: string;
   timeout?: number;
+  merge?: "3way";
   agentColor?: string;
   toolCallId?: string;
   deps: BackgroundDeps;
@@ -141,7 +143,7 @@ export interface StartBackgroundResult {
  * On completion, delivers a follow-up turn to the parent session.
  */
 export function startBackgroundTask(input: StartBackgroundInput): StartBackgroundResult {
-  const { agent, task, cwd, timeout, agentColor, toolCallId, deps } = input;
+  const { agent, task, cwd, timeout, merge, agentColor, toolCallId, deps } = input;
   const taskId = `bg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
   const controller = new AbortController();
   const startedAt = Date.now();
@@ -191,6 +193,8 @@ export function startBackgroundTask(input: StartBackgroundInput): StartBackgroun
       (progress) => deps.threadStore.updateProgress(thread.id, progress),
       () => ({ mode: "single" as const, agentScope: "user" as const, projectAgentsDir: null, results: [] }),
       () => deps.threadStore.refreshHeartbeat(thread.id),
+      undefined,
+      merge,
     )
     .then((result) => {
       bgTask.result = result;
@@ -261,13 +265,16 @@ function deliverCompletion(task: BackgroundTask, result: SubAgentResult, deps: B
   const phase = task.status;
   const summary = output.split("\n").slice(0, 1)[0]!.slice(0, 200);
   const elapsedMs = (task.completedAt ?? Date.now()) - task.startedAt;
+  // Worktree patch must reach the parent model in the follow-up turn (P0).
+  const patchBlock = formatPatchBlock(result);
+  const body = failed
+    ? `Background task ${task.id} (${task.agent}) ${phase}.\n\n${getResultOutput(result)}`
+    : `Background task ${task.id} (${task.agent}) completed.\n\n${output}`;
 
   deps.pi.sendMessage(
     {
       customType: "pi-subagent-complete",
-      content: failed
-        ? `Background task ${task.id} (${task.agent}) ${phase}.\n\n${getResultOutput(result)}`
-        : `Background task ${task.id} (${task.agent}) completed.\n\n${output}`,
+      content: patchBlock ? `${body}\n\n${patchBlock}` : body,
       display: true,
       details: {
         task_id: task.id,

package/extensions/index.ts

@@ -31,6 +31,7 @@ import { type AgentColor, type AgentConfig, type AgentScope, discoverAgents, for
 import {
   type SubAgentProgress,
   type SubAgentResult,
+  formatPatchBlock,
   getFinalOutput,
   getResultOutput,
   isFailedResult,
@@ -40,7 +41,7 @@ import {
 } from "./runner.ts";
 import {
   flushWarnings,
-  isRateLimitError,
+  isRetryableModelResult,
   normalizeTimeout,
   resolveSafeCwd,
   validateAgentTools,
@@ -52,6 +53,7 @@ import {
   MAX_PARALLEL_TASKS,
   MAX_CHAIN_LENGTH,
   MAX_INSTRUCTIONS_LENGTH,
+  HARD_TIMEOUT_MS,
 } from "./security.ts";
 import {
   aggregateUsage,
@@ -111,6 +113,7 @@ const TaskItem = Type.Object({
   task: Type.String({ description: "Task to delegate to the agent" }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
   timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in ms; aborts on no activity within timeout. Default: 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). The agent always has a lifetime cap: default 20 min  or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
+  merge: Type.Optional(StringEnum(["3way"] as const, { description: "With a worktree-sandboxed agent, apply its diff to the parent checkout via git apply --3way after it completes. Conflicts are reported, not resolved. Default: patch returned only." })),
 });
 
 const ChainItem = Type.Object({
@@ -118,6 +121,7 @@ const ChainItem = Type.Object({
   task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
   timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in ms; aborts on no activity within timeout. Default: 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). The agent always has a lifetime cap: default 20 min or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
+  merge: Type.Optional(StringEnum(["3way"] as const, { description: "With a worktree-sandboxed agent, apply its diff to the parent checkout via git apply --3way after the step completes. Conflicts are reported, not resolved." })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -157,6 +161,7 @@ const SubagentParams = Type.Object({
   // See Security model section in README.
   cwd: Type.Optional(Type.String({ description: "Working directory (single mode, must be inside workspace)" })),
   timeout: Type.Optional(Type.Number({ description: "Inactivity timeout for the whole run, in ms; resets on activity, aborts on silence. Default 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). Lifetime cap: 20 min or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
+  merge: Type.Optional(StringEnum(["3way"] as const, { description: "Single mode: with a worktree-sandboxed agent, apply its diff to the parent checkout via git apply --3way after it completes. Conflicts are reported, not resolved. Default: patch returned only." })),
   instructions: Type.Optional(Type.String({ description: "Bounded repository/task instructions passed to each child (max 16 KB)" })),
   abortOnFailure: Type.Optional(Type.Boolean({ description: "In parallel mode, cancel remaining tasks when one fails. Default: false.", default: false })),
 });
@@ -596,6 +601,7 @@ export default function (pi: ExtensionAPI) {
       "Bundled agents: scout (fast recon), tester (verification), worker (implementation), general-purpose (fallback), planner (planning), reviewer (review).",
       "For background single tasks use background:true — you will be notified on completion; DO NOT poll or sleep.",
       "Use operation: \"status\" with taskId to inspect a running/completed background task; operation: \"cancel\" to abort one.",
+      "Worktree-sandboxed agents return their diff as a patch block in the result; pass merge: \"3way\" to auto-apply it to the parent checkout (git apply --3way; conflicts reported, never silently resolved).",
       "Use /subagent list to list all available agents, /subagent <name> for agent details, /subagent @role for role detail.",
     ],
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -671,6 +677,7 @@ export default function (pi: ExtensionAPI) {
           ];
           if (snap.result) {
             lines.push(`Output: ${String(snap.result.output).slice(0, 2000)}`);
+            if (snap.result.patchLines) lines.push(`Patch: ${snap.result.patchLines} diff lines (worktree)`);
           } else {
             lines.push("(still running — no final output yet)");
           }
@@ -872,6 +879,7 @@ export default function (pi: ExtensionAPI) {
         heartbeatDetails?: () => SubagentDetails,
         onHeartbeat?: () => void,
         isReadOnly?: boolean,
+        merge?: "3way",
       ): Promise<SubAgentResult> {
         const agent = agents.find((a) => a.name === agentName);
 
@@ -912,12 +920,19 @@ export default function (pi: ExtensionAPI) {
         let tools: string[];
         let loadExtensions: boolean;
         let effectiveTimeoutMs: number | undefined;
+        let effectiveHardMs: number | undefined;
         let safeCwd: string;
         try {
           const resolved = resolveChildTools(agent.tools, agent.sandbox, isReadOnly);
           tools = resolved.tools;
           loadExtensions = resolved.loadExtensions;
-          effectiveTimeoutMs = resolveChildTimeout(timeoutMs, params.timeout);
+          // Precedence: per-call timeout > agent frontmatter default > global default.
+          // The hard lifetime cap must never be shorter than the idle window
+          // (same invariant as the env-var clamp in security.ts) — an agent
+          // with timeout: 45 under a 20-min default cap would otherwise be
+          // hard-killed mid-stream while visibly producing deltas.
+          effectiveTimeoutMs = resolveChildTimeout(timeoutMs ?? (agent.timeout ? agent.timeout * 60 * 1_000 : undefined), params.timeout);
+          effectiveHardMs = Math.max(HARD_TIMEOUT_MS, effectiveTimeoutMs ?? 0);
           safeCwd = resolveChildCwd(cwd);
         } catch (err: unknown) {
           const errorMsg = err instanceof Error ? err.message : String(err);
@@ -958,6 +973,7 @@ export default function (pi: ExtensionAPI) {
               runSubAgent({
                 cwd: safeCwd,
                 sandbox: agent.sandbox === "worktree" ? "worktree" : undefined,
+                merge: agent.sandbox === "worktree" ? merge : undefined,
                 systemPrompt: params.instructions
                 ? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
                 : agent.systemPrompt,
@@ -969,6 +985,7 @@ export default function (pi: ExtensionAPI) {
                 modelRegistry,
                 signal: parentSignal,
                 timeoutMs: effectiveTimeoutMs,
+                hardTimeoutMs: effectiveHardMs,
                 agentName,
                 thinkingLevel,
                 onMessage: onProgress,
@@ -976,7 +993,7 @@ export default function (pi: ExtensionAPI) {
                 loadExtensions,
                 projectTrusted,
               }),
-            isRateLimited: (result) => Boolean(result.errorMessage && isRateLimitError(result.errorMessage)),
+            isRateLimited: (result) => isRetryableModelResult(result),
             onExhausted: (reason, triedModels, remaining) => {
               const exhaustedStderr = reason === "no-model"
                 ? [
@@ -1035,6 +1052,8 @@ export default function (pi: ExtensionAPI) {
             (progress) => threadStore.updateProgress(thread.id, progress),
             () => makeDetails("chain")(results),
             () => threadStore.refreshHeartbeat(thread.id),
+            undefined,
+            step.merge,
           );
           threadStore.updateThread(thread.id, {
             status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -1055,6 +1074,8 @@ export default function (pi: ExtensionAPI) {
             // Include successful previous step outputs in the error content
             const prevCount = i;
             let contentText = `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`;
+            const failedPatch = formatPatchBlock(result);
+            if (failedPatch) contentText += `\n\n${failedPatch}`;
             if (prevCount > 0) {
               const prevSummaries = results
                 .slice(0, prevCount)
@@ -1076,16 +1097,22 @@ export default function (pi: ExtensionAPI) {
 
           if (onUpdate) {
             onUpdate({
-              content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
+              content: [{ type: "text", text: [getFinalOutput(result.messages) || "(no output)", formatPatchBlock(result)].filter(Boolean).join("\n\n") }],
               details: makeDetails("chain")(results),
             });
           }
         }
 
         const last = results[results.length - 1];
+        // Chain deliverable: final output plus every step's worktree patch,
+        // labeled so the parent can merge them in order.
+        const chainPatches = results
+          .map((r, i) => (formatPatchBlock(r) ? `Step ${i + 1} (${r.agent}): ${formatPatchBlock(r)}` : ""))
+          .filter(Boolean)
+          .join("\n\n");
         return {
           content: [
-            { type: "text", text: getFinalOutput(last.messages) || "(no output)" },
+            { type: "text", text: [getFinalOutput(last.messages) || "(no output)", chainPatches].filter(Boolean).join("\n\n") },
           ],
           details: makeDetails("chain")(results),
         };
@@ -1195,6 +1222,8 @@ export default function (pi: ExtensionAPI) {
                   (progress) => threadStore.updateProgress(parallelThreads[index].id, progress),
                   () => makeDetails("parallel")([...allResults]),
                   () => threadStore.refreshHeartbeat(parallelThreads[index].id),
+                  undefined,
+                  t.merge,
                 );
                 allResults[index] = result;
                 threadStore.updateThread(parallelThreads[index].id, {
@@ -1219,7 +1248,8 @@ export default function (pi: ExtensionAPI) {
               const status = isFailedResult(r)
                 ? `failed${r.stopReason ? ` (${r.stopReason})` : ""}`
                 : "completed";
-              return `### [${r.agent}] ${status}\n\n${output}`;
+              const patch = formatPatchBlock(r);
+              return `### [${r.agent}] ${status}\n\n${output}${patch ? `\n\n${patch}` : ""}`;
             });
 
             let headerText = `Parallel: ${successCount}/${results.length} succeeded`;
@@ -1247,6 +1277,7 @@ export default function (pi: ExtensionAPI) {
             task: params.task,
             cwd: params.cwd,
             timeout: params.timeout,
+            merge: params.merge,
             agentColor: agentToThemeColor(params.agent),
             toolCallId: _toolCallId,
             deps: { pi, ctx, runOne, threadStore },
@@ -1274,6 +1305,8 @@ export default function (pi: ExtensionAPI) {
           (progress) => threadStore.updateProgress(thread.id, progress),
           () => makeDetails("single")([]),
           () => threadStore.refreshHeartbeat(thread.id),
+          undefined,
+          params.merge,
         );
         threadStore.updateThread(thread.id, {
           status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -1293,11 +1326,12 @@ export default function (pi: ExtensionAPI) {
 
         if (isError) {
           const errorMsg = getResultOutput(result);
+          const patch = formatPatchBlock(result);
           return {
             content: [
               {
                 type: "text",
-                text: `Agent ${result.stopReason || "failed"}: ${errorMsg}`,
+                text: `Agent ${result.stopReason || "failed"}: ${errorMsg}${patch ? `\n\n${patch}` : ""}`,
               },
             ],
             details: makeDetails("single")([result]),
@@ -1307,7 +1341,7 @@ export default function (pi: ExtensionAPI) {
 
         return {
           content: [
-            { type: "text", text: getFinalOutput(result.messages) || "(no output)" },
+            { type: "text", text: [getFinalOutput(result.messages) || "(no output)", formatPatchBlock(result)].filter(Boolean).join("\n\n") },
           ],
           details: makeDetails("single")([result]),
         };

package/extensions/runner.ts

@@ -16,6 +16,8 @@
 
 import type { Message, Model } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import {
   createAgentSession,
@@ -32,6 +34,7 @@ import {
   type SubagentStatus,
   DEFAULT_TIMEOUT_MS,
   HARD_TIMEOUT_MS,
+  truncateParallelOutput,
 } from "./security.ts";
 
 // ---------------------------------------------------------------------------
@@ -122,6 +125,10 @@ export interface SubAgentResult {
   errorMessage?: string;
   /** Unified diff of changes made in an isolated worktree (sandbox: "worktree"). */
   patch?: string;
+  /** Set when merge:"3way" was requested: outcome of applying the patch to the parent checkout. */
+  mergeStatus?: "applied" | "conflict";
+  /** git apply error excerpt when mergeStatus === "conflict". */
+  mergeError?: string;
   /** Canonical result status (added in 0.6.0). */
   status?: SubagentStatus;
   /** Wall-clock duration of the run, set by runSubAgent (Date.now() - startedAt). */
@@ -146,6 +153,8 @@ export async function runSubAgent(options: {
   model: Model<any>;
   /** "worktree" runs the child in an isolated git worktree; the resulting diff is returned as result.patch. */
   sandbox?: "worktree";
+  /** With sandbox:"worktree", apply the captured diff to the parent checkout via `git apply --3way` after the run. */
+  merge?: "3way";
   /** Pi 0.80.10's canonical credential/model runtime. */
   modelRuntime?: unknown;
   /** Legacy Pi SDK session options retained for 0.80.6 tests and hosts. */
@@ -177,7 +186,7 @@ export async function runSubAgent(options: {
     cwd, systemPrompt, task, tools, model, modelRuntime, authStorage, modelRegistry, signal,
     agentName = "subagent", thinkingLevel = "off", onMessage, onProgress,
     timeoutMs = DEFAULT_INACTIVITY_TIMEOUT_MS, hardTimeoutMs = HARD_TIMEOUT_MS,
-    loadExtensions = false, projectTrusted = true, sandbox, exec,
+    loadExtensions = false, projectTrusted = true, sandbox, merge, exec,
   } = options;
   const result: SubAgentResult = {
     agent: agentName, task, exitCode: 0, messages: [], stderr: "",
@@ -229,11 +238,13 @@ export async function runSubAgent(options: {
     // ponytail: falls back to the in-process cwd when git is unavailable — the
     // worktree is an isolation optimization, not a hard requirement.
     let worktreeDir: string | undefined;
+    let worktreeRepoRoot: string | undefined;
     let childCwd = cwd;
     if (sandbox === "worktree") {
       const wt = await createWorktree(cwd, exec);
       if (wt.ok) {
         worktreeDir = wt.path;
+        worktreeRepoRoot = wt.repoRoot;
         childCwd = wt.path!;
       } else if (wt.error) {
         result.stderr = `Worktree unavailable (${wt.error}); running in workspace.`;
@@ -261,7 +272,10 @@ export async function runSubAgent(options: {
         const finish = (fn: () => void) => { if (!done) { done = true; unsubscribe?.(); fn(); } };
         unsubscribe = session.subscribe((event) => {
           try {
-            // Any SDK session lifecycle event is actual child activity, unlike a parent heartbeat.
+            // Any SDK session event — including message_update streaming
+            // deltas (thinking_delta/text_delta) — is real child activity
+            // and resets the idle timer. Only a stream with NO events at all
+            // for timeoutMs indicates a hung child.
             armIdle(); onProgress?.(snapshot(event.type));
             if (event.type === "message_end") {
               const msg = event.message as AgentMessage;
@@ -297,7 +311,25 @@ export async function runSubAgent(options: {
       if (worktreeDir) {
         // Capture the child's changes as a unified diff before tearing down.
         const diff = await captureWorktreeDiff(cwd, worktreeDir, exec);
-        if (diff.ok) result.patch = diff.diff;
+        if (diff.ok) {
+          result.patch = diff.diff;
+          // Opt-in 3-way merge: apply while the worktree still exists — the
+          // blobs `git add -A` staged live in the shared object DB and
+          // `git apply --3way` needs them. Applies are serialized (see
+          // applyWorktreePatch3way) so parallel siblings cannot race. Only
+          // successfully completed children auto-merge: a timed-out or
+          // aborted child's half-finished edits must not land on the parent
+          // checkout — their patch is still delivered for manual review.
+          if (merge === "3way" && result.status === "success" && worktreeRepoRoot && diff.diff && diff.diff !== "(no changes)") {
+            const applied = await applyWorktreePatch3way(worktreeRepoRoot, diff.diff, exec);
+            if (applied.ok) {
+              result.mergeStatus = "applied";
+            } else {
+              result.mergeStatus = "conflict";
+              result.mergeError = applied.stderr.slice(0, 1000);
+            }
+          }
+        }
         else if (diff.error) result.stderr = result.stderr ? `${result.stderr}; diff unavailable (${diff.error})` : `Diff unavailable (${diff.error})`;
       }
       return result;
@@ -323,7 +355,7 @@ export async function runSubAgent(options: {
 // ---------------------------------------------------------------------------
 
 /** Minimal exec fallback (child_process spawn) used when no exec is injected. */
-async function defaultExec(
+export async function defaultExec(
   command: string,
   args: string[],
   options?: { cwd?: string; timeout?: number },
@@ -358,7 +390,7 @@ async function runGit(
 export async function createWorktree(
   cwd: string,
   exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
-): Promise<{ ok: boolean; path?: string; error?: string }> {
+): Promise<{ ok: boolean; path?: string; repoRoot?: string; error?: string }> {
   try {
     const root = await runGit(cwd, ["rev-parse", "--show-toplevel"], exec);
     if (!root.ok) return { ok: false, error: root.stderr.trim() || "not a git repo" };
@@ -368,7 +400,7 @@ export async function createWorktree(
     const wtPath = path.join(repoRoot, ".pi-worktrees", id);
     const add = await runGit(repoRoot, ["worktree", "add", "--detach", wtPath, "HEAD"], exec);
     if (!add.ok) return { ok: false, error: add.stderr.trim() || "git worktree add failed" };
-    return { ok: true, path: wtPath };
+    return { ok: true, path: wtPath, repoRoot };
   } catch (error) {
     return { ok: false, error: error instanceof Error ? error.message : String(error) };
   }
@@ -403,6 +435,56 @@ export async function removeWorktree(
   } catch { /* best effort */ }
 }
 
+/** Serialized `git apply` on the parent checkout: parallel siblings finishing
+ *  at the same time must not race the merge (OMP's withRepoLock equivalent). */
+let applyChain: Promise<unknown> = Promise.resolve();
+
+/** Apply a unified diff to the repo root via `git apply --3way`. Never throws;
+ *  ok:false means conflict/failure — the caller reports it and still delivers
+ *  the patch text for manual merging. */
+export async function applyWorktreePatch3way(
+  repoRoot: string,
+  diff: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; stderr: string }> {
+  const run = applyChain.then(async (): Promise<{ ok: boolean; stderr: string }> => {
+    const tmp = path.join(os.tmpdir(), `pi-subagent-apply-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.patch`);
+    try {
+      // git apply interprets paths relative to cwd — write the diff to a file
+      // and apply at the repo root. captureWorktreeDiff trims trailing
+      // whitespace; git rejects a patch whose last line has no newline, so
+      // restore it (CRLF-aware: trimming "...\r\n" must not downgrade the
+      // final line ending to LF).
+      const patchText = diff.endsWith("\n") ? diff : `${diff}${diff.includes("\r\n") ? "\r\n" : "\n"}`;
+      await fs.writeFile(tmp, patchText, "utf8");
+      const res = await runGit(repoRoot, ["apply", "--3way", tmp], exec);
+      return { ok: res.ok, stderr: (res.stderr || res.stdout).trim() };
+    } catch (error) {
+      return { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+    } finally {
+      await fs.rm(tmp, { force: true }).catch(() => { /* best effort */ });
+    }
+  });
+  applyChain = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+/** Model-facing patch block for a worktree result; "" when there is no patch.
+ *  Applied merges omit the diff (the parent checkout already has it);
+ *  conflicts include it plus the git apply error. */
+export function formatPatchBlock(result: SubAgentResult): string {
+  if (!result.patch || result.patch === "(no changes)") return "";
+  const lines = result.patch.split("\n").length;
+  if (result.mergeStatus === "applied") {
+    return `🌿 worktree patch (${lines} diff lines) — already applied to the parent checkout via 3-way merge.`;
+  }
+  const head = result.mergeStatus === "conflict"
+    ? `🌿 worktree patch (${lines} diff lines) — 3-way merge CONFLICTED; resolve the markers in the files, or merge manually:`
+    : `🌿 worktree patch (${lines} diff lines) — merge explicitly via apply_patch or \`git apply\` (or pass merge:"3way" next time):`;
+  const err = result.mergeError ? `\n\ngit apply: ${result.mergeError}` : "";
+  return `${head}${err}\n\n${truncateParallelOutput(result.patch)}`;
+}
+
 
 export function getFinalOutput(messages: Message[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {

package/extensions/security.ts

@@ -668,6 +668,10 @@ const RATE_LIMIT_PATTERNS = [
   /capacity[\s_]exceeded/i,
   /usage[\s_]limit/i,
   /overloaded/i,
+  // Credential-cooldown errors (e.g. "All credentials for model X are
+  // cooling down") are capacity signals too: the model may be unavailable
+  // NOW but the next fallback candidate may not be in cooldown.
+  /credential[\s_]cooldown|cooldown[\s_]window|cooling[\s_]down/i,
 ];
 
 /**
@@ -679,3 +683,23 @@ const RATE_LIMIT_PATTERNS = [
 export function isRateLimitError(message: string): boolean {
   return RATE_LIMIT_PATTERNS.some(p => p.test(message));
 }
+
+/**
+ * Whether a sub-agent result should trigger model fallback: a rate-limit /
+ * credential-cooldown error, or an IDLE timeout (a stalled stream with zero
+ * events for the whole idle window — a known router/provider failure mode).
+ * The HARD lifetime cap is terminal: a task that ran 20 min is genuinely
+ * huge, not a stall, and retrying it on another model doubles the cost.
+ */
+export function isRetryableModelResult(result: {
+  errorMessage?: string;
+  stopReason?: string;
+  status?: string;
+}): boolean {
+  if (result.errorMessage && isRateLimitError(result.errorMessage)) return true;
+  return (
+    result.stopReason === "timeout" &&
+    result.status === "timeout" &&
+    !String(result.errorMessage ?? "").includes("Hard timeout")
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.17.0",
+  "version": "0.19.2",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",