pi-condense 2.10.3 → 2.10.5

package/CHANGELOG.md

@@ -7,6 +7,25 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.10.5] - 2026-09-15
+
+### Fixed
+
+- Mid-run auto-flush triggers (budget, delta, frontier-gap) stayed dead after every human reply until the new run's per-run turn index caught up with the session-wide persisted frontier: live `turn_end` batches carried Pi's run-local `event.turnIndex` while the frontier counts assistant messages session-wide. Live capture now derives the session-wide index from the session branch. Flush metrics entries gain a `stubCount` field. (#16)
+
+## [2.10.4] - 2026-09-15
+
+### Fixed
+
+- `saveConfig` no longer overwrites a `settings.json` it could not read as a JSON object (unreadable, truncated, or non-object); only a missing file starts from empty. A failed `/pruner` save now shows an error notification naming the file instead of an unhandled promise rejection; the change still applies to the current session. (#15)
+
+### Changed
+
+- `release.sh <level>` promotes the CHANGELOG `## [Unreleased]` section to the versioned heading and commits it with `package.json` in the single `Release X.Y.Z` commit; a missing or empty section fails the run. New CONFIG field `CHANGELOG_HEADING`.
+- Release skill: a user instruction naming the level is the approval - no proposal step or re-confirmation; bundled follow-ups run after `verify`.
+- AGENTS.md rewritten to always-on essentials plus routing; shared core bumped to v3. Session entry types table moved to `PRUNING.md`.
+- `.pi/gauntlet-overrides.md` gains `tracker: github`, the release path, and a write-gate carve-out for user-named writes; the Tickets section is superseded by the core Ticket convention.
+
 ## [2.10.3] - 2026-09-07
 
 - **Protected-path supersession.** Only the newest read of a protected path (`protectedPaths` / `protectedTools` calls with a string `path`) stays verbatim; earlier reads of the same path become a one-line `[Superseded: ...]` stub. Applied at render time (`pruneMessages` phase 1b, `src/supersede.ts`) and only when the pruner is already rewriting at or before that position, or on a cold-cache event (`session_start`, `session_tree`, `model_select`, `session_compact`, `thinking_level_select`) - never as the sole mid-prefix change. No new session entry, index record, or config key; supersession stops exactly when no protected call remains (`protectedPaths: []` with the default `protectedTools: []`); a read protected by tool name alone still participates. Spec: `doc/specs/2026-09-07-protected-path-supersede.md` (partially supersedes the 2026-06-11 protected-paths spec's "verbatim forever" edge case).

package/PRUNING.md

@@ -10,6 +10,7 @@
 2. [What Pruning Does](#what-pruning-does)
 3. [Pruned Data Is Still Available](#pruned-data-is-still-available)
 4. [What Actually Lives in the Pruner Index](#what-actually-lives-in-the-pruner-index)
+   - [Session entry types](#session-entry-types)
 5. [How the Model Re-reads Raw Outputs](#how-the-model-re-reads-raw-outputs)
 6. [How Prefix Caching Works](#how-prefix-caching-works)
 7. [Why Frequent Pruning Busts Cache](#why-frequent-pruning-busts-cache)
@@ -287,6 +288,21 @@ So after pruning, the model is working with a **two-layer memory**:
 | Indexed tool-call record | **Stored in pruner index** (`context-prune-index` session entry) | Lets the model re-open the original raw output later via `context_tree_query` |
 | Duplicate of an already-indexed record (same toolName + content) | **Aliased to the original; no new summary, no LLM call** (`context-prune-dedup-alias` session entry) | See [Content-hash dedup](#content-hash-dedup) |
 
+### Session entry types
+
+Custom session entry types written by the extension (NOT in LLM context unless noted). Rebuilt on `session_start` where stated; see the `Written by` column for the source.
+
+| customType | Written by | Purpose |
+|---|---|---|
+| `context-prune-index` | `indexer.addBatch`; also `indexer.backfillChainRecords` (uncovered-chain deterministic backfill, `src/chain-compressor.ts`) | One entry per summarized batch; rebuilds the in-memory `ToolCallRecord` map on `session_start`. A backfill-carrier entry additionally sets `backfilled: true` and carries `refs` (the allocated `t<N>` `SummaryToolCallRef[]`) - excluded from content-hash dedup canonical seeding on both the live path and `session_start` reconstruction; `refs` are re-registered via `registerSummaryRefs` on reconstruction since backfilled chains have no summary message to derive aliases from |
+| `context-prune-summary` | `flushPending` (runtime: `pi.sendMessage` steer; session: `appendCustomMessageEntry`) | The summary message itself; IS in LLM context (replaces the pruned raw outputs) |
+| `context-prune-stats` | `statsAccum.persist` | Cumulative summarizer token/cost snapshot |
+| `context-prune-frontier` | `flushPending` | Last attempted prune boundary (advances even on `skipped-oversized` / `skipped-trivial` / `skipped-deduped`) |
+| `context-prune-dedup-alias` | `indexer.registerDuplicate` | One entry per content-hash dedup hit; rebuilt on `session_start` to repopulate `dedupAliasToOriginal` |
+| `context-prune-chain` | `chain-compressor.compressEligible` (called from `flushPending` in `index.ts` and from `/pruner compact`) | One entry per chain that has been range-dropped from LLM context; drops are decided **positionally** by `resolveRange` (`src/chain-range-prune.ts`), not by id. `droppedToolCallIds` is a diagnostic cross-check only (recorded-vs-actual mismatch emits `range-id-mismatch`); `droppedOccurrenceKeys` (optional) is load-bearing - it's what the occurrence-keyed synthetic-body lookup (per-batch summary text/coverage) is keyed against; protected-output text is NOT keyed off it - `src/chain-range-prune.ts` pulls `protectedToolCallIds` live by bare id within the resolved range instead. Also carries optional `rangeSummaryText` (fused LLM range summary) when `fuseRangeSummary` is on, and optional `protectedToolCallIds` (verbatim protected outputs - ids protected by tool name or path glob - are relocated into the synthetic body as `<protected-output>` tags at render time). Optional `bodySource: "deterministic"` marks a chain that had zero per-batch summary coverage: `rangeSummaryText` then holds a zero-LLM stub (call count, tool histogram, span duration, `t<N>` refs) built by the uncovered-chain backfill path in `chain-compressor.ts`, instead of a summarizer-derived body. Rebuilt on `session_start` to repopulate the chain registry. |
+| `context-prune-diagnostic` | `pruneMessages` / `applyChainCompressions` / `chain-compressor.compressEligible` (via `DiagnosticSink.report`, `src/diagnostics.ts`) | One entry per distinct `(kind, dedupKey)` prune-time degradation (`unresolved-range` / `range-id-mismatch` / `orphan-sweep` / `backfill-empty`). Never in LLM context; deduped in-memory; reset on `session_start` and `session_tree`. Surfaced on the footer status widget as `diag u<N>/m<N>/o<N>/b<N>`. See [Diagnostics](#diagnostics). |
+| `context-prune-flush-metrics` | `flushPending` (end of every non-concurrent attempt, single `finally` emit site, outside the chain-compression try/catch) | One entry per flush attempt, all outcomes (incl. `empty`/`error`): trigger, batch counts, `stubCount` (tool calls newly made stub-eligible by the flush: dedup aliases on processed batches plus calls from actually-indexed batches; `0` when nothing was indexed or aliased), and the pre-flush `ContextMetricsSnapshot` (open-cycle thinking, largest-chain share, frontier gap). Append-only observability log - never in LLM context, never reconstructed on `session_start`. |
+
 ## How the Model Re-reads Raw Outputs
 
 The intended recovery flow is:
@@ -692,6 +708,8 @@ This is rare in practice once `minBatchChars` is on, because the cases where sum
 
 The last attempted prune boundary is persisted as `context-prune-frontier` so `flushPending` knows where the previous attempt left off, even if that attempt was a skip rather than a real summary. Without this, a batch that's been skipped as oversized would be re-attempted (with the same LLM call, the same oversize result, the same skip) on every subsequent flush.
 
+The frontier's `lastAttemptedTurnIndex` uses a session-wide numbering domain: it counts every projected assistant message from the start of the session, matching the rescan rule in `src/batch-capture.ts`. Pi's `event.turnIndex` resets on each `agent_start`, so live `turn_end` capture instead derives this session-wide index from the current session branch via `deriveLiveTurnIndex`. If `getBranch()` throws, capture temporarily falls back to the run-local index. When the branch is healthy at flush time, the rescan re-derives the session-wide index and the fallback value never persists; when branch reads keep failing through the flush, the queued run-local index persists and numbering self-corrects on the next healthy flush. This domain never decreases across compaction because compaction appends entries rather than removing them.
+
 ### Other UI / observability features
 
 - **Tree browser (`/pruner tree`):** interactive, foldable tree of pruned tool calls grouped under their summaries. `Ctrl-O` on a summary node opens the full markdown summary in a bordered overlay.

package/README.md

@@ -160,7 +160,7 @@ By default the extension is **off**. `/pruner on` enables it and it stays enable
 
 ## Configuration - the knobs most people touch
 
-Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_AGENT_DIR` if set, else `~/.pi/agent`). Each pi preset gets its own settings.
+Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_AGENT_DIR` if set, else `~/.pi/agent`). Each pi preset gets its own settings. A `settings.json` that cannot be read as a JSON object is never overwritten by a `/pruner` change: the change applies to the current session and an error notification names the file.
 
 | Key | Default | Notes |
 |---|---|---|

package/index.ts

@@ -13,9 +13,9 @@
  * Usage:  pi -e .
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./src/config.js";
-import { captureBatch, captureUnindexedBatchesFromSession, groupBatchesByMode, projectBranchMessages } from "./src/batch-capture.js";
+import { captureBatch, captureUnindexedBatchesFromSession, deriveLiveTurnIndex, groupBatchesByMode, projectBranchMessages } from "./src/batch-capture.js";
 import { summarizeBatch, summarizeBatches, summarizeRange } from "./src/summarizer.js";
 import { FallbackController } from "./src/summarizer-fallback.js";
 import { ToolCallIndexer } from "./src/indexer.js";
@@ -241,6 +241,7 @@ export default function (pi: ExtensionAPI) {
     // the emitter falls back to pi.appendEntry.
     let capturedBatches = 0;
     let processedCount = 0;
+    let stubCount = 0;
     let outcome: FlushMetricsEntry["outcome"] = "empty";
     let appendEntry: ((customType: string, data?: unknown) => void) | undefined;
 
@@ -251,6 +252,7 @@ export default function (pi: ExtensionAPI) {
         trigger,
         capturedBatches,
         processedBatches: processedCount,
+        stubCount,
         outcome,
         metrics: entryMetrics,
       };
@@ -486,6 +488,7 @@ export default function (pi: ExtensionAPI) {
           totalRawCharCount += dedupRawChars;
           totalToolCallCount += dedupCount;
           totalDedupedCount += dedupCount;
+          stubCount += dedupCount;
           dedupedBatches.push(batch);
           processedBatches.push(batch);
           continue;
@@ -500,6 +503,7 @@ export default function (pi: ExtensionAPI) {
           totalRawCharCount += batchRawCharCount + dedupRawChars;
           totalToolCallCount += batch.toolCalls.length + dedupCount;
           totalDedupedCount += dedupCount;
+          stubCount += dedupCount;
           trivialBatches.push(batch);
           processedBatches.push(batch);
           continue;
@@ -541,8 +545,10 @@ export default function (pi: ExtensionAPI) {
             // Keep the in-memory summary-body registry current so chain compression
             // can build synthetic chain messages without rescanning session entries.
             indexer.registerSummaryBody(batchOccurrenceKeys, summaryText);
+            stubCount += batch.toolCalls.length + dedupCount;
             floorSources.push(...batch.toolCalls);
           } else {
+            stubCount += dedupCount;
             oversizedBatches.push(batch);
           }
         } catch (err) {
@@ -889,10 +895,25 @@ export default function (pi: ExtensionAPI) {
 
     let pushedBatch = false;
     if (hasToolResults) {
+      // Live batches must be numbered in the frontier's session-wide domain, not
+      // Pi's run-local event.turnIndex (which resets on agent_start, #16). The
+      // branch at turn_end already holds the just-ended assistant message (pi
+      // persists it at message_end, a strictly earlier event), so the derived
+      // index is the rescan index of this turn.
+      let liveTurnIndex = event.turnIndex;
+      let branch: SessionEntry[] | undefined;
+      try {
+        branch = ctx.sessionManager.getBranch();
+      } catch {
+        // Transient getBranch failure must never block the turn; fall back to
+        // the run-local index (pre-#16 behavior). The flush-time rescan still
+        // recovers the batch.
+      }
+      if (branch) liveTurnIndex = deriveLiveTurnIndex(branch);
       const capturedBatch = captureBatch(
         event.message,
         event.toolResults,
-        event.turnIndex,
+        liveTurnIndex,
         Date.now()
       );
       // Drop user-protected tool/path results so they stay verbatim in context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.3",
+  "version": "2.10.5",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/batch-capture.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   captureBatch,
   captureUnindexedBatchesFromSession,
+  deriveLiveTurnIndex,
   projectBranchMessages,
   serializeBatchForSummarizer,
 } from "./batch-capture.js";
@@ -180,6 +181,45 @@ describe("projectBranchMessages", () => {
   });
 });
 
+describe("deriveLiveTurnIndex (#16)", () => {
+  // Branch mixing every entry class the projection must classify: tool-calling
+  // assistants, a text-only assistant, a custom_message steer, a pruner custom
+  // entry, a compaction entry. The last assistant carries a ready, unsummarized
+  // tool call so the rescan emits a batch for it.
+  function mixedBranch(): any[] {
+    return [
+      { type: "message", message: { role: "user", content: [{ type: "text", text: "start" }] } },
+      { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "tc-old", name: "read", arguments: {} }] } },
+      { type: "message", message: { role: "toolResult", toolCallId: "tc-old", toolName: "read", content: [{ type: "text", text: "y".repeat(200) }], timestamp: 1 } },
+      { type: "message", message: { role: "assistant", content: [{ type: "text", text: "text only" }] } },
+      { type: "custom_message", customType: "gauntlet-gate", content: "go", display: true },
+      { type: "custom", customType: "context-prune-summary", data: {} },
+      { type: "compaction", summary: "..." },
+      { type: "message", message: { role: "user", content: [{ type: "text", text: "again" }] } },
+      { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "tc-live", name: "read", arguments: {} }] } },
+      { type: "message", message: { role: "toolResult", toolCallId: "tc-live", toolName: "read", content: [{ type: "text", text: "x".repeat(200) }], timestamp: 2 } },
+    ];
+  }
+
+  test("returns the rescan index of the branch's last assistant message (AC5 parity)", () => {
+    const branch = mixedBranch();
+    // 3 projected assistant messages (tc-old, text-only, tc-live) -> last index 2.
+    // custom_message/custom/compaction entries never count.
+    expect(deriveLiveTurnIndex(branch)).toBe(2);
+    const rescan = captureUnindexedBatchesFromSession(branch, { isSummarized: () => false });
+    const liveBatch = rescan.find((b) => b.toolCalls.some((tc) => tc.toolCallId === "tc-live"));
+    expect(liveBatch).toBeDefined();
+    expect(liveBatch!.turnIndex).toBe(deriveLiveTurnIndex(branch));
+  });
+
+  test("returns -1 when the branch has no projected assistant message", () => {
+    expect(deriveLiveTurnIndex([])).toBe(-1);
+    expect(
+      deriveLiveTurnIndex([{ type: "message", message: { role: "user", content: [{ type: "text", text: "hi" }] } }]),
+    ).toBe(-1);
+  });
+});
+
 describe("custom-anchor group boundary", () => {
   function buildBranch(customType: string) {
     const entry = (message: any) => ({ type: "message", message });

package/src/batch-capture.ts

@@ -1,3 +1,4 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { CapturedBatch, CapturedToolCall, BatchingMode } from "./types.js";
 import { occKey, resultTimestampOf } from "./occurrence-key.js";
 import { isChainAnchorCustom } from "./chain-detector.js";
@@ -17,6 +18,22 @@ export function projectBranchMessages(branch: any[]): any[] {
     .map((e: any) => (e.type === "custom_message" ? projectCustomMessageEntry(e) : e.message));
 }
 
+/**
+ * Session-wide index for the live turn at `turn_end`: the index the rescan
+ * below assigns to the branch's last assistant message. Shares the rescan's
+ * counting rule (every projected assistant message, text-only included) so
+ * live capture and the persisted flush frontier live in one numbering domain.
+ * Returns -1 when the branch has no projected assistant message (harness-only;
+ * a real `turn_end` always follows a persisted assistant message).
+ */
+export function deriveLiveTurnIndex(branch: SessionEntry[]): number {
+  let count = 0;
+  for (const msg of projectBranchMessages(branch)) {
+    if (msg.role === "assistant") count++;
+  }
+  return count - 1;
+}
+
 /** True for SessionEntry shapes that project into an AgentMessage-like object (see projectBranchMessages). */
 function isProjectableEntry(e: any): boolean {
   return (e.type === "message" && e.message) || e.type === "custom_message";
@@ -109,8 +126,10 @@ export function captureUnindexedBatchesFromSession(
   // turnCounter increments for EVERY assistant message (not just prunable ones).
   // This makes turnIndex stable across multiple prune cycles: pruning removes
   // ToolResultMessages from the context event but leaves AssistantMessages in the
-  // session branch, so the count of all assistant messages never decreases and
-  // always matches Pi's own event.turnIndex numbering.
+  // session branch, so the count of all assistant messages never decreases. This
+  // session-wide count is the frontier's numbering domain; Pi's event.turnIndex
+  // matches it only inside one agent run (it resets on agent_start), so the live
+  // capture path derives the same index from the branch via deriveLiveTurnIndex.
   let turnCounter = 0;
 
   // userTurnGroup increments on every user message or eligible custom anchor seen

package/src/commands.test.ts

@@ -1,5 +1,15 @@
 import { describe, it, expect, mock } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Command handlers persist through src/config.ts, which resolves the settings
+// path lazily from PI_CODING_AGENT_DIR; point it at a scratch dir so no test
+// ever touches the developer's real settings.json.
+process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pi-condense-commands-test-"));
+
 import { pruneStatusText, setPruneStatusWidget, registerCommands } from "./commands.js";
+import { settingsPath } from "./config.js";
 import type { ContextPruneConfig, ContextMetricsSnapshot, SummarizerStats } from "./types.js";
 import { DEFAULT_CONFIG } from "./types.js";
 
@@ -26,6 +36,7 @@ function setupPrunerCommand(overrides: {
   flushPending?: (ctx: any, options?: any) => Promise<any>;
   getRearmed?: () => boolean;
   getContextMetrics?: (ctx: any) => ContextMetricsSnapshot;
+  save?: (config: ContextPruneConfig) => Promise<void>;
 } = {}) {
   let handler: (args: string, ctx: any) => Promise<void>;
   const notifications: { message: string; type?: string }[] = [];
@@ -59,6 +70,7 @@ function setupPrunerCommand(overrides: {
     undefined,
     overrides.getContextMetrics,
     overrides.getRearmed,
+    overrides.save,
   );
 
   const ctx: any = {
@@ -66,6 +78,7 @@ function setupPrunerCommand(overrides: {
       notify(message: string, type?: string) {
         notifications.push({ message, type });
       },
+      setStatus() {},
     },
   };
 
@@ -73,6 +86,7 @@ function setupPrunerCommand(overrides: {
     run: (args: string) => handler(args, ctx),
     notifications,
     flushCalls,
+    currentConfig,
   };
 }
 
@@ -176,6 +190,41 @@ describe("setPruneStatusWidget", () => {
   });
 });
 
+describe("/pruner off with a rejecting save (#15)", () => {
+  it("keeps the in-memory change, notifies an error naming the settings path, and raises no unhandledRejection", async () => {
+    const unhandled: unknown[] = [];
+    const recorder = (reason: unknown) => { unhandled.push(reason); };
+    process.on("unhandledRejection", recorder);
+    try {
+      const { run, notifications, currentConfig } = setupPrunerCommand({
+        save: () => Promise.reject(Object.assign(new Error("EACCES"), { code: "EACCES" })),
+      });
+
+      await run("off");
+
+      // The error toast lands after the handler returns; wait for it with a
+      // bounded poll rather than a microtask hop.
+      const deadline = Date.now() + 2000;
+      while (!notifications.some((n) => n.type === "error") && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      await new Promise((r) => setImmediate(r));
+
+      const errorIdx = notifications.findIndex((n) => n.type === "error");
+      const successIdx = notifications.findIndex((n) => n.message === "Context pruning disabled.");
+      expect(errorIdx).toBeGreaterThan(-1);
+      expect(successIdx).toBeGreaterThan(-1);
+      expect(successIdx).toBeLessThan(errorIdx);
+      expect(notifications[errorIdx].message).toContain(settingsPath());
+      expect(notifications[errorIdx].message).toContain("EACCES");
+      expect(currentConfig.value.enabled).toBe(false);
+      expect(unhandled).toEqual([]);
+    } finally {
+      process.off("unhandledRejection", recorder);
+    }
+  });
+});
+
 describe("diagnostic counters on the status line", () => {
   const zeroDiag = { "unresolved-range": 0, "range-id-mismatch": 0, "orphan-sweep": 0 } as const;
   const mixedDiag = { "unresolved-range": 2, "range-id-mismatch": 0, "orphan-sweep": 1 } as const;

package/src/commands.ts

@@ -23,7 +23,7 @@ import {
   DEFAULT_CONFIG,
 } from "./types.js";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { saveConfig } from "./config.js";
+import { saveConfig, persistConfig } from "./config.js";
 import { MAX_BUDGET_WINDOW } from "./budget.js";
 import { formatTokens, formatCost, formatCharProgress, formatCompactCount } from "./stats.js";
 import { Container, Text, SettingsList, type SettingItem } from "@earendil-works/pi-tui";
@@ -477,6 +477,7 @@ export function registerCommands(
   getDiagnosticCounts?: () => Record<DiagnosticKind, number>,
   getContextMetrics?: (ctx: ExtensionCommandContext) => ContextMetricsSnapshot,
   getRearmed?: () => boolean,
+  save: (config: ContextPruneConfig) => Promise<void> = saveConfig,
 ): void {
   // Register the /pruner command
   pi.registerCommand("pruner", {
@@ -822,7 +823,7 @@ export function registerCommands(
               };
             }
             currentConfig.value = newConfig;
-            saveConfig(newConfig);
+            void persistConfig((m, t) => ctx.ui.notify(m, t), newConfig, save);
             setPruneStatusWidget(ctx, newConfig, getLiveReclaim(), getDiagnosticCounts?.());
             settingsList?.invalidate();
           };
@@ -856,7 +857,7 @@ export function registerCommands(
         // ── /pruner on ──
         case "on": {
           currentConfig.value = { ...currentConfig.value, enabled: true };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify("Context pruning enabled.");
           setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.());
           break;
@@ -865,7 +866,7 @@ export function registerCommands(
         // ── /pruner off ──
         case "off": {
           currentConfig.value = { ...currentConfig.value, enabled: false };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify("Context pruning disabled.");
           setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.());
           break;
@@ -943,7 +944,7 @@ export function registerCommands(
               summarizerModel: parsed.model,
               summarizerThinking: parsed.thinking ?? currentConfig.value.summarizerThinking,
             };
-            saveConfig(currentConfig.value);
+            void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
             const thinkingText = parsed.thinking ? ` with thinking ${parsed.thinking}` : "";
             ctx.ui.notify(`Summarizer model set to: ${parsed.model}${thinkingText}`);
           }
@@ -971,7 +972,7 @@ export function registerCommands(
             );
             return;
           }
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(`Summarizer thinking set to: ${currentConfig.value.summarizerThinking}`);
           break;
         }
@@ -989,7 +990,7 @@ export function registerCommands(
           } else {
             currentConfig.value = { ...currentConfig.value, pruneOn: modeArg as ContextPruneConfig["pruneOn"] };
           }
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.());
           break;
         }
@@ -1013,7 +1014,7 @@ export function registerCommands(
             }
             currentConfig.value = { ...currentConfig.value, batchingMode: batchArg as ContextPruneConfig["batchingMode"] };
           }
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(`Batching mode set to: ${batchingModeLabel(currentConfig.value.batchingMode)}`);
           break;
         }
@@ -1164,7 +1165,7 @@ export function registerCommands(
           }
 
           currentConfig.value = { ...currentConfig.value, protectedTools: nextList };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(`Protected tools: ${protectedToolsDisplay(nextList)}`);
           break;
         }
@@ -1197,7 +1198,7 @@ export function registerCommands(
           }
 
           currentConfig.value = { ...currentConfig.value, protectedPaths: nextList };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(`Protected paths: ${protectedToolsDisplay(nextList)}`);
           break;
         }
@@ -1221,7 +1222,7 @@ export function registerCommands(
             break;
           }
           currentConfig.value = { ...currentConfig.value, minBatchChars: parsed };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(
             parsed === 0
               ? "minBatchChars set to 0 — pre-flush trivial-batch skipping disabled."
@@ -1244,7 +1245,7 @@ export function registerCommands(
             break;
           }
           currentConfig.value = { ...currentConfig.value, recoveryGraceTurns: parsed };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(
             parsed === 0
               ? "recovery-grace set to 0 - context_tree_query output stubs immediately."
@@ -1269,7 +1270,7 @@ export function registerCommands(
           }
           const next = arg === "on" || arg === "true";
           currentConfig.value = { ...currentConfig.value, dedupByContentHash: next };
-          saveConfig(currentConfig.value);
+          void persistConfig((m, t) => ctx.ui.notify(m, t), currentConfig.value, save);
           ctx.ui.notify(`Content-hash dedup turned ${next ? "ON" : "OFF"}.`);
           break;
         }

package/src/config.test.ts

@@ -1,8 +1,10 @@
-import { describe, expect, it, beforeAll, afterAll } from "bun:test";
+import { describe, expect, it, beforeAll, afterAll, afterEach } from "bun:test";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DEFAULT_CONFIG } from "./types.js";
+import type { ContextPruneConfig } from "./types.js";
 
 /**
  * config.ts resolves the settings path from getAgentDir() lazily on each
@@ -15,6 +17,8 @@ import { DEFAULT_CONFIG } from "./types.js";
 let tmpDir: string;
 let loadConfig: typeof import("./config.js").loadConfig;
 let saveConfig: typeof import("./config.js").saveConfig;
+let persistConfig: typeof import("./config.js").persistConfig;
+let SettingsReadError: typeof import("./config.js").SettingsReadError;
 let settingsPath: typeof import("./config.js").settingsPath;
 
 beforeAll(async () => {
@@ -23,9 +27,17 @@ beforeAll(async () => {
   const mod = await import("./config.js");
   loadConfig = mod.loadConfig;
   saveConfig = mod.saveConfig;
+  persistConfig = mod.persistConfig;
+  SettingsReadError = mod.SettingsReadError;
   settingsPath = mod.settingsPath;
 });
 
+// Every case below may leave a malformed settings.json behind; remove it so
+// the shared path is clean for the next case.
+afterEach(async () => {
+  await rm(settingsPath(), { force: true });
+});
+
 afterAll(async () => {
   delete process.env.PI_CODING_AGENT_DIR;
   await rm(tmpDir, { recursive: true, force: true });
@@ -163,3 +175,89 @@ describe("loadConfig frontierGapThresholdTokens normalization", () => {
     }
   });
 });
+
+describe("saveConfig fails closed (#15)", () => {
+  const config: ContextPruneConfig = { ...DEFAULT_CONFIG, enabled: false };
+
+  it("creates settings.json containing only contextPrune when the file is absent", async () => {
+    await rm(settingsPath(), { force: true });
+    await saveConfig(config);
+    const written = JSON.parse(await readFile(settingsPath(), "utf-8"));
+    expect(Object.keys(written)).toEqual(["contextPrune"]);
+    expect(written.contextPrune.enabled).toBe(false);
+  });
+
+  it("preserves other top-level keys and replaces contextPrune", async () => {
+    await writeFile(settingsPath(), '{"foo":1,"contextPrune":{"enabled":true}}');
+    await saveConfig(config);
+    const written = JSON.parse(await readFile(settingsPath(), "utf-8"));
+    expect(written.foo).toBe(1);
+    expect(written.contextPrune.enabled).toBe(false);
+  });
+
+  for (const [label, raw] of [
+    ["0-byte file", ""],
+    ["truncated JSON", '{"foo":'],
+    ["array", "[]"],
+    ["null", "null"],
+    ["string", '"str"'],
+    ["number", "42"],
+  ] as const) {
+    it(`rejects and leaves the file byte-identical for ${label}; loadConfig returns defaults`, async () => {
+      await writeFile(settingsPath(), raw);
+      const before = readFileSync(settingsPath());
+      await expect(saveConfig(config)).rejects.toBeInstanceOf(SettingsReadError);
+      expect(readFileSync(settingsPath()).equals(before)).toBe(true);
+      expect(await loadConfig()).toEqual({ ...DEFAULT_CONFIG });
+    });
+  }
+
+  it("rejects with reason EACCES when the injected read fails, leaving the file byte-identical", async () => {
+    await writeFile(settingsPath(), '{"foo":1}');
+    const before = readFileSync(settingsPath());
+    const read = (async () => {
+      throw Object.assign(new Error("permission denied"), { code: "EACCES" });
+    }) as unknown as typeof import("node:fs/promises").readFile;
+    const err = await saveConfig(config, read).catch((e) => e);
+    expect(err).toBeInstanceOf(SettingsReadError);
+    expect(err.reason).toBe("EACCES");
+    expect(err.path).toBe(settingsPath());
+    expect(readFileSync(settingsPath()).equals(before)).toBe(true);
+  });
+});
+
+describe("persistConfig (#15)", () => {
+  const config: ContextPruneConfig = { ...DEFAULT_CONFIG, enabled: false };
+
+  it("notifies once with type error and the settings path when the file is truncated", async () => {
+    await writeFile(settingsPath(), '{"foo":');
+    const calls: { message: string; type?: string }[] = [];
+    await persistConfig((message, type) => calls.push({ message, type }), config);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].type).toBe("error");
+    expect(calls[0].message).toContain(settingsPath());
+    expect(calls[0].message).toContain("invalid JSON");
+    expect(calls[0].message).toContain("Change applies to this session only.");
+  });
+
+  it("does not notify when the file is missing", async () => {
+    await rm(settingsPath(), { force: true });
+    const calls: unknown[] = [];
+    await persistConfig((message, type) => calls.push({ message, type }), config);
+    expect(calls).toHaveLength(0);
+    expect(JSON.parse(await readFile(settingsPath(), "utf-8")).contextPrune.enabled).toBe(false);
+  });
+
+  it("handles a save that rejects with undefined", async () => {
+    const calls: { message: string; type?: string }[] = [];
+    await persistConfig(
+      (message, type) => calls.push({ message, type }),
+      config,
+      () => Promise.reject(undefined),
+    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].type).toBe("error");
+    expect(calls[0].message).toContain(settingsPath());
+    expect(calls[0].message).toContain("undefined");
+  });
+});

package/src/config.ts

@@ -115,22 +115,58 @@ function normalize(existing: Partial<ContextPruneConfig>): ContextPruneConfig {
   };
 }
 
-async function readJsonObject(path: string): Promise<Record<string, unknown> | undefined> {
+export class SettingsReadError extends Error {
+  constructor(
+    public readonly path: string,
+    public readonly reason: string,
+  ) {
+    super(`settings.json unreadable at ${path}: ${reason}`);
+    this.name = "SettingsReadError";
+  }
+}
+
+/**
+ * Single classifier for settings.json read outcomes. Only ENOENT means "no
+ * file"; every other failure throws so a save never starts from `{}` over a
+ * file it could not read.
+ */
+async function readJsonObject(
+  path: string,
+  read: typeof readFile = readFile,
+): Promise<Record<string, unknown> | undefined> {
+  let raw: string;
   try {
-    const raw = await readFile(path, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as Record<string, unknown>;
-    }
-    return undefined;
+    raw = await read(path, "utf-8");
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") return undefined;
+    throw new SettingsReadError(path, e.code ?? e.message);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
   } catch {
-    return undefined;
+    throw new SettingsReadError(path, "invalid JSON");
+  }
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    return parsed as Record<string, unknown>;
   }
+  throw new SettingsReadError(path, "not a JSON object");
 }
 
-/** Reads `<agent-dir>/settings.json` and returns the `contextPrune` block, or defaults. */
+/**
+ * Reads `<agent-dir>/settings.json` and returns the `contextPrune` block, or
+ * defaults. Fail-soft: an unreadable or malformed file yields defaults, since
+ * a broken settings.json is pi-wide and not this extension's to report.
+ */
 export async function loadConfig(): Promise<ContextPruneConfig> {
-  const main = await readJsonObject(settingsPath());
+  let main: Record<string, unknown> | undefined;
+  try {
+    main = await readJsonObject(settingsPath());
+  } catch (err) {
+    if (err instanceof SettingsReadError) return { ...DEFAULT_CONFIG };
+    throw err;
+  }
   const namespaced = main?.[SETTINGS_KEY];
   if (namespaced && typeof namespaced === "object" && !Array.isArray(namespaced)) {
     return normalize(namespaced as Partial<ContextPruneConfig>);
@@ -140,18 +176,39 @@ export async function loadConfig(): Promise<ContextPruneConfig> {
 
 /**
  * Writes the full config back to `<agent-dir>/settings.json` under
- * {@link SETTINGS_KEY}, preserving every other top-level key in the file. Uses
- * a tmp-file + atomic rename so concurrent pi writes (e.g. theme changes via
- * `/settings`) cannot observe a partial file. We do not coordinate with pi's
- * own internal lock since both writers do whole-file replacements and a
- * last-write-wins race only loses a single change, never corrupts the file.
+ * {@link SETTINGS_KEY}, preserving every other top-level key in the file.
+ * Tmp-file + atomic rename, so a concurrent reader never observes a partial
+ * file. A file that cannot be read as a JSON object is never replaced: the
+ * read throws {@link SettingsReadError} before anything is written. Concurrent
+ * saves (ours or pi's own) are last-write-wins; that race is not coordinated.
  */
-export async function saveConfig(config: ContextPruneConfig): Promise<void> {
+export async function saveConfig(config: ContextPruneConfig, read: typeof readFile = readFile): Promise<void> {
   const path = settingsPath();
-  const current = (await readJsonObject(path)) ?? {};
+  const current = (await readJsonObject(path, read)) ?? {};
   const next = { ...current, [SETTINGS_KEY]: config };
   await mkdir(dirname(path), { recursive: true });
   const tmpPath = `${path}.${randomBytes(8).toString("hex")}.tmp`;
   await writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`);
   await rename(tmpPath, path);
 }
+
+type Notify = (message: string, type?: "info" | "warning" | "error") => void;
+
+/**
+ * Saves and reports failure through `notify` instead of rejecting, so callers
+ * can fire-and-forget. The in-memory change stands; only persistence failed.
+ */
+export async function persistConfig(
+  notify: Notify,
+  config: ContextPruneConfig,
+  save: (config: ContextPruneConfig) => Promise<void> = saveConfig,
+): Promise<void> {
+  try {
+    await save(config);
+  } catch (err) {
+    const reason = err instanceof SettingsReadError
+      ? err.reason
+      : ((err as NodeJS.ErrnoException | null | undefined)?.code ?? String(err));
+    notify(`Could not save settings to ${settingsPath()}: ${reason}. Change applies to this session only.`, "error");
+  }
+}

package/src/pruner.test.ts

@@ -76,6 +76,27 @@ describe("pruneMessages", () => {
     expect(out[1].content[0].text).toContain("context_tree_query");
   });
 
+  it("two renders of unchanged history are byte-identical (AC6 cache-prefix guard)", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc1"]),
+      shortRefs: new Map([["tc1", "t1"]]),
+    });
+    const build = () => [
+      { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "bash", input: {} }], timestamp: 0 },
+      {
+        role: "toolResult",
+        toolCallId: "tc1",
+        toolName: "bash",
+        content: [{ type: "text", text: "big output" }],
+        isError: false,
+        timestamp: 1,
+      },
+    ];
+    const first = pruneMessages(build(), indexer);
+    const second = pruneMessages(build(), indexer);
+    expect(JSON.stringify(second.messages)).toBe(JSON.stringify(first.messages));
+  });
+
   it("returns original array reference when nothing is summarized or compressed", () => {
     const indexer = makeMockIndexer();
     const messages = [{ role: "user", content: "hello", timestamp: 1 }];

package/src/reload-rearm.integration.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, mock } from "bun:test";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as actualCompat from "@earendil-works/pi-ai/compat";
@@ -150,6 +150,44 @@ function pendingBatchEntries(toolCallId: string, text: string, timestamp: number
   ];
 }
 
+function textOnlyTurns(count: number, startTs: number): any[] {
+  const msgs: any[] = [];
+  let t = startTs;
+  for (let i = 0; i < count; i++) {
+    msgs.push({ type: "message", message: { role: "user", content: [{ type: "text", text: `turn ${i}` }], timestamp: (t += 1000) } });
+    msgs.push({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `answer ${i}` }], timestamp: (t += 1000) } });
+  }
+  return msgs;
+}
+
+function frontierEntry(turnIndex: number, toolCallId: string): any {
+  return {
+    type: "custom",
+    customType: "context-prune-frontier",
+    data: {
+      lastAttemptedToolCallId: toolCallId,
+      lastAttemptedToolName: "read",
+      lastAttemptedTurnIndex: turnIndex,
+      lastAttemptedTimestamp: Date.now(),
+      attemptedBatchCount: 1,
+      attemptedToolCallCount: 1,
+      rawCharCount: 1000,
+      summaryCharCount: 100,
+      outcome: "summarized",
+    },
+  };
+}
+
+async function fireTurn(handlers: Map<string, any>, ctx: any, branch: any[], toolCallId: string, text: string, runLocalIndex: number) {
+  const t = Date.now();
+  const [, assistant, result] = pendingBatchEntries(toolCallId, text, t);
+  branch.push(assistant, result);
+  await handlers.get("turn_end")!(
+    { message: assistant.message, toolResults: [result.message], turnIndex: runLocalIndex },
+    ctx,
+  );
+}
+
 // Boots a fresh index.ts extension instance against an isolated agent dir +
 // session, mirroring the fixtures shared across the three scenarios below.
 //
@@ -288,6 +326,110 @@ async function boot(options?: Parameters<typeof bootExtension>[0]) {
 }
 
 describe("reload rearm (issue #6)", () => {
+  it("falls back to the run-local index at capture when getBranch throws, and the flush-time rescan re-derives the session-wide index", async () => {
+    const { handlers, ctx, notifications, appended } = await boot();
+
+    await handlers.get("session_start")!({}, ctx);
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+    const healthyGetBranch = ctx.sessionManager.getBranch;
+    ctx.sessionManager.getBranch = () => {
+      throw new Error("boom");
+    };
+
+    await expect(
+      handlers.get("turn_end")!(
+        {
+          message: { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "read", arguments: {} }] },
+          toolResults: [
+            { role: "toolResult", toolCallId: "tc2", toolName: "read", content: [{ type: "text", text: "result" }], timestamp: Date.now() },
+          ],
+          turnIndex: 7,
+        },
+        ctx,
+      ),
+    ).resolves.toBeUndefined();
+    expect(notifications.filter((message) => message.includes("pruner: 1 turn queued"))).toHaveLength(1);
+
+    ctx.sessionManager.getBranch = healthyGetBranch;
+    await handlers.get("message_end")!(
+      { message: { role: "assistant", content: [{ type: "text", text: "done" }] } },
+      ctx,
+    );
+
+    const flushMetrics = appended.find((entry) => entry.type === "context-prune-flush-metrics");
+    expect(flushMetrics).toBeDefined();
+    expect((flushMetrics!.data as any).outcome).not.toBe("error");
+
+    const frontier = appended.find((entry) => entry.type === "context-prune-frontier");
+    expect(frontier).toBeDefined();
+    // The flush-time rescan re-derives the session-wide index; the run-local fallback value never persists.
+    expect((frontier!.data as any).lastAttemptedTurnIndex).toBe(0);
+  });
+
+  it("persists the queued batch's run-local index when the flush itself runs on the getBranch fallback", async () => {
+    const { handlers, ctx, appended } = await boot();
+
+    await handlers.get("session_start")!({}, ctx);
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+    ctx.sessionManager.getBranch = () => {
+      throw new Error("boom");
+    };
+
+    // Long result text so the queued batch clears the oversized-summary guard
+    // and reaches indexer.addBatch (a 6-char result would be skipped-oversized
+    // and leave no index entry to assert against).
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc2", toolName: "read", content: [{ type: "text", text: "x".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 7,
+      },
+      ctx,
+    );
+
+    // getBranch is still down at flush time: capturePendingBatches' catch
+    // branch serves pendingBatches.slice() (index.ts), so the queued batch's
+    // captured run-local index (7) is what reaches persistence.
+    await handlers.get("message_end")!(
+      { message: { role: "assistant", content: [{ type: "text", text: "done" }] } },
+      ctx,
+    );
+
+    const flushMetrics = appended.find((entry) => entry.type === "context-prune-flush-metrics");
+    expect(flushMetrics).toBeDefined();
+    expect((flushMetrics!.data as any).outcome).toBe("summarized");
+
+    const indexEntry = appended.find((entry) => entry.type === "context-prune-index");
+    expect(indexEntry).toBeDefined();
+    expect((indexEntry!.data as any).toolCalls[0].turnIndex).toBe(7);
+
+    const frontier = appended.find((entry) => entry.type === "context-prune-frontier");
+    expect(frontier).toBeDefined();
+    expect((frontier!.data as any).lastAttemptedTurnIndex).toBe(7);
+  });
+
+  it("propagates turn-index derivation errors at turn_end", async () => {
+    const { handlers, ctx, branch } = await boot();
+
+    await handlers.get("session_start")!({}, ctx);
+    branch.push(null);
+
+    await expect(
+      handlers.get("turn_end")!(
+        {
+          message: { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "read", arguments: {} }] },
+          toolResults: [
+            { role: "toolResult", toolCallId: "tc2", toolName: "read", content: [{ type: "text", text: "result" }], timestamp: Date.now() },
+          ],
+          turnIndex: 0,
+        },
+        ctx,
+      ),
+    ).rejects.toThrow();
+  });
+
   it("rearms the turn_end budget gate after a reload so recovered pending work still flushes", async () => {
     const { handlers, ctx, appended } = await boot();
 
@@ -784,6 +926,8 @@ describe("reload rearm (issue #6)", () => {
     expect(flushMetricsEntries.length).toBe(1);
     const fm = flushMetricsEntries[0].data as any;
     expect(fm.trigger).toBe("frontier-gap");
+    // defaultBranch's single tc1 call is summarized+indexed by this flush.
+    expect(fm.stubCount).toBe(1);
     expect(fm.metrics.frontierGapTokens).toBeGreaterThanOrEqual(10);
 
     expect(notifications.some((n) => n.includes("un-pruned tail exceeded frontier gap threshold"))).toBe(true);
@@ -895,6 +1039,9 @@ describe("reload rearm (issue #6)", () => {
     expect(frontierEntries.length).toBe(1);
     const firstFrontier = frontierEntries[0].data as any;
     expect(firstFrontier.lastAttemptedToolCallId).toBe("tc-a");
+    // Turn 2's flush indexed tc-a (1 call) and aliased nothing else.
+    const firstMetrics = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect((firstMetrics[0].data as any).stubCount).toBe(1);
 
     // Grow the branch again (tc-b is still unsummarized/pending after the
     // restore; add tc-c as this turn's new work) — gap stays over threshold.
@@ -1228,12 +1375,47 @@ describe("supersede floor cadence (spec 2026-09-07)", () => {
     const frontierEntries = appended.filter((e) => e.type === "context-prune-frontier");
     expect(frontierEntries.length).toBe(1);
     expect((frontierEntries[0].data as any).outcome).toBe("skipped-trivial");
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(flushMetricsEntries.length).toBe(1);
+    expect((flushMetricsEntries[0].data as any).outcome).toBe("skipped-trivial");
+    expect((flushMetricsEntries[0].data as any).stubCount).toBe(0);
 
     const rendered = await render(branch, handlers, ctx);
     expect(toolResultText(rendered, "r1")).toBe("content-r1");
     expect(toolResultText(rendered, "r2")).toBe("content-r2");
   });
 
+  it("a partially deduped skipped-trivial batch counts only its alias in stubCount", async () => {
+    const R = "R".repeat(400);
+    const branch: any[] = [];
+    const { handlers, ctx, appended } = await boot({ protectedPaths: [PROTECTED_GLOB], branch });
+
+    await handlers.get("session_start")!({}, ctx);
+    await fireTurn(handlers, ctx, branch, "bashOrig", R, 1);
+    expect(appended.some((e) => e.type === "context-prune-index")).toBe(true);
+
+    const assistant = {
+      role: "assistant",
+      content: [
+        { type: "toolCall", id: "bashDup", name: "read", arguments: {} },
+        { type: "toolCall", id: "trivial", name: "read", arguments: {} },
+      ],
+    };
+    const toolResults = [
+      { role: "toolResult", toolCallId: "bashDup", toolName: "read", content: [{ type: "text", text: R }], timestamp: 90 },
+      { role: "toolResult", toolCallId: "trivial", toolName: "read", content: [{ type: "text", text: "" }], timestamp: 91 },
+    ];
+    branch.push({ type: "message", message: assistant }, ...toolResults.map((message) => ({ type: "message", message })));
+    await handlers.get("turn_end")!({ message: assistant, toolResults, turnIndex: 2 }, ctx);
+
+    const aliasEntries = appended.filter((e) => e.type === "context-prune-dedup-alias");
+    expect(aliasEntries.length).toBe(1);
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    const metrics = flushMetricsEntries[flushMetricsEntries.length - 1].data as any;
+    expect(metrics.outcome).toBe("skipped-trivial");
+    expect(metrics.stubCount).toBe(1);
+  });
+
   it("a skipped-oversized batch (summary longer than raw) sets no floor", async () => {
     const branch: any[] = [];
     const { handlers, ctx, appended } = await boot({ protectedPaths: [PROTECTED_GLOB], branch });
@@ -1263,6 +1445,10 @@ describe("supersede floor cadence (spec 2026-09-07)", () => {
     const frontierEntries = appended.filter((e) => e.type === "context-prune-frontier");
     expect(frontierEntries.length).toBe(1);
     expect((frontierEntries[0].data as any).outcome).toBe("skipped-oversized");
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(flushMetricsEntries.length).toBe(1);
+    expect((flushMetricsEntries[0].data as any).outcome).toBe("skipped-oversized");
+    expect((flushMetricsEntries[0].data as any).stubCount).toBe(0);
 
     const rendered = await render(branch, handlers, ctx);
     expect(toolResultText(rendered, "r1")).toBe("content-r1");
@@ -1316,6 +1502,10 @@ describe("supersede floor cadence (spec 2026-09-07)", () => {
     expect(frontierEntries[frontierEntries.length - 1].data && (frontierEntries[frontierEntries.length - 1].data as any).outcome).toBe(
       "skipped-deduped",
     );
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    const dedupMetrics = flushMetricsEntries[flushMetricsEntries.length - 1].data as any;
+    expect(dedupMetrics.outcome).toBe("skipped-deduped");
+    expect(dedupMetrics.stubCount).toBe(1);
     // The alias's own resultTimestamp (90) is <= the older read's (100) — the
     // property that lets it, alone, explain the activation below.
 
@@ -1434,3 +1624,108 @@ describe("supersede floor cadence (spec 2026-09-07)", () => {
     expect(toolResultText(rendered, "r_new")).toBe("content-r_new");
   });
 });
+
+describe("session-wide live turn index (#16)", () => {
+  it("AC8: pre-fix fixture with frontier 83 flushes one eligible live turn past the frontier", async () => {
+    const fixture = readFileSync(join(import.meta.dirname, "fixtures", "gh16-frontier-83.jsonl"), "utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    const { handlers, ctx, appended } = await boot({
+      branch: fixture,
+      autoBudgetThreshold: null,
+      budgetTurnDelta: null,
+      frontierGapThresholdTokens: 100,
+    });
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-live", "x".repeat(800), 0);
+
+    const fm = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(fm.length).toBe(1);
+    expect((fm[0].data as any).trigger).toBe("frontier-gap");
+    expect((fm[0].data as any).outcome).toBe("summarized");
+    expect((fm[0].data as any).stubCount).toBeGreaterThan(0);
+
+    const frontierEntries = appended.filter((e) => e.type === "context-prune-frontier");
+    const next = frontierEntries[frontierEntries.length - 1].data as any;
+    expect(next.lastAttemptedTurnIndex).toBeGreaterThanOrEqual(83);
+  });
+
+  it("AC1: a new run's first batch survives the frontier and reaches the budget gate", async () => {
+    const branch = [...textOnlyTurns(84, 1700000000000), frontierEntry(83, "tc-old")];
+    const { handlers, ctx, appended } = await boot({ branch, autoBudgetThreshold: 0.5 });
+    ctx.getContextUsage = () => ({ tokens: 900000, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-new", "x".repeat(400), 0);
+    const fm = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(fm.length).toBe(1);
+    expect((fm[0].data as any).trigger).toBe("budget");
+    expect((fm[0].data as any).trigger).not.toBe("rearmed");
+  });
+
+  it("AC2: an already-summarized live batch is still dropped (no re-summarization)", async () => {
+    const branch = [...textOnlyTurns(84, 1700000000000), frontierEntry(83, "tc-old")];
+    const { handlers, ctx, appended } = await boot({ branch, autoBudgetThreshold: 0.5 });
+    ctx.getContextUsage = () => ({ tokens: 900000, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-new", "x".repeat(400), 0);
+    const callsAfterFirst = summarizerCalls;
+    expect(appended.filter((e) => e.type === "context-prune-flush-metrics").length).toBe(1);
+    const [assistant, result] = ctx.sessionManager.getBranch().slice(-2);
+    await handlers.get("turn_end")!({ message: assistant.message, toolResults: [result.message], turnIndex: 1 }, ctx);
+    expect(summarizerCalls).toBe(callsAfterFirst);
+    expect(appended.filter((e) => e.type === "context-prune-flush-metrics").length).toBe(1);
+  });
+
+  it("AC3: above-frontier live batches in a continuing run keep flushing", async () => {
+    const branch = [...textOnlyTurns(84, 1700000000000), frontierEntry(83, "tc-old")];
+    const { handlers, ctx, appended } = await boot({ branch, autoBudgetThreshold: 0.5 });
+    ctx.getContextUsage = () => ({ tokens: 900000, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-a", "a".repeat(400), 0);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-b", "b".repeat(400), 1);
+    const fm = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(fm.length).toBe(2);
+    expect((fm[1].data as any).trigger).toBe("budget");
+  });
+
+  it("AC4: equal-index partial turn keeps only the suffix after the recorded call", async () => {
+    const branch = [...textOnlyTurns(2, 1700000000000), frontierEntry(2, "tc-2")];
+    const { handlers, ctx, appended } = await boot({ branch, autoBudgetThreshold: 0.5 });
+    ctx.getContextUsage = () => ({ tokens: 900000, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+    const t = Date.now();
+    const assistant = { type: "message", message: { role: "assistant", content: [
+      { type: "toolCall", id: "tc-1", name: "read", arguments: {} },
+      { type: "toolCall", id: "tc-2", name: "read", arguments: {} },
+      { type: "toolCall", id: "tc-3", name: "read", arguments: {} },
+    ] }, timestamp: t };
+    const results = ["tc-1", "tc-2", "tc-3"].map((id, i) => ({
+      type: "message", message: { role: "toolResult", toolCallId: id, toolName: "read", content: [{ type: "text", text: "x".repeat(400) }], timestamp: t + 1 + i },
+    }));
+    ctx.sessionManager.getBranch().push(assistant, ...results);
+    await handlers.get("turn_end")!({ message: assistant.message, toolResults: results.map((r) => r.message), turnIndex: 0 }, ctx);
+    const fm = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(fm.length).toBe(1);
+    expect((fm[0].data as any).stubCount).toBe(1);
+    const indexEntries = appended.filter((e) => e.type === "context-prune-index");
+    const indexPayload = JSON.stringify(indexEntries.map((e) => e.data));
+    expect(indexPayload).toContain("tc-3");
+    expect(indexPayload).not.toContain("tc-1");
+  });
+
+  it("AC7: frontier-gap fires on the second post-reply turn, not before", async () => {
+    const branch = [...textOnlyTurns(51, 1700000000000), frontierEntry(50, "tc-old")];
+    const { handlers, ctx, appended } = await boot({ branch, autoBudgetThreshold: null, budgetTurnDelta: null, frontierGapThresholdTokens: 1000 });
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+    await handlers.get("session_start")!({}, ctx);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-g1", "g".repeat(3500), 0);
+    expect(appended.some((e) => e.type === "context-prune-flush-metrics")).toBe(false);
+    await fireTurn(handlers, ctx, ctx.sessionManager.getBranch(), "tc-g2", "g".repeat(3500), 1);
+    const fm = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(fm.length).toBe(1);
+    expect((fm[0].data as any).trigger).toBe("frontier-gap");
+  });
+});

package/src/types.ts

@@ -732,6 +732,8 @@ export interface FlushMetricsEntry {
   /** Batches after rescan+trim, before processing. */
   capturedBatches: number;
   processedBatches: number;
+  /** Tool calls this flush newly made stub-eligible: dedup aliases on processed batches plus calls of batches actually indexed. 0 when nothing was indexed or aliased (all-trivial/oversized, or failure before any batch was processed). */
+  stubCount: number;
   outcome: "summarized" | "skipped-oversized" | "skipped-deduped" | "skipped-trivial" | "empty" | "error";
   /** Computed at flush ENTRY (pre-flush pressure). */
   metrics: ContextMetricsSnapshot;