pi-condense 2.10.0 → 2.10.2

package/CHANGELOG.md

@@ -7,6 +7,14 @@ 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.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`.
+
+## [2.10.1] - 2026-09-02
+
+- **Spill sidecar basenames capped at 255 bytes ([#14](https://github.com/jjuraszek/pi-condense/issues/14)).** Providers emitting 300+ char tool-call ids drove `blobPathFor` past the filesystem basename limit: eager spill failed silently (`ENAMETOOLONG` caught, oversized result stayed inline and bloated context) and the deterministic backfill aborted fail-closed. Fitting names stay byte-identical; over-limit names become `<234-byte sanitized prefix>.<16-hex sha1 of the unsanitized occurrence key>.txt` (exactly 255 bytes). The `.` separator is unreachable by `sanitizeId`, so capped names are namespace-disjoint from short-key names by construction - no probe, no migration, persisted `spillPath` read-back unchanged. Spec: `doc/specs/2026-09-02-gh-14-spill-filename-cap.md` (partially supersedes the 2026-06-02 spill spec's filename derivation).
+
 ## [2.10.0] - 2026-09-01
 
 - **Custom-message chain anchors ([#13](https://github.com/jjuraszek/pi-condense/issues/13)).** A non-pruner `role: "custom"` message (`customType` not prefixed `context-prune-`) can now open a chain, but only while the chain detector is idle - a non-pruner custom seen mid-chain stays passthrough, not a new anchor. `resolveRange` accepts these as start anchors fail-closed; persisted `custom_message` steers reach chain detection through a shared projection (`src/batch-capture.ts` `projectBranchMessages`); in `agent-message` batching, eligible customs also bound summary groups.

package/PRUNING.md

@@ -618,7 +618,7 @@ A tool call is protected if **either** its `toolName` is in `protectedTools` **o
 
 **`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`.
 
-**`protectedPaths: string[]`** (default `["**/skills/**/*.md"]`) - glob list matched against `args.path`. Designed for skill files that carry multi-step workflow gates; summarizing them is categorically lossy. Non-string or missing `path` arguments never match. Set `[]` to disable. Edit with `/pruner protected-paths`.
+**`protectedPaths: string[]`** (default `["**/skills/**/*.md", "**/gauntlet-overrides.md"]`) - glob list matched against `args.path`. Designed for skill files that carry multi-step workflow gates; summarizing them is categorically lossy. Non-string or missing `path` arguments never match. Set `[]` to disable. Edit with `/pruner protected-paths`.
 
 Glob contract: full-path match against the raw `args.path` string with `\` normalized to `/`. `*` and `?` match within a segment (no `/`); `**` crosses segments; `**/` also matches zero directories (so `**/SKILL.md` matches a bare relative `SKILL.md`). Case-sensitive. All other characters are regex-escaped literals.
 
@@ -630,7 +630,7 @@ Names and patterns that don't match any captured tool call are silently ignored.
 
 `spillThreshold: number` (default `65536`) is a capture-time safeguard for outsized single tool results (e.g. a 1 MB web fetch, a full binary diff). When a single `ToolResultMessage`'s `resultText.length` reaches the threshold, the result is spilled immediately at `turn_end` — before the pending-queue trim and before any LLM call.
 
-**Sidecar location:** `<sessionDir>/<sessionId>-blobs/<sanitizedToolCallId>.txt`.
+**Sidecar location:** `<sessionDir>/<sessionId>-blobs/<sanitizedToolCallId>.txt`. When that basename would exceed 255 bytes (very long provider tool-call ids), it is capped to exactly 255 bytes as `<first 234 bytes of the sanitized key>.<16-hex sha1 of the unsanitized occurrence key>.txt`; names that already fit are unchanged.
 
 **Index entry:** `addBatch` is called synchronously with the spilled body (no LLM round-trip). The record is immediately `isSummarized = true`; the pruner emits a mechanical file-pointer stub:
 

package/README.md

@@ -169,9 +169,11 @@ 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"]` | Tool names / path globs that are never pruned |
+| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md", "**/gauntlet-overrides.md"]` | Tool names / path globs that are never pruned |
 | `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.
+
 The full settings JSON, every key, the commands table, footer widget states, spilled-output details, and the summarizer-model-by-plan table live in **[doc/configuration.md](doc/configuration.md)**.
 
 ## Relationship to the rest of the platform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.0",
+  "version": "2.10.2",
   "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.ts

@@ -256,7 +256,7 @@ function protectedToolsDescription(config: ContextPruneConfig): string {
 }
 
 function protectedPathsDescription(config: ContextPruneConfig): string {
-  return `Glob patterns matched against a tool call's \`args.path\`; matching outputs are NEVER pruned. Currently: ${protectedToolsDisplay(config.protectedPaths)}. Edit via \`/pruner protected-paths\` (interactive) or \`/pruner protected-paths <comma-separated globs>\`. Set to 'none' to disable (kill switch). Default protects skill files: **/skills/**/*.md`;
+  return `Glob patterns matched against a tool call's \`args.path\`; matching outputs are NEVER pruned. Currently: ${protectedToolsDisplay(config.protectedPaths)}. Edit via \`/pruner protected-paths\` (interactive) or \`/pruner protected-paths <comma-separated globs>\`. Set to 'none' to disable (kill switch). Default protects skill files and per-repo gauntlet overrides: **/skills/**/*.md, **/gauntlet-overrides.md`;
 }
 
 const HELP_TEXT = `pruner — automatically summarizes tool-call outputs to keep context lean.

package/src/config.test.ts

@@ -35,6 +35,22 @@ async function writeContextPrune(overrides: Record<string, unknown>): Promise<vo
   await writeFile(settingsPath(), JSON.stringify({ contextPrune: overrides }));
 }
 
+describe("loadConfig protectedPaths", () => {
+  it("uses the defaults when unset", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.protectedPaths).toEqual(DEFAULT_CONFIG.protectedPaths);
+  });
+
+  it("replaces defaults with user-supplied paths, including an empty list", async () => {
+    for (const protectedPaths of [["**/custom.md"], []]) {
+      await writeContextPrune({ protectedPaths });
+      const config = await loadConfig();
+      expect(config.protectedPaths).toEqual(protectedPaths);
+    }
+  });
+});
+
 describe("loadConfig recoveryGraceTurns normalization", () => {
   it("preserves an explicit 0", async () => {
     await writeContextPrune({ recoveryGraceTurns: 0 });

package/src/oversized-spill.integration.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect } from "bun:test";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { ToolCallIndexer } from "./indexer.js";
+import { occKey } from "./occurrence-key.js";
 import { spillOversizedBatch, blobPathFor } from "./spill.js";
 import { pruneMessages } from "./pruner.js";
 import type { CapturedBatch } from "./types.js";
@@ -75,4 +76,51 @@ describe("oversized spill end-to-end", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  it("long-id record survives the backfill -> restart round trip (AC4)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-e2e-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const entries: any[] = [];
+      const appendEntry = (customType: string, data?: unknown) => {
+        entries.push({ type: "custom", customType, data });
+      };
+      const longId = "toolu_" + "q".repeat(494); // 500 chars
+      const body = "BACKFILL BODY\n".repeat(200);
+      const rec: any = {
+        toolCallId: longId, toolName: "bash", args: { command: "ls" },
+        resultText: body, isError: false, turnIndex: -1, timestamp: 1000, resultTimestamp: 1000,
+      };
+
+      // 1. backfill write: must not throw (fail-closed path), basename capped
+      await indexer.backfillChainRecords([rec], {
+        spillThreshold: 10, spillPreviewBytes: 16, sessionDir: dir, sessionId: "sid", appendEntry,
+      });
+      expect(rec.spillPath).toBeTruthy();
+      expect(Buffer.byteLength(basename(rec.spillPath), "utf8")).toBeLessThanOrEqual(255);
+
+      // 2. persisted index entry exists (backfilled shape)
+      expect(entries.some((e) => e.customType === CUSTOM_TYPE_INDEX && e.data.backfilled)).toBe(true);
+
+      // 3. restart: fresh indexer reconstructs from persisted entries only
+      const rebuilt = new ToolCallIndexer();
+      rebuilt.reconstructFromSession({ sessionManager: { getBranch: () => entries } } as any);
+      const restored = rebuilt.getRecord(occKey(longId, 1000))!;
+      expect(restored.spillPath).toBe(rec.spillPath);
+
+      // 4. read-back of the restored persisted path equals the original body
+      expect(await readFile(restored.spillPath!, "utf-8")).toBe(body);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("capped names are namespace-disjoint from short-key names", () => {
+    const cappedPath = blobPathFor("/s", "sid", "a".repeat(300));
+    const stem = basename(cappedPath).slice(0, -".txt".length);
+    // sanitizeId can never emit ".", so no short key maps onto a capped name -
+    // even the short key spelled exactly like the capped stem.
+    expect(stem).toContain(".");
+    expect(blobPathFor("/s", "sid", stem)).not.toBe(cappedPath);
+  });
 });

package/src/protected.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { globToRegExp, isProtected } from "./protected.js";
+import { DEFAULT_CONFIG } from "./types.js";
 
 describe("globToRegExp", () => {
   test("** crosses path segments", () => {
@@ -33,6 +34,27 @@ describe("globToRegExp", () => {
   });
 });
 
+describe("isProtected defaults", () => {
+  test.each([".pi/gauntlet-overrides.md", "doc/gauntlet-overrides.md"])(
+    "protects reads of %s",
+    (path) => {
+      expect(isProtected("read", { path }, DEFAULT_CONFIG)).toBe(true);
+    },
+  );
+
+  test("protects skill reads", () => {
+    expect(isProtected("read", { path: "/h/skills/x/SKILL.md" }, DEFAULT_CONFIG)).toBe(true);
+  });
+
+  test("does not protect sibling settings reads", () => {
+    expect(isProtected("read", { path: ".pi/settings.json" }, DEFAULT_CONFIG)).toBe(false);
+  });
+
+  test("does not infer paths from bash commands", () => {
+    expect(isProtected("bash", { command: "cat .pi/gauntlet-overrides.md" }, DEFAULT_CONFIG)).toBe(false);
+  });
+});
+
 describe("isProtected", () => {
   const cfg = { protectedTools: ["todowrite"], protectedPaths: ["**/skills/**/*.md"] };
 

package/src/spill.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "bun:test";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { sanitizeId, blobDirFor, blobPathFor, headPreview, spillOversizedBatch } from "./spill.js";
 import { ToolCallIndexer } from "./indexer.js";
 import { registerQueryTool } from "./query-tool.js";
@@ -24,6 +24,41 @@ describe("blobDirFor / blobPathFor", () => {
   });
 });
 
+describe("blobPathFor byte cap (gh-14)", () => {
+  const nameBytes = (p: string) => Buffer.byteLength(basename(p), "utf8");
+
+  it("251-byte sanitized base keeps today's formula (AC5 boundary, just-under)", () => {
+    const id = "a".repeat(251);
+    const p = blobPathFor("/s", "sid", id);
+    expect(p).toBe(join("/s", "sid-blobs", `${id}.txt`));
+    expect(nameBytes(p)).toBe(255);
+  });
+
+  it("252-byte sanitized base is capped to exactly 255 bytes (AC5 boundary, just-over)", () => {
+    const p = blobPathFor("/s", "sid", "a".repeat(252));
+    expect(nameBytes(p)).toBe(255);
+    expect(basename(p)).toMatch(/^a{234}\.[0-9a-f]{16}\.txt$/);
+  });
+
+  it("is deterministic: same long key -> identical path", () => {
+    const key = "x".repeat(500);
+    expect(blobPathFor("/s", "sid", key)).toBe(blobPathFor("/s", "sid", key));
+  });
+
+  it("two long ids sharing the first 300 chars map to distinct filenames (AC3)", () => {
+    const a = "t".repeat(300) + "A".repeat(200);
+    const b = "t".repeat(300) + "B".repeat(200);
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+
+  it("hashes the unsanitized key: long ids that sanitize identically stay distinct", () => {
+    const a = "p".repeat(300) + "/x";
+    const b = "p".repeat(300) + "\\x";
+    expect(sanitizeId(a)).toBe(sanitizeId(b));
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+});
+
 describe("headPreview", () => {
   it("returns the whole string when under the byte cap", () => {
     expect(headPreview("hello", 1024)).toBe("hello");
@@ -206,4 +241,39 @@ describe("spillOversizedBatch", () => {
       await expect(readFile(blobPathFor(dir, "sid", "tc2"), "utf-8")).rejects.toBeDefined();
     } finally { await rm(dir, { recursive: true, force: true }); }
   });
+
+  it("spills a 500-char tool-call id: file created, capped basename, record mutated (AC1)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494); // 500 chars
+      const body = "LONG-ID BODY ".repeat(10);
+      const batch = mkBatch([{ toolCallId: longId, toolName: "fetch", args: {}, resultText: body, isError: false, resultTimestamp: 1150 }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.has(longId)).toBe(true);
+      const rec = indexer.getRecord(occKey(longId, 1150))!;
+      expect(rec.resultText).toBe("");
+      expect(rec.resultPreview!.length).toBeGreaterThan(0);
+      expect(Buffer.byteLength(basename(rec.spillPath!), "utf8")).toBeLessThanOrEqual(255);
+      expect(await readFile(rec.spillPath!, "utf-8")).toBe(body);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  it("same 500-char id at two occurrences spills to two distinct files (AC2)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494);
+      const noDedup = { ...cfg, dedupByContentHash: false };
+      const b1 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "FIRST".repeat(20), isError: false, resultTimestamp: 1150 }]);
+      const b2 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "SECOND".repeat(20), isError: false, resultTimestamp: 3150 }]);
+      await spillOversizedBatch({ batch: b1, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      await spillOversizedBatch({ batch: b2, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      const rec1 = indexer.getRecord(occKey(longId, 1150))!;
+      const rec2 = indexer.getRecord(occKey(longId, 3150))!;
+      expect(rec1.spillPath).not.toBe(rec2.spillPath);
+      expect(await readFile(rec1.spillPath!, "utf-8")).toBe("FIRST".repeat(20));
+      expect(await readFile(rec2.spillPath!, "utf-8")).toBe("SECOND".repeat(20));
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
 });

package/src/spill.ts

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import { hashToolResult } from "./content-hash.js";
@@ -15,7 +16,18 @@ export function blobDirFor(sessionDir: string, sessionId: string): string {
 }
 
 export function blobPathFor(sessionDir: string, sessionId: string, toolCallId: string): string {
-  return join(blobDirFor(sessionDir, sessionId), `${sanitizeId(toolCallId)}.txt`);
+  const base = sanitizeId(toolCallId);
+  // 255-byte basename cap (gh-14). Uncapped budget: 255 - ".txt" = 251.
+  // Capped: 234-byte prefix + "." + 16-hex sha1 + ".txt" = 255 exactly.
+  // sanitizeId output is ASCII, so slice counts bytes. The "." separator is
+  // unreachable by sanitizeId, keeping capped names disjoint from short-key
+  // names. The hash covers the UNsanitized key so ids that sanitize
+  // identically stay distinct.
+  const name =
+    Buffer.byteLength(base, "utf8") <= 251
+      ? `${base}.txt`
+      : `${base.slice(0, 234)}.${createHash("sha1").update(toolCallId).digest("hex").slice(0, 16)}.txt`;
+  return join(blobDirFor(sessionDir, sessionId), name);
 }
 
 /** Head of `text` capped at `maxBytes` (UTF-8 safe), preferring a line boundary. */

package/src/types.ts

@@ -352,7 +352,8 @@ export interface ContextPruneConfig {
   /**
    * Glob patterns matched against a tool call's `args.path`. Matching calls are
    * protected with identical semantics to protectedTools. Default protects
-   * skill files and their sibling reference docs under any `skills/` dir.
+   * skill files and their sibling reference docs under any `skills/` dir,
+   * plus per-repo `gauntlet-overrides.md` files.
    * Kill switch: set to [] in settings.json (`contextPrune.protectedPaths`).
    */
   protectedPaths: string[];
@@ -562,7 +563,7 @@ export const DEFAULT_CONFIG: ContextPruneConfig = {
   summarizerIdleTimeoutMs: 20000,
   summarizerMaxTimeoutMs: 180000,
   protectedTools: [],
-  protectedPaths: ["**/skills/**/*.md"],
+  protectedPaths: ["**/skills/**/*.md", "**/gauntlet-overrides.md"],
   chainCompression: {
     enabled: true,
     rollingWindow: 3,