@axplusb/kepler 2.2.0 → 2.3.1

package/src/core/cache-control.mjs

@@ -0,0 +1,92 @@
+/**
+ * cache_control breakpoints for Anthropic prompt caching (PRD-071 Phase 2).
+ *
+ * Shared by every direct-API call site that talks to Anthropic — LocalAgent
+ * (Anthropic direct + OpenRouter passthrough) and agent-loop's Task sub-agents.
+ *
+ * Anthropic allows 4 breakpoints per request; we spend 3:
+ *   1) End of system prompt        (1h TTL — persistent across long-idle sessions)
+ *   2) Last tool schema            (1h TTL — persistent)
+ *   3) Second-to-last user message (5min TTL — rolls each turn, cheaper to write)
+ *
+ * The 4th slot stays reserved (attachments, future retrieval prefix).
+ *
+ * Extended 1-hour TTL is a beta — pass ANTHROPIC_BETA_HEADER on the request
+ * whenever any block carries ttl:'1h'.
+ */
+
+export const ANTHROPIC_BETA_HEADER = 'extended-cache-ttl-2025-04-11';
+
+const CACHE_1H = { type: 'ephemeral', ttl: '1h' };
+const CACHE_5M = { type: 'ephemeral' };
+
+/**
+ * Turn a `system` string into a content-block array with a cache_control
+ * breakpoint on the tail. If the caller already passed blocks, returns them
+ * unchanged. Undefined / non-string inputs pass through as-is.
+ */
+export function cacheableSystem(systemPrompt) {
+    if (Array.isArray(systemPrompt)) return systemPrompt;
+    if (!systemPrompt || typeof systemPrompt !== 'string') return systemPrompt;
+    return [{ type: 'text', text: systemPrompt, cache_control: CACHE_1H }];
+}
+
+/**
+ * Return a copy of `tools` with cache_control on the LAST tool. Anthropic
+ * caches system + tools as one prefix from that breakpoint, so this single
+ * marker covers the whole tool schema regardless of length.
+ */
+export function cacheableTools(tools) {
+    if (!Array.isArray(tools) || tools.length === 0) return tools || [];
+    const out = tools.slice();
+    const last = out[out.length - 1];
+    out[out.length - 1] = { ...last, cache_control: CACHE_1H };
+    return out;
+}
+
+/**
+ * Tag the SECOND-to-last user message with a 5-min cache_control breakpoint.
+ * Leaves the last turn write-through so the next round extends the cache
+ * instead of re-writing it. Returns messages unchanged when there aren't
+ * enough user turns yet (< 2).
+ *
+ * Handles both content shapes: string (wrapped into blocks) and block array
+ * (tagged on the last block).
+ */
+export function withMessageBreakpoint(messages) {
+    if (!Array.isArray(messages) || messages.length < 2) return messages;
+    const userIdx = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === 'user') userIdx.push(i);
+    }
+    if (userIdx.length < 2) return messages;
+    const targetIdx = userIdx[userIdx.length - 2];
+    const msg = messages[targetIdx];
+
+    if (typeof msg.content === 'string') {
+        return messages.map((m, i) => i === targetIdx ? {
+            ...m,
+            content: [{ type: 'text', text: m.content, cache_control: CACHE_5M }],
+        } : m);
+    }
+
+    if (Array.isArray(msg.content) && msg.content.length > 0) {
+        const blocks = msg.content.slice();
+        const last = blocks[blocks.length - 1];
+        blocks[blocks.length - 1] = { ...last, cache_control: CACHE_5M };
+        return messages.map((m, i) => i === targetIdx ? { ...m, content: blocks } : m);
+    }
+
+    return messages;
+}
+
+/**
+ * True if the given model id needs Anthropic-style explicit cache_control
+ * (vs OpenAI/DeepSeek which auto-cache). Handles bare Claude ids and
+ * OpenRouter's `anthropic/*` prefix.
+ */
+export function needsExplicitCacheControl(model) {
+    if (!model) return false;
+    const m = model.toLowerCase();
+    return m.startsWith('claude') || m.startsWith('anthropic/');
+}

