pi-condense 2.10.3 → 2.10.4

package/CHANGELOG.md

@@ -7,6 +7,19 @@ 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).

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:

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/package.json

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

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");
+  }
+}