killeros 2.0.15 → 2.0.17

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.17] - 2026-08-23
+
+### Added
+
+- Added per-task token usage to settled TUI receipts for ordinary requests and individual goal turns.
+
+### Changed
+
+- Limited push CI to `main` and `dev`; feature branches run through pull request CI without duplicate push runs.
+- Removed obsolete Pi tool API casts, shared caught-error formatting, and expanded the non-repeating startup tip and editor suggestion banks.
+- Clarified that the README's pinned Git tag is an example rather than the current package version.
+
+### Fixed
+
+- Limited retired-feature repository checks to tracked and non-ignored files so ignored private notes cannot fail the suite.
+
+## [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/Killeros.ts

@@ -48,10 +48,10 @@ export default function Killeros(pi: ExtensionAPI, options: KillerosOptions = {}
   registerCodexFastMode(pi);
   registerInitCommand(pi, initRuntime, goalRuntime);
   registerLifecycleHooks(pi);
+  registerWorkedFor(pi);
   const goalCompaction = registerGoalSettlement(pi, goalRuntime, initRuntime);
   registerAutoCompaction(pi, { goal: goalCompaction });
   registerInitSettlement(pi, initRuntime);
   registerRequestActivity(pi);
   registerCompletionNotifications(pi, options.completionNotifications);
-  registerWorkedFor(pi);
 }

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; settled task receipts with duration and token usage.
+- `/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 release by appending its tag, for example `@v2.0.17`. 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/auto-compaction.ts

@@ -6,6 +6,7 @@ import {
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { errorMessage } from "./errors.ts";
 import { createKillerosSettingsStore } from "./settings.ts";
 
 export const DEFAULT_AUTO_COMPACTION_PERCENT_REMAINING = 15;
@@ -71,6 +72,7 @@ function reserveTokens(settings: Pick<CompactionSettings, "reserveTokens">): num
     : 0;
 }
 
+/** Triggers at the stricter of the user's percentage and Pi's token reserve. */
 export function shouldTriggerAutoCompaction(
   usage: Pick<ContextUsage, "tokens" | "contextWindow"> | undefined,
   preference: AutoCompactionPreference,
@@ -90,10 +92,6 @@ export function shouldTriggerAutoCompaction(
   return remainingTokens <= threshold;
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function supportedMode(ctx: ExtensionContext): boolean {
   return ctx.mode === "tui" || ctx.mode === "rpc";
 }

package/killeros/errors.ts

@@ -1,6 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+/** Converts unknown caught values into text suitable for user-facing errors. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export function reportError(ctx: ExtensionContext, area: string, error: unknown): void {
-  const message = error instanceof Error ? error.message : String(error);
-  ctx.ui.notify(`${area}: ${message}`, "error");
+  ctx.ui.notify(`${area}: ${errorMessage(error)}`, "error");
 }

package/killeros/goals.ts

@@ -5,7 +5,6 @@ import path from "node:path";
 import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { MAX_NODE_TIMER_MS } from "./limits.ts";
 import { BoundedText } from "./bounded-text.ts";
 import { formatTime, formatTokens } from "./display.ts";
 import { reportError } from "./errors.ts";
@@ -131,6 +130,7 @@ function captureGoalFileBaseline(filePath: string): GoalFileBaseline {
   }
 }
 
+/** Captures one explicit absolute output path so goal completion can verify its creation or modification. */
 function inferGoalVerification(objective: string): GoalFileVerification | undefined {
   const destination = /\b(?:create|write|save|generate)\b[^\r\n]{0,160}?\b(?:file|document|markdown|report|spreadsheet|presentation|image)\b\s+(?:to|at|as|destination(?:\s+is)?|output(?:\s+(?:to|at))?)\b\s*(?:`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'|([A-Za-z]:\\[^\s,;]+|\/[^\s,;]+))/giu;
   const paths = [...objective.matchAll(destination)]