package/src/core/compact-history.mjs

@@ -0,0 +1,127 @@
+const SUMMARY_PREFIX = 'Session continuity summary after /compact:';
+
+export function parseCompactTailCount(rest = '', fallback = 8) {
+  const text = String(rest || '').trim();
+  const match = text.match(/(?:^|\s)(?:--tail=|--tail\s+)?(\d+)(?:\s|$)/);
+  const n = match ? Number(match[1]) : Number(fallback);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(2, Math.min(50, Math.floor(n)));
+}
+
+export function isCompactHistory(history = []) {
+  return typeof history?.[2]?.content === 'string'
+    && history[2].content.startsWith(SUMMARY_PREFIX);
+}
+
+export function extractCompactSummary(history = []) {
+  const content = String(history?.[2]?.content || '');
+  if (!content.startsWith(SUMMARY_PREFIX)) return '';
+  return content.slice(SUMMARY_PREFIX.length).trim();
+}
+
+export function prepareCompactHistory({
+  agentHistory = [],
+  tailCount = 8,
+  minSourceMessages = 2,
+} = {}) {
+  const history = Array.isArray(agentHistory)
+    ? agentHistory.filter(msg => msg && typeof msg.content === 'string' && msg.content.trim())
+    : [];
+  const beforeCount = history.length;
+  const retainedCount = Math.min(Math.max(2, Number(tailCount) || 8), Math.max(0, beforeCount));
+  const prefixCount = isCompactHistory(history) ? 3 : 0;
+  const sourceEnd = Math.max(prefixCount, beforeCount - retainedCount);
+  const sourceMessages = history.slice(prefixCount, sourceEnd);
+  const tail = history.slice(sourceEnd);
+
+  if (sourceMessages.length < minSourceMessages) {
+    return {
+      ok: false,
+      reason: beforeCount <= prefixCount + retainedCount
+        ? 'not enough history beyond the retained tail'
+        : 'not enough compactable messages',
+      beforeCount,
+      prefixCount,
+      sourceMessages,
+      tail,
+      retainedCount,
+    };
+  }
+
+  return {
+    ok: true,
+    beforeCount,
+    prefixCount,
+    sourceMessages,
+    tail,
+    retainedCount: tail.length,
+    previousSummary: extractCompactSummary(history),
+  };
+}
+
+export function applyCompactSummary({
+  prepared,
+  summary,
+  sessionId = '',
+  cwd = '',
+  originalRequest = '',
+  previousSourceMessageCount = 0,
+  now = new Date(),
+} = {}) {
+  if (!prepared?.ok) throw new Error(prepared?.reason || 'history is not compactable');
+  const compactSummary = String(summary || '').trim();
+  if (!compactSummary) throw new Error('summary is required');
+  const priorCount = Math.max(0, Number(previousSourceMessageCount) || 0);
+  const sourceMessageCount = priorCount + prepared.sourceMessages.length;
+  const timestamp = now instanceof Date ? now.toISOString() : String(now || new Date().toISOString());
+  const firstUser = originalRequest || firstUserMessage(prepared.sourceMessages) || firstUserMessage(prepared.tail) || '(unknown)';
+
+  const metadata = [
+    'Compact metadata.',
+    sessionId ? `Session: ${sessionId}` : '',
+    cwd ? `Project: ${cwd}` : '',
+    `Compacted at: ${timestamp}`,
+    `Covered live messages: ${sourceMessageCount}`,
+    `Retained tail messages: ${prepared.tail.length}`,
+  ].filter(Boolean).join('\n');
+
+  const agentHistory = [
+    { role: 'user', content: metadata },
+    { role: 'user', content: `Original user request from this compacted session:\n${firstUser}` },
+    { role: 'user', content: `${SUMMARY_PREFIX}\n${compactSummary}` },
+    ...prepared.tail,
+  ];
+
+  return {
+    agentHistory,
+    summary: compactSummary,
+    sourceMessageCount,
+    previousSourceMessageCount: priorCount,
+    beforeCount: prepared.beforeCount,
+    afterCount: agentHistory.length,
+    retainedCount: prepared.tail.length,
+    compactedCount: prepared.sourceMessages.length,
+  };
+}
+
+export function localCompactSummary(messages = []) {
+  const list = Array.isArray(messages) ? messages : [];
+  const userMessages = list.filter(m => m.role === 'user').map(m => String(m.content || '').trim()).filter(Boolean);
+  const assistantMessages = list.filter(m => m.role === 'assistant').map(m => String(m.content || '').trim()).filter(Boolean);
+  return [
+    'Local compact summary from live conversation context.',
+    userMessages.length ? `User requests (${userMessages.length}):` : '',
+    ...userMessages.slice(-8).map(text => `- ${truncate(text, 500)}`),
+    assistantMessages.length ? `Assistant progress (${assistantMessages.length}):` : '',
+    ...assistantMessages.slice(-8).map(text => `- ${truncate(text, 700)}`),
+  ].filter(Boolean).join('\n');
+}
+
+function firstUserMessage(messages = []) {
+  return messages.find(m => m?.role === 'user' && typeof m.content === 'string')?.content || '';
+}
+
+function truncate(text, max) {
+  const value = String(text || '').replace(/\s+/g, ' ').trim();
+  return value.length > max ? value.slice(0, max - 3) + '...' : value;
+}

