@mediadatafusion/pi-workflow-suite 0.0.11 → 0.0.13

package/extensions/subagent/repolock-guard.ts

@@ -1,6 +1,8 @@
 import { existsSync, realpathSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadWorkflowSettings } from "../workflow-model-router.js";
 
 const PATH_SCOPED_TOOLS = new Set(["read", "grep", "find", "ls", "edit", "write"]);
 
@@ -40,18 +42,151 @@ function piRuntimeInstructionPath(candidate: string): boolean {
     || rel === "themes" || rel.startsWith("themes/");
 }
 
+function packageInstructionPath(candidate: string): boolean {
+  const root = safeRealpath(join(dirname(fileURLToPath(import.meta.url)), ".."));
+  if (!pathInsideRoot(candidate, root)) return false;
+  const rel = candidate === root ? "" : candidate.slice(root.length + 1);
+  return rel === "skills" || rel.startsWith("skills/")
+    || rel === "agents" || rel.startsWith("agents/")
+    || rel === "config/prompts" || rel.startsWith("config/prompts/")
+    || rel === "prompts" || rel.startsWith("prompts/")
+    || rel === "themes" || rel.startsWith("themes/");
+}
+
+function piClipboardImageTempFile(candidate: string): boolean {
+  const base = candidate.split(/[\\/]/).pop() ?? "";
+  return /^pi-clipboard-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(?:png|jpg|jpeg|gif|webp|bmp|tiff|heic)$/i.test(base);
+}
+
+function piCodingAgentPackageRoot(): string | undefined {
+  try {
+    const resolver = (import.meta as ImportMeta & { resolve?: (specifier: string) => string }).resolve;
+    if (!resolver) return undefined;
+    const entry = fileURLToPath(resolver("@earendil-works/pi-coding-agent"));
+    return safeRealpath(resolve(dirname(entry), ".."));
+  } catch {
+    return undefined;
+  }
+}
+
+function piCodingAgentDocsPath(candidate: string): boolean {
+  const root = piCodingAgentPackageRoot();
+  if (!root || !pathInsideRoot(candidate, root)) return false;
+  const rel = candidate === root ? "" : candidate.slice(root.length + 1);
+  return rel === "docs" || rel.startsWith("docs/");
+}
+
+function userInstalledSkillPath(candidate: string): boolean {
+  const home = process.env.HOME;
+  if (!home) return false;
+  const root = safeRealpath(join(home, ".agents", "skills"));
+  if (!pathInsideRoot(candidate, root)) return false;
+  const rel = candidate === root ? "" : candidate.slice(root.length + 1);
+  const skillName = rel.split(/[\\/]/)[0];
+  return Boolean(skillName && skillName !== "." && skillName !== ".." && !skillName.startsWith("."));
+}
+
+function workflowStateReadPath(candidate: string): boolean {
+  const root = safeRealpath(getAgentDir());
+  if (!pathInsideRoot(candidate, root)) return false;
+  const rel = candidate === root ? "" : candidate.slice(root.length + 1);
+  return rel === "workflows/active.json"
+    || rel === "workflows/plans/latest.json"
+    || rel === "workflows/missions/latest.json";
+}
+
+const BLOCKED_EXECUTE_BASH: RegExp[] = [
+  /\brm\s+-[^\n;|&]*r[^\n;|&]*f\b/i,
+  /\bsudo\b/i,
+  /\bchmod\s+-R\b/i,
+  /\bchown\s+-R\b/i,
+  /\bgit\s+reset\b/i,
+  /\bgit\s+clean\b/i,
+  /\bgit\s+push\b/i,
+  /\bgit\s+checkout\b/i,
+  /\bgit\s+switch\b/i,
+  /\bnpm\s+install\b/i,
+  /\bpnpm\s+add\b/i,
+  /\byarn\s+add\b/i,
+  /\bpip\s+install\b/i,
+  /\bpip3?\s+install\b/i,
+  /\bbundle\s+install\b/i,
+  /\bgem\s+install\b/i,
+  /\bcargo\s+install\b/i,
+  /\bgo\s+(?:get|install)\b/i,
+  /\bdeno\s+(?:install|add|cache)\b/i,
+  /\bcomposer\s+(?:install|require|update)\b/i,
+  /\bmix\s+(?:deps\.get|deps\.compile)\b/i,
+  /\bbrew\s+install\b/i,
+  /\bapt\s+(?:install|get\s+install)\b/i,
+  /\byum\s+install\b/i,
+  /\bdnf\s+install\b/i,
+  /\bapk\s+add\b/i,
+  /\bnuget\s+install\b/i,
+  /\bdotnet\s+(?:add\s+package|tool\s+install|restore)\b/i,
+  /\bcabal\s+(?:install|update)\b/i,
+  /\bstack\s+(?:install|update)\b/i,
+  /\bconan\s+install\b/i,
+  /\bvcpkg\s+install\b/i,
+  /\bcoursier\s+(?:install|fetch)\b/i,
+  /\bcurl\b[^\n]*\|\s*sh\b/i,
+  /\bwget\b[^\n]*\|\s*sh\b/i,
+  /\bvercel\s+deploy\b/i,
+  /\bdeploy\b/i,
+  /\bsupabase\s+db\s+push\b/i,
+  /\bsupabase\s+migration\s+up\b/i,
+  /\bmigration\b[^\n]*(run|up|execute)/i,
+];
+
+const PACKAGE_INSTALL_RE = /\b(?:npm\s+install|pnpm\s+add|yarn\s+add|pip3?\s+install|bundle\s+install|gem\s+install|cargo\s+install|go\s+(?:get|install)|deno\s+(?:install|add|cache)|composer\s+(?:install|require|update)|mix\s+deps\.(?:get|compile)|brew\s+install|apt(?:-get)?\s+install|yum\s+install|dnf\s+install|apk\s+add|nuget\s+install|dotnet\s+(?:add\s+package|tool\s+install|restore)|cabal\s+(?:install|update)|stack\s+(?:install|update)|conan\s+install|vcpkg\s+install|coursier\s+(?:install|fetch))\b/i;
+
+function isBlockedExecuteCommand(command: string): boolean {
+  return BLOCKED_EXECUTE_BASH.some((pattern) => pattern.test(command));
+}
+
+function isPackageInstallCommand(command: string): boolean {
+  return PACKAGE_INSTALL_RE.test(command);
+}
+
+function commandBlocked(command: string, cwd?: string): boolean {
+  const settings = loadWorkflowSettings(cwd);
+  if (settings.safety.blockDestructiveCommands === false) return false;
+  if (isPackageInstallCommand(command) && settings.safety.allowPackageInstallInExecution !== false) return false;
+  return isBlockedExecuteCommand(command);
+}
+
 function repoLockPathBlock(pathValue: unknown, cwd: string, tool: string): string | undefined {
   if (process.env.PI_WORKFLOW_REPO_LOCK_ENABLED !== "1") return undefined;
   const root = safeRealpath(process.env.PI_WORKFLOW_REPO_LOCK_ROOT || cwd);
   const candidate = resolveCandidatePath(typeof pathValue === "string" && pathValue.trim() ? pathValue.trim() : ".", cwd);
   if (!pathInsideRoot(candidate, root)) {
-    if ((tool === "read" || tool === "grep" || tool === "find" || tool === "ls") && piRuntimeInstructionPath(candidate)) return undefined;
+    if ((tool === "read" || tool === "grep" || tool === "find" || tool === "ls") && (piRuntimeInstructionPath(candidate) || packageInstructionPath(candidate) || piCodingAgentDocsPath(candidate) || userInstalledSkillPath(candidate) || workflowStateReadPath(candidate) || piClipboardImageTempFile(candidate))) return undefined;
+    if (candidate.startsWith("/private/tmp/") || candidate.startsWith("/tmp/") || candidate.startsWith("/var/tmp/")) return undefined;
     return `Repo Lock blocked sub-agent path outside current repository: ${candidate} (repo root: ${root})`;
   }
   if ((tool === "edit" || tool === "write") && protectedRepoPath(candidate, root)) return `Repo Lock blocked sub-agent ${tool} for protected project control path: ${candidate}`;
   return undefined;
 }
 
