killeros 2.0.15 → 2.0.16

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.16] - 2026-08-23
+
+### Fixed
+
+- Kept `/handoff` input inside a cancellable TUI loader so buffered editor text cannot cross the session boundary.
+- Prevented a cancelled handoff from starting provider completion when authentication resolves late.
+- Made repository contract tests validate README facts without depending on discarded prose.
+
 ## [2.0.15] - 2026-08-23
 
 ### Added

package/README.md

@@ -1,127 +1,66 @@
 # KillerOS
 
-KillerOS is a TypeScript extension for the Pi coding agent. It adds a custom TUI, repository initialization, long-running goals, reasoning controls, interactive questions, lifecycle hooks, and a small set of command aliases.
+A TypeScript extension for the [Pi coding agent](https://github.com/earendil-works/pi) that replaces the stock TUI and adds long-running goals, reasoning controls, and workflow commands.
+
+## What you get
+
+- A custom TUI: startup card with version, model, provider, working directory, and Git branch; a dark theme with coral accents; a multiline editor with slash-command completion; a footer that tracks model, context, and goal state.
+- `/goal`: set an objective and Pi keeps working toward it across turns, compaction, reloads, and branch navigation. Pause, resume, edit, or clear it anytime.
+- `/init`: generates a root `AGENTS.md` from repository evidence, preserving compatible existing rules.
+- `/variants`: pick a reasoning level supported by the active model.
+- `/codex-fast`: toggles the `priority` service tier on Codex requests.
+- `/handoff`: starts a fresh linked session carrying visible continuation context.
+- Automatic context compaction when remaining tokens drop below 15% of the window (configurable).
+- A `question` tool with single-select and multi-select modes.
+- Lifecycle hooks (`tool_call`, `tool_result`, `agent_settled`) from `.pi/killeros-hooks.json`, plus `AGENTS.local.md` loading for trusted projects.
+- Optional completion sounds for settled requests.
+
 
 ## Requirements
 
-- Node.js `22.19.0` or later
-- Pi `0.84.2` or later
+- Node.js 22.19.0+
+- Pi 0.84.2+
 - An interactive TUI session for the custom header, editor, footer, `question`, and `/init`
 
-KillerOS ships as TypeScript. Pi supplies the runtime modules listed as peer dependencies.
-
 ## Install
 
-Install the current npm release:
-
 ```bash
 pi install npm:killeros
 ```
 
-Install from GitHub:
+Or from GitHub:
 
 ```bash
 pi install git:github.com/KyrosHendrix/pi-KillerOS
 ```
 
-Pin an install to version `v2.0.15`:
-
-```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.15
-```
-
-Add `-l` to either command to install only for the current project. Restart Pi after installing.
-
-## Features
-
-- A compact startup card with the extension version, model, provider, `/model`, working directory, Git branch, and a session-stable tip.
-- A dark theme with coral accents and neutral tool-call containers for pending, successful, and failed calls.
-- A 12-frame orange activity glyph with event-based status text and a quiet hidden-thinking label.
-- A multiline editor with a single focus-aware prompt arrow, a session-stable empty-state suggestion, overflow-only scroll indicators, Shift+Enter support, and slash-command completion.
-- A settled transcript line that reports `Done`, `Stopped`, or `Failed` with elapsed time, while preserving older `✻ Worked for ...` entries.
-- A responsive footer that keeps model, context, and goal state visible as the terminal gets narrower.
-- Automatic turn-boundary context compaction in TUI and RPC modes.
-- Optional completion sounds for successful and failed settled requests.
-- `/variants` for selecting a model reasoning level.
-- `/codex-fast` for toggling the `priority` service tier on Codex requests.
-- `/goal` for durable objectives with pause, resume, edit, clear, completion, continuation, and blocker audits.
-- `/init` for generating a root `AGENTS.md` from a bounded, safe set of repository files.
-- A `question` tool with single-select and opt-in multi-select controls.
-- Slash completion based on Pi's registered commands, extensions, prompts, and skills.
-- Goal-aware `/clear` and graceful `/exit` handling.
+Pin a version with `@v2.0.16`, add `-l` to install only for the current project. Restart Pi after installing.
 
 ## Commands
 
 ```text
 /init                     Generate root AGENTS.md from repository evidence
-/goal                     Open current goal status and valid actions
-/goal <objective>         Set an objective and start working
-/goal edit                Edit and reactivate the current goal
-/goal pause               Stop the current goal turn and automatic continuation
-/goal resume              Resume automatic continuation
-/goal clear               Stop current goal work and remove the goal
-/variants                 Open the reasoning-level selector
-/variants high            Set a reasoning level directly
-/codex-fast               Toggle process-local Codex fast mode
+/goal                     Open goal status, or set an objective with /goal <objective>
+/goal edit|pause|resume|clear
+/variants                 Reasoning-level selector (/variants high sets directly)
+/codex-fast               Toggle Codex fast mode
 /notification             Configure the completion sound
-/clear                    Start a new session after confirmation
-/handoff [focus]          Create a fresh session with visible continuation context
+/handoff [focus]          Fresh session with continuation context
+/clear                    New session after confirmation
 /exit                     Quit Pi gracefully
 ```
 
-### Codex fast mode
-
-`/codex-fast` takes no arguments. It toggles a process-local setting. When it is enabled and the active model uses the `openai-codex` provider, KillerOS adds `service_tier: "priority"` to the provider request. The footer shows bold `Fast` between the model and provider.
-
-The setting survives a session reload within the same process, does not change other providers, is not saved to KillerOS configuration, and starts disabled after Pi restarts. A provider failure leaves the setting enabled and follows Pi's normal error handling.
-
-### Goals
-
-`/goal` requires a saved session in TUI or RPC mode. Goal state is stored in versioned session entries on the active branch and restored after reload, resume, fork, and tree navigation.
-
-An active goal injects its unchanged objective on each turn and continues one settled turn at a time. The model must use KillerOS's private goal tool to report completion. If the objective explicitly asks for a named file-like deliverable at one quoted absolute path, KillerOS records that path and checks that a regular file exists before accepting completion. Other objectives use the model's completion report.
-
-KillerOS marks a goal blocked only after a stable lowercase blocker key recorded on three consecutive goal turns. A changed key, skipped turn, resume, or edit resets the streak. Final prose does not end the loop.
-
-Active goals replace the footer path with warning-yellow `/goal is active (...)` and keep the exact elapsed time visible.
-
-`/goal pause` and `/goal clear` save paused or cleared state before aborting current goal work, so settlement cannot restart it. Aborted turns, provider failures, and continuation failures pause safely. Failed edit and replacement writes dispatch no edited objective. Replacing unfinished work requires confirmation, and `/goal edit` works only in TUI mode.
-
-### Handoff
-
-`/handoff [focus]` requires a saved source session and is available only when Pi is idle, has no pending messages, and has no active `/goal`. It creates a fresh linked session with a visible handoff document that supplies context for the next turn. The source session stays unchanged, and handoff does not start an agent turn.
-
-### Repository initialization
-
-`/init` freezes a safe project-file map and exposes only dedicated read and list operations while it generates the root `AGENTS.md`. Git-ignored files, known secret paths, private-key formats, other guidance files, dependencies, links, non-regular files, and files outside the map are unavailable to the generation step.
-
-An existing root `AGENTS.md` is protected policy. Compatible rules are preserved. A real policy conflict leaves the file unchanged with a reason, and a concurrent target change aborts installation instead of replacing the newer file.
-
-The generated file uses four behavioral sections adapted from `writing-great-guidelines`. `/init` does not require another skill installation, ask setup questions, start a second model process, or write another file. Pi resources reload only after a successful write.
-
-### Interactive questions
-
-Single-select remains the default. Explicit `minSelections: 1` and `maxSelections: 1` are accepted; other single-select bounds are rejected. Use `mode: "multiple"` to opt into multi-select. The custom answer counts as one selection.
-
-In multi-select mode, use Space or a visible number to toggle an option, `/` to filter, and Enter to submit. The filter accepts spaces. Enter applies the filter and Escape returns to the choices. Checked options remain selected when the filter changes. Select `Type a custom answer` to add or edit one custom item alongside the checked options.
+## Behavior by mode
 
-Supported reasoning levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. KillerOS limits the selector to levels supported by the current model.
+| Mode | What works |
+| --- | --- |
+| TUI | Everything |
+| RPC | Goals, proactive compaction; no TUI components, `/goal edit`, `/init`, sounds, title indicator |
+| Print/JSON | No interactive questions, `/goal`, `/init`, or proactive compaction |
 
 ## Configuration
 
-KillerOS activates its packaged `killeros` theme when a TUI session starts. Tool-call backgrounds stay neutral in pending, successful, and failed states.
-
-The completion sound is a global user preference in Pi's agent directory and is off by default. Run `/notification` in TUI mode to change it. Enabled TUI tabs append `󰂚`, which requires a Nerd Font. KillerOS uses the terminal's audible bell, so a terminal that disables the bell cannot play the sound.
-
-### Automatic compaction
-
-Automatic compaction is enabled by default when Pi's effective `compaction.enabled` setting is true. After each completed assistant turn, including tool execution, KillerOS reads the active model's context usage and calls Pi's public compaction API when:
-
-```text
-remainingTokens <= max(contextWindow * percentRemaining / 100, reserveTokens)
-```
-
-The default `percentRemaining` is `15`. Pi owns `reserveTokens` and `keepRecentTokens`. KillerOS reads the effective settings through Pi's public `SettingsManager` with `getAgentDir()` and stores its own preference in the global `killeros.json` file:
+The packaged `killeros` theme activates on TUI start. Compaction triggers by default at 15% tokens remaining, stored in global `killeros.json`:
 
 ```json
 {
@@ -132,59 +71,21 @@ The default `percentRemaining` is `15`. Pi owns `reserveTokens` and `keepRecentT
 }
 ```
 
-Missing context readings skip the check. Successful ordinary-prompt compaction queues one hidden continuation. Active `/goal` runs use the existing session-compaction and goal-continuation path. Failed compaction does not retry automatically, and manual `/compact` behavior is unchanged.
-
-Pi writes the summary, applies manual focus instructions, tracks files, retries summarization, and handles overflow recovery. KillerOS only decides when to request proactive compaction.
-
-Manual `/compact` pauses the current goal turn before summarization. After Pi saves the summary, KillerOS resumes that goal revision automatically. A failed or cancelled manual compaction stays paused. Run `/goal pause` during the pause to cancel automatic recovery.
-
-### Project instructions and hooks
-
-For trusted projects, KillerOS loads `AGENTS.local.md` after Pi's shared repository context. A one-line `@path` or `@~/path` file imports personal guidance from another location.
+Completion sounds are off by default; change with `/notification` in TUI mode. The tab-title indicator requires a Nerd Font.
 
-Lifecycle hooks load from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`. Regular-expression matchers apply only to the first two events. KillerOS rejects a matcher on `agent_settled`.
+## Development
 
-Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. A failed `tool_call` hook blocks the tool. Failures for later events notify the user. If the parent request is aborted, KillerOS stops the hook process tree with bounded graceful and forced cleanup without reporting cancellation as a hook failure.
-
-## Behavior by mode
-
-| Mode | Behavior |
-| --- | --- |
-| TUI | All features are available, including proactive compaction, completion sounds, and the tab-title indicator. |
-| RPC | Proactive compaction and goal set/view/pause/resume/clear work. TUI components, `/goal edit`, `/init`, completion sounds, and the title indicator are disabled. |
-| Print/JSON | Interactive questions, `/goal`, `/init`, and proactive compaction are disabled. Completion sounds and the title indicator are disabled. |
-
-## Development and validation
-
-Source and tests use strict TypeScript. Tests run with Node's built-in test runner and type stripping.
-
-Before a release, run:
+Strict TypeScript throughout. Tests run on Node's built-in test runner:
 
 ```bash
-npm ci
-npm run check
-npm test
-npm pack --dry-run
-pi -ne -e . --mode rpc
+npm ci && npm run check && npm test
 ```
 
-The package manifest lists Pi's built-in modules as peer dependencies, so npm does not bundle another copy.
-
-## Releases
-
-For a normal release:
-
-1. Update the version in `package.json` and both matching version fields in `package-lock.json`.
-2. Add a dated section with the same version to `CHANGELOG.md`.
-3. Push the release commit to `main`.
-
-After the full CI workflow passes on `main`, the release workflow validates the commit and changelog, publishes the package to npm through trusted publishing, and creates the matching tag and GitHub release. The [`pi-package` keyword](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) makes the npm package visible in Pi's package catalog.
-
-Do not push version tags manually. Tag pushes cannot publish; every published commit must pass the full `main` CI workflow.
+Releases go through CI on `main`; do not push version tags manually.
 
 ## Security
 
