local-context-manager 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `local-context-manager` are documented here. Version numbers also mark the project milestones represented by the merged pull requests.
 
+## [0.3.1] - 2026-09-04
+
+This release makes context tuning intent-based for normal users while keeping numeric controls available for advanced setups.
+
+### Added
+
+- `balanced`, `aggressive`, and `relaxed` context profiles, with `balanced` as the zero-configuration default.
+- `/context-mode [aggressive|balanced|relaxed]` for symptom-based, session-local tuning.
+- Automatic downward adaptation for constrained model context windows; large advertised windows never expand the configured policy.
+- Effective profile and threshold reporting through `/context-stats`.
+
+### Changed
+
+- Numeric threshold settings remain supported as advanced overrides and are applied after profile selection.
+- The compaction gate and custom compaction hook now use the active, context-window-aware thresholds.
+
+### Boundaries
+
+- This release does not infer thresholds from hardware, learn a performance knee from latency, or retune profiles autonomously.
+
 ## [0.3.0] - 2026-09-04
 
 This release completes the public, npm-distributed extension workflow.
@@ -48,6 +68,7 @@ Initial extension milestone delivered by [PR #1](https://github.com/SaehwanPark/
 - Reviewed `/handoff <objective>` continuation prompts and fresh-session initialization.
 - Package metadata, examples, tests, and build/typecheck configuration.
 
+[0.3.1]: https://github.com/SaehwanPark/local-context-manager/pull/5
 [0.3.0]: https://github.com/SaehwanPark/local-context-manager/releases/tag/v0.3.0
 [0.2.0]: https://github.com/SaehwanPark/local-context-manager/pull/2
 [0.1.0]: https://github.com/SaehwanPark/local-context-manager/pull/1

package/README.md

@@ -18,11 +18,12 @@ Start (or reload) Pi in your project, then try:
 /context-stats
 ```
 
-The extension works with Pi's existing models and configuration. It does not install a model or change Pi's emergency compaction authority. To pin this release, use `npm:local-context-manager@0.3.0`.
+The extension works with Pi's existing models and configuration. It does not install a model or change Pi's emergency compaction authority. The latest published release can be pinned with `npm:local-context-manager@0.3.0`.
 
 ## What it adds
 
 - telemetry for context size, compaction, and reduced tool output;
+- balanced-by-default context profiles (`aggressive`, `balanced`, `relaxed`) with automatic downward adaptation for small model windows;
 - guarded proactive compaction at safe idle boundaries;
 - conservative reduction of only new oversized tool results, with a recovery path;
 - intentional phase compaction with `/compact-phase`;

package/examples/local-context-manager.json

@@ -1,5 +1,6 @@
 {
   "enabled": true,
+  "contextProfile": "balanced",
   "softWarningTokens": 24000,
   "compactThresholdTokens": 32000,
   "hardCeilingTokens": 48000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-context-manager",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A Pi extension for cache-friendly context control in long-running local-LLM workflows",
   "type": "module",
   "keywords": ["pi-package", "pi-extension", "local-llm", "context-management"],

package/src/config.ts

@@ -1,7 +1,17 @@
 import { readFile } from "node:fs/promises";
 
+export type ContextProfile = "aggressive" | "balanced" | "relaxed";
+
+export interface ContextThresholds {
+  softWarningTokens: number;
+  compactThresholdTokens: number;
+  hardCeilingTokens: number;
+  keepRecentTokens: number;
+}
+
 export interface LocalContextManagerConfig {
   enabled: boolean;
+  contextProfile: ContextProfile;
   softWarningTokens: number;
   compactThresholdTokens: number;
   hardCeilingTokens: number;
@@ -14,12 +24,34 @@ export interface LocalContextManagerConfig {
   debug: boolean;
 }
 
+export const CONTEXT_PROFILE_THRESHOLDS: Readonly<Record<ContextProfile, Readonly<ContextThresholds>>> = Object.freeze({
+  aggressive: Object.freeze({
+    keepRecentTokens: 8_000,
+    softWarningTokens: 16_000,
+    compactThresholdTokens: 24_000,
+    hardCeilingTokens: 36_000,
+  }),
+  balanced: Object.freeze({
+    keepRecentTokens: 10_000,
+    softWarningTokens: 24_000,
+    compactThresholdTokens: 32_000,
+    hardCeilingTokens: 48_000,
+  }),
+  relaxed: Object.freeze({
+    keepRecentTokens: 12_000,
+    softWarningTokens: 36_000,
+    compactThresholdTokens: 48_000,
+    hardCeilingTokens: 72_000,
+  }),
+});
+
 export const DEFAULT_CONFIG: Readonly<LocalContextManagerConfig> = Object.freeze({
   enabled: true,
-  softWarningTokens: 24_000,
-  compactThresholdTokens: 32_000,
-  hardCeilingTokens: 48_000,
-  keepRecentTokens: 10_000,
+  contextProfile: "balanced",
+  softWarningTokens: CONTEXT_PROFILE_THRESHOLDS.balanced.softWarningTokens,
+  compactThresholdTokens: CONTEXT_PROFILE_THRESHOLDS.balanced.compactThresholdTokens,
+  hardCeilingTokens: CONTEXT_PROFILE_THRESHOLDS.balanced.hardCeilingTokens,
+  keepRecentTokens: CONTEXT_PROFILE_THRESHOLDS.balanced.keepRecentTokens,
   toolOutputReduction: true,
   semanticCompaction: true,
   handoff: true,
@@ -40,6 +72,7 @@ export interface LoadConfigOptions {
   allowProjectConfig?: boolean;
 }
 
+const CONTEXT_PROFILE_KEYS = ["aggressive", "balanced", "relaxed"] as const;
 const BOOLEAN_KEYS = [
   "enabled",
   "toolOutputReduction",
@@ -58,10 +91,67 @@ const NUMBER_KEYS = [
 type RecordValue = Record<string, unknown>;
 type NumberConfigKey = (typeof NUMBER_KEYS)[number];
 
+function isContextProfile(value: unknown): value is ContextProfile {
+  return typeof value === "string" && (CONTEXT_PROFILE_KEYS as readonly string[]).includes(value);
+}
+
 function isRecord(value: unknown): value is RecordValue {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// Four ordered positive thresholds need a little room; real model windows are far larger.
+const MIN_ADAPTIVE_CONTEXT_WINDOW = 8;
+const CONTEXT_WINDOW_FRACTIONS = Object.freeze({
+  keepRecentTokens: 0.125,
+  softWarningTokens: 0.25,
+  compactThresholdTokens: 0.5,
+  hardCeilingTokens: 0.75,
+});
+
+/**
+ * Keep the configured policy as-is for normal and large windows, while reserving
+ * room for the next turn on constrained models. The fractions deliberately only
+ * lower thresholds; a large advertised window must not silently expand a user's
+ * preferred working context.
+ */
+export function getEffectiveThresholds(
+  config: LocalContextManagerConfig,
+  contextWindow?: number,
+): ContextThresholds {
+  const configured: ContextThresholds = {
+    keepRecentTokens: config.keepRecentTokens,
+    softWarningTokens: config.softWarningTokens,
+    compactThresholdTokens: config.compactThresholdTokens,
+    hardCeilingTokens: config.hardCeilingTokens,
+  };
+  if (
+    typeof contextWindow !== "number" ||
+    !Number.isFinite(contextWindow) ||
+    contextWindow < MIN_ADAPTIVE_CONTEXT_WINDOW
+  ) {
+    return configured;
+  }
+
+  return {
+    keepRecentTokens: Math.min(
+      configured.keepRecentTokens,
+      Math.floor(contextWindow * CONTEXT_WINDOW_FRACTIONS.keepRecentTokens),
+    ),
+    softWarningTokens: Math.min(
+      configured.softWarningTokens,
+      Math.floor(contextWindow * CONTEXT_WINDOW_FRACTIONS.softWarningTokens),
+    ),
+    compactThresholdTokens: Math.min(
+      configured.compactThresholdTokens,
+      Math.floor(contextWindow * CONTEXT_WINDOW_FRACTIONS.compactThresholdTokens),
+    ),
+    hardCeilingTokens: Math.min(
+      configured.hardCeilingTokens,
+      Math.floor(contextWindow * CONTEXT_WINDOW_FRACTIONS.hardCeilingTokens),
+    ),
+  };
+}
+
 function configObject(value: unknown): RecordValue | undefined {
   if (!isRecord(value)) {
     return undefined;
@@ -90,6 +180,23 @@ function applyLayer(
   const candidate = { ...base };
   const changedNumbers = new Set<NumberConfigKey>();
 
+  if ("contextProfile" in values) {
+    const value = values.contextProfile;
+    if (!isContextProfile(value)) {
+      errors.push(`Ignoring contextProfile${describeSource(source)}: expected aggressive, balanced, or relaxed`);
+    } else {
+      candidate.contextProfile = value;
+      Object.assign(candidate, CONTEXT_PROFILE_THRESHOLDS[value]);
+    }
+  }
+
+  const numericBase: ContextThresholds = {
+    keepRecentTokens: candidate.keepRecentTokens,
+    softWarningTokens: candidate.softWarningTokens,
+    compactThresholdTokens: candidate.compactThresholdTokens,
+    hardCeilingTokens: candidate.hardCeilingTokens,
+  };
+
   for (const key of BOOLEAN_KEYS) {
     if (!(key in values)) {
       continue;
@@ -149,18 +256,18 @@ function applyLayer(
       const lowerChanged = changedNumbers.has(lowerKey);
       const upperChanged = changedNumbers.has(upperKey);
       if (lowerChanged && !upperChanged) {
-        candidate[lowerKey] = base[lowerKey];
+        candidate[lowerKey] = numericBase[lowerKey];
         changedNumbers.delete(lowerKey);
       } else if (upperChanged && !lowerChanged) {
-        candidate[upperKey] = base[upperKey];
+        candidate[upperKey] = numericBase[upperKey];
         changedNumbers.delete(upperKey);
       } else {
         if (!lowerChanged && !upperChanged) {
           changed = false;
           break;
         }
-        candidate[lowerKey] = base[lowerKey];
-        candidate[upperKey] = base[upperKey];
+        candidate[lowerKey] = numericBase[lowerKey];
+        candidate[upperKey] = numericBase[upperKey];
         changedNumbers.delete(lowerKey);
         changedNumbers.delete(upperKey);
       }

package/src/index.ts

@@ -23,8 +23,12 @@ import {
 } from "./checkpoint-reset.js";
 import { getRearmTokens, CompactionGate, shouldTriggerThresholdCompaction } from "./policy.js";
 import {
+  CONTEXT_PROFILE_THRESHOLDS,
   DEFAULT_CONFIG,
+  getEffectiveThresholds,
   loadConfig,
+  type ContextProfile,
+  type ContextThresholds,
   type LocalContextManagerConfig,
 } from "./config.js";
 import {
@@ -48,6 +52,11 @@ const SEMANTIC_PARAMETERS = Type.Object({
 
 type CompactionRequestReason = "threshold" | "semantic";
 
+interface ObservedContext {
+  tokens: number | null;
+  thresholds: ContextThresholds;
+}
+
 interface PiPathSettings {
   agentDir: string;
   configDirName: string;
@@ -239,13 +248,22 @@ async function saveRecoveryCopy(text: string): Promise<string | undefined> {
   }
 }
 
-function statusWithCeiling(
+function resolveThresholds(
+  context: ExtensionContext,
   config: LocalContextManagerConfig,
   telemetry: ContextTelemetry,
+): ContextThresholds {
+  const contextWindow = telemetry.snapshot(config.compactThresholdTokens).contextWindow ?? context.model?.contextWindow;
+  return getEffectiveThresholds(config, contextWindow);
+}
+
+function statusWithCeiling(
+  telemetry: ContextTelemetry,
+  thresholds: ContextThresholds,
 ): string {
-  const snapshot = telemetry.snapshot(config.compactThresholdTokens);
+  const snapshot = telemetry.snapshot(thresholds.compactThresholdTokens);
   const status = formatTelemetryStatus(snapshot);
-  return snapshot.contextTokens !== null && snapshot.contextTokens >= config.hardCeilingTokens
+  return snapshot.contextTokens !== null && snapshot.contextTokens >= thresholds.hardCeilingTokens
     ? `${status} · hard ceiling`
     : status;
 }
@@ -254,13 +272,15 @@ function updateStatus(
   context: ExtensionContext,
   config: LocalContextManagerConfig,
   telemetry: ContextTelemetry,
+  thresholds?: ContextThresholds,
 ): void {
   if (!context.hasUI) {
     return;
   }
+  const activeThresholds = thresholds ?? resolveThresholds(context, config, telemetry);
   context.ui.setStatus(
     EXTENSION_STATUS_KEY,
-    config.enabled ? statusWithCeiling(config, telemetry) : "off",
+    config.enabled ? statusWithCeiling(telemetry, activeThresholds) : "off",
   );
 }
 
@@ -269,7 +289,7 @@ function observeContext(
   config: LocalContextManagerConfig,
   telemetry: ContextTelemetry,
   gate: CompactionGate,
-): number | null {
+): ObservedContext {
   const usage = context.getContextUsage();
   telemetry.observe(usage);
   if (usage?.tokens == null) {
@@ -282,10 +302,12 @@ function observeContext(
       debugLog(config, "could not estimate active context", error);
     }
   }
-  const snapshot = telemetry.snapshot(config.compactThresholdTokens);
+  const thresholds = resolveThresholds(context, config, telemetry);
+  gate.setRearmTokens(getRearmTokens(thresholds.softWarningTokens, thresholds.compactThresholdTokens));
+  const snapshot = telemetry.snapshot(thresholds.compactThresholdTokens);
   gate.observe(snapshot.contextTokens);
-  updateStatus(context, config, telemetry);
-  return snapshot.contextTokens;
+  updateStatus(context, config, telemetry, thresholds);
+  return { tokens: snapshot.contextTokens, thresholds };
 }
 
 function notifySoftWarning(
@@ -293,9 +315,10 @@ function notifySoftWarning(
   config: LocalContextManagerConfig,
   telemetry: ContextTelemetry,
   warned: { value: boolean },
-  tokens: number | null,
+  observed: ObservedContext,
 ): void {
-  if (tokens === null || warned.value || tokens < config.softWarningTokens) {
+  const { tokens, thresholds } = observed;
+  if (tokens === null || warned.value || tokens < thresholds.softWarningTokens) {
     return;
   }
   warned.value = true;
@@ -306,7 +329,23 @@ function notifySoftWarning(
     );
   }
   debugLog(config, `soft warning at ${tokens} tokens`);
-  updateStatus(context, config, telemetry);
+  updateStatus(context, config, telemetry, thresholds);
+}
+
+function parseContextProfile(value: string): ContextProfile | undefined {
+  if (value === "aggressive" || value === "balanced" || value === "relaxed") {
+    return value;
+  }
+  return undefined;
+}
+
+function formatThresholdSummary(thresholds: ContextThresholds): string {
+  return [
+    `keep ${thresholds.keepRecentTokens.toLocaleString()}`,
+    `warn ${thresholds.softWarningTokens.toLocaleString()}`,
+    `compact ${thresholds.compactThresholdTokens.toLocaleString()}`,
+    `ceiling ${thresholds.hardCeilingTokens.toLocaleString()}`,
+  ].join(" · ");
 }
 
 function buildCompactionOptions(
@@ -326,6 +365,7 @@ async function buildCustomCompaction(
   event: SessionBeforeCompactEvent,
   context: ExtensionContext,
   config: LocalContextManagerConfig,
+  thresholds: ContextThresholds,
 ): Promise<{ compaction: CompactionResult } | undefined> {
   const model = context.model;
   const nativeKeepRecentTokens = event.preparation.settings.keepRecentTokens;
@@ -333,7 +373,7 @@ async function buildCustomCompaction(
     !config.enabled ||
     !model ||
     !Number.isFinite(nativeKeepRecentTokens) ||
-    config.keepRecentTokens >= nativeKeepRecentTokens
+    thresholds.keepRecentTokens >= nativeKeepRecentTokens
   ) {
     return undefined;
   }
@@ -375,7 +415,7 @@ async function buildCustomCompaction(
       event.branchEntries,
       boundaryStart,
       event.branchEntries.length,
-      config.keepRecentTokens,
+      thresholds.keepRecentTokens,
     );
     const firstKeptEntry = event.branchEntries[cutPoint.firstKeptEntryIndex];
     if (!firstKeptEntry?.id) {
@@ -415,7 +455,7 @@ async function buildCustomCompaction(
       fileOps,
       settings: {
         ...event.preparation.settings,
-        keepRecentTokens: config.keepRecentTokens,
+        keepRecentTokens: thresholds.keepRecentTokens,
       },
     };
 
@@ -558,8 +598,9 @@ export default function (pi: ExtensionAPI): void {
       checkpointReset?.createdAt ?? null,
       checkpointReset?.path ?? null,
     );
+    const initialThresholds = getEffectiveThresholds(config, context.model?.contextWindow);
     gate = new CompactionGate({
-      rearmTokens: getRearmTokens(config.softWarningTokens, config.compactThresholdTokens),
+      rearmTokens: getRearmTokens(initialThresholds.softWarningTokens, initialThresholds.compactThresholdTokens),
     });
     warned.value = false;
     turnSerial = 0;
@@ -615,13 +656,13 @@ export default function (pi: ExtensionAPI): void {
   pi.on("turn_start", (_event, context) => {
     turnSerial += 1;
     telemetry.markTurn(turnSerial);
-    const tokens = observeContext(context, config, telemetry, gate);
-    notifySoftWarning(context, config, telemetry, warned, tokens);
+    const observed = observeContext(context, config, telemetry, gate);
+    notifySoftWarning(context, config, telemetry, warned, observed);
   });
 
   pi.on("turn_end", (_event, context) => {
-    const tokens = observeContext(context, config, telemetry, gate);
-    notifySoftWarning(context, config, telemetry, warned, tokens);
+    const observed = observeContext(context, config, telemetry, gate);
+    notifySoftWarning(context, config, telemetry, warned, observed);
 
     // turn_end is the first boundary after all tool results have landed. Only use
     // it when the host reports idle; a continuing tool loop is handled at
@@ -630,15 +671,15 @@ export default function (pi: ExtensionAPI): void {
       config.enabled &&
       !semanticRequested &&
       context.isIdle() &&
-      shouldTriggerThresholdCompaction(tokens, config.compactThresholdTokens)
+      shouldTriggerThresholdCompaction(observed.tokens, observed.thresholds.compactThresholdTokens)
     ) {
       requestCompaction(context, "threshold");
     }
   });
 
   pi.on("agent_settled", (_event, context) => {
-    const tokens = observeContext(context, config, telemetry, gate);
-    notifySoftWarning(context, config, telemetry, warned, tokens);
+    const observed = observeContext(context, config, telemetry, gate);
+    notifySoftWarning(context, config, telemetry, warned, observed);
 
     if (checkpointResetRequested) {
       const reason = checkpointResetReason;
@@ -662,13 +703,14 @@ export default function (pi: ExtensionAPI): void {
       );
       return;
     }
-    if (config.enabled && shouldTriggerThresholdCompaction(tokens, config.compactThresholdTokens)) {
+    if (config.enabled && shouldTriggerThresholdCompaction(observed.tokens, observed.thresholds.compactThresholdTokens)) {
       requestCompaction(context, "threshold");
     }
   });
 
   pi.on("session_compact", (event, context) => {
     const usage = context.getContextUsage();
+    telemetry.observe(usage);
     let activeEntries: SessionEntry[] = [];
     let activeToolOutputTokens = 0;
     try {
@@ -686,12 +728,14 @@ export default function (pi: ExtensionAPI): void {
       postTokens,
       activeToolOutputTokens,
     );
+    const thresholds = resolveThresholds(context, config, telemetry);
+    gate.setRearmTokens(getRearmTokens(thresholds.softWarningTokens, thresholds.compactThresholdTokens));
     gate.complete(postTokens, turnSerial);
     requestedCompaction = undefined;
     semanticRequested = false;
     semanticReason = undefined;
     warned.value = false;
-    updateStatus(context, config, telemetry);
+    updateStatus(context, config, telemetry, thresholds);
     debugLog(config, `compaction completed (${event.reason})`);
   });
 
@@ -766,7 +810,7 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_before_compact", async (event, context) => {
-    return buildCustomCompaction(event, context, config);
+    return buildCustomCompaction(event, context, config, resolveThresholds(context, config, telemetry));
   });
 
   pi.registerTool({
@@ -837,14 +881,68 @@ export default function (pi: ExtensionAPI): void {
   pi.registerCommand("context-stats", {
     description: "Show local context telemetry",
     handler: async (_args, context) => {
-      const tokens = observeContext(context, config, telemetry, gate);
-      const snapshot = telemetry.snapshot(config.compactThresholdTokens);
+      const observed = observeContext(context, config, telemetry, gate);
+      const snapshot = telemetry.snapshot(observed.thresholds.compactThresholdTokens);
       const details = [
         formatTelemetryDetails(snapshot),
-        `Soft warning: ${config.softWarningTokens.toLocaleString()} tokens`,
-        `Hard ceiling: ${config.hardCeilingTokens.toLocaleString()} tokens`,
+        `Context mode: ${config.contextProfile}`,
+        `Effective thresholds: ${formatThresholdSummary(observed.thresholds)}`,
+        `Soft warning: ${observed.thresholds.softWarningTokens.toLocaleString()} tokens`,
+        `Hard ceiling: ${observed.thresholds.hardCeilingTokens.toLocaleString()} tokens`,
         `Enabled: ${config.enabled ? "yes" : "no"}`,
-        `Current reading: ${tokens === null ? "unknown" : `${Math.round(tokens).toLocaleString()} tokens`}`,
+        `Current reading: ${observed.tokens === null ? "unknown" : `${Math.round(observed.tokens).toLocaleString()} tokens`}`,
+      ].join("\n");
+      if (context.hasUI) {
+        context.ui.notify(details, "info");
+      } else if (config.debug) {
+        console.error(details);
+      }
+    },
+  });
+
+  pi.registerCommand("context-mode", {
+    description: "Show or set context mode: aggressive, balanced, or relaxed",
+    handler: async (args, context) => {
+      const requested = args.trim().toLowerCase();
+      if (!requested) {
+        const observed = observeContext(context, config, telemetry, gate);
+        const snapshot = telemetry.snapshot(observed.thresholds.compactThresholdTokens);
+        const details = [
+          `Context mode: ${config.contextProfile}`,
+          `Effective thresholds: ${formatThresholdSummary(observed.thresholds)}`,
+          `Context window: ${snapshot.contextWindow === null ? "not reported" : `${Math.round(snapshot.contextWindow).toLocaleString()} tokens`}`,
+        ].join("\n");
+        if (context.hasUI) {
+          context.ui.notify(details, "info");
+        } else if (config.debug) {
+          console.error(details);
+        }
+        return;
+      }
+
+      const profile = parseContextProfile(requested);
+      if (!profile) {
+        if (context.hasUI) {
+          context.ui.notify("Usage: /context-mode [aggressive|balanced|relaxed]", "error");
+        } else {
+          debugLog(config, "Usage: /context-mode [aggressive|balanced|relaxed]");
+        }
+        return;
+      }
+
+      config = {
+        ...config,
+        contextProfile: profile,
+        ...CONTEXT_PROFILE_THRESHOLDS[profile],
+      };
+      warned.value = false;
+      const observed = observeContext(context, config, telemetry, gate);
+      const snapshot = telemetry.snapshot(observed.thresholds.compactThresholdTokens);
+      const details = [
+        `Context mode set to ${profile} for this session.`,
+        `Effective thresholds: ${formatThresholdSummary(observed.thresholds)}`,
+        `Context window: ${snapshot.contextWindow === null ? "not reported" : `${Math.round(snapshot.contextWindow).toLocaleString()} tokens`}`,
+        `To make it persistent, set \"contextProfile\": \"${profile}\" in local-context-manager.json.`,
       ].join("\n");
       if (context.hasUI) {
         context.ui.notify(details, "info");

package/src/policy.ts

@@ -11,7 +11,7 @@ export interface CompactionGateOptions {
  * threshold gate when the caller has deliberately asked for a new epoch.
  */
 export class CompactionGate {
-  private readonly rearmTokens: number;
+  private rearmTokens: number;
   private readonly minimumTurnGap: number;
   private armed = true;
   private inFlight = false;
@@ -23,6 +23,10 @@ export class CompactionGate {
     this.minimumTurnGap = Number.isFinite(minimumTurnGap) ? Math.max(0, Math.floor(minimumTurnGap)) : MIN_COMPACTION_TURN_GAP;
   }
 
+  setRearmTokens(rearmTokens: number): void {
+    this.rearmTokens = Number.isFinite(rearmTokens) ? Math.max(1, rearmTokens) : 1;
+  }
+
   observe(tokens: number | null): void {
     if (tokens !== null && Number.isFinite(tokens) && tokens <= this.rearmTokens) {
       this.armed = true;