pi-condense 2.10.2 → 2.10.4

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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.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).
+
 ## [2.10.2] - 2026-09-06
 
 - Protect `gauntlet-overrides.md` reads by default alongside skill files, including `.pi/` and `doc/` paths, so per-repo harness contracts survive context pruning. User-supplied `protectedPaths` still replaces the defaults; path matching remains limited to `args.path`.

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, 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:
@@ -567,6 +583,8 @@ graph LR
 captured batches (from turn_end or session scan)
   │
   ├─ 1. Protected-tools/paths filter   (capture-time, see below)
+  │     newest read per protected path stays verbatim; older reads of the same
+  │     path are stubbed at render time once the cache is cold anyway (see § Supersession)
   │     tool calls whose toolName is in protectedTools, OR whose args.path
   │     matches any protectedPaths glob, never enter the batch
   │
@@ -614,7 +632,7 @@ Implementation: `src/pruner.ts` `pruneMessages(messages, indexer)` returns `{ me
 
 ### Protected tools & paths
 
-A tool call is protected if **either** its `toolName` is in `protectedTools` **or** its `args.path` (string) matches any glob in `protectedPaths`. Protected calls are filtered out **at capture time** - they never enter the `pendingBatches` queue, so their raw `ToolResultMessage` stays verbatim in future LLM context.
+A tool call is protected if **either** its `toolName` is in `protectedTools` **or** its `args.path` (string) matches any glob in `protectedPaths`. Protected calls are filtered out **at capture time** - they never enter the `pendingBatches` queue, so their raw `ToolResultMessage` stays verbatim in future LLM context until a newer read of the same path supersedes it (below).
 
 **`protectedTools: string[]`** (default `[]`) - allowlist of tool names. Covers tools whose output is a small handle that must be reused byte-for-byte (e.g. a session-id) or planning tools like `todowrite` / `todoread`.
 
@@ -624,6 +642,10 @@ Glob contract: full-path match against the raw `args.path` string with `\` norma
 
 **Render-time re-check:** stub replacement runs in-flight on every turn (`pruneMessages`). If a tool call's persisted `args` now satisfy `isProtected` (e.g. a pattern was added mid-session), the stub is skipped and the raw result is left verbatim - this repairs already-summarized records in existing sessions with no schema change. Declared limitation: records inside already-compressed chains (`context-prune-chain` entries) are NOT repaired - their `protectedToolCallIds` set is fixed at compression time (forward-only). Dedup-alias edge: an alias resolving to an unprotected original stays stubbed.
 
+**Supersession (phase 1b, `src/supersede.ts`):** protected calls are never indexed, so content-hash dedup never sees them. Instead, at render time only the **newest** protected occurrence per normalized `args.path` (backslash -> slash; `offset`/`limit` ignored) stays verbatim; every earlier occurrence with a paired result becomes the one-line stub `[Superseded: <path> was read again later in this conversation - see the newer read. Re-read the file if this earlier content is needed.]`. The stub keeps `toolCallId`/`toolName`/`timestamp`, so pi-ai's orphan repair never fires; the assistant `toolCall` block is untouched. A call without a paired result never participates (an aborted call cannot steal the win). Recovery is "re-read the file" - no `t<N>` ref. Provider tool-call ids repeat across turns and an aborted call has no result, so a result is paired only with the same-id call in the immediately preceding assistant message (the per-turn open-set model orphan-sweep uses) - never by a global per-id cursor.
+
+**Cadence (prompt-cache economics):** a superseded read is stubbed only when the pruner is already rewriting at or before its position - `floor` is the earliest result timestamp phase 1 will stub on the next render (indexed batches, plus dedup aliases registered in the pre-flush pass - those are stubbed by phase 1 whatever their batch's outcome; a `skipped-trivial`/`skipped-oversized` batch's own calls set none) or the `startUserTimestamp` of a chain compressed this turn - or on a guaranteed-cold event: `session_start`, `session_tree`, `model_select`, `session_compact`, `thinking_level_select` (`floor = 0`, activate all). Activation is session-sticky (in-memory `occKey` set, cleared on `session_start`/`session_tree`); between those moments a freshly superseded copy stays verbatim on purpose, since a mid-prefix rewrite re-bills the whole tail once. `isProtected` is evaluated live, so a path that stops matching `protectedPaths` drops out of supersession and rejoins the normal pipeline. No config key: supersession is on whenever protection is. Spec: `doc/specs/2026-09-07-protected-path-supersede.md`.
+
 Names and patterns that don't match any captured tool call are silently ignored.
 
 ### Eager single-result spill
@@ -691,7 +713,7 @@ The last attempted prune boundary is persisted as `context-prune-frontier` so `f
 - **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.
 - **Configurable summarizer thinking (`summarizerThinking`):** trade summary cost / latency for quality (`off` / `minimal` / `low` / `medium` / `high` / `xhigh`). `default` omits the option entirely so the provider chooses.
 - **Cumulative stats:** `context-prune-stats` entries track input/output tokens and cost of every summarizer call; full detail surfaces in `/pruner stats`. Cost is also emitted on the `cost:external` pi.events channel for external aggregators (cumulative per session, live only).
-- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all four phases in a single point (stub-replace, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
+- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all five phases in a single point (stub-replace, supersede, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
 - **Live progress for `/pruner now`:** an `aboveEditor` widget shows one row per pending batch with braille spinner, streamed summary-char count, and ✓ / ⚠ status.
 
 ### Summarizer outage fallback
@@ -884,6 +906,7 @@ A **closed chain** is a span of messages from one user message - or a non-pruner
 raw messages from session
   │
   ├─ [1] tool-result stub-replace   (per-batch; existing)
+  ├─ [1b] supersede                (older protected reads of a re-read path -> stub; see § Supersession)
   ├─ [2] error-purge                (phase 2)
   ├─ [3] chain-range-prune          (runs AFTER stubs)
   │        resolve each entry to a positional index range
@@ -966,6 +989,8 @@ Chain compression does not delete data from the session JSONL. The original tool
 
 The protected output is relocated (moved), not copied — the original `ToolResultMessage` is dropped with the rest of the middle turns. The text stays in LLM context because it is embedded in the surviving synthetic block. It is NOT registered in the tool-call index and is NOT recoverable via `context_tree_query`; it does not need to be, because it is present verbatim.
 
+Relocation reads the array **after** phase 1b, so a protected read that has been superseded relocates as its one-line stub, not the verbatim body - the verbatim copy is the newer read elsewhere in context.
+
 The `context-prune-chain` session entry carries the matching `protectedToolCallIds` array so `session_start` reconstruction can re-embed the outputs on reload.
 
 **Rejected alternative:** skip compression for any chain that contains a protected tool. Rejected because `todowrite`/`todoread` recur in most chains for opted-in users, so this strategy would forfeit most chain compression for the people who most need `protectedTools`.
@@ -1089,7 +1114,7 @@ Error purge replaces those arg bodies with compact stubs after the error has coo
 **Transform position:** Error purge runs in Phase 2, after stub-replace and before chain range prune.
 
 ```
-[stub-replace] → [error-purge] → [chain-range-prune] → [orphan-sweep]
+[stub-replace] → [supersede] → [error-purge] → [chain-range-prune] → [orphan-sweep]
 ```
 
 **Config keys:**

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 |
 |---|---|---|
@@ -169,7 +169,7 @@ Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_A
 | `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
 | `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn`; the trigger point is capped at 300k tokens |
 | `frontierGapThresholdTokens` | `null` | Opt-in absolute-token flush trigger: fires at `turn_end` once the un-pruned tail past the prune frontier reaches N tokens, regardless of window size; recommended starting value `80000` |
-| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md", "**/gauntlet-overrides.md"]` | Tool names / path globs that are never pruned |
+| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md", "**/gauntlet-overrides.md"]` | Tool names / path globs that are never summarized; only the newest read per protected path stays verbatim (older reads of the same path are stubbed once the prompt cache is cold anyway) |
 | `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
 
 The default also protects reads of [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet)'s per-repo `gauntlet-overrides.md` so the repo's harness contract stays available for gate decisions after pruning.

package/index.ts

@@ -45,6 +45,7 @@ import { StatsAccumulator, emitExternalCost } from "./src/stats.js";
 import { PruneFrontierTracker } from "./src/frontier.js";
 import { BlockRefIssuer } from "./src/block-refs.js";
 import { compressEligible } from "./src/chain-compressor.js";
+import { createSupersedeState, earliestChainStart, earliestResultTimestamp, lowerFloor } from "./src/supersede.js";
 import { detectChains, withClosingMessage } from "./src/chain-detector.js";
 import { inGraceRecoveryToolCallIds } from "./src/recovery-grace.js";
 import { shouldBudgetFlush, shouldDeltaFlush, shouldFrontierGapFlush, usageFraction } from "./src/budget.js";
@@ -82,6 +83,10 @@ export default function (pi: ExtensionAPI) {
   // (dedup'd across the session's lifetime, not per-render).
   const diagnostics = new DiagnosticSink((type, data) => pi.appendEntry(type, data));
 
+  // Newest-protected-read-wins state (spec 2026-09-07). In-memory only: on
+  // session_start / session_tree the cold floor re-activates everything.
+  const supersede = createSupersedeState();
+
   // Pending batches — accumulated until the prune trigger fires
   const pendingBatches: CapturedBatch[] = [];
   let isFlushing = false;
@@ -454,6 +459,12 @@ export default function (pi: ExtensionAPI) {
       const dedupedBatches: CapturedBatch[] = [];
       let firstFailureIndex = -1;
 
+      // Every tool call phase 1 will stub on the next render is a floor
+      // source for supersession: dedup aliases regardless of batch outcome,
+      // plus the batch's own calls when the batch was actually indexed.
+      const floorSources: import("./src/types.js").CapturedToolCall[] = [];
+      for (let i = 0; i < batches.length; i++) floorSources.push(...dedupedPerBatch[i].toolCalls);
+
       for (let i = 0; i < batches.length; i++) {
         const result = results[i];
         if (result === null) {
@@ -530,6 +541,7 @@ 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);
+            floorSources.push(...batch.toolCalls);
           } else {
             oversizedBatches.push(batch);
           }
@@ -546,6 +558,8 @@ export default function (pi: ExtensionAPI) {
         processedBatches.push(batch);
       }
 
+      lowerFloor(supersede, earliestResultTimestamp(floorSources));
+
       // Restore unprocessed batches (those at and after the first failure)
       if (firstFailureIndex >= 0) {
         restoreBatches(batches.slice(firstFailureIndex));
@@ -664,6 +678,7 @@ export default function (pi: ExtensionAPI) {
             inGrace,
           );
           if (compressedEntries.length > 0) {
+            lowerFloor(supersede, earliestChainStart(compressedEntries));
             statsAccum.addChainsCompressed(compressedEntries.length);
             statsAccum.persist(pi);
             emitExternalCost(pi, statsAccum);
@@ -785,6 +800,8 @@ export default function (pi: ExtensionAPI) {
     statsAccum.reconstructFromSession(ctx);
     fallbackController.reset();
     diagnostics.reset();
+    supersede.activated.clear();
+    supersede.floor = 0;
 
     // Rebuild prune frontier from persisted session entries
     frontier.reconstructFromSession(ctx);
@@ -826,6 +843,8 @@ export default function (pi: ExtensionAPI) {
     blockRefs.rebuildFrom(indexer.getChainEntries().map((e) => e.blockId));
     statsAccum.reconstructFromSession(ctx);
     diagnostics.reset();
+    supersede.activated.clear();
+    supersede.floor = 0;
     frontier.reconstructFromSession(ctx);
     // Pending batches belong to the old branch — discard them
     pendingBatches.length = 0;
@@ -842,6 +861,18 @@ export default function (pi: ExtensionAPI) {
     setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
   });
 
+  // Cache is a per-model prefix; these three moments are cold regardless, so
+  // activating every pending supersession here costs no extra cache miss.
+  pi.on("model_select", async () => {
+    supersede.floor = 0;
+  });
+  pi.on("session_compact", async () => {
+    supersede.floor = 0;
+  });
+  pi.on("thinking_level_select", async () => {
+    supersede.floor = 0;
+  });
+
   // ── turn_end: capture batch, flush immediately or queue ──────────────────
   pi.on("turn_end", async (event, ctx) => {
     if (!currentConfig.value.enabled) return;
@@ -994,7 +1025,7 @@ export default function (pi: ExtensionAPI) {
 
     // pruneMessages is the single source of truth for "is there work to do".
     // It returns the original array reference (pruned: false) only when none of
-    // the four phases changed anything; index/registry emptiness alone does not
+    // the five phases changed anything; index/registry emptiness alone does not
     // imply a no-op, since error-purge (phase 2) prunes independently of them.
     // Calling it unconditionally is safe and avoids a split gate here.
     const result = pruneMessages(
@@ -1005,6 +1036,7 @@ export default function (pi: ExtensionAPI) {
       currentConfig.value,
       currentConfig.value.recoveryGraceTurns,
       diagnostics,
+      { state: supersede, isProtected: protectionPredicate },
     );
     if (result.pruned) {
       messages = result.messages;
@@ -1046,6 +1078,7 @@ export default function (pi: ExtensionAPI) {
       inGrace,
     );
     if (result.compressedEntries.length > 0) {
+      lowerFloor(supersede, earliestChainStart(result.compressedEntries));
       statsAccum.addChainsCompressed(result.compressedEntries.length);
       statsAccum.persist(pi);
       emitExternalCost(pi, statsAccum);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.2",
+  "version": "2.10.4",
   "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/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");
+  });
+});