package/src/core/headless.mjs

@@ -13,6 +13,7 @@
 
 import { TarangStreamClient } from './stream-client.mjs';
 import { createToolExecutor } from './tool-executor.mjs';
+import { buildWorkScope } from './work-scope.mjs';
 import { persistProjectArtifacts } from './project-artifacts.mjs';
 import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from './approval.mjs';
@@ -26,7 +27,7 @@ import { ApprovalManager } from './approval.mjs';
  * @param {number} [opts.maxCost] - abort if cost exceeds this USD amount
  * @param {boolean} [opts.verbose] - show progress on stderr
  */
-export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false }) {
+export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false }) {
     const startTime = Date.now();
 
     const log = (msg) => {
@@ -51,13 +52,41 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // Auto-approve everything — no prompts
     const approval = new ApprovalManager({ autoApprove: true });
 
-    // ── Stream client ──
-    const client = new TarangStreamClient({
-        baseUrl: creds.backendUrl,
-        token: creds.token,
-        toolExecutor,
-        approvalManager: approval,
-    });
+    // ── Client selection ──
+    // PRD-071 Phase 2 measurement — --local forces the CLI-side LocalAgent path,
+    // bypassing the backend so we can exercise the cache_control wiring we
+    // just added to _callClaude / _callOpenRouter. Model comes from the
+    // --model flag (which overrides settings dynamically for benchmarking).
+    let client;
+    if (local) {
+        const { LocalAgent } = await import('./local-agent.mjs');
+        const localModel = model || creds.models?.local || 'anthropic/claude-sonnet-4';
+        const orKey = process.env.OPENROUTER_API_KEY || creds.openRouterKey;
+        const anthKey = process.env.ANTHROPIC_API_KEY || creds.anthropicKey;
+        if (!orKey && !anthKey) {
+            emit({ type: 'error', error: '--local requires OPENROUTER_API_KEY or ANTHROPIC_API_KEY' });
+            process.exit(1);
+        }
+        client = {
+            execute: (instr, ctx) => new LocalAgent({
+                apiKey: anthKey,
+                openRouterKey: orKey,
+                model: localModel,
+                toolExecutor,
+                verbose,
+                cwd: process.cwd(),
+                maxTurns: 50,
+            }).execute(instr, ctx),
+        };
+        log(`Local mode: ${localModel}`);
+    } else {
+        client = new TarangStreamClient({
+            baseUrl: creds.backendUrl,
+            token: creds.token,
+            toolExecutor,
+            approvalManager: approval,
+        });
+    }
 
     // ── Timeout ──
     const timeoutMs = timeout * 1000;
@@ -70,10 +99,16 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // ── Execute ──
     emit({ type: 'start', timestamp: Date.now(), instruction, model: model || 'default', cwd: process.cwd() });
 
+    const projectResources = toolExecutor.getProjectResources();
     const execContext = {
         cwd: process.cwd(),
         freeswim: true,
-        project_resources: toolExecutor.getProjectResources(),
+        project_resources: projectResources,
+        work_scope: buildWorkScope({
+            instruction,
+            cwd: process.cwd(),
+            projectResources,
+        }),
         agent_context: toolExecutor.getAgentContext(),
     };
     if (model) execContext.model_override = model;
@@ -219,6 +254,47 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
         content_length: finalContent.length,
     });
 
