pi-condense 2.5.0 → 2.7.0

package/src/commands.test.ts

@@ -1,17 +1,129 @@
-import { describe, it, expect } from "bun:test";
-import { pruneStatusText, setPruneStatusWidget } from "./commands.js";
-import type { ContextPruneConfig } from "./types.js";
+import { describe, it, expect, mock } from "bun:test";
+import { pruneStatusText, setPruneStatusWidget, registerCommands } from "./commands.js";
+import type { ContextPruneConfig, ContextMetricsSnapshot, SummarizerStats } from "./types.js";
+import { DEFAULT_CONFIG } from "./types.js";
 
 const cfg = (enabled: boolean): ContextPruneConfig => ({ enabled } as ContextPruneConfig);
 const cfgVisible = (enabled: boolean): ContextPruneConfig =>
   ({ enabled, showPruneStatusLine: true } as ContextPruneConfig);
 
-function captureStatus(config: ContextPruneConfig, value?: Parameters<typeof setPruneStatusWidget>[2]): string | undefined {
+function captureStatus(
+  config: ContextPruneConfig,
+  value?: Parameters<typeof setPruneStatusWidget>[2],
+  diagnostics?: Parameters<typeof setPruneStatusWidget>[3],
+  metrics?: Parameters<typeof setPruneStatusWidget>[4],
+): string | undefined {
   let captured: string | undefined;
-  setPruneStatusWidget({ ui: { setStatus: (_id, text) => { captured = text; } } }, config, value);
+  setPruneStatusWidget({ ui: { setStatus: (_id, text) => { captured = text; } } }, config, value, diagnostics, metrics);
   return captured;
 }
 
+// ── /pruner command handler harness (registerCommands) ──────────────────────
+// Drives the real switch-statement handler registered by registerCommands,
+// with all injected collaborators stubbed. This is the seam for exercising
+// /pruner subcommands without booting the full index.ts extension.
+function setupPrunerCommand(overrides: {
+  capturePendingBatches?: () => any[];
+  flushPending?: (ctx: any, options?: any) => Promise<any>;
+  getRearmed?: () => boolean;
+  getContextMetrics?: (ctx: any) => ContextMetricsSnapshot;
+} = {}) {
+  let handler: (args: string, ctx: any) => Promise<void>;
+  const notifications: { message: string; type?: string }[] = [];
+  const flushCalls: any[] = [];
+
+  const flushPending =
+    overrides.flushPending ??
+    (async (_ctx: any, options?: any) => {
+      flushCalls.push(options);
+      return { ok: false, reason: "empty" };
+    });
+
+  const pi: any = {
+    registerCommand(_name: string, spec: { handler: (args: string, ctx: any) => Promise<void> }) {
+      handler = spec.handler;
+    },
+    registerMessageRenderer() {},
+  };
+
+  const currentConfig = { value: { ...DEFAULT_CONFIG, enabled: true } };
+
+  registerCommands(
+    pi,
+    currentConfig,
+    flushPending,
+    overrides.capturePendingBatches ?? (() => []),
+    () => ({ callCount: 0, totalInputTokens: 0, totalOutputTokens: 0, totalCost: 0 } as SummarizerStats),
+    () => undefined,
+    {} as any,
+    async () => ({ compressedEntries: [], skipped: 0 }),
+    undefined,
+    overrides.getContextMetrics,
+    undefined,
+    overrides.getRearmed,
+  );
+
+  const ctx: any = {
+    ui: {
+      notify(message: string, type?: string) {
+        notifications.push({ message, type });
+      },
+    },
+  };
+
+  return {
+    run: (args: string) => handler(args, ctx),
+    notifications,
+    flushCalls,
+  };
+}
+
+describe("/pruner now (empty capture)", () => {
+  it("invokes flushPending even when nothing is pending, so a flush-metrics entry is recorded", async () => {
+    const harness = setupPrunerCommand({ capturePendingBatches: () => [] });
+    await harness.run("now");
+
+    expect(harness.flushCalls.length).toBe(1);
+    expect(harness.flushCalls[0]).toMatchObject({ previewedBatches: [], trigger: "manual" });
+    expect(harness.notifications[0]?.message).toBe("pruner: nothing pending — no batches to summarize");
+  });
+});
+
+describe("/pruner status context block", () => {
+  const metrics: ContextMetricsSnapshot = {
+    openCycleThinkingTokens: 12000,
+    largestChainSharePct: 62,
+    frontierGapTokens: 195000,
+  };
+
+  it("renders the --- context --- block with all three metrics", async () => {
+    const harness = setupPrunerCommand({ getContextMetrics: () => metrics, getRearmed: () => false });
+    await harness.run("status");
+
+    const text = harness.notifications[0]?.message ?? "";
+    expect(text).toContain("--- context ---");
+    expect(text).toContain("thinking:     12.0k tokens (open segment)");
+    expect(text).toContain("chain share:  62%");
+    expect(text).toContain("frontier gap: 195.0k tokens");
+  });
+
+  it("appends the rearmed: line only when getRearmed() is true", async () => {
+    const armed = setupPrunerCommand({ getContextMetrics: () => metrics, getRearmed: () => true });
+    await armed.run("status");
+    expect(armed.notifications[0]?.message).toContain("rearmed:      yes");
+
+    const notArmed = setupPrunerCommand({ getContextMetrics: () => metrics, getRearmed: () => false });
+    await notArmed.run("status");
+    expect(notArmed.notifications[0]?.message).not.toContain("rearmed:");
+  });
+
+  it("omits the context block entirely when getContextMetrics is unwired", async () => {
+    const harness = setupPrunerCommand();
+    await harness.run("status");
+    expect(harness.notifications[0]?.message).not.toContain("--- context ---");
+  });
+});
+
 describe("pruneStatusText", () => {
   it("disabled config -> 'prune: OFF'", () => {
     expect(pruneStatusText(cfg(false))).toBe("prune: OFF");
@@ -65,3 +177,54 @@ describe("setPruneStatusWidget", () => {
     expect(captureStatus(cfg(true))).toBeUndefined();
   });
 });
+
+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;
+
+  it("omits the diagnostic segment when all counters are zero", () => {
+    expect(pruneStatusText(cfg(true), undefined, zeroDiag)).toBe("prune: ON");
+  });
+
+  it("appends a compact segment when a counter fires, omitting zero kinds", () => {
+    const text = pruneStatusText(cfg(true), undefined, mixedDiag);
+    expect(text).toBe("prune: ON \u00b7 diag u2/o1");
+  });
+
+  it("appends the diagnostic segment to the reclaim form too", () => {
+    const text = pruneStatusText(cfg(true), { beforeChars: 368000, afterChars: 56000 }, mixedDiag);
+    expect(text).toBe("prune: ON \u00b7 92.0k->14.0k (-85%) \u00b7 diag u2/o1");
+  });
+
+  it("setPruneStatusWidget forwards the counters", () => {
+    expect(captureStatus(cfgVisible(true), undefined, { "unresolved-range": 1, "range-id-mismatch": 0, "orphan-sweep": 0 })).toBe(
+      "\u2502 prune: ON \u00b7 diag u1",
+    );
+  });
+});
+
+describe("context metrics suffix on the status line", () => {
+  const metrics: ContextMetricsSnapshot = {
+    openCycleThinkingTokens: 12000,
+    largestChainSharePct: 62,
+    frontierGapTokens: 195000,
+  };
+
+  it("appends a compact think/gap/chain segment when frontierGapTokens > 0", () => {
+    const text = pruneStatusText(cfg(true), undefined, undefined, metrics);
+    expect(text).toContain("\u00b7 think 12.0k \u00b7 gap 195.0k \u00b7 chain 62%");
+  });
+
+  it("omits the suffix when frontierGapTokens is 0", () => {
+    const withZeroGap = { ...metrics, frontierGapTokens: 0 };
+    expect(pruneStatusText(cfg(true), undefined, undefined, withZeroGap)).toBe(
+      pruneStatusText(cfg(true)),
+    );
+  });
+
+  it("composes after the diag suffix when both are present", () => {
+    const mixedDiag = { "unresolved-range": 2, "range-id-mismatch": 0, "orphan-sweep": 1 } as const;
+    const text = pruneStatusText(cfg(true), undefined, mixedDiag, metrics);
+    expect(text).toBe("prune: ON \u00b7 diag u2/o1 \u00b7 think 12.0k \u00b7 gap 195.0k \u00b7 chain 62%");
+  });
+});

package/src/commands.ts

@@ -5,6 +5,8 @@ import {
   type CapturedBatch,
   type ChainCompressionEntry,
   type FlushOptions,
+  type DiagnosticKind,
+  type ContextMetricsSnapshot,
   PRUNE_ON_MODES,
   BATCHING_MODES,
   STATUS_WIDGET_ID,
@@ -57,25 +59,43 @@ class SettingsOverlay extends Container {
 
 // ── Status widget text ──────────────────────────────────────────────────────
 
-export function pruneStatusText(config: ContextPruneConfig, reclaim?: LiveReclaim): string {
+export function pruneStatusText(
+  config: ContextPruneConfig,
+  reclaim?: LiveReclaim,
+  diagnostics?: Record<DiagnosticKind, number>,
+  metrics?: ContextMetricsSnapshot,
+): string {
   if (!config.enabled) return "prune: OFF";
-  if (!reclaim || reclaim.beforeChars <= 0) return "prune: ON";
+  const diag = diagnostics
+    ? [
+        diagnostics["unresolved-range"] ? `u${diagnostics["unresolved-range"]}` : "",
+        diagnostics["range-id-mismatch"] ? `m${diagnostics["range-id-mismatch"]}` : "",
+        diagnostics["orphan-sweep"] ? `o${diagnostics["orphan-sweep"]}` : "",
+      ].filter(Boolean)
+    : [];
+  const suffix = diag.length > 0 ? ` \u00b7 diag ${diag.join("/")}` : "";
+  const metricsSuffix = metrics && metrics.frontierGapTokens > 0
+    ? ` \u00b7 think ${formatCompactCount(metrics.openCycleThinkingTokens)} \u00b7 gap ${formatCompactCount(metrics.frontierGapTokens)} \u00b7 chain ${metrics.largestChainSharePct}%`
+    : "";
+  if (!reclaim || reclaim.beforeChars <= 0) return `prune: ON${suffix}${metricsSuffix}`;
   const beforeTok = Math.round(reclaim.beforeChars / 4);
   const afterTok = Math.round(reclaim.afterChars / 4);
   const reduction = Math.max(0, Math.round((1 - afterTok / beforeTok) * 100));
-  return `prune: ON \u00b7 ${formatCompactCount(beforeTok)}->${formatCompactCount(afterTok)} (-${reduction}%)`;
+  return `prune: ON \u00b7 ${formatCompactCount(beforeTok)}->${formatCompactCount(afterTok)} (-${reduction}%)${suffix}${metricsSuffix}`;
 }
 
 export function setPruneStatusWidget(
   ctx: { ui: { setStatus: (id: string, text?: string) => void } },
   config: ContextPruneConfig,
   value?: LiveReclaim | string,
+  diagnostics?: Record<DiagnosticKind, number>,
+  metrics?: ContextMetricsSnapshot,
 ): void {
   if (!config.showPruneStatusLine) {
     ctx.ui.setStatus(STATUS_WIDGET_ID, undefined);
     return;
   }
-  const text = typeof value === "string" ? value : pruneStatusText(config, value);
+  const text = typeof value === "string" ? value : pruneStatusText(config, value, diagnostics, metrics);
   // Leading-only separator: the footer joins extension status segments with a
   // single space, so a trailing divider collides with the next segment's leading
   // one and renders doubled. One leading bar yields single dividers between
@@ -455,6 +475,10 @@ export function registerCommands(
   getLiveReclaim: () => LiveReclaim | undefined,
   indexer: ToolCallIndexer,
   compactChains: (ctx: ExtensionCommandContext) => Promise<{ compressedEntries: ChainCompressionEntry[]; skipped: number }>,
+  getDiagnosticCounts?: () => Record<DiagnosticKind, number>,
+  getContextMetrics?: (ctx: ExtensionCommandContext) => ContextMetricsSnapshot,
+  getCachedMetrics?: () => ContextMetricsSnapshot | undefined,
+  getRearmed?: () => boolean,
 ): void {
   // Register the /pruner command
   pi.registerCommand("pruner", {
@@ -801,7 +825,7 @@ export function registerCommands(
             }
             currentConfig.value = newConfig;
             saveConfig(newConfig);
-            setPruneStatusWidget(ctx, newConfig, getLiveReclaim());
+            setPruneStatusWidget(ctx, newConfig, getLiveReclaim(), getDiagnosticCounts?.(), getCachedMetrics?.());
             settingsList?.invalidate();
           };
 
@@ -836,7 +860,7 @@ export function registerCommands(
           currentConfig.value = { ...currentConfig.value, enabled: true };
           saveConfig(currentConfig.value);
           ctx.ui.notify("Context pruning enabled.");
-          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim());
+          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.(), getCachedMetrics?.());
           break;
         }
 
@@ -845,7 +869,7 @@ export function registerCommands(
           currentConfig.value = { ...currentConfig.value, enabled: false };
           saveConfig(currentConfig.value);
           ctx.ui.notify("Context pruning disabled.");
-          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim());
+          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.(), getCachedMetrics?.());
           break;
         }
 
@@ -858,8 +882,12 @@ export function registerCommands(
             ? `\n  --- summarizer ---\n  calls:       ${s.callCount}\n  input:       ${formatTokens(s.totalInputTokens)} tokens\n  output:      ${formatTokens(s.totalOutputTokens)} tokens\n  cost:        ${formatCost(s.totalCost)}`
             : "\n  (no summarizer calls yet)";
           const fmtTimeout = (ms: number) => (ms === 0 ? "disabled" : `${Math.round(ms / 1000)}s`);
+          const m = getContextMetrics?.(ctx);
+          const contextLine = m
+            ? `\n  --- context ---\n  thinking:     ${formatTokens(m.openCycleThinkingTokens)} tokens (open segment)\n  chain share:  ${m.largestChainSharePct}%\n  frontier gap: ${formatTokens(m.frontierGapTokens)} tokens${getRearmed?.() ? "\n  rearmed:      yes" : ""}`
+            : "";
           ctx.ui.notify(
-            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  idle to:  ${fmtTimeout(cfg.summarizerIdleTimeoutMs)}\n  max to:   ${fmtTimeout(cfg.summarizerMaxTimeoutMs)}\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}`,
+            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  idle to:  ${fmtTimeout(cfg.summarizerIdleTimeoutMs)}\n  max to:   ${fmtTimeout(cfg.summarizerMaxTimeoutMs)}\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}${contextLine}`,
           );
           break;
         }
@@ -964,7 +992,7 @@ export function registerCommands(
             currentConfig.value = { ...currentConfig.value, pruneOn: modeArg as ContextPruneConfig["pruneOn"] };
           }
           saveConfig(currentConfig.value);
-          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim());
+          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.(), getCachedMetrics?.());
           break;
         }
 
