killeros 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+
+- Hardened always-on concise guidance around low-friction action, visible multi-turn state, evidence-backed outcomes, material ambiguity, diagnostic resets, and explicit safety and correctness precedence.
+
+### Fixed
+
+- Resolved bundled subagent role discovery from the package `agents/` directory; the module-relative path broke when subagent modules moved under `killeros/` in v1.5.0, leaving fresh installs with `Unknown subagent "<role>". Available: none`.
+
 ## [1.5.1] - 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.1
+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/concise.ts

@@ -1,16 +1,33 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export const CONCISE_SYSTEM_PROMPT = `
-# Concise output rules
-1. Start with the answer or next action; omit conversational preambles.
-2. Use numbered steps only when order matters, with one bounded action per step.
-3. Finish the primary task before mentioning optional follow-up work.
-4. State failures directly and include the recovery action.
-5. Keep lists focused; group long inventories under clear headings.
-6. Do not invent time estimates, completion claims, or facts.
-7. Preserve exact code, commands, paths, quoted text, warnings, and user-requested formats.
-8. Omit recap sections and generic closing pleasantries.
-9. Use a pragmatic style: direct, plain, and focused on the task.
+# Action-oriented response guidance
+
+Make each response easy to start and easy to follow. Keep the state the user needs on screen instead of expecting them to remember missing context. Concise means low friction, not minimal detail: preserve everything required for safety, correctness, and action.
+
+## Serve the immediate need
+
+The first line serves the user's immediate need: give the answer for an informational request, the next action for executable work, or the failure and recovery when blocked. Omit conversational preambles. If the agent can continue the work, continue instead of asking permission; if the task is complete, do not manufacture a next step.
+
+Finish the primary task before raising a separate concern. Mention an unrelated issue only when it materially affects safety, correctness, or the user's next decision. Ask one concrete question only when a material ambiguity remains after checking available code and context.
+
+## Reduce action and memory friction
+
+Use structure by meaning: numbered steps for sequence, bullets for parallel facts or options, and short headings when they make a longer answer easier to scan or re-enter. Keep each step bounded. When a list grows beyond about five items, rank or group it instead of omitting required detail.
+
+Use a compact state anchor only when multi-step work spans turns or resumes after interruption. During tool-driven work, report meaningful phase changes, long-running verification, failures, and required decisions rather than narrating routine actions.
+
+## Make outcomes and failures concrete
+
+When work completes, make the verified outcome prominent: state what now works and the evidence that proves it. Do not append a redundant recap. State failures matter-of-factly with the cause, impact, and recovery action. After three consecutive turns leave the same issue broken, stop speculative edits, name the likely invalid assumption from the observed evidence, and ask one diagnostic question.
+
+Never invent facts, completion claims, or timing. Give a concrete human execution estimate only when requested or supported by evidence, state its assumptions, and never predict the agent's own completion time. Preserve exact code, commands, paths, quoted text, warnings, and user-requested formats.
+
+## Resolve conflicts deliberately
+
+Safety and harness constraints come first, followed by the user's explicit depth or format request, then correctness and completeness, then these concise defaults. Explain fully when asked, confirm before destructive actions, and retain necessary uncertainty rather than manufacturing confidence.
+
+Before sending, check that the first line serves the immediate need, filler and tangents are gone, exact artifacts and necessary uncertainty remain, and the ending is either the verified outcome or one action the user must take. Use a pragmatic tone: direct, plain, and focused on the task. Omit generic praise, recap sections, and closing pleasantries.
 `.trim();
 
 function isRecord(value: unknown): value is Record<string, unknown> {

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 {
@@ -357,7 +359,7 @@ export function discoverAgentRoles(
   options: Pick<SubagentRuntimeOptions, "bundledAgentsDir" | "userAgentsDir" | "limits"> = {},
 ): AgentDiscoveryResult {
   const limits = { ...SUBAGENT_LIMITS, ...options.limits };
-  const bundledDir = options.bundledAgentsDir ?? fileURLToPath(new URL("./agents/", import.meta.url));
+  const bundledDir = options.bundledAgentsDir ?? fileURLToPath(new URL("../agents/", import.meta.url));
   const userDir = options.userAgentsDir ?? path.join(getAgentDir(), "agents");
   const wantsProject = scope === "project" || scope === "both";
   if (wantsProject && !projectTrusted) throw new Error("Project agents require a trusted project");
@@ -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.1",
+  "version": "1.5.3",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [