killeros 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.7] - 2026-08-01
+
+### Fixed
+
+- Serialized every write-capable task in a parallel batch in input order instead of rejecting batches with multiple writers.
+- Settled queued tasks on interrupted parallel batches and documented the shared-worktree execution model.
+- Restricted the `message` parameter to `action: "steer"` and added focused regression coverage.
+
+## [1.4.6] - 2026-08-01
+
+### Fixed
+
+- Made the registered task schema use the same ten-task limit as runtime validation.
+- Kept one isolated Pi session ID and session directory across steering restarts so a child retains its conversation.
+- Bound retained trace, stderr, and returned text, and spooled large JSONL lines to temporary storage without stopping the child or reporting a retention cutoff as `limited`.
+- Kept explicit embedding resource guards and user stops visible as terminal states.
+
 ## [1.4.5] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-  pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.5
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.7
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -97,13 +97,13 @@ KillerOS ships `planner`, `reviewer`, `scout`, and `security` as read-only roles
 
 The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
 
-The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. For example:
+The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Parallel batches run read-only roles concurrently, up to four at a time, then run every write-capable role serially in input order because all children share the parent worktree. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. The `message` field is only valid with `action: "steer"`. For example:
 
 ```json
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as ephemeral `pi --mode json -p --no-session` processes with explicit local tools plus `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output quota. The parent still limits each request to eight tasks and four parallel readers and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Esc cancellation terminates active children and escalates after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output execution quota. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks and four parallel readers and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Esc cancellation terminates active children and escalates after five seconds.
 
 ### Thread lifecycle
 