@@ -1011,7 +1039,7 @@ export function registerCommands(
             // tool-result savings; but assistant-message savings (thinking + toolCall args + text)
             // are not counted at all, so the two errors partly cancel. Treat as a rough proxy.
             const droppedChars = compressedEntries.reduce((total, entry) => {
-              const records = indexer.lookupToolCalls(entry.droppedToolCallIds);
+              const records = indexer.lookupToolCalls(entry.droppedOccurrenceKeys ?? entry.droppedToolCallIds);
               return total + records.reduce((s, r) => s + r.resultText.length, 0);
             }, 0);
             const reclaimedTokens = Math.ceil(droppedChars / 4);
@@ -1037,6 +1065,11 @@ export function registerCommands(
           const batches = capturePendingBatches(ctx);
           if (batches.length === 0) {
             ctx.ui.notify("pruner: nothing pending — no batches to summarize", "info");
+            // Still invoke flushPending so its finally-emitted flush-metrics entry
+            // records this attempt (outcome "empty") — the incident's exact
+            // undiagnosable "nothing pending" report is precisely what this log
+            // exists to make diagnosable on recurrence.
+            await flushPending(ctx, { previewedBatches: batches, trigger: "manual" });
             break;
           }
 
@@ -1061,7 +1094,7 @@ export function registerCommands(
 
           // Remove the widget and restore the normal footer status.
           clearWidget();
-          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim());
+          setPruneStatusWidget(ctx, currentConfig.value, getLiveReclaim(), getDiagnosticCounts?.(), getCachedMetrics?.());
 
           if (!result.ok) {
             const suffix = "error" in result && result.error ? ` (${result.error})` : "";

package/src/context-metrics.test.ts

@@ -0,0 +1,335 @@
+import { describe, expect, test } from "bun:test";
+import { computeContextMetrics } from "./context-metrics.js";
+import type { PruneFrontier } from "./types.js";
+
+// ── Minimal message factories (mirrors src/chain-detector.test.ts style) ───
+
+function userMsg(timestamp: number, text = "do the thing"): any {
+  return { role: "user", content: [{ type: "text", text }], timestamp };
+}
+
+function assistantWithTools(timestamp: number, toolCallIds: string[]): any {
+  return {
+    role: "assistant",
+    content: [
+      { type: "text", text: "working..." },
+      ...toolCallIds.map((id) => ({ type: "toolCall", id, name: "bash", arguments: {} })),
+    ],
+    timestamp,
+    usage: {},
+    stopReason: "toolUse",
+  };
+}
+
+function assistantWithToolsAndThinking(timestamp: number, toolCallIds: string[], thinking = "hmm"): any {
+  return {
+    role: "assistant",
+    content: [
+      { type: "thinking", thinking, thinkingSignature: "sig" },
+      { type: "text", text: "working..." },
+      ...toolCallIds.map((id) => ({ type: "toolCall", id, name: "bash", arguments: {} })),
+    ],
+    timestamp,
+    usage: {},
+    stopReason: "toolUse",
+  };
+}
+
+function toolResult(timestamp: number, toolCallId: string, toolName = "bash", text = "output"): any {
+  return {
+    role: "toolResult",
+    toolCallId,
+    toolName,
+    content: [{ type: "text", text }],
+    isError: false,
+    timestamp,
+  };
+}
+
+function assistantText(timestamp: number, text = "done"): any {
+  return { role: "assistant", content: [{ type: "text", text }], timestamp, usage: {}, stopReason: "stop" };
+}
+
+function assistantTextWithThinking(timestamp: number, thinking = "closing thought", text = "done"): any {
+  return {
+    role: "assistant",
+    content: [
+      { type: "thinking", thinking, thinkingSignature: "sig" },
+      { type: "text", text },
+    ],
+    timestamp,
+    usage: {},
+    stopReason: "stop",
+  };
+}
+
+const noSummarized = () => false;
+const noProtected = () => false;
+
+function fullFrontier(overrides: Partial<PruneFrontier>): PruneFrontier {
+  return {
+    lastAttemptedToolCallId: "tc1",
+    lastAttemptedToolName: "bash",
+    lastAttemptedTurnIndex: 0,
+    lastAttemptedTimestamp: 0,
+    attemptedBatchCount: 1,
+    attemptedToolCallCount: 1,
+    rawCharCount: 0,
+    summaryCharCount: 0,
+    outcome: "summarized",
+    ...overrides,
+  };
+}
+
+describe("computeContextMetrics", () => {
+  test("empty branch -> all zeros", () => {
+    const result = computeContextMetrics([], null, noSummarized, noProtected);
+    expect(result).toEqual({ openCycleThinkingTokens: 0, largestChainSharePct: 0, frontierGapTokens: 0 });
+  });
+
+  test("open segment thinking: only counts thinking blocks strictly after the last text-only assistant", () => {
+    const openThinkingBlock = { type: "thinking", thinking: "open thought that survives", thinkingSignature: "sig" };
+    const msgs = [
+      userMsg(100),
+      assistantTextWithThinking(200, "excluded thought A"), // text-only -> excluded (at/before boundary)
+      userMsg(300),
+      assistantWithTools(400, ["tc1"]),
+      toolResult(500, "tc1"),
+      assistantTextWithThinking(600, "excluded thought B"), // new last text-only assistant
+      userMsg(700),
+      {
+        role: "assistant",
+        content: [openThinkingBlock, { type: "text", text: "working" }, { type: "toolCall", id: "tc2", name: "bash", arguments: {} }],
+        timestamp: 800,
+        usage: {},
+        stopReason: "toolUse",
+      },
+      toolResult(900, "tc2"),
+    ];
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(openThinkingBlock).length / 4);
+    expect(result.openCycleThinkingTokens).toBe(expected);
+  });
+
+  test("zero text-only assistants -> whole branch is the open segment", () => {
+    const thinkingBlock = { type: "thinking", thinking: "the only thought", thinkingSignature: "sig" };
+    const msgs = [
+      userMsg(100),
+      { role: "assistant", content: [thinkingBlock, { type: "toolCall", id: "tc1", name: "bash", arguments: {} }], timestamp: 200, usage: {}, stopReason: "toolUse" },
+      toolResult(300, "tc1"),
+    ];
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.openCycleThinkingTokens).toBe(Math.round(JSON.stringify(thinkingBlock).length / 4));
+  });
+
+  test("no thinking blocks anywhere -> openCycleThinkingTokens is 0", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1"]), toolResult(300, "tc1")];
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.openCycleThinkingTokens).toBe(0);
+  });
+
+  test("largestChainSharePct: closed chain larger than open segment -> chain dominates", () => {
+    const msgs = [
+      userMsg(100),
+      assistantWithTools(200, ["tc1"]),
+      toolResult(300, "tc1", "bash", "x".repeat(2000)), // big closed chain
+      assistantText(400),
+      userMsg(500),
+      assistantText(600), // tiny open segment (single text-only assistant, itself excluded from open... )
+    ];
+    // Recompute manually to avoid relying on the implementation under test.
+    const chars = msgs.map((m) => JSON.stringify(m).length);
+    const totalChars = chars.reduce((a, b) => a + b, 0);
+    const chainChars = chars[0] + chars[1] + chars[2] + chars[3]; // userMsg..assistantText(400)
+    const openSegmentChars = 0; // last text-only assistant is msgs[5] itself; open segment is empty (after index 5)
+    const expectedPct = Math.round((100 * Math.max(chainChars, openSegmentChars)) / totalChars);
+
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.largestChainSharePct).toBe(expectedPct);
+    expect(chainChars).toBeGreaterThan(openSegmentChars);
+  });
+
+  test("largestChainSharePct: open segment larger than any closed chain -> open segment dominates", () => {
+    const msgs = [
+      userMsg(100),
+      assistantWithTools(200, ["tc1"]),
+      toolResult(300, "tc1"), // small closed chain
+      assistantText(400), // closes chain 1
+      userMsg(500),
+      assistantWithTools(600, ["tc2"]),
+      toolResult(700, "tc2", "bash", "y".repeat(3000)), // large open segment (never closes)
+    ];
+    const chars = msgs.map((m) => JSON.stringify(m).length);
+    const totalChars = chars.reduce((a, b) => a + b, 0);
+    const chainChars = chars[0] + chars[1] + chars[2] + chars[3];
+    const openSegmentChars = chars[4] + chars[5] + chars[6];
+    const expectedPct = Math.round((100 * Math.max(chainChars, openSegmentChars)) / totalChars);
+
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.largestChainSharePct).toBe(expectedPct);
+    expect(openSegmentChars).toBeGreaterThan(chainChars);
+  });
+
+  test("largestChainSharePct: a projected custom_message entry (role \"custom\") counts toward the denominator only, never the chain numerator", () => {
+    // Mirrors index.ts's branch projection for persisted summary custom_message
+    // entries: role "custom" never matches the user/assistant/toolResult roles
+    // detectChains and isTextOnlyAssistant key off, so it cannot join a chain
+    // or the open segment -- it only inflates totalChars (the denominator).
+    // The customEntry sits between two final text-only assistant messages, so
+    // it lands outside both the chain range and the open-cycle segment --
+    // isolating the denominator effect from any open-segment interaction.
+    const chainMsgs = [
+      userMsg(100),
+      assistantWithTools(200, ["tc1"]),
+      toolResult(300, "tc1", "bash", "x".repeat(2000)),
+      assistantText(400),
+    ];
+    const customEntry = { role: "custom", customType: "pi-condense:summary", content: "s".repeat(3000), display: true, timestamp: 450 };
+    const closer = assistantText(500, "ok");
+
+    const withoutCustom = computeContextMetrics(chainMsgs, null, noSummarized, noProtected);
+    const withCustom = computeContextMetrics([...chainMsgs, customEntry, closer], null, noSummarized, noProtected);
+
+    const chainChars = chainMsgs.map((m) => JSON.stringify(m).length).reduce((a, b) => a + b, 0);
+    const totalWithCustom = [...chainMsgs, customEntry, closer].map((m) => JSON.stringify(m).length).reduce((a, b) => a + b, 0);
+    const expectedPctWithCustom = Math.round((100 * chainChars) / totalWithCustom);
+
+    expect(withoutCustom.largestChainSharePct).toBe(100);
+    expect(withCustom.largestChainSharePct).toBe(expectedPctWithCustom);
+    expect(withCustom.largestChainSharePct).toBeLessThan(withoutCustom.largestChainSharePct);
+  });
+
+  test("largestChainSharePct: interrupted chain (null finalAssistantTimestamp) is counted", () => {
+    const msgs = [
+      userMsg(100),
+      assistantWithTools(200, ["tc1"]),
+      toolResult(300, "tc1", "bash", "z".repeat(5000)), // huge interrupted chain
+      userMsg(400), // interrupts before text-only close
+      assistantText(500), // closes the second (tiny) chain
+    ];
+    const chars = msgs.map((m) => JSON.stringify(m).length);
+    const totalChars = chars.reduce((a, b) => a + b, 0);
+    const interruptedChainChars = chars[0] + chars[1] + chars[2]; // startIdx..(nextUserIdx - 1)
+    const openSegmentChars = 0; // last text-only assistant is msgs[4] itself
+    const expectedPct = Math.round((100 * Math.max(interruptedChainChars, openSegmentChars)) / totalChars);
+
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.largestChainSharePct).toBe(expectedPct);
+    expect(expectedPct).toBeGreaterThan(0);
+  });
+
+  test("largestChainSharePct: empty branch denominator is 0 -> 0 (not NaN)", () => {
+    const result = computeContextMetrics([], null, noSummarized, noProtected);
+    expect(result.largestChainSharePct).toBe(0);
+  });
+
+  test("frontierGapTokens: null frontier -> whole branch counted", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2"]), toolResult(300, "tc1"), toolResult(310, "tc2")];
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(msgs[2]).length / 4) + Math.round(JSON.stringify(msgs[3]).length / 4);
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+
+  test("frontierGapTokens: boundary mid-turn split excludes at-or-before calls, includes later calls in same turn", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2"]), toolResult(300, "tc1"), toolResult(310, "tc2")];
+    const frontier = fullFrontier({ lastAttemptedToolCallId: "tc1", lastAttemptedTurnIndex: 0 });
+    const result = computeContextMetrics(msgs, frontier, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(msgs[3]).length / 4); // only tc2's result
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+
+  test("frontierGapTokens: bare-id miss (id not present in the matched turn) -> whole branch counted", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2"]), toolResult(300, "tc1"), toolResult(310, "tc2")];
+    const frontier = fullFrontier({ lastAttemptedToolCallId: "tc-does-not-exist", lastAttemptedTurnIndex: 0 });
+    const result = computeContextMetrics(msgs, frontier, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(msgs[2]).length / 4) + Math.round(JSON.stringify(msgs[3]).length / 4);
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+
+  test("frontierGapTokens: turn index not found in branch -> whole branch counted", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1"]), toolResult(300, "tc1")];
+    const frontier = fullFrontier({ lastAttemptedToolCallId: "tc1", lastAttemptedTurnIndex: 99 });
+    const result = computeContextMetrics(msgs, frontier, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(msgs[2]).length / 4);
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+
+  test("frontierGapTokens: excludes a toolResult whose occurrence key is already summarized", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1"]), toolResult(300, "tc1")];
+    const isSummarized = (key: string) => key === "tc1@300";
+    const result = computeContextMetrics(msgs, null, isSummarized, noProtected);
+    expect(result.frontierGapTokens).toBe(0);
+  });
+
+  test("frontierGapTokens: excludes a toolResult from a protected tool (args looked up from the pairing toolCall)", () => {
+    const msgs = [
+      userMsg(100),
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc1", name: "read", arguments: { path: "/skills/secret.md" } }],
+        timestamp: 200,
+        usage: {},
+        stopReason: "toolUse",
+      },
+      toolResult(300, "tc1", "read"),
+    ];
+    const isProtected = (toolName: string, args: unknown) =>
+      toolName === "read" && typeof (args as any)?.path === "string" && (args as any).path.includes("/skills/");
+    const result = computeContextMetrics(msgs, null, noSummarized, isProtected);
+    expect(result.frontierGapTokens).toBe(0);
+  });
+
+  test("exact-value pin: frontierGapTokens equals Math.round(JSON.stringify(msg).length / 4) for a single toolResult", () => {
+    const result_msg = toolResult(300, "tc1", "bash", "a fixed output payload");
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1"]), result_msg];
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.frontierGapTokens).toBe(Math.round(JSON.stringify(result_msg).length / 4));
+  });
+
+  test("frontierGapTokens: a toolCall id reused in a LATER turn (past the boundary) still counts its result — exclusion is positional, not id-global", () => {
+    const laterResult = toolResult(700, "tc1", "bash", "y".repeat(196)); // ~49 tokens
+    const msgs = [
+      userMsg(100),
+      assistantWithTools(200, ["tc1"]), // turn 0 — this is the boundary turn
+      toolResult(300, "tc1"), // boundary result — correctly excluded
+      assistantText(400), // closes turn 0's chain
+      userMsg(500),
+      assistantWithTools(600, ["tc1"]), // turn 1 — reuses bare id "tc1" (legal: ids are only unique per turn)
+      laterResult, // must be counted: it is positionally after the boundary
+    ];
+    const frontier = fullFrontier({ lastAttemptedToolCallId: "tc1", lastAttemptedTurnIndex: 0 });
+    const result = computeContextMetrics(msgs, frontier, noSummarized, noProtected);
+    const expected = Math.round(JSON.stringify(laterResult).length / 4);
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+
+  test("frontierGapTokens: args pairing for a reused id uses the nearest preceding assistant's toolCall, not a global id map", () => {
+    const msgs = [
+      userMsg(100),
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc1", name: "read", arguments: { path: "/normal.md" } }],
+        timestamp: 200,
+        usage: {},
+        stopReason: "toolUse",
+      }, // turn 0 — unprotected args
+      toolResult(300, "tc1", "read"),
+      assistantText(400),
+      userMsg(500),
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc1", name: "read", arguments: { path: "/skills/secret.md" } }],
+        timestamp: 600,
+        usage: {},
+        stopReason: "toolUse",
+      }, // turn 1 — reuses bare id "tc1" with protected args
+      toolResult(700, "tc1", "read"),
+    ];
+    const isProtected = (toolName: string, args: unknown) =>
+      toolName === "read" && typeof (args as any)?.path === "string" && (args as any).path.includes("/skills/");
+    const result = computeContextMetrics(msgs, null, noSummarized, isProtected);
+    // turn 0's result (unprotected args) counts; turn 1's result (protected args) is excluded.
+    const expected = Math.round(JSON.stringify(msgs[2]).length / 4);
+    expect(result.frontierGapTokens).toBe(expected);
+  });
+});