+    // PRD-071 §1.5 — cache summary for benchmark harness. Machine-readable,
+    // one file per run. Fields match what benchmark/cache-check.sh already
+    // computes (input, cache_read, cache_write, rate) so the shell script
+    // becomes a thin reader instead of re-doing the arithmetic.
+    if (cacheReport && usage) {
+        const cacheRead = usage.cache_read || 0;
+        const cacheWrite = usage.cache_write || 0;
+        const inputT = usage.input_tokens || 0;
+        // Two conventions in the wild:
+        //   OpenAI/DeepSeek: input_tokens INCLUDES cached tokens
+        //                    → hit_rate = cache_read / input_tokens
+        //   Anthropic:       input_tokens EXCLUDES cache reads AND writes
+        //                    → hit_rate = cache_read / (input + cache_read + cache_write)
+        // Report both. Also expose `cache_hit_rate_pct` as the "sane" number
+        // — auto-detects convention by whether cache_read > input_tokens.
+        const rateOpenAI = inputT > 0 ? Math.round((cacheRead / inputT) * 100) : 0;
+        const anthropicDenom = inputT + cacheRead + cacheWrite;
+        const rateAnthropic = anthropicDenom > 0 ? Math.round((cacheRead / anthropicDenom) * 100) : 0;
+        const rateAuto = cacheRead > inputT ? rateAnthropic : rateOpenAI;
+        const report = {
+            schema: 'kepler.cache-report/1',
+            model: model || 'default',
+            input_tokens: inputT,
+            output_tokens: usage.output_tokens || 0,
+            cache_read_tokens: cacheRead,
+            cache_write_tokens: cacheWrite,
+            cache_hit_rate_pct: rateAuto,
+            cache_hit_rate_openai_pct: rateOpenAI,
+            cache_hit_rate_anthropic_pct: rateAnthropic,
+            duration_s: Math.round(durationS * 10) / 10,
+            cost_usd: totalCost,
+        };
+        try {
+            const fs = await import('node:fs');
+            fs.writeFileSync(cacheReport, JSON.stringify(report, null, 2) + '\n');
+            log(`Cache report written: ${cacheReport}`);
+        } catch (err) {
+            log(`Cache report write failed: ${err.message}`);
+        }
+    }
+
     log(`Done: ${toolCount} tools, ${durationS.toFixed(1)}s, $${totalCost.toFixed(3)}`);
 
     // Write final content to stderr so it's human-readable (stdout is JSONL)

package/src/core/jsonl-writer.mjs

@@ -317,6 +317,15 @@ export class JsonlWriter {
     }
   }
 