@@ -163,7 +163,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For release `1.4.5`, publish after the validation checks pass:
+For release `1.4.7`, publish after the validation checks pass:
 
 ```bash
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [

package/subagent-process.ts

@@ -1,11 +1,19 @@
 import { spawn } from "node:child_process";
-import { statSync } from "node:fs";
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 export const SUBAGENT_PROCESS_LIMITS = {
   killGraceMs: 5_000,
 } as const;
 
+export const SUBAGENT_PROCESS_RETENTION = {
+  jsonlMemoryBytes: 1 * 1024 * 1024,
+  traceBytes: 2 * 1024 * 1024,
+  stderrBytes: 64 * 1024,
+  outputBytes: 1 * 1024 * 1024,
+} as const;
+
 export type SubagentProcessStatus = "running" | "complete" | "failed" | "cancelled" | "limited";
 
 export interface SubagentProcessUsage {
@@ -56,11 +64,12 @@ export interface SubagentProcessChild {
 }
 
 export interface SubagentProcessOptions {
-  /** Exact Pi arguments. Include `--mode json` and `--no-session`. */
+  /** Exact Pi arguments. Include `--mode json` and either `--no-session` or an isolated session id and directory. */
   args: readonly string[];
   cwd: string;
   signal?: AbortSignal;
   limits?: Partial<SubagentProcessLimits>;
+  retention?: Partial<SubagentProcessRetention>;
   environment?: NodeJS.ProcessEnv;
   onUpdate?: (result: Readonly<SubagentProcessResult>) => void;
   /** Test or embed hook. It receives the exact Pi arguments supplied above. */
@@ -78,6 +87,13 @@ export interface SubagentProcessLimits {
   killGraceMs: number;
 }
 
+export interface SubagentProcessRetention {
+  jsonlMemoryBytes: number;
+  traceBytes: number;
+  stderrBytes: number;
+  outputBytes: number;
+}
+
 export interface SubagentProcessHandle {
   readonly pid: number | undefined;
   readonly result: Promise<SubagentProcessResult>;
@@ -188,6 +204,13 @@ function hasJsonMode(args: readonly string[]): boolean {
   return args.some((arg, index) => arg === "--mode=json" || arg === "--mode" && args[index + 1] === "json");
 }
 
+function hasIsolatedSession(args: readonly string[]): boolean {
+  const sessionId = args.indexOf("--session-id");
+  const sessionDir = args.indexOf("--session-dir");
+  return sessionId >= 0 && typeof args[sessionId + 1] === "string"
+    && sessionDir >= 0 && typeof args[sessionDir + 1] === "string";
+}
+
 function normalizeLimits(overrides: Partial<SubagentProcessLimits> | undefined): SubagentProcessLimits {
   const limits = { ...SUBAGENT_PROCESS_LIMITS, ...overrides };
   for (const name of ["wallTimeMs", "jsonlLineBytes", "traceBytes", "stderrBytes", "outputBytes", "killGraceMs"] as const) {
@@ -201,6 +224,15 @@ function normalizeLimits(overrides: Partial<SubagentProcessLimits> | undefined):
   return limits;
 }
 
+function normalizeRetention(overrides: Partial<SubagentProcessRetention> | undefined): SubagentProcessRetention {
+  const retention = { ...SUBAGENT_PROCESS_RETENTION, ...overrides };
+  for (const name of ["jsonlMemoryBytes", "traceBytes", "stderrBytes", "outputBytes"] as const) {
+    const value = retention[name];
+    if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  return retention;
+}
+
 function getPiInvocation(args: string[]): { command: string; args: string[] } {
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
@@ -268,8 +300,11 @@ function terminateProcess(child: SubagentProcessChild, force: boolean): void {
 export function runSubagentProcess(options: SubagentProcessOptions): SubagentProcessHandle {
   const args = [...options.args];
   if (!hasJsonMode(args)) throw new Error("Subagent Pi arguments must include --mode json");
-  if (!args.includes("--no-session")) throw new Error("Subagent Pi arguments must include --no-session");
+  if (!args.includes("--no-session") && !hasIsolatedSession(args)) {
+    throw new Error("Subagent Pi arguments must include --no-session or an isolated --session-id and --session-dir");
+  }
   const limits = normalizeLimits(options.limits);
+  const retention = normalizeRetention(options.retention);
   const startedAt = Date.now();
   const state: SubagentProcessResult = {
     status: "running",
@@ -295,6 +330,8 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let requestedReason: string | undefined;
   let stdoutLine = Buffer.alloc(0);
   let stdoutLineBytes = 0;
+  let stdoutLineSpoolDirectory: string | undefined;
+  let stdoutLineSpoolDescriptor: number | undefined;
   let stderr = Buffer.alloc(0);
   let outputBytesSeen = 0;
   let forceTimer: NodeJS.Timeout | undefined;
@@ -303,16 +340,53 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let resolveResult!: (result: SubagentProcessResult) => void;
   const result = new Promise<SubagentProcessResult>((resolve) => { resolveResult = resolve; });
 
+  const clearStdoutLine = (): void => {
+    if (stdoutLineSpoolDescriptor !== undefined) {
+      try {
+        closeSync(stdoutLineSpoolDescriptor);
+      } catch (error) {
+        state.errorMessage ??= `Could not close child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      stdoutLineSpoolDescriptor = undefined;
+    }
+    if (stdoutLineSpoolDirectory) {
+      try {
+        rmSync(stdoutLineSpoolDirectory, { recursive: true, force: true });
+      } catch (error) {
+        state.errorMessage ??= `Could not remove child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      stdoutLineSpoolDirectory = undefined;
+    }
+    stdoutLine = Buffer.alloc(0);
+    stdoutLineBytes = 0;
+  };
+  const readStdoutLine = (): string => {
+    if (stdoutLineSpoolDirectory) {
+      const filePath = path.join(stdoutLineSpoolDirectory, "line.jsonl");
+      try {
+        if (stdoutLineSpoolDescriptor !== undefined) {
+          closeSync(stdoutLineSpoolDescriptor);
+          stdoutLineSpoolDescriptor = undefined;
+        }
+        return readFileSync(filePath, "utf8");
+      } catch (error) {
+        state.errorMessage ??= `Could not read child JSONL spool: ${error instanceof Error ? error.message : String(error)}`;
+        return "";
+      } finally {
+        clearStdoutLine();
+      }
+    }
+    const line = stdoutLine.toString("utf8", 0, stdoutLineBytes);
+    clearStdoutLine();
+    return line;
+  };
+
   const publish = (): void => options.onUpdate?.(cloneResult(state));
   const finish = (code: number | null): void => {
     if (closed || finishing) return;
     finishing = true;
-    if (stdoutLineBytes && !requestedStatus) {
-      const finalLine = stdoutLine.toString("utf8", 0, stdoutLineBytes);
-      stdoutLine = Buffer.alloc(0);
-      stdoutLineBytes = 0;
-      processLine(finalLine);
-    }
+    if (stdoutLineBytes && !requestedStatus) processLine(readStdoutLine());
+    else clearStdoutLine();
     closed = true;
     if (forceTimer) clearTimeout(forceTimer);
     if (settleTimer) clearTimeout(settleTimer);
@@ -383,17 +457,20 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       } else if (limits.quotaUsd !== undefined && state.usage.cost.total > limits.quotaUsd) {
         requestTermination("limited", "quota_cost", `Child cost exceeds $${limits.quotaUsd}`);
       }
-      if (appendTrace(state, traceMessage(message), limits.traceBytes)) {
+      const traceTruncatedBefore = state.traceTruncatedBytes;
+      appendTrace(state, traceMessage(message), Math.min(retention.traceBytes, limits.traceBytes ?? retention.traceBytes));
+      if (limits.traceBytes !== undefined && state.traceTruncatedBytes > traceTruncatedBefore && state.traceBytes >= limits.traceBytes) {
         requestTermination("limited", "trace_limit", `Retained child trace exceeds ${limits.traceBytes} bytes`);
       }
       const output = textContent(message);
       if (output) {
-        const capped = truncateUtf8(output, limits.outputBytes ?? Buffer.byteLength(output, "utf8"));
+        const outputLimit = Math.min(retention.outputBytes, limits.outputBytes ?? retention.outputBytes);
+        const capped = truncateUtf8(output, outputLimit);
         state.output = capped.text;
         state.outputTruncatedBytes = capped.omittedBytes;
         outputBytesSeen += Buffer.byteLength(output, "utf8");
         state.outputBytes = outputBytesSeen;
-        state.outputTruncatedBytes = Math.max(state.outputTruncatedBytes, limits.outputBytes === undefined ? 0 : outputBytesSeen - limits.outputBytes);
+        state.outputTruncatedBytes = Math.max(state.outputTruncatedBytes, outputBytesSeen - (limits.outputBytes ?? retention.outputBytes));
         if (limits.outputBytes !== undefined && outputBytesSeen > limits.outputBytes) requestTermination("limited", "output_limit", `Child output exceeds ${limits.outputBytes} bytes`);
       }
       if (typeof message.model === "string") state.model = message.provider ? `${message.provider}/${message.model}` : message.model;
@@ -406,7 +483,9 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       publish();
     } else if (event?.type === "tool_result_end" && event.message) {
       const name = typeof event.message.toolName === "string" ? event.message.toolName : "tool";
-      if (appendTrace(state, [`${name} result${event.message.isError ? " (error)" : ""}`], limits.traceBytes)) {
+      const traceTruncatedBefore = state.traceTruncatedBytes;
+      appendTrace(state, [`${name} result${event.message.isError ? " (error)" : ""}`], Math.min(retention.traceBytes, limits.traceBytes ?? retention.traceBytes));
+      if (limits.traceBytes !== undefined && state.traceTruncatedBytes > traceTruncatedBefore && state.traceBytes >= limits.traceBytes) {
         requestTermination("limited", "trace_limit", `Retained child trace exceeds ${limits.traceBytes} bytes`);
       }
       publish();
@@ -418,6 +497,22 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
       requestTermination("limited", "jsonl_line_limit", `Child JSONL line exceeds ${limits.jsonlLineBytes} bytes`);
       return false;
     }
+    if (nextBytes > retention.jsonlMemoryBytes) {
+      try {
+        if (stdoutLineSpoolDescriptor === undefined) {
+          stdoutLineSpoolDirectory = mkdtempSync(path.join(os.tmpdir(), "killeros-jsonl-"));
+          stdoutLineSpoolDescriptor = openSync(path.join(stdoutLineSpoolDirectory, "line.jsonl"), "w");
+          if (stdoutLineBytes) writeSync(stdoutLineSpoolDescriptor, stdoutLine);
+          stdoutLine = Buffer.alloc(0);
+        }
+        if (fragment.length) writeSync(stdoutLineSpoolDescriptor, fragment);
+      } catch (error) {
+        requestTermination("failed", "jsonl_spool_error", `Could not spool child JSONL: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+      }
+      stdoutLineBytes = nextBytes;
+      return true;
+    }
     if (nextBytes > stdoutLine.length) {
       const nextCapacity = limits.jsonlLineBytes === undefined
         ? Math.max(nextBytes, stdoutLine.length * 2, 4_096)
@@ -449,21 +544,19 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
           const end = newline < 0 ? buffer.length : newline;
           if (!appendStdout(buffer.subarray(offset, end))) return;
           if (newline < 0) return;
-          const line = stdoutLine.toString("utf8", 0, stdoutLineBytes);
-          stdoutLine = Buffer.alloc(0);
-          stdoutLineBytes = 0;
-          processLine(line);
+          processLine(readStdoutLine());
           offset = newline + 1;
         }
       });
       child.stderr.on("data", (chunk: Buffer | string) => {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        const retained = limits.stderrBytes === undefined
-          ? buffer
-          : buffer.subarray(0, Math.max(0, limits.stderrBytes - stderr.length));
+        const stderrLimit = Math.min(retention.stderrBytes, limits.stderrBytes ?? retention.stderrBytes);
+        const retained = buffer.subarray(0, Math.max(0, stderrLimit - stderr.length));
         if (retained.length) stderr = Buffer.concat([stderr, retained]);
         state.stderrTruncatedBytes += buffer.length - retained.length;
-        if (buffer.length > retained.length) requestTermination("limited", "stderr_limit", `Child stderr exceeds ${limits.stderrBytes} bytes`);
+        if (limits.stderrBytes !== undefined && stderr.length + state.stderrTruncatedBytes > limits.stderrBytes) {
+          requestTermination("limited", "stderr_limit", `Child stderr exceeds ${limits.stderrBytes} bytes`);
+        }
       });
       child.on("error", (error) => requestTermination("failed", "spawn_error", error.message));
       child.once("close", finish);

