killeros 2.0.9 → 2.0.10

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.10] - 2026-08-16
+
+### Added
+
+- Added proactive turn-boundary compaction with Pi-owned settings and safe continuation for ordinary prompts and active goals.
+- Added reusable multi-activation decision-gated workflow registrations while preserving exact-match behavior.
+
 ## [2.0.9] - 2026-08-15
 
 ### Added

package/Killeros.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerRequestActivity } from "./killeros/activity.ts";
+import { registerAutoCompaction } from "./killeros/auto-compaction.ts";
 import {
   createSlashCommandResolver,
   registerAliases,
@@ -62,7 +63,8 @@ export default function Killeros(pi: ExtensionAPI, options: KillerosOptions = {}
   registerVariants(pi);
   registerInitCommand(pi, initRuntime, goalRuntime);
   registerLifecycleHooks(pi);
-  registerGoalSettlement(pi, goalRuntime, initRuntime);
+  const goalCompaction = registerGoalSettlement(pi, goalRuntime, initRuntime);
+  registerAutoCompaction(pi, { goal: goalCompaction });
   registerInitSettlement(pi, initRuntime);
   registerRequestActivity(pi);
   registerCompletionNotifications(pi, options.completionNotifications);

package/README.md

@@ -31,7 +31,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.9
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.10
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -44,7 +44,7 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - Frameless multiline editor with one focus-aware `❯`, a shuffled session-stable empty-state suggestion, overflow-only scroll indicators, Shift+Enter support, and slash-command autocomplete; KillerOS preserves an editor factory configured by another extension
 - One compact TUI transcript line reporting truthful `Done`, `Stopped`, or `Failed` settlement with elapsed time while preserving older `✻ Worked for …` entries
 - Compact two-deck footer with session state above workspace state; model, context, and active goals stay prioritized as reasoning, time, cost, branch, and path reduce by available width
-- Pi-owned context compaction with active goals continuing from Pi's settled boundary after manual, threshold, and overflow compaction
+- Proactive turn-boundary context compaction in TUI and RPC modes, with ordinary prompts and active goals continuing safely after a successful summary
 - Optional completion sounds after successful or failed settled requests, excluding manual aborts
 - `/variants` selector and direct reasoning-level arguments
 - Codex-style `/goal` with an interactive status/action panel, durable objectives, immediate pause and clear cancellation, automatic continuation, explicit completion, and durable blocker audits
@@ -81,7 +81,7 @@ The generated file uses the four behavioral sections adapted from `writing-great
 
 ### Decision-gated workflows
 
-Explicit `/skill:decision-gated-workflow` activation opens the shared question UI before Pi expands the skill. `Normal` allows only interview and read-only tools; `With docs` additionally permits agreed glossary, context-map, and ADR paths. The selected policy remains active until the workflow is explicitly finished or cancelled, and lifecycle changes clear it safely. Extensions can supply additional adapters through `KillerosOptions.decisionGatedWorkflows`.
+Explicit `/skill:<name>` activation opens the shared question UI before Pi expands a registered skill. `WorkflowAdapter.activation` keeps the existing exact-match API, while `WorkflowAdapter.activations` lets one policy register multiple explicit skill names without duplicating the gate. `Normal` allows only interview and read-only tools; `With docs` additionally permits agreed glossary, context-map, and ADR paths. Unregistered names pass through unchanged, duplicate or ambiguous registrations fail at startup, and the selected policy remains active until the workflow is explicitly finished or cancelled. Extensions can supply additional adapters through `KillerosOptions.decisionGatedWorkflows`.
 
 ### Interactive questions
 
@@ -97,9 +97,22 @@ KillerOS activates its packaged `killeros` theme when a TUI session starts. Tool
 
 The completion sound is a global user preference stored in Pi's agent directory and is off by default. Run `/notification` in TUI mode to enable or disable it; enabling does not play a preview. Enabled TUI tabs append `󰂚`, which requires a Nerd Font in the terminal tab UI. An unsupported font may show a box without affecting sound. KillerOS uses the terminal's audible bell and cannot produce sound when the terminal disables it.
 
+Automatic compaction is enabled by default when Pi's effective `compaction.enabled` setting is true. After each completed assistant turn, including its tool execution, KillerOS reads the active model's current context usage and triggers the public Pi compaction API when `remainingTokens <= max(contextWindow * percentRemaining / 100, reserveTokens)`. The default `percentRemaining` is `15`; `reserveTokens` and `keepRecentTokens` remain Pi-owned. KillerOS reads those effective settings with Pi's public `SettingsManager` using `getAgentDir()` and the current project trust state. The KillerOS-only preference lives in the same global `killeros.json` file:
+
+```json
+{
+  "autoCompaction": {
+    "enabled": true,
+    "percentRemaining": 15
+  }
+}
+```
+
+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. A failed compaction does not automatically retry. Manual `/compact` behavior is unchanged.
+
 KillerOS displays session costs in USD. The footer uses Pi's human-readable model name when available, keeps the provider visually secondary, and renders context as `percent left (tokens)` without a progress bar. An active goal replaces the right-side path with warning-yellow `/goal is active (...)` and keeps exact seconds in minute and hour formats. Paused and blocked goals retain their existing placement; completed goals remain in transcript history and `/goal` status rather than the footer. At narrow widths, context pressure and actionable goal state take priority.
 
-Pi decides when compaction runs and Pi writes the summary, applies manual focus instructions, tracks files, retries summarization, and handles overflow recovery. KillerOS does not add a second threshold or replace Pi's summary. Active `/goal` work continues from Pi's settled boundary, after Pi finishes retries, compaction, and queued work.
+Pi writes the summary, applies manual focus instructions, tracks files, retries summarization, and handles overflow recovery. KillerOS owns only the proactive turn-boundary trigger and does not replace Pi's compaction implementation. Active `/goal` work continues from the settled compaction boundary, after Pi finishes retries, compaction, and queued work.
 
 Manual `/compact` aborts the current goal turn before summarization, so KillerOS records an honest temporary pause for that exact goal revision. After Pi saves the manual summary, KillerOS resumes that revision automatically. A failed or cancelled manual compaction stays paused; run `/goal pause` during the pause to cancel automatic recovery.
 
@@ -111,9 +124,9 @@ Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supp
 
 | Mode | Behavior |
 |---|---|
-| TUI | All features are available, including the completion sound and tab-title indicator |
-| RPC | 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`, and `/init` fail explicitly; completion sounds and the title indicator are disabled |
+| TUI | All features are available, including proactive compaction, the completion sound, 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 |
 
 ## Validation
 

package/killeros/auto-compaction.ts

@@ -0,0 +1,224 @@
+import {
+  getAgentDir,
+  SettingsManager,
+  type CompactionSettings,
+  type ContextUsage,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+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.";
+
+export interface AutoCompactionPreference {
+  enabled: boolean;
+  percentRemaining: number;
+}
+
+export interface AutoCompactionGoalHandlers {
+  isActive(ctx: ExtensionContext): boolean;
+  onRequested(): void;
+  onCompleted(ctx: ExtensionContext): void;
+  onFailed(ctx: ExtensionContext, error: unknown): void;
+}
+
+export interface AutoCompactionDependencies {
+  loadPreference?: (ctx: ExtensionContext) => AutoCompactionPreference;
+  getCompactionSettings?: (ctx: ExtensionContext) => CompactionSettings;
+  goal?: AutoCompactionGoalHandlers;
+}
+
+interface AutoCompactionRequest {
+  goal: boolean;
+  token: symbol;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function readAutoCompactionPreference(
+  settings: Readonly<Record<string, unknown>>,
+): AutoCompactionPreference {
+  const raw = isRecord(settings.autoCompaction) ? settings.autoCompaction : {};
+  const percentRemaining = typeof raw.percentRemaining === "number"
+    && Number.isFinite(raw.percentRemaining)
+    && raw.percentRemaining >= 0
+    && raw.percentRemaining <= 100
+    ? raw.percentRemaining
+    : DEFAULT_AUTO_COMPACTION_PERCENT_REMAINING;
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : true,
+    percentRemaining,
+  };
+}
+
+function defaultPreference(): AutoCompactionPreference {
+  return readAutoCompactionPreference(createKillerosSettingsStore().load());
+}
+
+function defaultCompactionSettings(ctx: ExtensionContext): CompactionSettings {
+  return SettingsManager.create(ctx.cwd, getAgentDir(), {
+    projectTrusted: ctx.isProjectTrusted(),
+  }).getCompactionSettings();
+}
+
+function reserveTokens(settings: Pick<CompactionSettings, "reserveTokens">): number {
+  return typeof settings.reserveTokens === "number" && Number.isFinite(settings.reserveTokens)
+    ? Math.max(0, settings.reserveTokens)
+    : 0;
+}
+
+export function shouldTriggerAutoCompaction(
+  usage: Pick<ContextUsage, "tokens" | "contextWindow"> | undefined,
+  preference: AutoCompactionPreference,
+  compactionSettings: Pick<CompactionSettings, "enabled" | "reserveTokens">,
+): boolean {
+  if (!preference.enabled || !compactionSettings.enabled || usage?.tokens === undefined || usage.tokens === null) {
+    return false;
+  }
+  if (!Number.isFinite(usage.tokens) || !Number.isFinite(usage.contextWindow) || usage.contextWindow <= 0) {
+    return false;
+  }
+  const remainingTokens = usage.contextWindow - usage.tokens;
+  const threshold = Math.max(
+    usage.contextWindow * preference.percentRemaining / 100,
+    reserveTokens(compactionSettings),
+  );
+  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";
+}
+
+export function registerAutoCompaction(
+  pi: ExtensionAPI,
+  dependencies: AutoCompactionDependencies = {},
+): void {
+  const loadPreference = dependencies.loadPreference ?? (() => defaultPreference());
+  const getCompactionSettings = dependencies.getCompactionSettings ?? defaultCompactionSettings;
+  let request: AutoCompactionRequest | undefined;
+  let armed = true;
+  let settingsErrorReported = false;
+
+  const resetForLifecycle = (): void => {
+    request = undefined;
+    armed = true;
+    settingsErrorReported = false;
+  };
+
+  const notifyFailure = (ctx: ExtensionContext, error: unknown): void => {
+    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;
+    request = undefined;
+    if (goal && dependencies.goal) {
+      try {
+        dependencies.goal.onFailed(ctx, error);
+      } catch (callbackError) {
+        notifyFailure(ctx, callbackError);
+      }
+      return;
+    }
+    notifyFailure(ctx, error);
+  };
+
+  pi.on("turn_end", (_event, ctx) => {
+    if (!supportedMode(ctx) || request) return;
+
+    let preference: AutoCompactionPreference;
+    let compactionSettings: CompactionSettings;
+    let usage: ContextUsage | undefined;
+    try {
+      preference = loadPreference(ctx);
+      compactionSettings = getCompactionSettings(ctx);
+    } catch (error) {
+      if (!settingsErrorReported) {
+        settingsErrorReported = true;
+        ctx.ui.notify(`Automatic compaction settings could not be read: ${errorMessage(error)}`, "error");
+      }
+      return;
+    }
+    try {
+      usage = ctx.getContextUsage();
+    } catch {
+      return;
+    }
+    if (!usage) return;
+    if (usage.tokens !== null && usage.tokens !== undefined && Number.isFinite(usage.tokens)
+      && Number.isFinite(usage.contextWindow) && usage.contextWindow > 0) {
+      const remainingTokens = usage.contextWindow - usage.tokens;
+      const threshold = Math.max(
+        usage.contextWindow * preference.percentRemaining / 100,
+        reserveTokens(compactionSettings),
+      );
+      if (remainingTokens > threshold) {
+        armed = true;
+      }
+    }
+    if (!armed) return;
+    if (!shouldTriggerAutoCompaction(usage, preference, compactionSettings)) return;
+
+    armed = false;
+    const token = Symbol();
+    const goal = dependencies.goal?.isActive(ctx) === true;
+    request = { goal, token };
+    if (goal && dependencies.goal) {
+      try {
+        dependencies.goal.onRequested();
+      } catch (error) {
+        finishFailure(ctx, token, true, error);
+        return;
+      }
+    }
+
+    try {
+      ctx.compact({
+        onComplete: () => {
+          if (!request || request.token !== token) return;
+          request = undefined;
+          if (goal && dependencies.goal) {
+            try {
+              dependencies.goal.onCompleted(ctx);
+            } catch (error) {
+              notifyFailure(ctx, error);
+            }
+            return;
+          }
+          try {
+            pi.sendMessage({
+              customType: AUTO_COMPACTION_MESSAGE_TYPE,
+              content: AUTO_COMPACTION_MESSAGE,
+              display: false,
+            }, { triggerTurn: true, deliverAs: "followUp" });
+          } catch (error) {
+            notifyFailure(ctx, error);
+          }
+        },
+        onError: (error) => finishFailure(ctx, token, goal, error),
+      });
+    } catch (error) {
+      finishFailure(ctx, token, goal, error);
+    }
+  });
+
+  pi.on("session_start", resetForLifecycle);
+  pi.on("session_shutdown", resetForLifecycle);
+  pi.on("session_tree", resetForLifecycle);
+  pi.on("session_before_switch", resetForLifecycle);
+  pi.on("session_before_fork", resetForLifecycle);
+}

package/killeros/goals.ts

@@ -264,7 +264,10 @@ function transitionGoal(
     resumeAfterManualCompaction: options.resumeAfterManualCompaction,
   };
   persistGoalState(pi, runtime, event, next);
-  if (status !== "active") runtime.continuationScheduled = false;
+  if (status !== "active") {
+    runtime.continuationScheduled = false;
+    runtime.automaticCompaction = undefined;
+  }
   return next;
 }
 
@@ -272,6 +275,7 @@ function clearGoalExecutionFlags(runtime: GoalRuntime): void {
   runtime.continuationScheduled = false;
   runtime.goalTurnInFlight = false;
   runtime.agentEndObserved = false;
+  runtime.automaticCompaction = undefined;
   runtime.lastStopReason = undefined;
   runtime.lastError = undefined;
 }
@@ -333,6 +337,7 @@ export function pauseGoalAfterFailure(
     syncGoalUpdateTool(pi, runtime);
     runtime.persistenceRetryNeeded = true;
     runtime.continuationScheduled = false;
+    runtime.automaticCompaction = undefined;
     runtime.requestRender?.();
   }
   if (notify) ctx.ui.notify(`Goal paused: ${reason}\n${recoveryInstruction}`, "error");
@@ -359,6 +364,7 @@ function pauseGoalForPossibleManualCompaction(
     syncGoalUpdateTool(pi, runtime);
     runtime.persistenceRetryNeeded = true;
     runtime.continuationScheduled = false;
+    runtime.automaticCompaction = undefined;
     runtime.requestRender?.();
   }
   ctx.ui.notify(
@@ -384,6 +390,7 @@ function recoverGoalAfterManualCompaction(
     return false;
   }
   runtime.continuationScheduled = false;
+  runtime.automaticCompaction = undefined;
   ctx.ui.notify("Manual compaction complete. Goal resumed.", "info");
   setImmediate(() => scheduleGoalContinuation(pi, runtime, initState, ctx));
   return true;
@@ -450,6 +457,42 @@ function scheduleGoalContinuation(
   }
 }
 
+function completeAutomaticCompaction(
+  pi: ExtensionAPI,
+  runtime: GoalRuntime,
+  initState: InitRuntime,
+  ctx: ExtensionContext,
+): void {
+  if (runtime.automaticCompaction === undefined) return;
+  if (runtime.state?.status !== "active" || initState.active) {
+    runtime.automaticCompaction = undefined;
+    return;
+  }
+  runtime.automaticCompaction = "completed";
+  if (runtime.goalTurnInFlight || !ctx.isIdle()) return;
+  runtime.automaticCompaction = undefined;
+  setImmediate(() => scheduleGoalContinuation(pi, runtime, initState, ctx));
+}
+
+function failAutomaticCompaction(
+  pi: ExtensionAPI,
+  runtime: GoalRuntime,
+  ctx: ExtensionContext,
+  error: unknown,
+): void {
+  if (runtime.automaticCompaction === undefined) return;
+  runtime.automaticCompaction = undefined;
+  if (runtime.state?.status !== "active") return;
+  const reason = error instanceof Error ? error.message : String(error);
+  pauseGoalAfterFailure(
+    pi,
+    runtime,
+    ctx,
+    `automatic compaction failed: ${reason}`,
+    "Automatic continuation is stopped. Run /goal resume after resolving the compaction problem.",
+  );
+}
+
 function goalInstructions(state: GoalState, heading: string): string {
   return [
     `# ${heading}`,
@@ -598,6 +641,7 @@ export function registerGoal(
     runtime.continuationHeld = false;
     runtime.goalTurnInFlight = false;
     runtime.agentEndObserved = false;
+    runtime.automaticCompaction = undefined;
     runtime.persistenceRetryNeeded = false;
     runtime.lastStopReason = undefined;
     runtime.lastError = undefined;
@@ -630,6 +674,7 @@ export function registerGoal(
     runtime.continuationHeld = false;
     runtime.goalTurnInFlight = false;
     runtime.agentEndObserved = false;
+    runtime.automaticCompaction = undefined;
     runtime.persistenceRetryNeeded = false;
     runtime.lastStopReason = undefined;
     runtime.lastError = undefined;
@@ -983,7 +1028,12 @@ export function registerGoalSettlement(
   pi: ExtensionAPI,
   runtime: GoalRuntime,
   initState: InitRuntime,
-): void {
+): {
+  isActive(ctx: ExtensionContext): boolean;
+  onRequested(): void;
+  onCompleted(ctx: ExtensionContext): void;
+  onFailed(ctx: ExtensionContext, error: unknown): void;
+} {
   pi.on("agent_settled", (_event, ctx) => {
     const wasGoalTurn = runtime.goalTurnInFlight;
     const continuationWasScheduled = runtime.continuationScheduled;
@@ -1000,6 +1050,7 @@ export function registerGoalSettlement(
       return;
     }
     if (!agentEndObserved) {
+      if (runtime.automaticCompaction !== undefined) return;
       pauseGoalAfterFailure(pi, runtime, ctx, "the goal turn ended without an agent result");
       return;
     }
@@ -1007,6 +1058,12 @@ export function registerGoalSettlement(
       const reason = runtime.lastError || "the agent turn was aborted";
       runtime.lastStopReason = undefined;
       runtime.lastError = undefined;
+      if (runtime.automaticCompaction !== undefined) {
+        if (runtime.automaticCompaction === "completed") {
+          completeAutomaticCompaction(pi, runtime, initState, ctx);
+        }
+        return;
+      }
       pauseGoalForPossibleManualCompaction(pi, runtime, ctx, reason);
       return;
     }
@@ -1023,7 +1080,23 @@ export function registerGoalSettlement(
   });
 
   pi.on("session_compact", (event, ctx) => {
+    if (runtime.automaticCompaction !== undefined) {
+      completeAutomaticCompaction(pi, runtime, initState, ctx);
+      return;
+    }
     if (event.reason !== "manual") return;
     recoverGoalAfterManualCompaction(pi, runtime, initState, ctx);
   });
+
+  return {
+    isActive: (ctx: ExtensionContext): boolean => isGoalModeSupported(ctx)
+      && isSavedSession(ctx)
+      && runtime.state?.status === "active"
+      && !initState.active,
+    onRequested: (): void => {
+      if (runtime.state?.status === "active") runtime.automaticCompaction = "pending";
+    },
+    onCompleted: (ctx: ExtensionContext): void => completeAutomaticCompaction(pi, runtime, initState, ctx),
+    onFailed: (ctx: ExtensionContext, error: unknown): void => failAutomaticCompaction(pi, runtime, ctx, error),
+  };
 }

package/killeros/notifications.ts

@@ -1,12 +1,10 @@
-import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename } from "node:path";
 import type { StopReason } from "@earendil-works/pi-ai";
 import {
-  getAgentDir,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { createKillerosSettingsStore } from "./settings.ts";
 
 export interface NotificationPreferenceStore {
   load(): boolean;
@@ -20,42 +18,14 @@ export interface CompletionNotificationDependencies {
 
 export const COMPLETION_BELL_GLYPH = "󰂚";
 
-const defaultSettingsPath = (): string => join(getAgentDir(), "killeros.json");
-
-type StoredSettings = Record<string, unknown>;
-
-function readStoredSettings(settingsPath: string): StoredSettings {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(settingsPath, "utf8"));
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error("KillerOS settings must contain a JSON object");
-    }
-    return parsed as StoredSettings;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
-    throw error;
-  }
-}
-
 export function createNotificationPreferenceStore(
-  settingsPath = defaultSettingsPath(),
+  settingsPath?: string,
 ): NotificationPreferenceStore {
+  const settings = createKillerosSettingsStore(settingsPath);
   return {
-    load: () => readStoredSettings(settingsPath).completionSound === true,
+    load: () => settings.load().completionSound === true,
     save: (enabled) => {
-      const current = readStoredSettings(settingsPath);
-      mkdirSync(dirname(settingsPath), { recursive: true });
-      const temporaryPath = `${settingsPath}.${process.pid}.${randomUUID()}.tmp`;
-      try {
-        writeFileSync(
-          temporaryPath,
-          `${JSON.stringify({ ...current, completionSound: enabled }, null, 2)}\n`,
-          { encoding: "utf8", mode: 0o600 },
-        );
-        renameSync(temporaryPath, settingsPath);
-      } finally {
-        rmSync(temporaryPath, { force: true });
-      }
+      settings.update({ completionSound: enabled });
     },
   };
 }

package/killeros/runtime.ts

@@ -57,6 +57,7 @@ export interface GoalRuntime {
   continuationHeld: boolean;
   goalTurnInFlight: boolean;
   agentEndObserved: boolean;
+  automaticCompaction?: "pending" | "completed";
   persistenceRetryNeeded: boolean;
   lastStopReason?: string;
   lastError?: string;
@@ -73,6 +74,7 @@ export function createGoalRuntime(): GoalRuntime {
     continuationHeld: false,
     goalTurnInFlight: false,
     agentEndObserved: false,
+    automaticCompaction: undefined,
     persistenceRetryNeeded: false,
   };
 }

package/killeros/settings.ts

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type KillerosSettings = Record<string, unknown>;
+
+export interface KillerosSettingsStore {
+  load(): KillerosSettings;
+  update(patch: Readonly<Record<string, unknown>>): void;
+}
+
+function readStoredSettings(settingsPath: string): KillerosSettings {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(settingsPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("KillerOS settings must contain a JSON object");
+    }
+    return parsed as KillerosSettings;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+export function createKillerosSettingsStore(
+  settingsPath = join(getAgentDir(), "killeros.json"),
+): KillerosSettingsStore {
+  return {
+    load: () => readStoredSettings(settingsPath),
+    update: (patch) => {
+      const current = readStoredSettings(settingsPath);
+      mkdirSync(dirname(settingsPath), { recursive: true });
+      const temporaryPath = `${settingsPath}.${process.pid}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(
+          temporaryPath,
+          `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`,
+          { encoding: "utf8", mode: 0o600 },
+        );
+        renameSync(temporaryPath, settingsPath);
+      } finally {
+        rmSync(temporaryPath, { force: true });
+      }
+    },
+  };
+}

package/killeros/workflow-gate.ts

@@ -19,7 +19,10 @@ export interface WorkflowPolicy {
 
 export interface WorkflowAdapter {
   id: string;
-  activation: string;
+  /** The existing single explicit skill activation API. */
+  activation?: string;
+  /** Additional explicit skill activations that share this adapter policy. */
+  activations?: readonly string[];
   question: QuestionParamsValue;
   policies: readonly WorkflowPolicy[];
   selectPolicy: (details: QuestionDetails) => WorkflowPolicy | undefined;
@@ -48,11 +51,14 @@ type InternalState =
   | {
     kind: "pending_decision";
     adapter: WorkflowAdapter;
+    activation: string;
     abortController: AbortController;
     token: symbol;
   }
-  | { kind: "active"; adapter: WorkflowAdapter; policy: WorkflowPolicy; token: symbol }
-  | { kind: "terminal_cleanup"; adapter: WorkflowAdapter; reason: WorkflowTerminalReason; token: symbol };
+  | { kind: "active"; adapter: WorkflowAdapter; activation: string; policy: WorkflowPolicy; token: symbol }
+  | { kind: "terminal_cleanup"; adapter: WorkflowAdapter; activation: string; reason: WorkflowTerminalReason; token: symbol };
+
+const ACTIVATION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 
 function explicitSkillActivation(text: string): string | undefined {
   if (!text.startsWith("/skill:")) return;
@@ -76,21 +82,21 @@ function publicState(state: InternalState): WorkflowGateState {
     return {
       kind: state.kind,
       adapterId: state.adapter.id,
-      activation: state.adapter.activation,
+      activation: state.activation,
     };
   }
   if (state.kind === "terminal_cleanup") {
     return {
       kind: state.kind,
       adapterId: state.adapter.id,
-      activation: state.adapter.activation,
+      activation: state.activation,
       reason: state.reason,
     };
   }
   return {
     kind: state.kind,
     adapterId: state.adapter.id,
-    activation: state.adapter.activation,
+    activation: state.activation,
     policyId: state.policy.id,
   };
 }
@@ -141,14 +147,26 @@ export function registerWorkflowGate(
   const adaptersByActivation = new Map<string, WorkflowAdapter>();
   for (const adapter of adapters) {
     if (!adapter.id.trim()) throw new Error("Decision-gated workflow adapters require an id");
-    if (!/^[-A-Za-z0-9._]+$/u.test(adapter.activation)) {
-      throw new Error(`Invalid decision-gated workflow activation: ${adapter.activation}`);
+    if (adapter.activations !== undefined && !Array.isArray(adapter.activations)) {
+      throw new Error(`Workflow adapter ${adapter.id} activations must be an array`);
     }
-    if (adaptersByActivation.has(adapter.activation)) {
-      throw new Error(`Duplicate decision-gated workflow activation: ${adapter.activation}`);
+    const activations = [
+      ...(adapter.activation === undefined ? [] : [adapter.activation]),
+      ...(adapter.activations ?? []),
+    ];
+    if (activations.length === 0) {
+      throw new Error(`Workflow adapter ${adapter.id} must register at least one explicit skill activation`);
+    }
+    for (const activation of activations) {
+      if (typeof activation !== "string" || !ACTIVATION_PATTERN.test(activation)) {
+        throw new Error(`Invalid decision-gated workflow activation: ${activation}`);
+      }
+      if (adaptersByActivation.has(activation)) {
+        throw new Error(`Duplicate decision-gated workflow activation: ${activation}`);
+      }
+      adaptersByActivation.set(activation, adapter);
     }
     if (adapter.policies.length === 0) throw new Error(`Workflow adapter ${adapter.id} has no policies`);
-    adaptersByActivation.set(adapter.activation, adapter);
   }
 
   let state: InternalState = { kind: "inactive" };
@@ -160,6 +178,7 @@ export function registerWorkflowGate(
     state = {
       kind: "terminal_cleanup",
       adapter: current.adapter,
+      activation: current.activation,
       reason,
       token: current.token,
     };
@@ -204,13 +223,12 @@ export function registerWorkflowGate(
   };
 
   pi.on("input", async (event, ctx) => {
-    const activation = explicitSkillActivation(event.text);
-    if (!activation) return;
-
-    if (state.kind === "pending_decision" || state.kind === "terminal_cleanup") {
+    if ((state.kind === "pending_decision" || state.kind === "terminal_cleanup") && event.text.startsWith("/skill:")) {
       notify(ctx, "A decision-gated workflow is waiting for its structured question; skill routing is blocked", "warning");
       return { action: "handled" };
     }
+    const activation = explicitSkillActivation(event.text);
+    if (!activation) return;
 
     const adapter = adaptersByActivation.get(activation);
     if (!adapter) return;
@@ -230,7 +248,7 @@ export function registerWorkflowGate(
 
     const abortController = new AbortController();
     const token = Symbol();
-    state = { kind: "pending_decision", adapter, abortController, token };
+    state = { kind: "pending_decision", adapter, activation, abortController, token };
     let details: QuestionDetails;
     try {
       details = await questionRunner.ask(adapter.question, abortController.signal, ctx);
@@ -275,7 +293,7 @@ export function registerWorkflowGate(
     if (state.kind !== "pending_decision" || state.adapter !== adapter || state.token !== token) {
       return { action: "handled" };
     }
-    state = { kind: "active", adapter, policy, token };
+    state = { kind: "active", adapter, activation, policy, token };
     return { action: "continue" };
   });
 

package/package.json

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