killeros 1.4.7 → 1.4.9

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.7
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.9
 ```
 
 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}`. 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:
+The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles use one shared slot by default; set `writerConcurrency` above `1` only after proving path ownership in the shared worktree. Reader-only batches reject `writerConcurrency` because it does not apply. All children share the parent worktree, so concurrent writers must avoid file conflicts. 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 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.
+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.
 
 ### Thread lifecycle
 
@@ -111,9 +111,9 @@ Each delegated task creates a named child thread. Its contract records the paren
 
 Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `closed`. The parent renders separate **Active** and **Done** lists. Active threads show their name, task, model, usage, and direct controls. Done threads keep their handoff and trace available until the parent closes them.
 
-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.
+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. 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. Explicit user interruptions and real child-process failures remain visible. Esc cancellation 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. 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.
 
 The replacement lifecycle has nine phases:
 
@@ -124,8 +124,8 @@ The replacement lifecycle has nine phases:
 5. **Interrupt:** stop one or all active children while preserving partial work.
 6. **Collect:** return a concise handoff while retaining the expanded trace.
 7. **Guard:** honor only explicitly configured child resource guards; do not impose a routine turn stop.
-8. **Close:** remove a finished or stopped thread from the workspace without deleting its result record.
-9. **Prove:** test identity, visibility, controls, natural completion, guards, partial handoffs, and closure.
+8. **Close:** remove a finished or stopped thread from the workspace while retaining a small inspectable tombstone; heavy payloads may be evicted under the retention budget.
+9. **Prove:** test identity, visibility, controls, natural completion, guards, partial handoffs, bounded retention, and closure.
 
 ## Configuration
 