package/subagents.ts

@@ -20,9 +20,12 @@ import { runSubagentProcess, type SubagentProcessHandle, type SubagentProcessRes
 import { formatThreadBoard, formatThreadInspection, type ThreadRecord as ThreadBoardRecord } from "./subagent-ui.ts";
 
 export const SUBAGENT_LIMITS = {
-  maxTasks: 8,
+  maxTasks: 10,
   maxReadConcurrency: 4,
   toolOutputBytes: 50 * 1024,
+  traceRetentionBytes: 8 * 1024 * 1024,
+  stderrRetentionBytes: 1 * 1024 * 1024,
+  taskOutputRetentionBytes: 1 * 1024 * 1024,
   roleFileBytes: 64 * 1024,
   taskCharacters: 20_000,
   killGraceMs: 5_000,
@@ -110,6 +113,7 @@ export interface SubagentDetails {
   mode: "single" | "parallel" | "chain";
   agentScope: AgentScope;
   projectAgentsDir: string | null;
+  executionNote?: string;
   results: SubagentTaskResult[];
   aggregateUsage: SubagentUsage;
   parentId?: string;
@@ -511,7 +515,12 @@ function cloneResult(result: SubagentTaskResult): SubagentTaskResult {
   };
 }
 
-function mergeTaskResults(previous: SubagentTaskResult | undefined, next: SubagentTaskResult, maxTraceBytes?: number): SubagentTaskResult {
+function mergeTaskResults(
+  previous: SubagentTaskResult | undefined,
+  next: SubagentTaskResult,
+  maxTraceBytes?: number,
+  maxStderrBytes?: number,
+): SubagentTaskResult {
   if (!previous) return cloneResult(next);
   const merged = cloneResult(next);
   const trace: string[] = [];
@@ -527,9 +536,11 @@ function mergeTaskResults(previous: SubagentTaskResult | undefined, next: Subage
   merged.trace = trace;
   merged.traceBytes = traceBytes;
   merged.traceTruncatedBytes = traceTruncatedBytes;
-  merged.stderr = [previous.stderr, next.stderr].filter(Boolean).join("\n");
+  const stderr = [previous.stderr, next.stderr].filter(Boolean).join("\n");
+  const retainedStderr = truncateUtf8(stderr, maxStderrBytes === undefined ? Buffer.byteLength(stderr, "utf8") : maxStderrBytes);
+  merged.stderr = retainedStderr.text;
   merged.stderrBytes = previous.stderrBytes + next.stderrBytes;
-  merged.stderrTruncatedBytes = previous.stderrTruncatedBytes + next.stderrTruncatedBytes;
+  merged.stderrTruncatedBytes = previous.stderrTruncatedBytes + next.stderrTruncatedBytes + retainedStderr.omittedBytes;
   merged.output = next.output || previous.output;
   merged.outputBytes = previous.outputBytes + next.outputBytes;
   merged.outputTruncatedBytes = previous.outputTruncatedBytes + next.outputTruncatedBytes;
@@ -565,6 +576,8 @@ interface RunTaskOptions {
   webExtension?: string;
   projectTrusted: boolean;
   limits: SubagentLimits;
+  sessionDirectory: string;
+  sessionId: string;
   timeoutMs?: number;
   onChange: (result: SubagentTaskResult) => void;
   onHandle?: (handle: SubagentProcessHandle) => void;
@@ -631,7 +644,8 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
     const args = [
       "--mode", "json",
       "-p",
-      "--no-session",
+      "--session-dir", options.sessionDirectory,
+      "--session-id", options.sessionId,
       "--no-extensions",
       "--extension", options.webExtension ?? SUBAGENT_WEB_EXTENSION,
       "--no-prompt-templates",
@@ -657,6 +671,11 @@ async function runTask(options: RunTaskOptions): Promise<SubagentTaskResult> {
         ...(limits.quotaUsd === undefined ? {} : { quotaUsd: limits.quotaUsd }),
         killGraceMs: limits.killGraceMs,
       },
+      retention: {
+        traceBytes: limits.traceRetentionBytes,
+        stderrBytes: limits.stderrRetentionBytes,
+        outputBytes: limits.taskOutputRetentionBytes,
+      },
       onUpdate: (next) => applyProcessResult(result, next, startedAt, options.onChange),
     });
     options.onHandle?.(handle);
@@ -694,35 +713,35 @@ async function mapReadTasks<T>(items: T[], concurrency: number, run: (item: T, i
   await Promise.all(workers);
 }
 
-const TaskSchema = Type.Object({
-  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
-  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Bounded task for the role" }),
-});
-
-const ChainTaskSchema = Type.Object({
-  agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
-  task: Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
-});
-
-const SubagentParams = Type.Object({
-  action: Type.Optional(StringEnum(["spawn", "list", "inspect", "steer", "interrupt", "collect", "close"] as const, {
-    default: "spawn",
-    description: "Thread lifecycle action",
-  })),
-  threadId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" })),
-  message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message" })),
-  all: Type.Optional(Type.Boolean({ description: "Interrupt every active child thread" })),
-  agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
-  task: Type.Optional(Type.String({ minLength: 1, maxLength: SUBAGENT_LIMITS.taskCharacters, description: "Task for single mode" })),
-  tasks: Type.Optional(Type.Array(TaskSchema, { minItems: 1, maxItems: SUBAGENT_LIMITS.maxTasks, description: "Parallel role tasks" })),
-  chain: Type.Optional(Type.Array(ChainTaskSchema, { minItems: 1, maxItems: SUBAGENT_LIMITS.maxTasks, description: "Sequential role tasks; {previous} inserts the prior result" })),
-  model: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Model for every task as provider/model; inherit uses each role setting or the active parent" })),
-  thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 16, description: "Thinking effort for every task: off, minimal, low, medium, high, xhigh, max, or inherit" })),
-  agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, {
-    default: "user",
-    description: "Role sources: user includes bundled and personal; project includes bundled and trusted project; both includes all",
-  })),
-});
+function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxReadConcurrency" | "taskCharacters">) {
+  const taskSchema = Type.Object({
+    agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Bounded task for the role" }),
+  });
+  const chainTaskSchema = Type.Object({
+    agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
+    task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task with optional {previous} handoff placeholder" }),
+  });
+  return Type.Object({
+    action: Type.Optional(StringEnum(["spawn", "list", "inspect", "steer", "interrupt", "collect", "close"] as const, {
+      default: "spawn",
+      description: "Thread lifecycle action",
+    })),
+    threadId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" })),
+    message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message; only valid with action steer" })),
+    all: Type.Optional(Type.Boolean({ description: "Interrupt every active child thread" })),
+    agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
+    task: Type.Optional(Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task for single mode" })),
+    tasks: Type.Optional(Type.Array(taskSchema, { minItems: 1, maxItems: limits.maxTasks, description: `Parallel role tasks: read-only roles run concurrently up to ${limits.maxReadConcurrency}; write-capable roles run serially in input order because all children share the parent worktree` })),
+    chain: Type.Optional(Type.Array(chainTaskSchema, { minItems: 1, maxItems: limits.maxTasks, description: "Sequential role tasks; {previous} inserts the prior result" })),
+    model: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Model for every task as provider/model; inherit uses each role setting or the active parent" })),
+    thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 16, description: "Thinking effort for every task: off, minimal, low, medium, high, xhigh, max, or inherit" })),
+    agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, {
+      default: "user",
+      description: "Role sources: user includes bundled and personal; project includes bundled and trusted project; both includes all",
+    })),
+  });
+}
 
 type TaskInput = { agent: string; task: string };
 