+function stripQuotedSlashes(command: string): string {
+  return command
+    .replace(/'([^']*)'/g, (_full, content: string) => {
+      // If content starts with /regex/ or /regex/flags (awk/sed address pattern), mask slashes
+      if (/^\/[^/]+\/(?:[gimp]*$|\s)/.test(content)) return "'" + content.replace(/\//g, " ") + "'";
+      // If content starts with /, it's a quoted absolute path — preserve
+      if (content.startsWith('/')) return _full;
+      // Content contains / but is not a path — mask (sed expression, prose, etc.)
+      if (content.includes('/')) return "'" + content.replace(/\//g, " ") + "'";
+      return _full;
+    })
+    .replace(/"([^"]*)"/g, (_full, content: string) => {
+      if (/^\/[^/]+\/(?:[gimp]*$|\s)/.test(content)) return '"' + content.replace(/\//g, " ") + '"';
+      if (content.startsWith('/')) return _full;
+      if (content.includes('/')) return '"' + content.replace(/\//g, " ") + '"';
+      return _full;
+    });
+}
+
 function stripHereDocBodies(command: string): string {
   const lines = command.split("\n");
   const kept: string[] = [];
@@ -72,21 +207,104 @@ function stripUriTokens(command: string): string {
 }
 
 function bashPathCandidates(command: string): string[] {
-  const trimmed = stripUriTokens(stripHereDocBodies(command)).trim();
+  const trimmed = stripUriTokens(stripHereDocBodies(stripQuotedSlashes(command))).trim();
   if (!trimmed) return [];
   return Array.from(trimmed.matchAll(/(?:^|[\s=:'"`])((?:\.{1,2}|~|\/)[^\s'"`;&|)]*)/g)).map((match) => match[1]).filter(Boolean);
 }
 
+function hasShellControlOperator(command: string): boolean {
+  let quote: "'" | '"' | undefined;
+  for (let i = 0; i < command.length; i += 1) {
+    const char = command[i];
+    if (char === "\\") { i += 1; continue; }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (char === ";" || char === "|" || char === "&" || char === "<" || char === ">" || char === "\n") return true;
+  }
+  return quote !== undefined;
+}
+
+function shellWords(command: string): string[] | undefined {
+  const words: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  for (let i = 0; i < command.length; i += 1) {
+    const char = command[i];
+    if (char === "\\") {
+      i += 1;
+      current += command[i] ?? "";
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (/\s/.test(char)) {
+      if (current) { words.push(current); current = ""; }
+      continue;
+    }
+    current += char;
+  }
+  if (quote) return undefined;
+  if (current) words.push(current);
+  return words;
+}
+
+function simpleCpSourceOperands(command: string): Set<string> | undefined {
+  if (hasShellControlOperator(command)) return undefined;
+  const words = shellWords(command);
+  if (!words || words.length < 3) return undefined;
+  const commandName = words[0].split(/[\\/]/).pop();
+  if (commandName !== "cp") return undefined;
+  const operands: string[] = [];
+  let endOfOptions = false;
+  for (const word of words.slice(1)) {
+    if (!endOfOptions && word === "--") { endOfOptions = true; continue; }
+    if (!endOfOptions && word.startsWith("-")) continue;
+    operands.push(word);
+  }
+  if (operands.length < 2) return undefined;
+  return new Set(operands.slice(0, -1));
+}
+
+function simpleReadOnlyBashAllowed(command: string): boolean {
+  if (hasShellControlOperator(command)) return false;
+  const words = shellWords(command);
+  if (!words?.length) return false;
+  const commandName = words[0].split(/[\\/]/).pop();
+  if (commandName === "cat" || commandName === "ls" || commandName === "grep" || commandName === "rg") return true;
+  if (commandName !== "find") return false;
+  return !words.some((word) => word === "-delete" || word === "-exec" || word === "-execdir" || word === "-ok" || word === "-okdir" || word === "-fprint" || word === "-fprintf");
+}
+
+function piCodingAgentDocsBashReadAllowed(command: string): boolean {
+  return simpleReadOnlyBashAllowed(command);
+}
+
 function repoLockBashBlock(command: string, cwd: string): string | undefined {
   if (process.env.PI_WORKFLOW_REPO_LOCK_ENABLED !== "1") return undefined;
   const root = safeRealpath(process.env.PI_WORKFLOW_REPO_LOCK_ROOT || cwd);
   const candidates = bashPathCandidates(command);
+  const cpSourceOperands = simpleCpSourceOperands(command);
   for (const raw of candidates) {
     if (raw === "." || raw === "./" || raw === "/") continue;
     const cleaned = raw.replace(/[),]+$/, "");
     if (!cleaned || cleaned.startsWith("./node_modules/.bin")) continue;
+    if (cleaned.startsWith("/dev/")) continue;
+    if (cleaned.startsWith("/tmp/") || cleaned.startsWith("/private/tmp/") || cleaned.startsWith("/var/tmp/")) continue;
     const candidate = resolveCandidatePath(cleaned, cwd);
-    if (!pathInsideRoot(candidate, root)) return `Repo Lock blocked sub-agent bash path outside current repository: ${cleaned} -> ${candidate} (repo root: ${root})`;
+    if (!pathInsideRoot(candidate, root)) {
+      if (piCodingAgentDocsPath(candidate) && piCodingAgentDocsBashReadAllowed(command)) continue;
+      if (userInstalledSkillPath(candidate) && simpleReadOnlyBashAllowed(command)) continue;
+      if (workflowStateReadPath(candidate) && simpleReadOnlyBashAllowed(command)) continue;
+      if (piClipboardImageTempFile(candidate) && cpSourceOperands?.has(cleaned)) continue;
+      return `Repo Lock blocked sub-agent bash path outside current repository: ${cleaned} -> ${candidate} (repo root: ${root})`;
+    }
   }
   return undefined;
 }
@@ -101,11 +319,13 @@ export default function repoLockSubagentGuard(pi: ExtensionAPI): void {
       const command = String((event.input as { command?: unknown }).command ?? "");
       const reason = repoLockBashBlock(command, ctx.cwd);
       if (reason) return { block: true, reason };
+      if (commandBlocked(command, ctx.cwd)) return { block: true, reason: "Destructive or out-of-scope command blocked" };
     }
   });
 
   pi.on("user_bash", (event, ctx) => {
     const reason = repoLockBashBlock(event.command, ctx.cwd);
     if (reason) return { result: { output: reason, exitCode: 1, cancelled: false, truncated: false } };
+    if (commandBlocked(event.command, ctx.cwd)) return { result: { output: "Destructive command blocked", exitCode: 1, cancelled: false, truncated: false } };
   });
 }

package/extensions/subagent/runner.ts

@@ -9,6 +9,7 @@ import { execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as crypto from "node:crypto";
 import type { Message } from "@earendil-works/pi-ai";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { loadWorkflowSettings } from "../workflow-model-router.js";
@@ -18,6 +19,12 @@ export interface WorkflowSubagentTask {
   agent: string;
   task: string;
   cwd?: string;
+  schema?: Record<string, unknown>;
+  background?: boolean;
+  model?: string;
+  skills?: string;
+  output?: string;
+  workflowPhase?: string;
 }
 
 export interface WorkflowSubagentUsage {
@@ -42,6 +49,7 @@ export interface WorkflowSubagentResult {
   model?: string;
   stopReason?: string;
   errorMessage?: string;
+  parsedOutput?: unknown;
 }
 
 export interface WorkflowSubagentRunResult {
@@ -58,9 +66,50 @@ export interface WorkflowSubagentRunOptions {
   staleMinutes?: number;
   signal?: AbortSignal;
   onUpdate?: (results: WorkflowSubagentResult[]) => void;
+  concurrency?: number;
+  failFast?: boolean;
+  background?: boolean;
+}
+
+const DEFAULT_CONCURRENCY = 8;
+
+// ── Orphan process tracking (#8) ──────────────────────────────
+const trackedPids = new Set<number>();
+
+export function trackedOrphanPids(): ReadonlySet<number> {
+  return trackedPids;
+}
+
+export function trackSubagentPid(pid: number): void {
+  trackedPids.add(pid);
+}
+
+export function untrackSubagentPid(pid: number): void {
+  trackedPids.delete(pid);
+}
+
+export function cleanupOrphanProcesses(): void {
+  for (const pid of trackedPids) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* already dead */ }
+  }
+  trackedPids.clear();
+}
+
+// Clean up on parent exit (unexpected death)
+if (typeof process.on === "function") {
+  process.on("exit", () => { for (const pid of trackedPids) { try { process.kill(pid, "SIGTERM"); } catch { /* ignore */ } } });
+}
+
+// ── Result caching (#6) ─────────────────────────────────────
+const resultCache = new Map<string, WorkflowSubagentResult>();
+
+function cacheKey(agent: string, task: string, cwd: string): string {
+  return crypto.createHash("sha256").update(`${agent}\n${task}\n${cwd}`).digest("hex");
 }
 
-const MAX_CONCURRENCY = 4;
+export function clearSubagentResultCache(): void {
+  resultCache.clear();
+}
 const REPOLOCK_GUARD_EXTENSION = path.join(path.dirname(new URL(import.meta.url).pathname), "repolock-guard.ts");
 
 function safeRealpath(candidate: string): string {
@@ -104,19 +153,30 @@ function finalOutput(messages: Message[]): string {
   return "";
 }
 
-async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: number, fn: (item: TIn, index: number) => Promise<TOut>): Promise<TOut[]> {
+async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: number, fn: (item: TIn, index: number) => Promise<TOut>, failFast = false): Promise<TOut[]> {
   if (items.length === 0) return [];
   const limit = Math.max(1, Math.min(concurrency, items.length));
   const results: TOut[] = new Array(items.length);
   let nextIndex = 0;
+  let firstError: Error | undefined;
   const workers = new Array(limit).fill(null).map(async () => {
     while (true) {
+      if (failFast && firstError) return;
       const current = nextIndex++;
       if (current >= items.length) return;
-      results[current] = await fn(items[current], current);
+      try {
+        results[current] = await fn(items[current], current);
+      } catch (err) {
+        if (failFast) {
+          firstError = err instanceof Error ? err : new Error(String(err));
+          return;
+        }
+        throw err;
+      }
     }
   });
   await Promise.all(workers);
+  if (failFast && firstError) throw firstError;
   return results;
 }
 
@@ -166,6 +226,12 @@ async function runSingleWorkflowSubagent(
 
   const lockRoot = repoLockRootForSubagent(defaultCwd);
   const effectiveCwd = resolveSubagentCwd(task.cwd, defaultCwd);
+
+  // ── Result caching (#6): check cache before spawning ──
+  const key = cacheKey(agent.name, task.task, effectiveCwd);
+  const cached = signal?.aborted ? undefined : resultCache.get(key);
+  if (cached) return { ...cached, output: `${cached.output}\n\n[cached]` };
+
   if (lockRoot && !pathInsideRoot(effectiveCwd, lockRoot)) {
     return {
       agent: task.agent,
@@ -188,7 +254,7 @@ async function runSingleWorkflowSubagent(
   const messages: Message[] = [];
   const usage: WorkflowSubagentUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
   let stderr = "";
-  let model = agent.model;
+  let model = task.model || agent.model;
   let stopReason: string | undefined;
   let errorMessage: string | undefined;
 
@@ -199,7 +265,11 @@ async function runSingleWorkflowSubagent(
       tmpPromptPath = tmp.filePath;
       args.push("--append-system-prompt", tmpPromptPath);
     }
-    args.push(`Task: ${task.task}`);
+    // ── Structured output (#5): inject schema if present ──
+    const schemaInstruction = task.schema
+      ? `\n\nReturn your final result as a single valid JSON object matching this schema:\n${JSON.stringify(task.schema, null, 2)}\n\nWrap ONLY the JSON object in a \`\`\`json code block at the end of your response.`
+      : "";
+    args.push(`Task: ${task.task}${schemaInstruction}`);
 
     let wasAborted = false;
     let timeoutReason = "";
@@ -216,9 +286,13 @@ async function runSingleWorkflowSubagent(
           ...process.env,
           PI_SUBAGENT_WORKER: "1",
           PI_SUBAGENT_NAME: agent.name,
+          ...(task.workflowPhase ? { PI_WORKFLOW_SUBAGENT_PHASE: task.workflowPhase } : {}),
           ...(lockRoot ? { PI_WORKFLOW_REPO_LOCK_ENABLED: "1", PI_WORKFLOW_REPO_LOCK_ROOT: lockRoot } : {}),
+          ...(task.skills ? { PI_SUBAGENT_SKILLS: task.skills } : {}),
+          ...(task.output ? { PI_SUBAGENT_OUTPUT: task.output } : {}),
         },
       });
+      trackedPids.add(proc.pid!);
       let buffer = "";
       let lastOutputAt = Date.now();
       let settled = false;
@@ -228,8 +302,8 @@ async function runSingleWorkflowSubagent(
         timeoutReason = reason;
         wasAborted = true;
         errorMessage = reason;
-        proc.kill("SIGTERM");
-        setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000);
+        try { process.kill(-proc.pid!, "SIGTERM"); } catch { proc.kill("SIGTERM"); }
+        setTimeout(() => { if (!proc.killed) { try { process.kill(-proc.pid!, "SIGKILL"); } catch { proc.kill("SIGKILL"); } } }, 5000);
       };
       const timeoutTimer = setTimeout(() => stopProcess(`Sub-agent timed out after ${Math.round(timeoutMs / 60000)} minute(s).`), timeoutMs);
       const staleTimer = setInterval(() => {
@@ -275,13 +349,19 @@ async function runSingleWorkflowSubagent(
       proc.stderr.on("data", (data) => { stderr += data.toString(); });
       proc.on("close", (code) => {
         settled = true;
+        trackedPids.delete(proc.pid!);
         clearTimeout(timeoutTimer);
         clearInterval(staleTimer);
         if (buffer.trim()) processLine(buffer);
+        // Kill process group to clean up background child processes
+        // (dev servers, static servers, tools — any program the sub-agent started).
+        // process.kill(-pid) signals the entire process group; works on all Unix.
+        try { if (proc.pid) process.kill(-proc.pid, "SIGTERM"); } catch { /* group empty */ }
         resolve(code ?? 0);
       });
       proc.on("error", () => {
         settled = true;
+        trackedPids.delete(proc.pid!);
         clearTimeout(timeoutTimer);
         clearInterval(staleTimer);
         resolve(1);
@@ -293,19 +373,41 @@ async function runSingleWorkflowSubagent(
       }
     });
 
-    return {
+    const rawOutput = finalOutput(messages);
+    // ── Structured output (#5): try JSON parse against schema ──
+    let parsedOutput: unknown;
+    if (task.schema && rawOutput) {
+      const jsonMatch = rawOutput.match(/```json\s*([\s\S]*?)\s*```/);
+      const candidate = jsonMatch ? jsonMatch[1].trim() : rawOutput.trim();
+      try { parsedOutput = JSON.parse(candidate); } catch { /* free-form output, not JSON */ }
+    }
+
+    const result: WorkflowSubagentResult = {
       agent: agent.name,
       agentSource: agent.source,
       agentTools: agent.tools,
       task: task.task,
       exitCode: wasAborted ? 1 : exitCode,
-      output: finalOutput(messages),
+      output: rawOutput,
       stderr,
       usage,
       model,
       stopReason: wasAborted ? "aborted" : stopReason,
       errorMessage: wasAborted ? (timeoutReason || "Subagent was aborted") : errorMessage,
+      parsedOutput,
     };
+
+    // ── Result caching (#6): store successful results ──
+    if (!wasAborted && exitCode === 0 && !signal?.aborted) {
+      resultCache.set(key, result);
+    }
+
+    // ── Retry-on-timeout (#3): retry once on timeout/stale ──
+    if (wasAborted && timeoutReason && !signal?.aborted) {
+      return result; // single attempt; retry is handled at the runWorkflowSubagents level
+    }
+
+    return result;
   } finally {
     if (tmpPromptPath) try { fs.unlinkSync(tmpPromptPath); } catch { /* ignore */ }
     if (tmpPromptDir) try { fs.rmdirSync(tmpPromptDir); } catch { /* ignore */ }
@@ -325,12 +427,34 @@ export async function runWorkflowSubagents(options: WorkflowSubagentRunOptions):
     usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
   }));
   options.onUpdate?.([...running]);
-  const results = await mapWithConcurrencyLimit(options.tasks, MAX_CONCURRENCY, async (task, index) => {
-    const result = await runSingleWorkflowSubagent(options.cwd, discovery.agents, task, options.signal, { timeoutMinutes: options.timeoutMinutes, staleMinutes: options.staleMinutes });
+
+  const executeTask = async (task: WorkflowSubagentTask, index: number): Promise<WorkflowSubagentResult> => {
+    const limits = { timeoutMinutes: options.timeoutMinutes, staleMinutes: options.staleMinutes };
+    let result = await runSingleWorkflowSubagent(options.cwd, discovery.agents, task, options.signal, limits);
+    // ── Retry-on-timeout (#3): retry once on timeout/stale ──
+    if (result.exitCode !== 0 && result.stopReason === "aborted" && result.errorMessage?.includes("timed out") && !options.signal?.aborted) {
+      const retryResult = await runSingleWorkflowSubagent(options.cwd, discovery.agents, task, options.signal, limits);
+      retryResult.output = `[retry after timeout]\n${retryResult.output}`;
+      result = retryResult;
+    }
     running[index] = result;
     options.onUpdate?.([...running]);
     return result;
-  });
+  };
+
+  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+
+  if (options.background) {
+    // Fire-and-forget: start execution, don't await, deliver results via onUpdate
+    mapWithConcurrencyLimit(options.tasks, concurrency, executeTask, options.failFast).then((results) => {
+      // Results delivered via onUpdate during execution; final result available for next turn
+    }).catch(() => {
+      // Background failures are non-fatal; onUpdate already reported individual failures
+    });
+    return { agentScope, projectAgentsDir: discovery.projectAgentsDir, results: running };
+  }
+
+  const results = await mapWithConcurrencyLimit(options.tasks, concurrency, executeTask, options.failFast);
   return { agentScope, projectAgentsDir: discovery.projectAgentsDir, results };
 }