@@ -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.7`, publish after the validation checks pass:
+For release `1.4.9`, publish after the validation checks pass:
 
 ```bash
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [
@@ -46,11 +46,11 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "pi-web-access": "*",
-    "typebox": "*"
+    "@earendil-works/pi-ai": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@earendil-works/pi-tui": ">=0.82.1",
+    "pi-web-access": ">=0.17.1",
+    "typebox": ">=1.1.38 <2"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.82.1",

package/subagent-lifecycle.ts

@@ -97,6 +97,8 @@ export interface SubagentThread extends SubagentThreadSpec {
   result?: string;
   failure?: { message: string; code?: string };
   stopReason?: string;
+  /** True when close evicted the heavy trace, prompt, handoff, and result fields. */
+  evicted: boolean;
   timestamps: SubagentThreadTimestamps;
   version: number;
 }
@@ -192,6 +194,7 @@ function snapshot(thread: SubagentThread): SubagentThread {
     result: thread.result,
     failure: thread.failure ? { ...thread.failure } : undefined,
     stopReason: thread.stopReason,
+    evicted: thread.evicted,
     timestamps: { ...thread.timestamps },
     version: thread.version,
   };
@@ -287,6 +290,7 @@ export class SubagentThreadRegistry {
       usage: emptyUsage(),
       trace: [],
       steering: [],
+      evicted: false,
       timestamps: { createdAt: timestamp, updatedAt: timestamp },
       version: 1,
     };
@@ -413,7 +417,7 @@ export class SubagentThreadRegistry {
     return snapshot(thread);
   }
 
-  /** Closes a terminal record while retaining its result for inspection. */
+  /** Closes a terminal record and retains only a small tombstone for inspection. */
   close(id: SubagentThreadId): SubagentThread {
     this.assertOpen();
     const thread = this.requireThread(id);
@@ -421,10 +425,32 @@ export class SubagentThreadRegistry {
     if (!isTerminal(thread.state)) throw new Error(`Cannot close thread ${id} from ${thread.state}`);
     thread.state = "closed";
     thread.timestamps.closedAt = this.now();
+    thread.prompt = "[closed thread prompt evicted]";
+    thread.handoff = undefined;
+    thread.trace = [];
+    thread.steering = [];
+    thread.result = undefined;
+    thread.failure = thread.failure ? { message: thread.failure.message.slice(0, 512), code: thread.failure.code } : undefined;
+    thread.evicted = true;
     this.changed(thread, "close");
     return snapshot(thread);
   }
 
+  /** Remove the oldest closed tombstones and return bounded eviction notices. */
+  pruneClosed(maxRecords: number): SubagentThread[] {
+    this.assertOpen();
+    const closed = [...this.threads.values()]
+      .filter((thread) => thread.state === "closed")
+      .sort((left, right) => (left.timestamps.closedAt ?? left.timestamps.updatedAt) - (right.timestamps.closedAt ?? right.timestamps.updatedAt));
+    const removed: SubagentThread[] = [];
+    while (closed.length > Math.max(0, Math.floor(maxRecords))) {
+      const thread = closed.shift()!;
+      this.threads.delete(thread.id);
+      removed.push(snapshot(thread));
+    }
+    return removed;
+  }
+
   subscribe(listener: SubagentThreadListener): () => void {
     if (this.disposed) return () => {};
     this.listeners.add(listener);

package/subagent-process.ts

@@ -3,7 +3,10 @@ import { closeSync, mkdtempSync, openSync, readFileSync, rmSync, statSync, write
 import os from "node:os";
 import path from "node:path";
 
+export const MAX_NODE_TIMER_MS = 2_147_483_647;
+
 export const SUBAGENT_PROCESS_LIMITS = {
+  jsonlLineBytes: 8 * 1024 * 1024,
   killGraceMs: 5_000,
 } as const;
 
@@ -96,6 +99,10 @@ export interface SubagentProcessRetention {
 
 export interface SubagentProcessHandle {
   readonly pid: number | undefined;
+  /** True after the child close event, or when no child was spawned. */
+  readonly hasExited: boolean;
+  /** Resolves after the child close event, or when no child was spawned. */
+  readonly exited: Promise<void>;
   readonly result: Promise<SubagentProcessResult>;
   /** Stop this child and retain any work received before it exits. */
   stop(reason?: string): void;
@@ -215,7 +222,10 @@ function normalizeLimits(overrides: Partial<SubagentProcessLimits> | undefined):
   const limits = { ...SUBAGENT_PROCESS_LIMITS, ...overrides };
   for (const name of ["wallTimeMs", "jsonlLineBytes", "traceBytes", "stderrBytes", "outputBytes", "killGraceMs"] as const) {
     const value = limits[name];
-    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) throw new RangeError(`${name} must be a positive safe integer`);
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0 || value > MAX_NODE_TIMER_MS && (name === "wallTimeMs" || name === "killGraceMs"))) {
+      const bound = name === "wallTimeMs" || name === "killGraceMs" ? ` no greater than ${MAX_NODE_TIMER_MS}` : "";
+      throw new RangeError(`${name} must be a positive safe integer${bound}`);
+    }
   }
   for (const name of ["quotaTokens", "quotaUsd"] as const) {
     const value = limits[name];
@@ -324,6 +334,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
     durationMs: 0,
   };
   let child: SubagentProcessChild | undefined;
+  let processExited = false;
   let closed = false;
   let finishing = false;
   let requestedStatus: Exclude<SubagentProcessStatus, "running" | "complete"> | undefined;
@@ -338,7 +349,14 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let settleTimer: NodeJS.Timeout | undefined;
   let timeoutTimer: NodeJS.Timeout | undefined;
   let resolveResult!: (result: SubagentProcessResult) => void;
+  let resolveExited!: () => void;
   const result = new Promise<SubagentProcessResult>((resolve) => { resolveResult = resolve; });
+  const exited = new Promise<void>((resolve) => { resolveExited = resolve; });
+  const markExited = (): void => {
+    if (processExited) return;
+    processExited = true;
+    resolveExited();
+  };
 
   const clearStdoutLine = (): void => {
     if (stdoutLineSpoolDescriptor !== undefined) {
@@ -385,6 +403,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   const finish = (code: number | null): void => {
     if (closed || finishing) return;
     finishing = true;
+    if (!child || processExited) markExited();
     if (stdoutLineBytes && !requestedStatus) processLine(readStdoutLine());
     else clearStdoutLine();
     closed = true;
@@ -559,7 +578,10 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
         }
       });
       child.on("error", (error) => requestTermination("failed", "spawn_error", error.message));
-      child.once("close", finish);
+      child.once("close", (code) => {
+        markExited();
+        finish(code);
+      });
       if (limits.wallTimeMs !== undefined) timeoutTimer = setTimeout(() => requestTermination("limited", "wall_time_limit"), limits.wallTimeMs);
       options.signal?.addEventListener("abort", abortHandler, { once: true });
       if (options.signal?.aborted) abortHandler();
@@ -570,6 +592,8 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
 
   return {
     get pid() { return child?.pid; },
+    get hasExited() { return processExited; },
+    exited,
     result,
     stop(reason = "stopped") { requestTermination("cancelled", reason); },
     snapshot: () => cloneResult(state),