@@ -739,16 +758,12 @@ function clipCharacters(text: string, maxCharacters: number, fromEnd = false): s
   return (fromEnd ? characters.slice(-maxCharacters) : characters.slice(0, maxCharacters)).join("");
 }
 
-function buildSteeredTask(task: string, steering: readonly string[], previousOutput: string | undefined, maxCharacters: number): string {
+function buildSteeredTask(task: string, steering: readonly string[], maxCharacters: number): string {
   const steeringLabel = "\n\nParent steering:\n";
   const steeringText = clipCharacters(steering.join("\n"), Math.max(0, maxCharacters - [...steeringLabel].length), true);
-  const previousLabel = previousOutput ? "\n\nPrevious child handoff:\n" : "";
-  const required = [...steeringLabel, ...steeringText, ...previousLabel].length;
+  const required = [...steeringLabel, ...steeringText].length;
   const taskText = clipCharacters(task, Math.max(0, maxCharacters - required));
-  const previousText = previousOutput
-    ? clipCharacters(previousOutput, Math.max(0, maxCharacters - [...taskText, ...steeringLabel, ...steeringText, ...previousLabel].length))
-    : "";
-  return `${taskText}${previousText ? `${previousLabel}${previousText}` : ""}${steeringLabel}${steeringText}`;
+  return `${taskText}${steeringLabel}${steeringText}`;
 }
 
 function formatUsage(usage: SubagentUsage): string {
@@ -953,7 +968,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   };
 
   const syncThread = (threadId: SubagentThreadId, next: SubagentTaskResult, runtime?: ActiveThreadRuntime): SubagentTaskResult => {
-    const effective = mergeTaskResults(runtime?.aggregate, next, limits.traceBytes);
+    const effective = mergeTaskResults(runtime?.aggregate, next, limits.traceRetentionBytes, limits.stderrRetentionBytes);
     if (runtime?.requestedReason && next.status === "cancelled") effective.terminationReason = runtime.requestedReason;
     savedResults.set(threadId, cloneResult(effective));
     let thread = threads.inspect(threadId);
@@ -966,9 +981,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     const from = runtime?.traceCount ?? 0;
     let retainedTraceBytes = thread.trace.reduce((total, entry) => total + Buffer.byteLength(entry.message ?? "", "utf8"), 0);
     for (const entry of next.trace.slice(from)) {
-      const retained = truncateUtf8(entry, limits.traceBytes === undefined
+      const retained = truncateUtf8(entry, limits.traceRetentionBytes === undefined
         ? Buffer.byteLength(entry, "utf8")
-        : Math.max(0, limits.traceBytes - retainedTraceBytes));
+        : Math.max(0, limits.traceRetentionBytes - retainedTraceBytes));
       if (retained.text) {
         threads.trace(threadId, { kind: "child", message: retained.text });
         retainedTraceBytes += Buffer.byteLength(retained.text, "utf8");
@@ -1015,20 +1030,23 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   pi.registerTool({
     name: "subagent",
     label: "Subagents",
-    description: "Spawn and manage named child threads. Children finish naturally; time, output, trace, stderr, quota, task count, and concurrency are the hard edges. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed handoffs.",
+    description: `Spawn and manage named child threads. Children finish naturally. Parallel tasks run read-only roles concurrently up to ${limits.maxReadConcurrency}, then run write-capable roles serially in input order because all children share the parent worktree. The message parameter is only valid with action steer. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed handoffs.`,
     promptSnippet: "Delegate bounded specialist work to isolated KillerOS subagents",
     promptGuidelines: [
       "Use subagent for clearly separable specialist work; prefer read-only scout, planner, reviewer, or security roles before a writer.",
-      "Do not request multiple write-capable subagents in one parallel batch.",
+      `Parallel tasks run read-only roles concurrently up to ${limits.maxReadConcurrency}, then queue write-capable roles in input order because all children share the parent worktree.`,
       "Every child can load relevant skills with read and can use web_search, source_check, fetch_content, and get_search_content for external research.",
       "When the user names a model or thinking effort, pass model and thinking separately; use inherit when the active parent or role setting should decide.",
       "Keep completed and stopped threads inspectable until the parent explicitly closes them.",
     ],
-    parameters: SubagentParams,
+    parameters: createSubagentParams(limits),
     executionMode: "parallel",
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const action = params.action ?? "spawn";
+      if (params.message !== undefined && action !== "steer") {
+        throw new Error("message is only valid with action steer");
+      }
       const parentId = parentThreadId(ctx);
       const actionDetails = (selectedThreadId?: string): SubagentDetails => detailsFor(parentId, "single", params.agentScope ?? "user", null, selectedThreadId);
       const actionResult = (text: string, selectedThreadId?: string) => {
@@ -1147,10 +1165,17 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         ? [{ agent: params.agent!, task: params.task! }]
         : hasParallel ? params.tasks! : params.chain!;
       if (inputs.length > limits.maxTasks) throw new Error(`At most ${limits.maxTasks} subagent tasks are allowed`);
-      if (hasParallel) {
-        const writers = inputs.filter((input) => roles.get(input.agent)!.access === "write");
-        if (writers.length > 1) throw new Error("Parallel batches may contain at most one write-capable subagent; writers are serialized");
-      }
+      const readIndexes = hasParallel
+        ? inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "read")
+        : [];
+      const writerIndexes = hasParallel
+        ? inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "write").map(({ index }) => index)
+        : [];
+      const executionNote = hasParallel
+        ? writerIndexes.length
+          ? `Parallel schedule: read-only tasks run concurrently up to ${limits.maxReadConcurrency}; write-capable tasks are queued (serialized) in input order because all children share the parent worktree.`
+          : `Parallel schedule: read-only tasks run concurrently up to ${limits.maxReadConcurrency}.`
+        : undefined;
 
       const inFlight = threads.listAll().filter((thread) => ["queued", "active"].includes(thread.state)).length;
       if (inFlight + inputs.length > limits.maxTasks) {
@@ -1173,7 +1198,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         const currentResults = results.map(cloneResult);
         (onUpdate as ToolUpdate | undefined)?.({
           content: [{ type: "text", text: message }],
-          details: { ...board, results: currentResults, aggregateUsage: aggregateUsage(currentResults) },
+          details: { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) },
         });
       };
       const runAt = async (index: number, task: string): Promise<void> => {
@@ -1214,6 +1239,23 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           emit();
           return;
         }
+        let sessionDirectory: string;
+        try {
+          sessionDirectory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-session-"));
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          results[index] = {
+            ...results[index]!,
+            status: "failed",
+            terminationReason: "session_error",
+            errorMessage: message,
+          };
+          threads.fail(threadId, { message, code: "session_error" });
+          savedResults.set(threadId, cloneResult(results[index]!));
+          emit();
+          return;
+        }
+        const sessionId = `killeros-${threadId.replace(/[^A-Za-z0-9_.-]/gu, "_")}`;
         const controller = new AbortController();
         const abortParent = (): void => controller.abort();
         if (signal) {
@@ -1224,7 +1266,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         activeRuntimes.set(threadId, runtime);
         const agent = roles.get(input.agent)!;
         const queuedSteering = initialThread.steering.map((entry) => entry.message);
-        let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, undefined, limits.taskCharacters) : task;
+        let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, limits.taskCharacters) : task;
         const stopForBudget = (reason: string, message: string): void => {
           const limited = cloneResult(runtime.aggregate ?? results[index]!);
           limited.status = "limited";
@@ -1248,7 +1290,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             const aggregate = runtime.aggregate;
             const wallTimeMs = agent.timeoutMs ?? limits.wallTimeMs;
             const remainingWallTimeMs = wallTimeMs === undefined ? undefined : wallTimeMs - (Date.now() - runtime.startedAt);
-            const usedTraceBytes = aggregate?.traceBytes ?? 0;
+            const usedTraceBytes = (aggregate?.traceBytes ?? 0) + (aggregate?.traceTruncatedBytes ?? 0);
             const usedStderrBytes = aggregate?.stderrBytes ?? 0;
             const usedOutputBytes = aggregate?.outputBytes ?? 0;
             const usedTokens = aggregate?.usage.totalTokens ?? 0;
@@ -1257,15 +1299,15 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               stopForBudget("wall_time_limit", `Child thread exceeds ${wallTimeMs} ms`);
               break;
             }
-            if (limits.traceBytes !== undefined && (usedTraceBytes >= limits.traceBytes || aggregate?.traceTruncatedBytes)) {
+            if (limits.traceBytes !== undefined && usedTraceBytes >= limits.traceBytes) {
               stopForBudget("trace_limit", `Child thread retains more than ${limits.traceBytes} trace bytes`);
               break;
             }
-            if (limits.stderrBytes !== undefined && (usedStderrBytes >= limits.stderrBytes || aggregate?.stderrTruncatedBytes)) {
+            if (limits.stderrBytes !== undefined && usedStderrBytes >= limits.stderrBytes) {
               stopForBudget("stderr_limit", `Child thread emits more than ${limits.stderrBytes} stderr bytes`);
               break;
             }
-            if (limits.taskOutputBytes !== undefined && (usedOutputBytes >= limits.taskOutputBytes || aggregate?.outputTruncatedBytes)) {
+            if (limits.taskOutputBytes !== undefined && usedOutputBytes >= limits.taskOutputBytes) {
               stopForBudget("output_limit", `Child thread emits more than ${limits.taskOutputBytes} output bytes`);
               break;
             }
@@ -1289,6 +1331,8 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               webExtension: options.webExtension,
               projectTrusted: ctx.isProjectTrusted(),
               spawnProcess,
+              sessionDirectory,
+              sessionId,
               limits: {
                 ...limits,
                 ...(limits.traceBytes === undefined ? {} : { traceBytes: limits.traceBytes - usedTraceBytes }),
@@ -1305,7 +1349,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
               },
             });
             next.task = task;
-            runtime.aggregate = mergeTaskResults(runtime.aggregate, next, limits.traceBytes);
+            runtime.aggregate = mergeTaskResults(runtime.aggregate, next, limits.traceRetentionBytes, limits.stderrRetentionBytes);
             runtime.aggregate.task = task;
             results[index] = cloneResult(runtime.aggregate);
             savedResults.set(threadId, cloneResult(runtime.aggregate));
@@ -1321,15 +1365,37 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
                 handoff: runtime.aggregate.output ? { summary: runtime.aggregate.output } : undefined,
               });
             }
-            currentTask = buildSteeredTask(task, steering, runtime.aggregate.output, limits.taskCharacters);
+            currentTask = buildSteeredTask(task, steering, limits.taskCharacters);
           }
         } finally {
           activeRuntimes.delete(threadId);
           signal?.removeEventListener("abort", abortParent);
+          try {
+            await rm(sessionDirectory, { recursive: true, force: true });
+          } catch {
+            // Temporary child session cleanup is best effort after process termination.
+          }
         }
         emit();
       };
 
