killeros 1.5.2 → 1.5.3

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [1.5.3] - 2026-08-03
+
+### Fixed
+
+- Returned spawned thread IDs immediately and delivered completed handoffs as Pi follow-ups, making active `inspect`, `steer`, and `interrupt` actions reachable through normal parent turns.
+- Ignored provider-generated `threadId` values during spawn argument preparation and TUI rendering while retaining strict action validation during execution.
+- Connected Pi's parent cancellation signal to active child processes so Escape stops the subagent, suppresses replacement follow-up turns, and returns control to the terminal.
+- Made `/exit` abort an active run before requesting Pi's graceful shutdown, and made session teardown await bounded background-child settlement.
+- Corrected the README cancellation contract so it matches active-child termination.
+
 ## [1.5.2] - 2026-08-03
 
 ### Changed

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.5.2
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.5.3
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -118,7 +118,9 @@ The three spawn shapes cannot be mixed. The `message` field is only valid with `
 {"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 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, trace, stderr, or returned-output execution quota; each JSONL record still has a bounded 8 MiB parser ceiling. 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, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. A parent tool-call abort cancels queued tasks but lets already-running children finish; explicit `interrupt` actions and session shutdown terminate active children and escalate after five seconds.
+Spawn returns the generated thread IDs immediately while the children continue in the background. This lets the parent use `list`, `inspect`, `steer`, `interrupt`, `collect`, and `close` in later tool calls. When the batch settles, KillerOS delivers its bounded handoff as a Pi follow-up and triggers the parent turn. A batch cancelled by parent Escape remains inspectable but does not trigger a replacement turn.
+
+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, trace, stderr, or returned-output execution quota; each JSONL record still has a bounded 8 MiB parser ceiling. 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, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Aborting the originating parent turn stops its queued and active children; explicit `interrupt` actions and session shutdown also terminate active children and escalate after five seconds.
 
 ### Thread lifecycle
 
@@ -128,7 +130,7 @@ Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `close
 
 The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful. Closing removes a thread from the active workspace; heavy trace and result payloads are evicted as needed under the bounded retention budget, leaving a small inspectable tombstone.
 
-A child completes naturally when it returns a final answer. The default path has no per-child execution quota, while every JSONL record has an 8 MiB parser ceiling. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Parent tool-call aborts leave active children running while queued work is settled as cancelled; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown still terminates active children and escalates after five seconds.
+A child completes naturally when it returns a final answer. The default path has no per-child execution quota, while every JSONL record has an 8 MiB parser ceiling. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Aborting the originating parent turn settles queued work as cancelled and terminates active children; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown also terminates active children and escalates after five seconds.
 
 The replacement lifecycle has nine phases:
 

package/killeros/commands.ts

@@ -15,7 +15,10 @@ export function registerAliases(pi: ExtensionAPI): void {
   pi.registerCommand("clear", { description: "Start a new session after confirmation", handler: startNewSession });
   pi.registerCommand("exit", {
     description: "Quit Pi gracefully",
-    handler: async (_args, ctx) => ctx.shutdown(),
+    handler: async (_args, ctx) => {
+      if (!ctx.isIdle()) ctx.abort();
+      ctx.shutdown();
+    },
   });
 }
 

package/killeros/subagents.ts

@@ -164,6 +164,8 @@ export interface SubagentRuntimeOptions {
   webExtension?: string;
   spawnProcess?: (args: string[], cwd: string, environment?: NodeJS.ProcessEnv) => SpawnedProcess;
   limits?: Partial<SubagentLimits>;
+  /** Test and embedding compatibility mode; production spawns return immediately. */
+  awaitSpawnCompletion?: boolean;
 }
 
 class AgentConfigurationError extends Error {
@@ -950,6 +952,19 @@ export function tryNormalizeSubagentRequest(
   }
 }
 
+function prepareSubagentRequest(
+  value: unknown,
+  limits: Pick<SubagentLimits, "maxTasks" | "taskCharacters">,
+): NormalizedSubagentRequest {
+  const record = requireRecord(value, "subagent request");
+  const action = record.action ?? SUBAGENT_ACTION.spawn;
+  if (action === SUBAGENT_ACTION.spawn && Object.hasOwn(record, "threadId")) {
+    const { threadId: _generatedThreadId, ...spawnRecord } = record;
+    return normalizeSubagentRequest(spawnRecord, limits);
+  }
+  return normalizeSubagentRequest(record, limits);
+}
+
 function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxReadConcurrency" | "taskCharacters">) {
   const taskSchema = Type.Object({
     agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
@@ -959,9 +974,9 @@ function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxRead
     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" }),
   }, { additionalProperties: false });
