pi-pier 0.2.7 → 0.3.0

package/src/ask-user.ts

@@ -6,6 +6,7 @@
  * so the model cannot forget a free-text escape and Esc is a real decline.
  */
 import { Type } from 'typebox';
+import { runMultiSelect } from './ask-multi.ts';
 
 export const ASK_TOOL_NAME = 'ask_user_question';
 export const OTHER_OPTION = 'Other (type your own)';
@@ -44,16 +45,18 @@ export const ASK_PARAMETERS = Type.Object({
   options: Type.Optional(Type.Array(OptionSchema, {
     description: '2-5 authored choices. Do NOT include Other; the UI appends it.',
   })),
-  multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false)' })),
+  multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false). In the TUI this opens an interactive toggle list (space toggles, enter confirms, esc declines).' })),
+  allowOther: Type.Optional(Type.Boolean({ description: 'Set false to offer the authored choices only, with no free-text row (default true).' })),
   recommended: Type.Optional(Type.Number({ description: '0-based index of the recommended option; UI adds (Recommended)' })),
   questions: Type.Optional(Type.Array(
     Type.Object({
       id: Type.Optional(Type.String({ description: 'Stable id for mapping answers' })),
       question: Type.String({ description: 'Question text' }),
       options: Type.Array(OptionSchema, {
-        description: '2-5 authored choices. Do NOT include Other; the UI appends it.',
+        description: '2-5 authored choices. Do NOT include Other; the UI appends it unless allowOther is false.',
       }),
-      multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false)' })),
+      multi: Type.Optional(Type.Boolean({ description: 'Allow multiple selections (default false). In the TUI this opens an interactive toggle list (space toggles, enter confirms).' })),
+      allowOther: Type.Optional(Type.Boolean({ description: 'Set false to offer the authored choices only, with no free-text row (default true).' })),
       recommended: Type.Optional(Type.Number({ description: '0-based recommended option index' })),
     }),
     { description: '1-4 related questions in one call. Wins over top-level question/options when set.' },
@@ -66,14 +69,16 @@ export const ASK_TOOL_DESCRIPTION = [
   'While waiting, the pane shows as blocked in herdr (the human sees it and can step in).',
   'Prefer 2-5 options with short labels; put tradeoffs in description.',
   'Do NOT include an "Other" option — the UI appends "Other (type your own)" automatically.',
-  'Use recommended (0-based) to mark the default; "(Recommended)" is added automatically.',
-  'Use multi: true when several options can apply. Group related questions in questions (max 4) rather than calling this tool repeatedly.',
+  'Use recommended (0-based) to mark the default; "(Recommended)" is added automatically — do NOT write it in the label.',
+  'Use multi: true when several options can apply — the TUI opens an interactive toggle list (space toggles a row, a toggles all, enter confirms, esc declines) instead of making the human type numbers.',
+  'Set allowOther: false when the authored choices are exhaustive and a free-text answer would be misleading.',
   'The answer comes back as the tool result; then continue your work.',
 ].join(' ');
 
 export const ASK_PROMPT_GUIDELINES = [
   'Default to action. Ask only when options have materially different tradeoffs the user must decide.',
-  'Do NOT include "Other" in options; the UI appends it.',
+  'Do NOT include "Other" in options; the UI appends it unless allowOther is false. Group related questions in questions (max 4) rather than calling this tool repeatedly.',
+  'For multi questions the human toggles rows in a list and confirms with enter — never instruct them to type indices.',
   'Short option labels; explanatory tradeoffs in description.',
 ];
 
@@ -83,6 +88,8 @@ export type AskQuestion = {
   question: string;
   options: AskOption[];
   multi: boolean;
+  /** When false the UI offers the authored choices only (no free-text row). */
+  allowOther: boolean;
   recommended?: number;
 };
 export type AskSpec =
@@ -112,6 +119,8 @@ export type AskToolResult = {
 export type AskUi = {
   select?: (title: string, options: string[], opts?: { signal?: AbortSignal }) => Promise<string | undefined>;
   input: (title: string, placeholder?: string, opts?: { signal?: AbortSignal }) => Promise<string | undefined>;
+  /** TUI-only: full custom components (absent in RPC mode, where it returns undefined). */
+  custom?: (factory: unknown) => Promise<unknown>;
 };
 
 export type PrepareAskResult =
@@ -169,8 +178,19 @@ function parseOptions(raw: unknown): { ok: true; options: AskOption[] } | { ok:
   const seen = new Set<string>();
   for (const item of raw) {
     const rec = asRecord(item);
-    const label = typeof rec?.label === 'string' ? rec.label.trim() : '';
-    if (!label) return fail('Error: each option needs a non-empty label', 'empty_options');
+    const rawLabel = typeof rec?.label === 'string' ? rec.label.trim() : '';
+    // B3: models often repeat the UI's own marker (`label: 'Redis (Recommended)'`), which rendered
+    // as "Redis (Recommended) (Recommended)". Only a trailing bracketed marker is stripped, so a
+    // label that merely mentions the word ("Recommended approach") survives untouched.
+    const label = rawLabel.replace(/\s*[([]\s*recommended\s*[)\]]\s*$/i, '').trim();
+    if (!label) {
+      return fail(
+        rawLabel
+          ? `Error: option label "${rawLabel}" is only the marker the UI appends — give the choice a real name and pass "recommended" instead`
+          : 'Error: each option needs a non-empty label',
+        'empty_options',
+      );
+    }
     if (label.length > MAX_LABEL_CHARS) {
       return fail(`Error: option label exceeds ${MAX_LABEL_CHARS} characters`, 'label_too_long');
     }
@@ -205,6 +225,7 @@ function parseQuestion(raw: unknown): { ok: true; question: AskQuestion } | { ok
       question,
       options: parsed.options,
       multi: rec.multi === true,
+      allowOther: rec.allowOther !== false,
       ...(id ? { id } : {}),
       ...(recommended !== undefined ? { recommended } : {}),
     },
@@ -255,6 +276,7 @@ export function prepareAsk(params: unknown): PrepareAskResult {
         question,
         options: parsed.options,
         multi: rec.multi === true,
+        allowOther: rec.allowOther !== false,
         ...(recommended !== undefined ? { recommended } : {}),
       }],
     },
@@ -276,7 +298,7 @@ export function formatAuthoredLine(option: AskOption, index: number, recommended
 
 export function optionLines(question: AskQuestion): string[] {
   const lines = question.options.map((option, i) => formatAuthoredLine(option, i, question.recommended));
-  lines.push(`${question.options.length + 1}. ${OTHER_OPTION}`);
+  if (question.allowOther !== false) lines.push(`${question.options.length + 1}. ${OTHER_OPTION}`);
   return lines;
 }
 
@@ -333,11 +355,37 @@ async function askSingle(ui: AskUi, question: AskQuestion, signal?: AbortSignal)
 }
 
 async function askMulti(ui: AskUi, question: AskQuestion, signal?: AbortSignal): Promise<AskAnswer | undefined> {
+  // TUI path: a real toggle list. ctx.ui.custom is absent in RPC mode (or returns undefined),
+  // in which case we fall through to the typed-index prompt below.
+  if (typeof ui.custom === 'function') {
+    const outcome = await runMultiSelect(ui.custom, question.question, {
+      options: question.options,
+      allowOther: question.allowOther,
+      ...(question.recommended !== undefined ? { recommended: question.recommended } : {}),
+    });
+    if (outcome?.kind === 'cancel') return undefined;
+    if (outcome?.kind === 'other') {
+      const typed = await ui.input(`${question.question}\n\n${CUSTOM_ANSWER_TITLE}`, '', signal ? { signal } : undefined);
+      if (typed == null || !typed.trim()) return undefined;
+      return withId(question, {
+        question: question.question,
+        kind: 'custom',
+        answer: OTHER_ANSWER,
+        customInput: typed.trim(),
+      });
+    }
+    if (outcome?.kind === 'selected') {
+      return withId(question, { question: question.question, kind: 'multi', answer: null, selected: outcome.labels });
+    }
+  }
   const list = question.options
     .map((option, i) => formatAuthoredLine(option, i, question.recommended))
     .join('\n');
+  const hint = question.allowOther === false
+    ? `Enter the numbers of all that apply, comma-separated (e.g. "1,3"). There is no free-text answer for this question.`
+    : MULTI_INSTRUCTIONS;
   const value = await ui.input(
-    `${question.question}\n\n${list}\n\n${MULTI_INSTRUCTIONS}`,
+    `${question.question}\n\n${list}\n\n${hint}`,
     '1,3',
     signal ? { signal } : undefined,
   );
@@ -360,6 +408,8 @@ async function askMulti(ui: AskUi, question: AskQuestion, signal?: AbortSignal):
     }
     return withId(question, { question: question.question, kind: 'multi', answer: null, selected });
   }
+  // Unparsable input is a free-text answer only when the free-text row was offered.
+  if (question.allowOther === false) return undefined;
   return withId(question, {
     question: question.question,
     kind: 'custom',

package/src/bootstrap.ts

@@ -15,6 +15,7 @@ import Group from '@deepseek-ai/cordis-plugin-group';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import { DisposeLedger } from './ledger.ts';
+import { pierOption } from './pier-options.ts';
 
 export interface BootstrapHooks {
   onDispose?: () => void;
@@ -60,7 +61,8 @@ export async function createCordisApp(hooks: BootstrapHooks = {}): Promise<Cordi
     console.error(`[pi-herdr] cordis loader degraded (bare tree): ${err instanceof Error ? err.message : String(err)}`);
   }
 
-  if (loaderReady && detectExposeInternals() && process.env.PI_HERDR_HMR === '1') {
+  // B10: canonical PIER_HMR, legacy PI_HERDR_HMR.
+  if (loaderReady && detectExposeInternals() && pierOption('PIER_HMR') === '1') {
     try {
       const withLoader = root as Context & {
         loader?: { create: (o: { name: string; config?: unknown }) => Promise<unknown> };
@@ -78,7 +80,8 @@ export async function createCordisApp(hooks: BootstrapHooks = {}): Promise<Cordi
       console.error('[pi-herdr] hmr active (dev posture: --expose-internals + PI_HERDR_HMR=1)');
       // D80⑤: HMR already disposes old fiber effects; this hook additionally retires old pi-surface generations.
       // d87 keeps generations registered after the reload boundary alive; disposeKey retires only older entries.
-      root.on('hmr/reload', (reloads: unknown) => {
+      // Cordis' own HMR boundary event (not part of pi's typed Events map).
+      (root as unknown as { on(name: string, fn: (reloads: unknown) => void): void }).on('hmr/reload', (reloads: unknown) => {
         try {
           const files: string[] = [];
           for (const r of (reloads as Map<unknown, { filename?: string }>).values()) {

package/src/compact-coordinator.ts

@@ -0,0 +1,454 @@
+/**
+ * D100 Online Context Compact Coordinator.
+ *
+ * Orchestrates:
+ *  - Tracking todo completion boundaries (filtered to source === 'tool').
+ *  - Evaluating KV-cache economics & window protection on turn_end.
+ *  - Guarding against ejecting queued messages (hasPendingMessages check).
+ *  - Aborting turn and executing Pi native compaction with custom instructions.
+ *  - Feeding remaining tasks forward and injecting continuation turn.
+ *  - Persisting state to session entries across branches and restores.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  decideCompaction,
+  DEFAULT_COMPACTION_ECONOMICS,
+  estimateRemainingRequests,
+  MAX_BOUNDARY_SAMPLES,
+  nativeCompactionFeasible,
+  resolveCacheRatioFromCost,
+  type CompactionDecision,
+} from './compact-economics-core.ts';
+import type { TodoItem } from './todo-core.ts';
+import type { TodoCompletionSource } from './todos-service.ts';
+import type { OnlineContextCompactConfig } from './efficiency-config-core.ts';
+import {
+  appendEfficiencyLog,
+  efficiencyLogPath,
+  resolveSessionRoot,
+} from './efficiency-store.ts';
+
+export const COMPACT_STATE_CUSTOM_TYPE = 'pi-herdr.efficiency-state';
+export const COMPACTION_CONTINUE_TYPE = 'pi-herdr.compaction-continue';
+export const DEFAULT_KEEP_RECENT_TOKENS = 20_000;
+export const DEFAULT_MEMO_TOKENS = 1_000;
+
+export interface CoordinatorState {
+  version: 1;
+  epoch: number;
+  completedBoundaryRequestCounts: number[];
+  carriedDebtTokens: number;
+  cacheDebtRepaymentTokens: number;
+  priorCompactionCount: number;
+  positiveContextDeltaTotal: number;
+  positiveContextDeltaCount: number;
+  lastContextTokens: number | null;
+  currentBoundaryRequestCount: number;
+}
+
+export function initialCoordinatorState(): CoordinatorState {
+  return {
+    version: 1,
+    epoch: 0,
+    completedBoundaryRequestCounts: [],
+    carriedDebtTokens: 0,
+    cacheDebtRepaymentTokens: 0,
+    priorCompactionCount: 0,
+    positiveContextDeltaTotal: 0,
+    positiveContextDeltaCount: 0,
+    lastContextTokens: null,
+    currentBoundaryRequestCount: 0,
+  };
+}
+
+export function restoreCoordinatorState(entries: readonly unknown[]): CoordinatorState {
+  if (!Array.isArray(entries)) return initialCoordinatorState();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as { type?: string; customType?: string; data?: unknown };
+    if (entry && entry.type === 'custom' && entry.customType === COMPACT_STATE_CUSTOM_TYPE) {
+      const d = entry.data as Partial<CoordinatorState>;
+      if (d && d.version === 1 && Array.isArray(d.completedBoundaryRequestCounts)) {
+        return {
+          version: 1,
+          epoch: typeof d.epoch === 'number' ? d.epoch : 0,
+          completedBoundaryRequestCounts: [...d.completedBoundaryRequestCounts],
+          carriedDebtTokens: typeof d.carriedDebtTokens === 'number' ? d.carriedDebtTokens : 0,
+          cacheDebtRepaymentTokens: typeof d.cacheDebtRepaymentTokens === 'number' ? d.cacheDebtRepaymentTokens : 0,
+          priorCompactionCount: typeof d.priorCompactionCount === 'number' ? d.priorCompactionCount : 0,
+          positiveContextDeltaTotal: typeof d.positiveContextDeltaTotal === 'number' ? d.positiveContextDeltaTotal : 0,
+          positiveContextDeltaCount: typeof d.positiveContextDeltaCount === 'number' ? d.positiveContextDeltaCount : 0,
+          lastContextTokens: typeof d.lastContextTokens === 'number' ? d.lastContextTokens : null,
+          currentBoundaryRequestCount: typeof d.currentBoundaryRequestCount === 'number' ? d.currentBoundaryRequestCount : 0,
+        };
+      }
+    }
+  }
+  return initialCoordinatorState();
+}
+
+export class CompactCoordinator {
+  state: CoordinatorState = initialCoordinatorState();
+  compactionInFlight = false;
+  intentionalAbort = false;
+  selectedCompaction: CompactionDecision | null = null;
+  pendingBoundaryCompleted = false;
+
+  recordBoundaryCompleted(count: number, source?: TodoCompletionSource): void {
+    // Only count completed transitions originating from model tool calls
+    if (source !== 'tool' || count <= 0) return;
+    this.pendingBoundaryCompleted = true;
+    if (this.state.currentBoundaryRequestCount > 0) {
+      this.state.completedBoundaryRequestCounts.push(this.state.currentBoundaryRequestCount);
+      if (this.state.completedBoundaryRequestCounts.length > MAX_BOUNDARY_SAMPLES) {
+        this.state.completedBoundaryRequestCounts.splice(
+          0,
+          this.state.completedBoundaryRequestCounts.length - MAX_BOUNDARY_SAMPLES,
+        );
+      }
+      this.state.currentBoundaryRequestCount = 0;
+    }
+  }
+
+  onBeforeProviderRequest(contextTokens: number): void {
+    this.state.currentBoundaryRequestCount++;
+    if (this.state.carriedDebtTokens > 0 && this.state.cacheDebtRepaymentTokens > 0) {
+      this.state.carriedDebtTokens = Math.max(
+        0,
+        this.state.carriedDebtTokens - this.state.cacheDebtRepaymentTokens,
+      );
+      if (this.state.carriedDebtTokens === 0) {
+        this.state.cacheDebtRepaymentTokens = 0;
+      }
+    }
+    if (this.state.lastContextTokens !== null && contextTokens > this.state.lastContextTokens) {
+      this.state.positiveContextDeltaTotal += contextTokens - this.state.lastContextTokens;
+      this.state.positiveContextDeltaCount++;
+    }
+    this.state.lastContextTokens = contextTokens;
+  }
+
+  onInput(event: { text?: string; source?: string; streamingBehavior?: string }): void {
+    // Ignore internal messages dispatched by extensions (D96 reminders, pipe injections, followUps)
+    if (event.source === 'extension' || event.text?.startsWith('CORRECTION:')) {
+      return;
+    }
+
+    const fromHuman =
+      event.source === 'interactive' ||
+      event.source === 'rpc' ||
+      event.source === undefined;
+
+    // If human typed a new prompt or steer directive, reset expectations (correction)
+    if (fromHuman) {
+      this.selectedCompaction = null;
+      this.intentionalAbort = false;
+      this.pendingBoundaryCompleted = false;
+      // completedBoundaryRequestCounts deliberately survives: it measures
+      // requests-per-boundary pacing, which holds across human turns. Clearing it
+      // zeroed the mean and pinned expectedRemainingRequests at 1 after every
+      // prompt, so OCC never saw a horizon worth compacting under (2026-09-17
+      // review: compact.jsonl epoch kept climbing 1→9 with zero compactions).
+      this.state.carriedDebtTokens = 0;
+      this.state.epoch++;
+    }
+  }
+
+  onTurnEnd(opts: {
+    ctx: ExtensionContext;
+    todos: readonly TodoItem[];
+    config: OnlineContextCompactConfig;
+    cancelReminder?: () => void;
+  }): void {
+    const boundary = this.pendingBoundaryCompleted;
+    this.pendingBoundaryCompleted = false;
+
+    if (!boundary || this.selectedCompaction) return;
+    if (!opts.config.enabled) return;
+
+    // Safety guard: if user typed something that is queued, don't abort!
+    if (opts.ctx.hasPendingMessages?.()) return;
+
+    const usage = opts.ctx.getContextUsage?.();
+    const contextTokens =
+      typeof usage?.tokens === 'number' && usage.tokens > 0
+        ? usage.tokens
+        : this.state.lastContextTokens ?? 0;
+    const contextWindowTokens = usage?.contextWindow ?? opts.ctx.model?.contextWindow ?? null;
+    const fixedTokens = Math.ceil(Buffer.byteLength(opts.ctx.getSystemPrompt?.() ?? '') / 4);
+    const keepRecentTokens = opts.config.keepRecentTokens ?? DEFAULT_KEEP_RECENT_TOKENS;
+    const archiveTokens = Math.max(0, contextTokens - fixedTokens - keepRecentTokens);
+    const remainingBoundaries = opts.todos.filter(
+      (it) => it.status !== 'completed' && it.status !== 'abandoned',
+    ).length;
+
+    const averageContextTokenIncrement =
+      this.state.positiveContextDeltaCount > 0
+        ? this.state.positiveContextDeltaTotal / this.state.positiveContextDeltaCount
+        : null;
+    const cacheRatio = resolveCacheRatioFromCost(
+      opts.config.cacheWriteReadRatio,
+      opts.ctx.model?.cost,
+      { provider: opts.ctx.model?.provider, modelId: opts.ctx.model?.id },
+    );
+
+    const decision = decideCompaction({
+      writeTokens: contextTokens,
+      archiveTokens,
+      memoTokens: DEFAULT_MEMO_TOKENS,
+      contextTokens,
+      completedBoundaryRequestCounts: this.state.completedBoundaryRequestCounts,
+      remainingBoundaries,
+      averageContextTokenIncrement,
+      contextWindowTokens,
+      priorCompactionCount: this.state.priorCompactionCount,
+      carriedDebtTokens: this.state.carriedDebtTokens,
+      cacheDebtRepaymentTokens: this.state.cacheDebtRepaymentTokens,
+      cacheWriteReadRatio: cacheRatio,
+      economics: {
+        ...DEFAULT_COMPACTION_ECONOMICS,
+        firstCompactionRequestScale: opts.config.firstCompactionRequestScale,
+        subsequentCompactionMargin: opts.config.subsequentCompactionMargin,
+      },
+    });
+
+    if (decision.compact) {
+      const branch = opts.ctx.sessionManager?.getBranch?.() ?? [];
+      const keepRecentTokens = opts.config.keepRecentTokens ?? DEFAULT_KEEP_RECENT_TOKENS;
+      const feasible = nativeCompactionFeasible(branch, keepRecentTokens);
+      if (!feasible) {
+        if (opts.config.logEnabled) {
+          this.logDecision(opts.ctx, { ...decision, compact: false, reason: 'native_not_compactable' });
+        }
+        return;
+      }
+
+      this.selectedCompaction = decision;
+      this.intentionalAbort = true;
+      opts.cancelReminder?.();
+      opts.ctx.abort();
+    } else if (opts.config.logEnabled) {
+      this.logDecision(opts.ctx, decision);
+    }
+  }
+
+  async onAgentSettled(opts: {
+    ctx: ExtensionContext;
+    todos: readonly TodoItem[];
+    pi: ExtensionAPI;
+    config: OnlineContextCompactConfig;
+    cancelReminder?: () => void;
+    onBeforeCompact?: (sessionRoot: string, ctx: ExtensionContext) => Promise<void>;
+  }): Promise<void> {
+    if (!this.selectedCompaction || !opts.ctx.isIdle()) return;
+    const decision = this.selectedCompaction;
+    this.selectedCompaction = null;
+
+    opts.cancelReminder?.();
+    this.compactionInFlight = true;
+
+    const sessionDir = opts.ctx.sessionManager?.getSessionDir?.();
+    const sessionId = opts.ctx.sessionManager?.getSessionId?.();
+    const sessionRoot = resolveSessionRoot(sessionDir, sessionId);
+
+    if (sessionRoot && opts.onBeforeCompact) {
+      try {
+        await opts.onBeforeCompact(sessionRoot, opts.ctx);
+      } catch {
+        /* ignore batch packing errors before compaction */
+      }
+    }
+
+    const remaining = opts.todos.filter(
+      (it) => it.status !== 'completed' && it.status !== 'abandoned',
+    );
+    const taskLines = remaining
+      .map((it) => `- [${it.status}] ${it.content}${it.blocker ? ` (waiting on: ${it.blocker})` : ''}`)
+      .join('\n');
+
+    const customInstructions = [
+      'Preserve completed work, verification results, important decisions, and remaining work.',
+      remaining.length > 0 ? `Active/remaining tasks to preserve:\n${taskLines}` : 'All listed tasks are completed.',
+    ].join('\n\n');
+
+    const startMs = Date.now();
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (!settled) {
+          settled = true;
+          resolve();
+        }
+      };
+
+      opts.ctx.compact({
+        customInstructions,
+        onComplete: (compaction) => {
+          try {
+            this.state.priorCompactionCount++;
+            const incrementalRatio = decision.incrementalCacheCostRatio ?? 0;
+            this.state.carriedDebtTokens = decision.writeTokens * incrementalRatio;
+            this.state.cacheDebtRepaymentTokens = Math.max(0, decision.archiveTokens - decision.memoTokens);
+            this.state.epoch++;
+
+            opts.pi.appendEntry(COMPACT_STATE_CUSTOM_TYPE, this.state);
+
+            if (opts.config.logEnabled) {
+              const sessionDir = opts.ctx.sessionManager?.getSessionDir?.();
+              const sessionId = opts.ctx.sessionManager?.getSessionId?.();
+              const root = resolveSessionRoot(sessionDir, sessionId);
+              if (root) {
+                const logPath = efficiencyLogPath(root, 'compact');
+                void appendEfficiencyLog(logPath, {
+                  schema: 'pier-efficiency/1',
+                  mechanism: 'onlineContextCompact',
+                  ts: new Date().toISOString(),
+                  sessionId: sessionId ?? 'unknown',
+                  epoch: this.state.epoch,
+                  decision: decision.reason,
+                  writeTokens: decision.writeTokens,
+                  archiveTokens: decision.archiveTokens,
+                  savedTokens: Math.max(0, decision.archiveTokens - decision.memoTokens),
+                  breakevenRequests: decision.breakevenRequests,
+                  expectedRemainingRequests: decision.expectedRemainingRequests,
+                  carriedDebtTokens: this.state.carriedDebtTokens,
+                  summaryTokens: typeof compaction?.summary === 'string' ? Math.ceil(compaction.summary.length / 4) : 0,
+                  priorCompactionCount: this.state.priorCompactionCount,
+                  durationMs: Date.now() - startMs,
+                }).catch(() => {});
+              }
+            }
+
+            try {
+              opts.pi.sendMessage(
+                {
+                  customType: COMPACTION_CONTINUE_TYPE,
+                  content: 'Online context compaction finished. Active tasks preserved. Continue working on remaining tasks.',
+                  display: false,
+                },
+                { triggerTurn: true },
+              );
+            } catch {
+              /* ignore continuation failure */
+            }
+          } finally {
+            this.compactionInFlight = false;
+            this.intentionalAbort = false;
+            finish();
+          }
+        },
+        onError: (error) => {
+          this.compactionInFlight = false;
+          this.intentionalAbort = false;
+
+          // `Compaction cancelled` / AbortError mean the user (or pi) cancelled on purpose.
+          // Telemetry must keep those apart from real failures, and a cancelled compaction
+          // must NOT be answered with a turn-triggering continuation.
+          const cancelled =
+            error instanceof Error &&
+            (error.name === 'AbortError' || error.message === 'Compaction cancelled');
+
+          if (opts.config.logEnabled) {
+            const sessionDir = opts.ctx.sessionManager?.getSessionDir?.();
+            const sessionId = opts.ctx.sessionManager?.getSessionId?.();
+            const root = resolveSessionRoot(sessionDir, sessionId);
+            if (root) {
+              const logPath = efficiencyLogPath(root, 'compact');
+              void appendEfficiencyLog(logPath, {
+                schema: 'pier-efficiency/1',
+                mechanism: 'onlineContextCompact',
+                event: 'compaction-failed',
+                ts: new Date().toISOString(),
+                sessionId: sessionId ?? 'unknown',
+                epoch: this.state.epoch,
+                decision: decision.reason,
+                cancelled,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startMs,
+              }).catch(() => {});
+            }
+          }
+
+          if (cancelled) {
+            finish();
+            return;
+          }
+
+          // Resume the task: OCC aborted the turn on purpose, so a failed compaction would
+          // otherwise leave the session parked on an aborted assistant message. Pi's own
+          // threshold compaction stays available as the safety net.
+          try {
+            opts.pi.sendMessage(
+              {
+                customType: COMPACTION_CONTINUE_TYPE,
+                content: 'Context compaction failed. Continuing with the current context.',
+                display: false,
+              },
+              { triggerTurn: true },
+            );
+          } catch {
+            /* ignore continuation failure */
+          }
+
+          finish();
+        },
+      });
+    });
+  }
+
+  rebuildFromBranch(entries: readonly unknown[]): void {
+    this.state = restoreCoordinatorState(entries);
+    this.selectedCompaction = null;
+    this.compactionInFlight = false;
+    this.intentionalAbort = false;
+    this.pendingBoundaryCompleted = false;
+  }
+
+  getRemainingHorizon(remainingBoundaries = 3, contextWindowTokens: number | null = null): number {
+    const counts = this.state.completedBoundaryRequestCounts;
+    if (counts.length === 0) return 4;
+
+    const est = estimateRemainingRequests({
+      completedBoundaryRequestCounts: counts,
+      remainingBoundaries,
+      scale: 1.0,
+      standardDeviationK: 0.0,
+      contextTokens: this.state.lastContextTokens ?? 0,
+      contextWindowTokens,
+      averageContextTokenIncrement:
+        this.state.positiveContextDeltaCount > 0
+          ? this.state.positiveContextDeltaTotal / this.state.positiveContextDeltaCount
+          : null,
+    });
+    return Math.max(1, est.expectedRemainingRequests);
+  }
+
+  private logDecision(ctx: ExtensionContext, decision: CompactionDecision): void {
+    const sessionDir = ctx.sessionManager?.getSessionDir?.();
+    const sessionId = ctx.sessionManager?.getSessionId?.();
+    const root = resolveSessionRoot(sessionDir, sessionId);
+    if (!root) return;
+    const logPath = efficiencyLogPath(root, 'compact');
+    void appendEfficiencyLog(logPath, {
+      schema: 'pier-efficiency/1',
+      mechanism: 'onlineContextCompact',
+      event: 'decision',
+      ts: new Date().toISOString(),
+      sessionId: sessionId ?? 'unknown',
+      epoch: this.state.epoch,
+      decision: decision.reason,
+      compact: decision.compact,
+      writeTokens: decision.writeTokens,
+      archiveTokens: decision.archiveTokens,
+      breakevenRequests: decision.breakevenRequests,
+      expectedRemainingRequests: decision.expectedRemainingRequests,
+      // 2026-09-17: without resolvedRatio/model the 61x cache_ratio_unavailable
+      // run was un-diagnosable from logs alone (which price table? which family?).
+      resolvedRatio: decision.cacheWriteReadRatio,
+      incrementalCacheCostRatio: decision.incrementalCacheCostRatio,
+      remainingBoundaries: decision.remainingBoundaries,
+      model: ctx.model?.id ?? undefined,
+      provider: ctx.model?.provider ?? undefined,
+    }).catch(() => {});
+  }
+}