+      const settleQueued = (reason: string): void => {
+        for (let index = 0; index < results.length; index += 1) {
+          const result = results[index]!;
+          if (result.status !== "queued") continue;
+          const thread = threads.inspect(threadRecords[index]!.id);
+          const alreadyStopped = thread?.state === "stopped";
+          result.status = signal?.aborted || alreadyStopped ? "cancelled" : "failed";
+          result.terminationReason = alreadyStopped
+            ? thread.stopReason ?? "interrupted"
+            : signal?.aborted ? "abort" : reason;
+          if (thread?.state === "queued" || thread?.state === "active") {
+            threads.stop(threadRecords[index]!.id, { reason: result.terminationReason });
+          }
+          savedResults.set(threadRecords[index]!.id, cloneResult(result));
+        }
+      };
+
       emit(`${mode}: ${results.length} queued`);
       if (hasChain) {
         let previous = "";
@@ -1339,33 +1405,21 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           if (results[index]!.status !== "complete") break;
           previous = results[index]!.output;
         }
-        for (let index = 0; index < results.length; index += 1) {
-          const result = results[index]!;
-          if (result.status === "queued") {
-            const thread = threads.inspect(threadRecords[index]!.id);
-            const alreadyStopped = thread?.state === "stopped";
-            result.status = signal?.aborted || alreadyStopped ? "cancelled" : "failed";
-            result.terminationReason = alreadyStopped
-              ? thread.stopReason ?? "interrupted"
-              : signal?.aborted ? "abort" : "chain_stopped";
-            if (thread?.state === "queued" || thread?.state === "active") {
-              threads.stop(threadRecords[index]!.id, { reason: result.terminationReason });
-            }
-            savedResults.set(threadRecords[index]!.id, cloneResult(result));
-          }
-        }
+        settleQueued("chain_stopped");
       } else if (hasParallel) {
-        const readIndexes = inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "read");
-        const writerIndex = inputs.findIndex((input) => roles.get(input.agent)!.access === "write");
-        await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
-        if (writerIndex >= 0) await runAt(writerIndex, inputs[writerIndex]!.task);
+        try {
+          await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
+          for (const index of writerIndexes) await runAt(index, inputs[index]!.task);
+        } finally {
+          settleQueued("parallel_stopped");
+        }
       } else {
         await runAt(0, inputs[0]!.task);
       }
 
       const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
       const currentResults = results.map(cloneResult);