-Pi extensions run with your user permissions. Review the source before installing KillerOS globally. KillerOS runs lifecycle hook commands only for projects Pi marks as trusted. Review `.pi/killeros-hooks.json` before enabling project trust.
+Pi extensions run with your user permissions. Review the source before installing globally. Hook commands run only for projects Pi marks as trusted; check `.pi/killeros-hooks.json` before enabling project trust.
 
 ## License
 

package/killeros/handoff.ts

@@ -1,5 +1,5 @@
 import { contentText } from "@earendil-works/pi-ai";
-import { convertToLlm, type ExtensionAPI, type ExtensionCommandContext, serializeConversation, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { BorderedLoader, convertToLlm, type ExtensionAPI, type ExtensionCommandContext, serializeConversation, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { GoalRuntime } from "./runtime.ts";
 import { safeTerminalText } from "./safe-terminal-text.ts";
 
@@ -25,6 +25,10 @@ const HANDOFF_SYSTEM_PROMPT = [
   "Keep active constraints and unfinished work even when the requested focus is narrower.",
   "Use exactly these second-level Markdown headings: Objective, Current state, Decisions, Constraints, Completed work, Relevant artifacts, Verification, Blockers or open questions, Exact next action, and Suggested skills.",
 ].join("\n");
+type HandoffGenerationResult =
+  | { kind: "summary"; summary: string }
+  | { kind: "cancelled" }
+  | { kind: "error"; error: unknown };
 
 /** Builds the one-off summary request from Pi's active context projection. */
 function createHandoffRequest(
@@ -83,6 +87,41 @@ function reportHandoffError(ctx: ExtensionCommandContext, error: unknown): void
   ctx.ui.notify(`Handoff failed: ${message}`, "error");
 }
 
+/** Generates and validates a handoff summary with optional cancellation. */
+async function generateHandoffSummary(
+  ctx: ExtensionCommandContext,
+  conversation: string,
+  focus: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  if (!ctx.model) throw new Error("No current model is available");
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+  signal?.throwIfAborted();
+  if (!auth.ok) throw new Error(auth.error);
+
+  const response = await ctx.modelRegistry.complete(ctx.model, {
+    systemPrompt: HANDOFF_SYSTEM_PROMPT,
+    messages: [{
+      role: "user",
+      content: createHandoffRequest(conversation, focus, ctx.getSystemPromptOptions().skills ?? []),
+      timestamp: Date.now(),
+    }],
+  }, {
+    apiKey: auth.apiKey,
+    headers: auth.headers,
+    env: auth.env,
+    maxTokens: 2_048,
+    signal,
+  });
+  if (response.stopReason === "error") throw new Error(response.errorMessage || "Handoff summary failed");
+  if (response.stopReason !== "stop") throw new Error("The handoff summary did not finish");
+
+  const summary = safeTerminalText(contentText(response.content)).trim();
+  if (!summary) throw new Error("The handoff summary was empty");
+  return summary;
+}
+
 /** Registers the idle-only command that summarizes context into a child session. */
 export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime): void {
   pi.registerCommand("handoff", {
@@ -106,31 +145,30 @@ export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime): voi
         const messages = ctx.sessionManager.buildContextEntries().flatMap(sessionEntryToContextMessages);
         const conversation = serializeConversation(convertToLlm(messages));
         if (!conversation.trim()) throw new Error("No usable session context is available");
-        if (!ctx.model) throw new Error("No current model is available");
-
-        const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
-        if (!auth.ok) throw new Error(auth.error);
-
         focus = safeTerminalText(args).trim();
-        const response = await ctx.modelRegistry.complete(ctx.model, {
-          systemPrompt: HANDOFF_SYSTEM_PROMPT,
-          messages: [{
-            role: "user",
-            content: createHandoffRequest(conversation, focus, ctx.getSystemPromptOptions().skills ?? []),
-            timestamp: Date.now(),
-          }],
-        }, {
-          apiKey: auth.apiKey,
-          headers: auth.headers,
-          env: auth.env,
-          maxTokens: 2_048,
-        });
-        if (response.stopReason === "error") throw new Error(response.errorMessage || "Handoff summary failed");
-        if (response.stopReason !== "stop") throw new Error("The handoff summary did not finish");
-        const summary = safeTerminalText(contentText(response.content)).trim();
-        if (!summary) throw new Error("The handoff summary was empty");
+        const generation = ctx.mode === "tui"
+          ? await ctx.ui.custom<HandoffGenerationResult>((tui, theme, _keybindings, done) => {
+            const loader = new BorderedLoader(tui, theme, "Generating handoff...");
+            let settled = false;
+            const finish = (result: HandoffGenerationResult): void => {
+              if (settled) return;
+              settled = true;
+              done(result);
+            };
+            loader.onAbort = () => finish({ kind: "cancelled" });
+            generateHandoffSummary(ctx, conversation, focus, loader.signal)
+              .then((summary) => finish({ kind: "summary", summary }))
+              .catch((error: unknown) => finish({ kind: "error", error }));
+            return loader;
+          })
+          : { kind: "summary", summary: await generateHandoffSummary(ctx, conversation, focus) } as const;
+        if (generation.kind === "cancelled") {
+          ctx.ui.notify("Handoff cancelled", "info");
+          return;
+        }
+        if (generation.kind === "error") throw generation.error;
 
-        document = handoffDocument(summary);
+        document = handoffDocument(generation.summary);
         if (!hasRequiredHandoffContent(document, focus)) {
           throw new Error("The handoff summary did not contain every required section");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "description": "TUI, goals, and workflow automation for the Pi coding agent",
   "type": "module",
   "keywords": [