+  async flush() {
+    await this._flush();
+    if (this._flushPromise) await this._flushPromise;
+  }
+
+  get transcriptPath() {
+    return this._transcriptPath;
+  }
+
   // ── Internal ──
 
   _resetTurn() {

package/src/core/local-agent.mjs

@@ -6,6 +6,14 @@
 
 import { ContextRetriever } from '../context/retriever.mjs';
 import { createStagnationTracker, stagnationMessage } from './stagnation.mjs';
+import { PromptCache } from './cache.mjs';
+import {
+    ANTHROPIC_BETA_HEADER,
+    cacheableSystem,
+    cacheableTools,
+    withMessageBreakpoint,
+    needsExplicitCacheControl,
+} from './cache-control.mjs';
 
 const MAX_ITERATIONS = 50;
 
@@ -209,12 +217,14 @@ export class LocalAgent {
         this.stagnationDetection = stagnationDetection;
         this.stagnationThreshold = stagnationThreshold;
         this._cancelled = false;
+        this.promptCache = new PromptCache();
     }
 
     async *execute(instruction, context = {}) {
         this._cancelled = false;
         const startTime = Date.now();
         let toolCount = 0;
+        const usageTotals = { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 };
 
         yield { type: 'status', data: { message: `Local mode: ${this.model}` } };
 
@@ -252,7 +262,15 @@ export class LocalAgent {
                 return;
             }
 
-            const { content, stopReason } = response;
+            const { content, stopReason, usage } = response;
+
+            if (usage) {
+                this.promptCache.updateStats(usage);
+                usageTotals.input_tokens += usage.input_tokens || 0;
+                usageTotals.output_tokens += usage.output_tokens || 0;
+                usageTotals.cache_read_tokens += usage.cache_read_input_tokens || 0;
+                usageTotals.cache_creation_tokens += usage.cache_creation_input_tokens || 0;
+            }
 
             // Process content blocks
             let hasToolUse = false;
@@ -303,13 +321,29 @@ export class LocalAgent {
 
             if (!hasToolUse || stopReason === 'end_turn') {
                 const duration = (Date.now() - startTime) / 1000;
-                yield { type: 'complete', data: { summary: 'Done (local)', changes: toolCount, duration_s: duration } };
+                yield {
+                    type: 'complete',
+                    data: {
+                        summary: 'Done (local)',
+                        changes: toolCount,
+                        duration_s: duration,
+                        usage: _buildLocalUsageEnvelope(this.model, usageTotals),
+                    },
+                };
                 return;
             }
         }
 
         yield { type: 'error', data: { message: `Max turns (${this.maxTurns}) reached.` } };
-        yield { type: 'complete', data: { summary: 'Aborted (max turns)', changes: toolCount, duration_s: (Date.now() - startTime) / 1000 } };
+        yield {
+            type: 'complete',
+            data: {
+                summary: 'Aborted (max turns)',
+                changes: toolCount,
+                duration_s: (Date.now() - startTime) / 1000,
+                usage: _buildLocalUsageEnvelope(this.model, usageTotals),
+            },
+        };
     }
 
     async _callLLM(systemPrompt, messages, tools) {
@@ -333,18 +367,26 @@ export class LocalAgent {
     }
 
     async _callClaude(systemPrompt, messages, tools) {
+        // PRD-071 Phase 2 — cache_control breakpoints for Anthropic direct.
+        // Extended 1-hour TTL beta on the persistent prefix (system + tools).
+        // Message history breakpoint stays at default 5-min TTL.
+        const cachedSystem = cacheableSystem(systemPrompt);
+        const cachedTools = cacheableTools(tools);
+        const cachedMessages = withMessageBreakpoint(messages);
+
         const resp = await fetch('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
                 'x-api-key': this.apiKey,
                 'anthropic-version': '2023-06-01',
+                'anthropic-beta': ANTHROPIC_BETA_HEADER,
                 'content-type': 'application/json',
             },
             body: JSON.stringify({
                 model: this.model,
-                system: systemPrompt,
-                messages,
-                tools: tools.length > 0 ? tools : undefined,
+                system: cachedSystem,
+                messages: cachedMessages,
+                tools: cachedTools.length > 0 ? cachedTools : undefined,
                 max_tokens: 8192,
             }),
         });
@@ -353,7 +395,7 @@ export class LocalAgent {
             throw new Error(`Claude API ${resp.status}: ${text.slice(0, 200)}`);
         }
         const data = await resp.json();
-        return { content: data.content || [], stopReason: data.stop_reason };
+        return { content: data.content || [], stopReason: data.stop_reason, usage: data.usage || null };
     }
 
     async _callOpenRouter(systemPrompt, messages, tools) {
@@ -363,17 +405,43 @@ export class LocalAgent {
             model = `anthropic/${model}`;
         }
 
-        const orMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+        // PRD-071 Phase 2 — for anthropic/* models we need explicit cache_control
+        // breakpoints (OpenRouter relays them through to Anthropic). OpenAI +
+        // DeepSeek auto-cache, so the string system prompt path is fine there.
+        const isAnthropic = needsExplicitCacheControl(model);
+        const systemForOR = isAnthropic
+            ? { role: 'system', content: cacheableSystem(systemPrompt) }
+            : { role: 'system', content: systemPrompt };
+        const messagesForOR = isAnthropic ? withMessageBreakpoint(messages) : messages;
+        const orMessages = [systemForOR, ...messagesForOR];
+
+        // Same tool-schema shape as before, but tag the last tool for Anthropic
+        // (OpenRouter passes cache_control on function tools through).
+        const orTools = tools.length > 0
+            ? tools.map(t => ({
+                type: 'function',
+                function: { name: t.name, description: t.description, parameters: t.input_schema },
+            }))
+            : [];
+        const finalTools = isAnthropic ? cacheableTools(orTools) : orTools;
+
+        const headers = {
+            'Authorization': `Bearer ${this.openRouterKey}`,
+            'Content-Type': 'application/json',
+        };
+        // OpenRouter forwards `anthropic-beta` to Anthropic upstreams.
+        if (isAnthropic) headers['anthropic-beta'] = ANTHROPIC_BETA_HEADER;
+
         const resp = await fetch('https://openrouter.ai/api/v1/chat/completions', {
             method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.openRouterKey}`,
-                'Content-Type': 'application/json',
-            },
+            headers,
             body: JSON.stringify({
                 model,
                 messages: orMessages,
-                tools: tools.length > 0 ? tools.map(t => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.input_schema } })) : undefined,
+                tools: finalTools.length > 0 ? finalTools : undefined,
+                // Ask OpenRouter to include upstream cache accounting in the
+                // usage payload so PromptCache.updateStats() sees real numbers.
+                usage: { include: true },
             }),
         });
         if (!resp.ok) {
@@ -389,7 +457,11 @@ export class LocalAgent {
                 content.push({ type: 'tool_use', id: tc.id, name: tc.function.name, input: JSON.parse(tc.function.arguments || '{}') });
             }
         }
-        return { content, stopReason: choice?.finish_reason === 'stop' ? 'end_turn' : 'tool_use' };
+        return {
+            content,
+            stopReason: choice?.finish_reason === 'stop' ? 'end_turn' : 'tool_use',
+            usage: _normalizeOpenRouterUsage(data.usage),
+        };
     }
 
     _buildToolDefs() {
@@ -427,3 +499,38 @@ export class LocalAgent {
 
     cancel() { this._cancelled = true; }
 }
+
+// Shape the accumulated per-turn totals into the same envelope the remote
+// SSE `complete` event uses, so repl.mjs:837 can consume both modes with the
+// same code path. `models[0].role = 'local'` distinguishes single-agent
+// local mode from remote's Coder/Explorer/Planner breakdown.
+function _buildLocalUsageEnvelope(model, totals) {
+    return {
+        total_input_tokens: totals.input_tokens,
+        total_output_tokens: totals.output_tokens,
+        models: [{
+            model,
+            role: 'local',
+            input_tokens: totals.input_tokens,
+            output_tokens: totals.output_tokens,
+            cache_read_tokens: totals.cache_read_tokens,
+            cache_creation_tokens: totals.cache_creation_tokens,
+        }],
+    };
+}
+
+// Normalize OpenRouter usage into Anthropic's field names so downstream
+// consumers (PromptCache, pricing.calculateCost) don't branch on shape.
+// OpenRouter returns OpenAI-style: prompt_tokens, completion_tokens,
+// prompt_tokens_details.cached_tokens. When the underlying model is
+// Anthropic, OpenRouter also relays cache_read_input_tokens verbatim.
+function _normalizeOpenRouterUsage(usage) {
+    if (!usage) return null;
+    const cachedFromOpenAI = usage.prompt_tokens_details?.cached_tokens || 0;
+    return {
+        input_tokens: usage.prompt_tokens || 0,
+        output_tokens: usage.completion_tokens || 0,
+        cache_read_input_tokens: usage.cache_read_input_tokens || cachedFromOpenAI || 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+    };
+}

package/src/core/local-store.mjs

@@ -531,10 +531,10 @@ export function buildResumeHistory(detail, mode = 'compact') {
   );
 
   // PRD-068 §5.14.4: resume mode picker.
-  //   'full'       — every turn sent verbatim (unchanged)
-  //   'tail-N'     — recap block as system prime + last N conversation messages so the
-  //                  agent has real recent conversation to reference.
-  //   'summary'    — recap block only. Cheapest continuity, biggest lossiness.
+  //   'full'            — every turn sent verbatim (unchanged)
+  //   'checkpoint-full' — latest summary checkpoint + every message after it
+  //   'tail-N'          — recap block + last N conversation messages
+  //   'summary'         — recap block only. Cheapest continuity, biggest lossiness.
   let agentHistory;
   let sourceMessages = fullAgentHistory;
   let summaryMessageIndex = -1;
@@ -543,6 +543,22 @@ export function buildResumeHistory(detail, mode = 'compact') {
   if (mode === 'full') {
     agentHistory = fullAgentHistory;
     summaryCoveredMessageCount = fullAgentHistory.length;
+  } else if (mode === 'checkpoint-full') {
+    sourceMessages = [];
+    const tail = fullAgentHistory.slice(summaryCheckpointMessageCount);
+    activeSummary = priorSummary
+      || summaryForMessages(fullAgentHistory.slice(0, summaryCheckpointMessageCount), {
+        fallback: summary,
+        label: 'Summary checkpoint',
+      });
+    summaryCoveredMessageCount = summaryCheckpointMessageCount;
+    agentHistory = [
+      { role: 'user', content: metadata },
+      { role: 'user', content: `Original user request from this resumed session:\n${originalRequest || '(unknown)'}` },
+      { role: 'user', content: activeSummary || summary },
+      ...tail,
+    ];
+    summaryMessageIndex = 2;
   } else if (mode === 'recap+tail' || /^tail-\d+$/.test(String(mode || ''))) {
     const tailTurns = tailTurnsForMode(mode, detail);
     const { tail, startIndex } = tailHistorySliceByRecentMessages(fullAgentHistory, tailTurns);

package/src/core/resume-mode.mjs

@@ -104,7 +104,7 @@ export function decideResumeMode({
  * Estimate the context tokens for a candidate mode. Used by the tri-choice
  * overlay to render "62k / 14k / 2k" per option before the user commits.
  *
- * @param {'full' | 'summary' | 'tail-10' | 'tail-20' | 'recap+tail'} choice
+ * @param {'full' | 'checkpoint-full' | 'summary' | 'tail-10' | 'tail-20' | 'recap+tail'} choice
  * @param {number} fullTokens — projected transcript size in full mode
  * @param {object} [opts]
  * @returns {number} projected tokens for the chosen mode
@@ -116,11 +116,21 @@ export function projectedTokensForChoice(choice, fullTokens, opts = {}) {
     tailBaseTokens = 2000,
     perTailTurnTokens = 500,
     summaryBaseTokens = 2000,
+    resumeSummary = null,
   } = opts;
 
   switch (choice) {
     case 'full':
       return Math.max(0, Number(fullTokens) || 0);
+    case 'checkpoint-full': {
+      const full = Math.max(0, Number(fullTokens) || 0);
+      const fullMessages = Math.max(0, Number(resumeSummary?.fullMessageCount) || 0);
+      const covered = Math.max(0, Number(resumeSummary?.sourceMessageCount) || 0);
+      if (!fullMessages || covered <= 0) return full;
+      const remainingMessages = Math.max(0, fullMessages - covered);
+      if (remainingMessages === 0) return summaryBaseTokens;
+      return summaryBaseTokens + (perTailTurnTokens * remainingMessages);
+    }
     case 'tail-10':
       return tailBaseTokens + (10 * perTailTurnTokens);
     case 'tail-20':