-  const threadId = Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" });
+  const threadId = Type.String({ minLength: 1, maxLength: 128, description: "Existing child thread ID; omit when spawning because KillerOS creates it" });
   return Type.Object({
-    action: Type.Optional(StringEnum(SUBAGENT_ACTIONS, { default: SUBAGENT_ACTION.spawn, description: "Spawn, list, inspect, steer, interrupt, collect, or close" })),
+    action: Type.Optional(StringEnum(SUBAGENT_ACTIONS, { default: SUBAGENT_ACTION.spawn, description: "Spawn, list, inspect, steer, interrupt, collect, or close. Omit threadId when spawning" })),
     threadId: Type.Optional(threadId),
     message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Steering message; valid only with action steer" })),
     all: Type.Optional(Type.Literal(true, { description: "Interrupt every active child thread" })),
@@ -1187,6 +1202,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   const spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
   const threads = new SubagentThreadRegistry();
   const activeRuntimes = new Map<string, ActiveThreadRuntime>();
+  const backgroundBatches = new Set<Promise<unknown>>();
   const savedResults = new Map<string, SubagentTaskResult>();
   const evictedThreadParents = new Map<string, string | undefined>();
   const maxClosedThreads = Number.isSafeInteger(limits.threadRetentionRecords) && limits.threadRetentionRecords > 0
@@ -1334,7 +1350,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   };
 
   if (typeof pi.on === "function") {
-    pi.on("session_shutdown", () => {
+    pi.on("session_shutdown", async () => {
       for (const runtime of activeRuntimes.values()) {
         runtime.restarting = false;
         runtime.requestedReason = "session_shutdown";
@@ -1344,6 +1360,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       threads.dispose();
       savedResults.clear();
       evictedThreadParents.clear();
+      await Promise.allSettled([...backgroundBatches]);
     });
   }
 
@@ -1361,7 +1378,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     ],
     parameters: createSubagentParams(limits),
     prepareArguments(args) {
-      return normalizeSubagentRequest(args, limits).input;
+      return prepareSubagentRequest(args, limits).input;
     },
     executionMode: "parallel",
 
@@ -1523,7 +1540,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       const results = threadRecords.map((thread, index) => {
         return makeQueuedResult(thread.id, inputs[index]!.agent, inputs[index]!.task, hasChain ? index + 1 : undefined);
       });
+      let updatesOpen = true;
       const emit = (message = `${mode}: ${results.filter((result) => !["queued", "running"].includes(result.status)).length}/${results.length} settled`): void => {
+        if (!updatesOpen) return;
         const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
         const currentResults = results.map(cloneResult);
         (onUpdate as ToolUpdate | undefined)?.({
@@ -1584,11 +1603,20 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           traceCount: 0,
           startedAt: Date.now(),
         };
+        const abortFromParent = (): void => {
+          runtime.restarting = false;
+          runtime.requestedReason = "abort";
+          runtime.handle?.stop("abort");
+          controller.abort();
+        };
+        signal?.addEventListener("abort", abortFromParent, { once: true });
+        if (signal?.aborted) abortFromParent();
         activeRuntimes.set(threadId, runtime);
         let sessionDirectory: string;
         try {
           sessionDirectory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-session-"));
         } catch (error) {
+          signal?.removeEventListener("abort", abortFromParent);
           activeRuntimes.delete(threadId);
           const message = error instanceof Error ? error.message : String(error);
           results[index] = {
@@ -1604,6 +1632,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         }
         const currentThread = threads.inspect(threadId);
         if (controller.signal.aborted || threads.isDisposed || currentThread?.state !== "active") {
+          signal?.removeEventListener("abort", abortFromParent);
           activeRuntimes.delete(threadId);
           try {
             await rm(sessionDirectory, { recursive: true, force: true });
@@ -1748,6 +1777,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             currentTask = buildSteeredTask(task, steering, limits.taskCharacters);
           }
         } finally {
+          signal?.removeEventListener("abort", abortFromParent);
           activeRuntimes.delete(threadId);
           const removeSessionDirectory = async (): Promise<void> => {
             try {
@@ -1782,48 +1812,111 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         }
       };
 
-      emit(`${mode}: ${results.length} queued`);
-      if (hasChain) {
-        let previous = "";
-        for (let index = 0; index < inputs.length; index += 1) {
-          const task = expandChainTask(inputs[index]!.task, previous, limits.taskCharacters);
-          if (task === undefined) {
-            failQueuedTask(index, "task_limit", `Expanded task exceeds ${limits.taskCharacters} characters`);
-            break;
+      const finishBatch = async () => {
+        if (hasChain) {
+          let previous = "";
+          for (let index = 0; index < inputs.length; index += 1) {
+            const task = expandChainTask(inputs[index]!.task, previous, limits.taskCharacters);
+            if (task === undefined) {
+              failQueuedTask(index, "task_limit", `Expanded task exceeds ${limits.taskCharacters} characters`);
+              break;
+            }
+            await runAt(index, task);
+            if (results[index]!.status !== "complete") break;
+            previous = results[index]!.output;
+          }
+          settleQueued("chain_stopped");
+        } else if (hasParallel) {
+          try {
+            if (useSharedParallelPool) {
+              const indexes = inputs.map((_, index) => index);
+              await mapReadTasks(indexes, writerConcurrency, async (index) => runAt(index, inputs[index]!.task));
+            } else {
+              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");
           }
-          await runAt(index, task);
-          if (results[index]!.status !== "complete") break;
-          previous = results[index]!.output;
+        } else {
+          await runAt(0, inputs[0]!.task);
         }
-        settleQueued("chain_stopped");
-      } else if (hasParallel) {
+
+        const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
+        const currentResults = results.map(cloneResult);
+        const details: SubagentDetails = { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
+        return {
+          content: [{ type: "text" as const, text: buildToolContent(mode, details.results, limits.toolOutputBytes) }],
+          details,
+          usage: details.aggregateUsage,
+        };
+      };
+
+      emit(`${mode}: ${results.length} queued`);
+      if (options.awaitSpawnCompletion === true) {
+        const foregroundBatch = finishBatch();
+        backgroundBatches.add(foregroundBatch);
         try {
-          if (useSharedParallelPool) {
-            const indexes = inputs.map((_, index) => index);
-            await mapReadTasks(indexes, writerConcurrency, async (index) => runAt(index, inputs[index]!.task));
-          } else {
-            await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
-            for (const index of writerIndexes) await runAt(index, inputs[index]!.task);
-          }
+          return await foregroundBatch;
         } finally {
-          settleQueued("parallel_stopped");
+          backgroundBatches.delete(foregroundBatch);
         }
-      } else {
-        await runAt(0, inputs[0]!.task);
       }
 
-      const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
-      const currentResults = results.map(cloneResult);
-      const details: SubagentDetails = { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
+      const queuedBoard = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
+      const queuedResults = results.map(cloneResult);
+      const queuedDetails: SubagentDetails = {
+        ...queuedBoard,
+        executionNote,
+        results: queuedResults,
+        aggregateUsage: aggregateUsage(queuedResults),
+      };
+      const threadList = threadRecords.map((thread) => `${thread.id} (${thread.role})`).join(", ");
+      updatesOpen = false;
+      const backgroundBatch = finishBatch().then((completed) => {
+        if (threads.isDisposed || completed.details.results.some((result) => result.terminationReason === "abort")) return;
+        try {
+          pi.sendMessage({
+            customType: "killeros-subagent-settled",
+            content: `Subagent batch settled: ${threadList}\n\n${completed.content[0].text}`,
+            display: true,
+          }, { triggerTurn: true, deliverAs: "followUp" });
+        } catch {
+          // The completed handoff remains available through list, inspect, and collect.
+        }
+      }).catch((error) => {
+        if (threads.isDisposed) return;
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+          pi.sendMessage({
+            customType: "killeros-subagent-settled",
+            content: `Subagent batch failed: ${threadList}\n\n${message}`,
+            display: true,
+          }, { triggerTurn: true, deliverAs: "followUp" });
+        } catch {
+          // The thread registry retains any partial state for inspection.
+        }
+      });
+      backgroundBatches.add(backgroundBatch);
+      void backgroundBatch.finally(() => backgroundBatches.delete(backgroundBatch));
       return {
-        content: [{ type: "text", text: buildToolContent(mode, details.results, limits.toolOutputBytes) }],
-        details,
-        usage: details.aggregateUsage,
+        content: [{
+          type: "text",
+          text: boundedText(`Started child threads: ${threadList}. They continue in the background; use list, inspect, steer, interrupt, collect, or close while they run.`, limits.toolOutputBytes, "\n\n[Spawn output truncated.]"),
+        }],
+        details: queuedDetails,
+        usage: queuedDetails.aggregateUsage,
       };
     },
 
     renderCall(args, theme) {
-      const parsed = tryNormalizeSubagentRequest(args, limits);
+      let renderArgs = args;
+      try {
+        renderArgs = prepareSubagentRequest(args, limits).input;
+      } catch {
+        // Strict rendering below displays malformed requests as invalid.
+      }
+      const parsed = tryNormalizeSubagentRequest(renderArgs, limits);
       if (!parsed.ok) {
         return new Text(`${theme.fg("toolTitle", theme.bold("subagent"))}${theme.fg("error", " · invalid request")}`, 0, 0);
       }

package/package.json

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