@@ -283,12 +283,10 @@ function sumGoalTokens(ctx: ExtensionContext): number {
 }
 
 function setGoalUpdateToolActive(pi: ExtensionAPI, active: boolean): void {
-  const api = pi as ExtensionAPI & { getActiveTools?: () => string[]; setActiveTools?: (names: string[]) => void };
-  if (!api.getActiveTools || !api.setActiveTools) return;
-  const activeTools = api.getActiveTools();
+  const activeTools = pi.getActiveTools();
   const isActive = activeTools.includes(GOAL_UPDATE_TOOL);
   if (active === isActive) return;
-  api.setActiveTools(active
+  pi.setActiveTools(active
     ? [...activeTools, GOAL_UPDATE_TOOL]
     : activeTools.filter((name) => name !== GOAL_UPDATE_TOOL));
 }
@@ -495,6 +493,7 @@ function beginGoalTurn(
   return next;
 }
 
+/** Starts one goal turn only after Pi is idle and all competing workflow gates are clear. */
 function scheduleGoalContinuation(
   pi: ExtensionAPI,
   runtime: GoalRuntime,

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/killeros/init-target.ts

@@ -146,6 +146,7 @@ async function pathExists(filePath: string): Promise<boolean> {
   }
 }
 
+/** Installs generated guidance atomically and preserves any target changed after baseline capture. */
 export async function installInitAgentsFile(
   targetPath: string,
   content: string,

package/killeros/init.ts

@@ -47,16 +47,14 @@ After a successful write, read generated AGENTS.md once through killeros_init_re
 `.trim();
 
 function setInitTools(pi: ExtensionAPI, initState: InitRuntime, active: boolean): void {
-  const runtime = pi as ExtensionAPI & { getActiveTools?: () => string[]; setActiveTools?: (names: string[]) => void };
-  if (!runtime.getActiveTools || !runtime.setActiveTools) return;
   if (active) {
-    initState.activeTools ??= runtime.getActiveTools().filter((name) => !INIT_SCOPED_TOOLS.includes(name as (typeof INIT_SCOPED_TOOLS)[number]));
-    runtime.setActiveTools([...INIT_SCOPED_TOOLS]);
+    initState.activeTools ??= pi.getActiveTools().filter((name) => !INIT_SCOPED_TOOLS.includes(name as (typeof INIT_SCOPED_TOOLS)[number]));
+    pi.setActiveTools([...INIT_SCOPED_TOOLS]);
   } else if (initState.activeTools) {
-    runtime.setActiveTools(initState.activeTools);
+    pi.setActiveTools(initState.activeTools);
     initState.activeTools = undefined;
   } else {
-    runtime.setActiveTools(runtime.getActiveTools().filter((name) => !INIT_SCOPED_TOOLS.includes(name as (typeof INIT_SCOPED_TOOLS)[number])));
+    pi.setActiveTools(pi.getActiveTools().filter((name) => !INIT_SCOPED_TOOLS.includes(name as (typeof INIT_SCOPED_TOOLS)[number])));
   }
 }
 

package/killeros/notifications.ts

@@ -4,6 +4,7 @@ import {
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { errorMessage } from "./errors.ts";
 import { createKillerosSettingsStore } from "./settings.ts";
 
 export interface NotificationPreferenceStore {
@@ -40,10 +41,6 @@ export function formatNotificationTitle(
   return enabled ? `${base} ${COMPLETION_BELL_GLYPH}` : base;
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function registerCompletionNotifications(
   pi: ExtensionAPI,
   dependencies?: CompletionNotificationDependencies,

package/killeros/shell-ui.ts

@@ -45,6 +45,12 @@ const STARTUP_TIPS = [
   "Run /variants to tune the model's reasoning depth.",
   "Type / to browse every command available in this session.",
   "Run /notification to enable a terminal bell when work settles.",
+  "Run /goal <objective> to keep long-running work moving across turns.",
+  "Run /init to generate root AGENTS.md from bounded repository evidence.",
+  "Run /handoff [focus] to continue work in a fresh linked session.",
+  "Run /codex-fast to toggle priority requests for Codex models.",
+  "Run /clear to start a fresh session after confirmation.",
+  "Ask the agent to show a short choice list when you need to decide.",
 ] as const;
 
 const EDITOR_SUGGESTIONS = [
@@ -52,6 +58,12 @@ const EDITOR_SUGGESTIONS = [
   'Try "find edge cases in <filepath>"',
   'Try "simplify <filepath> without changing behavior"',
   'Try "write tests for <filepath>"',
+  'Try "trace this failure to its first bad state"',
+  'Try "review this diff against <spec>"',
+  'Try "explain why this test fails"',
+  'Try "find the smallest safe fix for <issue>"',
+  'Try "map the data flow through <feature>"',
+  'Try "draft an implementation plan for <feature>"',
 ] as const;
 
 export function resolveGitBranch(cwd: string): Promise<string | undefined> {
@@ -216,6 +228,7 @@ function extractTerminalSequence(text: string, position: number): { code: string
   return undefined;
 }
 
+/** Styles valid slash-command tokens while preserving embedded terminal control sequences. */
 export function highlightSlashCommands(
   line: string,
   isValidCommand: (name: string) => boolean,

package/killeros/worked-for.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { StopReason } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
+import { formatTokens } from "./display.ts";
+import { errorMessage } from "./errors.ts";
 
 const WORKED_FOR_ENTRY_TYPE = "killeros-worked-for";
 
@@ -17,7 +19,14 @@ interface WorkedForEntryDataV2 {
   outcome: WorkedForOutcome;
 }
 
-type WorkedForEntryData = WorkedForEntryDataV1 | WorkedForEntryDataV2;
+interface WorkedForEntryDataV3 {
+  version: 3;
+  milliseconds: number;
+  outcome: WorkedForOutcome;
+  tokens: number;
+}
+
+type WorkedForEntryData = WorkedForEntryDataV1 | WorkedForEntryDataV2 | WorkedForEntryDataV3;
 
 const OUTCOMES = {
   done: { marker: "✓", label: "Done", color: "success" },
@@ -29,6 +38,23 @@ function isWorkedForOutcome(value: unknown): value is WorkedForOutcome {
   return value === "done" || value === "stopped" || value === "failed";
 }
 
+function sessionTokenTotal(ctx: ExtensionContext): number | undefined {
+  try {
+    let total = 0;
+    for (const entry of ctx.sessionManager.getEntries()) {
+      const tokens = entry.type === "message" && (entry.message.role === "assistant" || entry.message.role === "toolResult")
+        ? entry.message.usage?.totalTokens
+        : (entry.type === "compaction" || entry.type === "branch_summary")
+          ? entry.usage?.totalTokens
+          : undefined;
+      if (typeof tokens === "number" && Number.isFinite(tokens) && tokens > 0) total += tokens;
+    }
+    return total;
+  } catch {
+    return undefined;
+  }
+}
+
 export function formatWorkedForDuration(milliseconds: number): string {
   const boundedMilliseconds = Number.isFinite(milliseconds) ? Math.max(0, milliseconds) : 0;
   const totalSeconds = Math.max(1, Math.floor(boundedMilliseconds / 1_000));
@@ -49,10 +75,11 @@ function parseWorkedForEntryData(data: unknown): WorkedForEntryData | undefined
     return undefined;
   }
   if (data.version === 1) return { version: 1, milliseconds: data.milliseconds };
-  if (data.version !== 2 || !("outcome" in data) || !isWorkedForOutcome(data.outcome)) {
-    return undefined;
-  }
-  return { version: 2, milliseconds: data.milliseconds, outcome: data.outcome };
+  if (!("outcome" in data) || !isWorkedForOutcome(data.outcome)) return undefined;
+  if (data.version === 2) return { version: 2, milliseconds: data.milliseconds, outcome: data.outcome };
+  if (data.version !== 3 || !("tokens" in data)
+    || typeof data.tokens !== "number" || !Number.isFinite(data.tokens) || data.tokens < 0) return undefined;
+  return { version: 3, milliseconds: data.milliseconds, outcome: data.outcome, tokens: data.tokens };
 }
 
 export function workedForOutcome(stopReason: StopReason | undefined): WorkedForOutcome {
@@ -61,15 +88,12 @@ export function workedForOutcome(stopReason: StopReason | undefined): WorkedForO
   return "failed";
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function registerWorkedFor(
   pi: ExtensionAPI,
   now: () => number = Date.now,
 ): void {
   let startedAt: number | undefined;
+  let startedTokens: number | undefined;
   let stopReason: StopReason | undefined;
 
   pi.registerEntryRenderer<WorkedForEntryData>(WORKED_FOR_ENTRY_TYPE, (entry, _options, theme) => {
@@ -83,8 +107,9 @@ export function registerWorkedFor(
       );
     }
     const outcome = OUTCOMES[data.outcome];
+    const tokens = data.version === 3 ? ` · ↑ ${formatTokens(data.tokens)} tokens` : "";
     return new Text(
-      `${theme.fg(outcome.color, `${outcome.marker} ${outcome.label}`)}${theme.fg("dim", ` · ${formatWorkedForDuration(data.milliseconds)}`)}`,
+      `${theme.fg(outcome.color, `${outcome.marker} ${outcome.label}`)}${theme.fg("dim", ` · ${formatWorkedForDuration(data.milliseconds)}${tokens}`)}`,
       0,
       0,
     );
@@ -92,12 +117,14 @@ export function registerWorkedFor(
 
   pi.on("session_start", () => {
     startedAt = undefined;
+    startedTokens = undefined;
     stopReason = undefined;
   });
 
   pi.on("agent_start", (_event, ctx) => {
     if (ctx.mode !== "tui" || startedAt !== undefined) return;
     startedAt = now();
+    startedTokens = sessionTokenTotal(ctx);
   });
 
   pi.on("agent_end", (event, ctx) => {
@@ -112,16 +139,21 @@ export function registerWorkedFor(
 
   pi.on("agent_settled", (_event, ctx) => {
     if (ctx.mode !== "tui" || startedAt === undefined) return;
-    if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
     const milliseconds = Math.max(0, now() - startedAt);
+    const settledTokens = sessionTokenTotal(ctx);
+    const tokens = startedTokens === undefined || settledTokens === undefined
+      ? 0
+      : Math.max(0, settledTokens - startedTokens);
     const outcome = workedForOutcome(stopReason);
     startedAt = undefined;
+    startedTokens = undefined;
     stopReason = undefined;
     try {
-      pi.appendEntry<WorkedForEntryDataV2>(WORKED_FOR_ENTRY_TYPE, {
-        version: 2,
+      pi.appendEntry<WorkedForEntryDataV3>(WORKED_FOR_ENTRY_TYPE, {
+        version: 3,
         milliseconds,
         outcome,
+        tokens,
       });
     } catch (error) {
       ctx.ui.notify(`Worked-for timing could not be saved: ${errorMessage(error)}`, "error");
@@ -130,6 +162,7 @@ export function registerWorkedFor(
 
   pi.on("session_shutdown", () => {
     startedAt = undefined;
+    startedTokens = undefined;
     stopReason = undefined;
   });
 }

package/package.json

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

package/killeros/limits.ts

@@ -1 +0,0 @@
-export const MAX_NODE_TIMER_MS = 2_147_483_647;