killeros 2.0.19 → 2.0.20

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.20] - 2026-08-25
+
+### Changed
+
+- Added a typescript-eslint type-checked lint gate (`npm run lint`) alongside `tsc --noEmit`, and cleaned up the dead imports and untyped boundaries it surfaced.
+
+### Fixed
+
+- Treated Pi's exact `Nothing to compact (session too small)` rejection as an expected automatic-compaction skip: no failure notification, silent retry on the next eligible turn, and active goals resume through a dedicated skip recovery instead of pausing for `/goal resume`.
+- Made `/handoff` resilient to an unreadable `killeros.json`: explicit `KillerosOptions` budgets bypass the file, while other summaries fall back to the default budget with a visible warning.
+- Named `/handoff` output truncation instead of reporting "did not finish", raised the default summary budget to 8192 tokens for reasoning models, and made the budget configurable through `KillerosOptions` or the `killeros.json` `handoffMaxTokens` key.
+
 ## [2.0.19] - 2026-08-24
 
 ### Changed

package/Killeros.ts

@@ -30,6 +30,8 @@ export { buildInitEvidence, listInitEvidence, readInitEvidence } from "./killero
 export { captureInitTargetBaseline, installInitAgentsFile, validateGeneratedGuidance, writeInitAgentsFile } from "./killeros/init-target.ts";
 export interface KillerosOptions {
   completionNotifications?: CompletionNotificationDependencies;
+  /** Output-token budget for /handoff summaries; invalid values fall back to killeros.json, then the default. */
+  handoffMaxTokens?: number;
 }
 
 export default function Killeros(pi: ExtensionAPI, options: KillerosOptions = {}): void {
@@ -41,7 +43,7 @@ export default function Killeros(pi: ExtensionAPI, options: KillerosOptions = {}
   registerPersonalInstructions(pi, initRuntime);
   registerQuestionTool(pi);
   registerAliases(pi);
-  registerHandoff(pi, goalRuntime);
+  registerHandoff(pi, goalRuntime, options.handoffMaxTokens);
   registerSlashAutocomplete(pi, commandResolver);
   registerFooter(pi, goalRuntime);
   registerVariants(pi);

package/README.md

@@ -34,7 +34,7 @@ Or from GitHub:
 pi install git:github.com/KyrosHendrix/pi-KillerOS
 ```
 
-Pin a release by appending its tag, for example `@v2.0.19`. Add `-l` to install only for the current project. Restart Pi after installing.
+Pin a release by appending its tag, for example `@v2.0.20`. Add `-l` to install only for the current project. Restart Pi after installing.
 
 ## Commands
 
@@ -67,10 +67,13 @@ The packaged `killeros` theme activates on TUI start. Compaction triggers by def
   "autoCompaction": {
     "enabled": true,
     "percentRemaining": 15
-  }
+  },
+  "handoffMaxTokens": 8192
 }
 ```
 
+`handoffMaxTokens` caps the `/handoff` summary output at 8192 tokens by default; raise it when long sessions truncate the summary.
+
 Completion sounds are off by default; change with `/notification` in TUI mode. The tab-title indicator requires a Nerd Font.
 
 ## Development

package/killeros/auto-compaction.ts

@@ -12,6 +12,8 @@ import { createKillerosSettingsStore } from "./settings.ts";
 export const DEFAULT_AUTO_COMPACTION_PERCENT_REMAINING = 15;
 export const AUTO_COMPACTION_MESSAGE_TYPE = "killeros-auto-compaction";
 export const AUTO_COMPACTION_MESSAGE = "Continue the interrupted task from the compacted context.";
+/** Pi's exact rejection when a session has no eligible history to summarize; an expected skip, not a failure. */
+export const SESSION_TOO_SMALL_COMPACTION_ERROR = "Nothing to compact (session too small)";
 
 export interface AutoCompactionPreference {
   enabled: boolean;
@@ -23,6 +25,8 @@ export interface AutoCompactionGoalHandlers {
   onRequested(): void;
   onCompleted(ctx: ExtensionContext): void;
   onFailed(ctx: ExtensionContext, error: unknown): void;
+  /** Recovers the goal paused for a request Pi rejected as session-too-small, without claiming success. */
+  onSkipped(ctx: ExtensionContext): void;
 }
 
 export interface AutoCompactionDependencies {
@@ -72,6 +76,11 @@ function reserveTokens(settings: Pick<CompactionSettings, "reserveTokens">): num
     : 0;
 }
 
+/** Matches only Pi's exact rejection text on a real Error; near-matches and stringified values stay failures. */
+export function isSessionTooSmallCompactionError(error: unknown): boolean {
+  return error instanceof Error && error.message === SESSION_TOO_SMALL_COMPACTION_ERROR;
+}
+
 /** Triggers at the stricter of the user's percentage and Pi's token reserve. */
 export function shouldTriggerAutoCompaction(
   usage: Pick<ContextUsage, "tokens" | "contextWindow"> | undefined,
@@ -116,13 +125,7 @@ export function registerAutoCompaction(
     ctx.ui.notify(`Automatic compaction failed: ${errorMessage(error)}`, "error");
   };
 
-  const finishFailure = (
-    ctx: ExtensionContext,
-    token: symbol,
-    goal: boolean,
-    error: unknown,
-  ): void => {
-    if (!request || request.token !== token) return;
+  const finishFailure = (ctx: ExtensionContext, goal: boolean, error: unknown): void => {
     request = undefined;
     if (goal && dependencies.goal) {
       try {
@@ -135,6 +138,33 @@ export function registerAutoCompaction(
     notifyFailure(ctx, error);
   };
 
+  /** Ends a request with Pi's expected eligibility rejection: silent, rearmed, and never a failure. */
+  const finishSkip = (ctx: ExtensionContext, goal: boolean): void => {
+    request = undefined;
+    armed = true;
+    if (!goal) return;
+    try {
+      dependencies.goal?.onSkipped(ctx);
+    } catch (callbackError) {
+      notifyFailure(ctx, callbackError);
+    }
+  };
+
+  /** Single entry point for rejected requests: classifies before any sanitization, stale tokens stay inert. */
+  const finishRequestError = (
+    ctx: ExtensionContext,
+    token: symbol,
+    goal: boolean,
+    error: unknown,
+  ): void => {
+    if (!request || request.token !== token) return;
+    if (isSessionTooSmallCompactionError(error)) {
+      finishSkip(ctx, goal);
+      return;
+    }
+    finishFailure(ctx, goal, error);
+  };
+
   pi.on("turn_end", (_event, ctx) => {
     if (!supportedMode(ctx) || request) return;
 
@@ -179,7 +209,7 @@ export function registerAutoCompaction(
       try {
         dependencies.goal.onRequested();
       } catch (error) {
-        finishFailure(ctx, token, true, error);
+        finishFailure(ctx, true, error);
         return;
       }
     }
@@ -207,10 +237,10 @@ export function registerAutoCompaction(
             notifyFailure(ctx, error);
           }
         },
-        onError: (error) => finishFailure(ctx, token, goal, error),
+        onError: (error) => finishRequestError(ctx, token, goal, error),
       });
     } catch (error) {
-      finishFailure(ctx, token, goal, error);
+      finishRequestError(ctx, token, goal, error);
     }
   });
 

package/killeros/footer.ts

@@ -1,5 +1,5 @@
-import { DynamicBorder, type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
-import { Container, Text, truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
+import { type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
 import { isCodexFastEnabled, subscribeCodexFast } from "./codex-fast-state.ts";
 import { formatCwd, formatTime, formatTokens, padRight } from "./display.ts";
 import { goalElapsedMilliseconds } from "./goals.ts";

package/killeros/goals.ts

@@ -624,7 +624,7 @@ function scheduleGoalContinuation(
   }
 }
 
-/** Resumes the revision paused by automatic compaction after both host callbacks settle. */
+/** Resumes the revision paused by automatic compaction once both host callbacks settle and Pi reports an outcome. */
 function finalizeAutomaticCompaction(
   pi: ExtensionAPI,
   runtime: GoalRuntime,
@@ -632,7 +632,8 @@ function finalizeAutomaticCompaction(
   ctx: ExtensionContext,
 ): void {
   const recovery = runtime.automaticCompaction;
-  if (!recovery?.compactionSucceeded || !recovery.turnSettled) return;
+  if (!recovery || recovery.outcome === "pending" || !recovery.turnSettled) return;
+  const skipped = recovery.outcome === "skipped";
   runtime.automaticCompaction = undefined;
   if (runtime.state?.status !== "paused"
     || runtime.state.revision !== recovery.pausedRevision
@@ -641,7 +642,9 @@ function finalizeAutomaticCompaction(
     transitionGoal(pi, runtime, "resume", "active", undefined, { resetBlockedAudit: true });
   } catch (error) {
     runtime.persistenceRetryNeeded = true;
-    reportError(ctx, "Automatic compaction succeeded, but the goal could not be resumed", error);
+    reportError(ctx, skipped
+      ? "Automatic compaction was skipped, but the goal could not be resumed"
+      : "Automatic compaction succeeded, but the goal could not be resumed", error);
     return;
   }
   runtime.continuationScheduled = false;
@@ -656,7 +659,19 @@ function completeAutomaticCompaction(
   ctx: ExtensionContext,
 ): void {
   if (!runtime.automaticCompaction) return;
-  runtime.automaticCompaction.compactionSucceeded = true;
+  runtime.automaticCompaction.outcome = "completed";
+  finalizeAutomaticCompaction(pi, runtime, initState, ctx);
+}
+
+/** Records Pi's expected session-too-small rejection and resumes without claiming compaction succeeded. */
+function skipAutomaticCompaction(
+  pi: ExtensionAPI,
+  runtime: GoalRuntime,
+  initState: InitRuntime,
+  ctx: ExtensionContext,
+): void {
+  if (!runtime.automaticCompaction) return;
+  runtime.automaticCompaction.outcome = "skipped";
   finalizeAutomaticCompaction(pi, runtime, initState, ctx);
 }
 
@@ -1247,6 +1262,7 @@ export function registerGoalSettlement(
   onRequested(): void;
   onCompleted(ctx: ExtensionContext): void;
   onFailed(ctx: ExtensionContext, error: unknown): void;
+  onSkipped(ctx: ExtensionContext): void;
 } {
   pi.on("agent_settled", (_event, ctx) => {
     const wasGoalTurn = runtime.goalTurnInFlight;
@@ -1333,7 +1349,7 @@ export function registerGoalSettlement(
         const paused = transitionGoal(pi, runtime, "pause", "paused");
         runtime.automaticCompaction = {
           pausedRevision: paused.revision,
-          compactionSucceeded: false,
+          outcome: "pending",
           turnSettled: false,
         };
       } catch (error) {
@@ -1355,5 +1371,6 @@ export function registerGoalSettlement(
     },
     onCompleted: (ctx: ExtensionContext): void => completeAutomaticCompaction(pi, runtime, initState, ctx),
     onFailed: (ctx: ExtensionContext, error: unknown): void => failAutomaticCompaction(pi, runtime, ctx, error),
+    onSkipped: (ctx: ExtensionContext): void => skipAutomaticCompaction(pi, runtime, initState, ctx),
   };
 }

package/killeros/handoff.ts

@@ -1,10 +1,13 @@
 import { contentText } from "@earendil-works/pi-ai";
 import { BorderedLoader, convertToLlm, type ExtensionAPI, type ExtensionCommandContext, serializeConversation, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { reportError } from "./errors.ts";
+import { errorMessage, reportError } from "./errors.ts";
 import type { GoalRuntime } from "./runtime.ts";
+import { createKillerosSettingsStore, type KillerosSettings } from "./settings.ts";
 import { safeTerminalText } from "./safe-terminal-text.ts";
 
 const HANDOFF_UNAVAILABLE = "/handoff is not available while an agent or /goal is running.";
+/** Output-token budget with headroom for reasoning traces plus all ten sections. */
+export const DEFAULT_HANDOFF_MAX_TOKENS = 8_192;
 const HANDOFF_SECTIONS = [
   "Objective",
   "Current state",
@@ -69,6 +72,20 @@ function sessionName(sourceName: string | undefined, focus: string, document: st
   return `${shortBase || "Handoff"} · handoff`;
 }
 
+/** Accepts only positive integers. */
+function isPositiveInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function positiveIntOr(value: unknown, fallback: number): number {
+  return isPositiveInt(value) ? value : fallback;
+}
+
+/** Resolves the summary budget: explicit option first, then killeros.json, then the default. */
+export function resolveHandoffMaxTokens(settings: Readonly<KillerosSettings>, override?: number): number {
+  return positiveIntOr(override, positiveIntOr(settings.handoffMaxTokens, DEFAULT_HANDOFF_MAX_TOKENS));
+}
+
 /** Checks that the model returned every section needed to continue safely. */
 function hasRequiredHandoffContent(document: string, focus: string): boolean {
   if (focus && !document.includes(focus)) return false;
@@ -82,16 +99,16 @@ function hasRequiredHandoffContent(document: string, focus: string): boolean {
   });
 }
 
-/** Generates and validates a handoff summary with optional cancellation. */
-async function generateHandoffSummary(
+/** Generates a handoff summary; throws named errors for truncation and provider failures. */
+export async function generateHandoffSummary(
   ctx: ExtensionCommandContext,
   conversation: string,
   focus: string,
-  signal?: AbortSignal,
+  options: { maxTokens: number; signal?: AbortSignal },
 ): Promise<string> {
   if (!ctx.model) throw new Error("No current model is available");
 
-  signal?.throwIfAborted();
+  options.signal?.throwIfAborted();
 
   const response = await ctx.modelRegistry.complete(ctx.model, {
     systemPrompt: HANDOFF_SYSTEM_PROMPT,
@@ -101,10 +118,13 @@ async function generateHandoffSummary(
       timestamp: Date.now(),
     }],
   }, {
-    maxTokens: 2_048,
-    signal,
+    maxTokens: options.maxTokens,
+    signal: options.signal,
   });
   if (response.stopReason === "error") throw new Error(response.errorMessage || "Handoff summary failed");
+  if (response.stopReason === "length") {
+    throw new Error(`The handoff summary exceeded its ${options.maxTokens}-token output budget. Shorten the source session or raise the handoff token budget.`);
+  }
   if (response.stopReason !== "stop") throw new Error("The handoff summary did not finish");
 
   const summary = safeTerminalText(contentText(response.content)).trim();
@@ -113,7 +133,7 @@ async function generateHandoffSummary(
 }
 
 /** Registers the idle-only command that summarizes context into a child session. */
-export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime): void {
+export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime, handoffMaxTokens?: number): void {
   pi.registerCommand("handoff", {
     description: "Create a fresh session with a continuation handoff",
     handler: async (args, ctx) => {
@@ -136,6 +156,16 @@ export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime): voi
         const conversation = serializeConversation(convertToLlm(messages));
         if (!conversation.trim()) throw new Error("No usable session context is available");
         focus = safeTerminalText(args).trim();
+        let maxTokens = handoffMaxTokens;
+        if (!isPositiveInt(maxTokens)) {
+          let settings: KillerosSettings = {};
+          try {
+            settings = createKillerosSettingsStore().load();
+          } catch (error) {
+            ctx.ui.notify(`killeros.json could not be read; using the default handoff budget: ${errorMessage(error)}`, "warning");
+          }
+          maxTokens = resolveHandoffMaxTokens(settings);
+        }
         const generation = ctx.mode === "tui"
           ? await ctx.ui.custom<HandoffGenerationResult>((tui, theme, _keybindings, done) => {
             const loader = new BorderedLoader(tui, theme, "Generating handoff...");
@@ -146,12 +176,12 @@ export function registerHandoff(pi: ExtensionAPI, goalRuntime: GoalRuntime): voi
               done(result);
             };
             loader.onAbort = () => finish({ kind: "cancelled" });
-            generateHandoffSummary(ctx, conversation, focus, loader.signal)
+            generateHandoffSummary(ctx, conversation, focus, { maxTokens, signal: 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;
+          : { kind: "summary", summary: await generateHandoffSummary(ctx, conversation, focus, { maxTokens }) } as const;
         if (generation.kind === "cancelled") {
           ctx.ui.notify("Handoff cancelled", "info");
           return;

package/killeros/hooks.ts

@@ -261,7 +261,7 @@ export function executeHook(
   if (signal?.aborted) {
     return Promise.resolve({ code: 130, stdout: "", stderr: "", timedOut: false, cancelled: true, exitUnconfirmed: false });
   }
-  let child;
+  let child: HookChildProcess;
   try {
     child = spawnProcess(command, {
       cwd,

package/killeros/personal-instructions.ts

@@ -1,9 +1,8 @@
-import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
+import { closeSync, openSync, readSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { fileURLToPath } from "node:url";
-import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { InitRuntime } from "./runtime.ts";
 
 const PERSONAL_INSTRUCTIONS_FILE = "AGENTS.local.md";

package/killeros/question.ts

@@ -1,7 +1,6 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
   type ExtensionAPI,
-  type ExtensionContext,
   type ThemeColor,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";

package/killeros/runtime.ts

@@ -82,9 +82,12 @@ export type GoalState = GoalStateCommon & (
     }
 );
 
+/** Pi request outcomes for goal recovery: awaiting result, compacted, or rejected as session-too-small. */
+export type AutomaticGoalCompactionOutcome = "pending" | "completed" | "skipped";
+
 export interface AutomaticGoalCompaction {
   pausedRevision: number;
-  compactionSucceeded: boolean;
+  outcome: AutomaticGoalCompactionOutcome;
   turnSettled: boolean;
 }
 

package/killeros/shell-ui.ts

@@ -2,7 +2,6 @@ import { execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
 import {
   CustomEditor,
-  VERSION,
   type ExtensionAPI,
   type ExtensionContext,
   type KeybindingsManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "2.0.19",
+  "version": "2.0.20",
   "description": "TUI, goals, and workflow automation for the Pi coding agent",
   "type": "module",
   "keywords": [
@@ -30,7 +30,8 @@
     "node": ">=22.19.0"
   },
   "scripts": {
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && eslint .",
+    "lint": "eslint .",
     "test": "node --test --experimental-strip-types test/*.test.*"
   },
   "pi": {
@@ -52,8 +53,10 @@
     "@earendil-works/pi-coding-agent": "0.84.3",
     "@earendil-works/pi-tui": "0.84.3",
     "@types/node": "24.12.4",
+    "eslint": "^10.9.1",
     "typebox": "1.1.38",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.68.0"
   },
   "overrides": {
     "brace-expansion": "5.0.9",