-      const details: SubagentDetails = { ...board, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
+      const details: SubagentDetails = { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
       return {
         content: [{ type: "text", text: buildToolContent(mode, details.results, limits.toolOutputBytes) }],
         details,
@@ -1376,7 +1430,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     renderCall(args, theme) {
       const scope = args.agentScope ?? "user";
       if (args.action && args.action !== "spawn") return new Text(`${theme.fg("toolTitle", theme.bold("threads "))}${theme.fg("accent", args.action)}${theme.fg("dim", args.threadId ? ` · ${args.threadId}` : "")}`, 0, 0);
-      if (args.tasks?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${args.tasks.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+      if (args.tasks?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${args.tasks.length} · readers first; writers serial`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
       if (args.chain?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `chain ${args.chain.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
       return new Text(`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "…")}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
     },
@@ -1399,6 +1453,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           theme.fg("toolTitle", theme.bold(`Done (${board.done.length})`)),
           ...board.done.map((task) => `${theme.fg(task.state.status === "complete" ? "success" : "warning", `${task.state.label}`)} ${theme.fg("toolTitle", theme.bold(task.agent))}${theme.fg("dim", ` · ${task.id} · ${task.usage.text}`)}`),
         ];
+        if (details.executionNote) lines.push(theme.fg("dim", details.executionNote));
         lines.push(theme.fg("dim", `Total · ${formatUsage(details.aggregateUsage)} · Ctrl+O to expand`));
         return new Text(lines.join("\n"), 0, 0);
       }
@@ -1406,6 +1461,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       const container = new Container();
       container.addChild(new Text(theme.fg("toolTitle", theme.bold(`Subagents · ${details.mode}`)), 0, 0));
       container.addChild(new Text(theme.fg("dim", `Active ${board.active.length} · Done ${board.done.length} · Controls: Inspect · Steer · Interrupt · Collect · Close`), 0, 0));
+      if (details.executionNote) container.addChild(new Text(theme.fg("dim", details.executionNote), 0, 0));
       if (board.selected) {
         const inspection = formatThreadInspection(threadBoardRecord(details.results.find((task) => task.id === board.selected!.id)!));
         container.addChild(new Spacer(1));