@axplusb/kepler 2.3.0 → 2.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axplusb/kepler",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {

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/error-guidance.mjs

@@ -0,0 +1,287 @@
+function compact(value) {
+  return String(value || '').trim();
+}
+
+function lower(value) {
+  return compact(value).toLowerCase();
+}
+
+const PROVIDER_ALIASES = new Map([
+  ['openrouter', 'openrouter'],
+  ['openrouterv2', 'openrouter'],
+  ['openroutergateway', 'openrouter'],
+  ['openrouterv2gateway', 'openrouter'],
+  ['anthropic', 'anthropic'],
+  ['claude', 'anthropic'],
+  ['claudegateway', 'anthropic'],
+  ['openai', 'openai'],
+  ['openaigateway', 'openai'],
+  ['google', 'googleai'],
+  ['googleai', 'googleai'],
+  ['googlegateway', 'googleai'],
+  ['googleaigateway', 'googleai'],
+  ['gemini', 'googleai'],
+  ['azure', 'azureopenai'],
+  ['azureopenai', 'azureopenai'],
+  ['azureopenaigateway', 'azureopenai'],
+  ['bedrock', 'bedrock'],
+  ['aws', 'bedrock'],
+  ['bedrockgateway', 'bedrock'],
+  ['databricks', 'databricks'],
+  ['databricksgateway', 'databricks'],
+  ['custom', 'custom'],
+  ['byom', 'custom'],
+  ['openai-compatible', 'custom'],
+  ['deepseek', 'deepseek'],
+  ['deepseekgateway', 'deepseek'],
+  ['dashscope', 'dashscope'],
+  ['dashscopegateway', 'dashscope'],
+  ['qwen', 'dashscope'],
+  ['zhipu', 'zhipu'],
+  ['zhipugateway', 'zhipu'],
+  ['glm', 'zhipu'],
+  ['moonshot', 'moonshot'],
+  ['moonshotgateway', 'moonshot'],
+  ['kimi', 'moonshot'],
+  ['xai', 'xai'],
+  ['xaigateway', 'xai'],
+  ['grok', 'xai'],
+  ['mistral', 'mistral'],
+  ['mistralgateway', 'mistral'],
+]);
+
+const PROVIDER_GUIDANCE = {
+  openrouter: {
+    label: 'OpenRouter',
+    lines: [
+      'Check that your OpenRouter API key is saved and has enough credits/quota.',
+      'Verify the selected model is available on OpenRouter and that provider routing is allowed for it.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  anthropic: {
+    label: 'Anthropic',
+    lines: [
+      'Check that your Anthropic API key is saved and active.',
+      'Verify the selected Claude model is enabled for your Anthropic account and region.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  openai: {
+    label: 'OpenAI',
+    lines: [
+      'Check that your OpenAI API key is saved and has access to the selected model.',
+      'Verify project billing, model permissions, and rate limits in your OpenAI account.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  googleai: {
+    label: 'Google AI',
+    lines: [
+      'Check that your Google AI API key is saved and active.',
+      'Verify the selected Gemini model is available for that key and region.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  azureopenai: {
+    label: 'Azure OpenAI',
+    lines: [
+      'Check that Azure OpenAI API key, endpoint, API version, and deployment/model name are saved.',
+      'Verify the deployment exists in Azure AI Foundry and the key has access to that resource.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  bedrock: {
+    label: 'AWS Bedrock',
+    lines: [
+      'Check that AWS Access Key ID, Secret Access Key, optional Session Token, and Region are saved.',
+      'Verify the IAM principal can call bedrock-runtime:InvokeModel for the selected model and region.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  databricks: {
+    label: 'Databricks',
+    lines: [
+      'Check that your Databricks host/workspace URL and token are saved.',
+      'Verify the selected serving endpoint exists and the token can query it.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  custom: {
+    label: 'custom OpenAI-compatible provider',
+    lines: [
+      'Check that base URL, API key, and model name are saved for the custom provider.',
+      'Verify the endpoint supports OpenAI-compatible chat completions for the selected model.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  deepseek: {
+    label: 'DeepSeek',
+    lines: [
+      'Check that your DeepSeek API key is saved and active.',
+      'Verify the selected DeepSeek model is available and your account has quota.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  dashscope: {
+    label: 'DashScope/Qwen',
+    lines: [
+      'Check that your DashScope API key is saved and active.',
+      'Verify the selected Qwen model is available for your account and region.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  zhipu: {
+    label: 'Zhipu/GLM',
+    lines: [
+      'Check that your Zhipu API key is saved and active.',
+      'Verify the selected GLM model is enabled and your account has quota.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  moonshot: {
+    label: 'Moonshot/Kimi',
+    lines: [
+      'Check that your Moonshot API key is saved and active.',
+      'Verify the selected Kimi model is enabled and your account has quota.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  xai: {
+    label: 'xAI',
+    lines: [
+      'Check that your xAI API key is saved and active.',
+      'Verify the selected Grok model is enabled and your account has quota.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+  mistral: {
+    label: 'Mistral',
+    lines: [
+      'Check that your Mistral API key is saved and active.',
+      'Verify the selected Mistral model is enabled and your account has quota.',
+      'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+    ],
+  },
+};
+
+export function isBedrockMissingCredentials(data = {}) {
+  const haystack = [
+    data.message,
+    data.error,
+    data.code,
+    data.phase,
+    data.provider,
+    data.gateway,
+    data.gateway_type,
+    data.exception_type,
+  ].map(lower).join(' ');
+
+  const mentionsBedrock = haystack.includes('bedrock');
+  const mentionsAwsCreds = haystack.includes('aws credentials')
+    || haystack.includes('aws credential')
+    || haystack.includes('aws_access_key')
+    || haystack.includes('aws_secret')
+    || haystack.includes('access key')
+    || haystack.includes('secret access key');
+
+  return mentionsBedrock && mentionsAwsCreds;
+}
+
+export function normalizeGatewayProvider(data = {}) {
+  const direct = [
+    data.provider,
+    data.gateway,
+    data.gateway_type,
+    data.gatewayType,
+  ].map(normalizeProviderToken).find(Boolean);
+  if (direct) return direct;
+
+  const haystack = [
+    data.message,
+    data.error,
+    data.code,
+    data.phase,
+    data.operation,
+    data.exception_type,
+    data.model,
+  ].map(lower).join(' ');
+
+  for (const [alias, provider] of PROVIDER_ALIASES.entries()) {
+    if (haystack.includes(alias)) return provider;
+  }
+  return '';
+}
+
+export function formatAgentErrorGuidance(data = {}) {
+  const message = compact(data.message || data.error || 'Agent execution failed.');
+  const code = compact(data.code);
+  const phase = compact(data.phase);
+  const provider = normalizeGatewayProvider(data);
+  const providerMeta = provider || compact(data.provider || data.gateway || data.gateway_type);
+  const taskId = compact(data.task_id);
+  const retryAfter = data.retry_after != null ? compact(data.retry_after) : '';
+  const retryable = data.retryable === true;
+
+  if (isBedrockMissingCredentials(data)) {
+    return {
+      title: 'AWS Bedrock credentials are missing.',
+      lines: [
+        'Kepler reached the Bedrock gateway, but the backend did not receive AWS Access Key ID and Secret Access Key.',
+        'Open Kepler/AppStak model settings, re-save the AWS Bedrock provider with Access Key ID, Secret Access Key, and Region, then retry.',
+        'If settings were just updated, run /login or restart the CLI so provider settings sync again.',
+      ],
+      meta: buildMeta({ code, phase, provider: provider || 'bedrock', taskId, retryAfter, retryable }),
+    };
+  }
+
+  const lines = [];
+  const providerGuidance = PROVIDER_GUIDANCE[provider];
+  if (phase === 'gateway' || code.includes('gateway')) {
+    const label = providerGuidance?.label || 'provider';
+    lines.push(`The ${label} gateway failed before the agent could respond.`);
+    if (providerGuidance) {
+      lines.push(...providerGuidance.lines);
+    } else {
+      lines.push('Check the selected provider, model, and BYOK credentials in settings, then retry.');
+    }
+  } else if (/authentication|token/i.test(message)) {
+    lines.push('Run /login to re-authenticate.');
+  } else if (/api key|openrouter/i.test(message)) {
+    lines.push('Run /config to set up or refresh your provider settings.');
+  } else if (/backend|network/i.test(message)) {
+    lines.push('Check that the backend is reachable, then retry.');
+  }
+
+  if (retryable && retryAfter) {
+    lines.push(`This looks retryable after ${retryAfter}s.`);
+  } else if (retryable) {
+    lines.push('This looks retryable.');
+  }
+
+  return {
+    title: message,
+    lines,
+    meta: buildMeta({ code, phase, provider: providerMeta, taskId, retryAfter, retryable }),
+  };
+}
+
+function normalizeProviderToken(value) {
+  const raw = lower(value);
+  if (!raw) return '';
+  const compacted = raw.replace(/[^a-z0-9]/g, '');
+  return PROVIDER_ALIASES.get(raw)
+    || PROVIDER_ALIASES.get(compacted)
+    || '';
+}
+
+function buildMeta({ code, phase, provider, taskId, retryAfter, retryable }) {
+  const parts = [];
+  if (provider) parts.push(`provider=${provider}`);
+  if (phase) parts.push(`phase=${phase}`);
+  if (code) parts.push(`code=${code}`);
+  if (retryable) parts.push(`retryable=true`);
+  if (retryAfter) parts.push(`retry_after=${retryAfter}s`);
+  if (taskId) parts.push(`task=${taskId}`);
+  return parts;
+}

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-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':

package/src/terminal/repl.mjs

@@ -40,6 +40,7 @@ import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from '../core/approval.mjs';
 import { resolveBackendUrl } from '../core/backend-url.mjs';
 import { formatMessageWindow, lowWindowStatus, messagesRemaining } from '../core/rate-limit-display.mjs';
+import { formatAgentErrorGuidance } from '../core/error-guidance.mjs';
 import { BUILTIN_AGENTS, runAgent } from './agents.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
@@ -49,6 +50,7 @@ import { buildContextEnvelope } from '../core/context-envelope.mjs';
 import { buildResumeHistory, combineResumeSummaries, getRecentSessions, getSessionDetail, getTranscriptProjectRoots } from '../core/local-store.mjs';
 import { decideResumeMode, projectedTokensForChoice, formatTokens as formatCtxTokens } from '../core/resume-mode.mjs';
 import { appendTask, ensureTaskFiles, loadTaskBoard, moveTask, removeTask, taskCounts, TASK_FILES, updateTask } from '../core/tasks.mjs';
+import { applyCompactSummary, localCompactSummary, parseCompactTailCount, prepareCompactHistory } from '../core/compact-history.mjs';
 import { toolDisplayLabel, toolDisplaySummary } from './tool-display.mjs';
 import { createOrbit } from '../state/orbit.mjs';
 import { attachOrbit, unmount as unmountStatusBar } from '../ui/status-bar.mjs';
@@ -196,6 +198,18 @@ function formatResumeCheckpointStatus(session) {
   return c.dim(` · summarized${pct}`);
 }
 
+function formatResumeContextStatus(session) {
+  const full = formatCtxTokens(session?.contextTokens || 0);
+  const marker = session?.resumeSummary;
+  if (!marker || !Number(marker.sourceMessageCount)) {
+    return c.dim(`${full.padStart(5, ' ')} ctx`);
+  }
+  const resumable = formatCtxTokens(projectedTokensForChoice('checkpoint-full', session.contextTokens || 0, {
+    resumeSummary: marker,
+  }));
+  return c.dim(`${resumable.padStart(5, ' ')} resumable · ${full} full`) + formatResumeCheckpointStatus(session);
+}
+
 function formatRelativeTime(iso) {
   if (!iso) return '';
   const t = Date.parse(iso);
@@ -250,7 +264,7 @@ async function pickResumableSession(resumable, ctx) {
         const ago = formatRelativeTime(s.updatedAt || s.startedAt).padEnd(9, ' ').slice(0, 9);
         const status = endStatusMarker(s.endStatus);
         const msgs = String(s.messageCount).padStart(3, ' ') + ' msgs';
-        const ctx = c.dim(`${formatCtxTokens(s.contextTokens).padStart(5, ' ')} ctx`) + formatResumeCheckpointStatus(s);
+        const ctx = formatResumeContextStatus(s);
         const cost = formatSessionCost(s.costUsd);
         const partial = s.partial ? c.yellow(' ⚠partial') : '';
         const instr = oneLineInstruction(s.instruction, 48);
@@ -308,8 +322,14 @@ async function chooseThresholdMode(ctx, decision) {
   if (rl) rl.pause();
 
   const canFull = decision.mode !== 'no-full-allowed';
+  const hasCheckpoint = Boolean(decision.resumeSummary?.sourceMessageCount);
+  const firstOption = canFull
+    ? { key: 'f', value: 'full', label: 'full transcript', enabled: true }
+    : hasCheckpoint
+      ? { key: 'f', value: 'checkpoint-full', label: 'checkpointed transcript', enabled: true }
+      : { key: 'f', value: 'full', label: 'full transcript', enabled: false };
   const options = [
-    { key: 'f', value: 'full',    label: 'full transcript', enabled: canFull },
+    firstOption,
     { key: 's', value: 'summary', label: 'summary only',    enabled: true },
     { key: '1', value: 'tail-10', label: 'summary + last 10 turns', enabled: true },
     { key: '2', value: 'tail-20', label: 'summary + last 20 turns', enabled: true },
@@ -328,7 +348,8 @@ async function chooseThresholdMode(ctx, decision) {
       const projected = formatCtxTokens(decision.projected);
       const win = formatCtxTokens(decision.windowSize);
       const lines = [];
-      lines.push(`  This session would use  ${c.brand(`${projected} / ${win}`)} tokens  (${pct}%)`);
+      const rawLabel = hasCheckpoint ? 'Raw full transcript would use' : 'This session would use';
+      lines.push(`  ${rawLabel}  ${c.brand(`${projected} / ${win}`)} tokens  (${pct}%)`);
       if (decision.resumeSummary?.sourceMessageCount) {
         const covered = Number(decision.resumeSummary.sourceMessageCount) || 0;
         const full = Number(decision.resumeSummary.fullMessageCount) || 0;
@@ -337,14 +358,18 @@ async function chooseThresholdMode(ctx, decision) {
       }
       lines.push(canFull
         ? `  ${c.yellow('⚠')} ${c.dim('close to the highWatermark — consider a leaner mode:')}`
-        : `  ${c.red('⛔')} ${c.dim('over hardCap — full mode disabled:')}`);
+        : hasCheckpoint
+          ? `  ${c.yellow('⚠')} ${c.dim('raw full is over hardCap — checkpoint/tail modes are available:')}`
+          : `  ${c.red('⛔')} ${c.dim('over hardCap — full mode disabled:')}`);
       lines.push('');
       for (let i = 0; i < options.length; i++) {
         const o = options[i];
         const disabled = !o.enabled;
         const marker = i === selected && !disabled ? c.brand('▸') : ' ';
         const keyTag = c.dim('[') + (disabled ? c.dim(o.key) : c.brand(o.key)) + c.dim(']');
-        const proj = formatCtxTokens(projectedTokensForChoice(o.value, decision.projected));
+        const proj = formatCtxTokens(projectedTokensForChoice(o.value, decision.projected, {
+          resumeSummary: decision.resumeSummary,
+        }));
         const label = disabled ? c.dim(o.label) : (i === selected ? c.brand(o.label) : o.label);
         const projCol = c.dim(`${proj.padStart(5, ' ')} ctx`);
         const suffix = disabled ? c.dim('  (over hardCap)') : '';
@@ -389,6 +414,7 @@ async function chooseThresholdMode(ctx, decision) {
 }
 
 function resumeModeLabel(mode = 'full') {
+  if (mode === 'checkpoint-full') return 'checkpointed transcript';
   if (mode === 'summary') return 'summary only';
   const tailTurns = resumeTailTurnCount(mode);
   if (tailTurns) return `summary + last ${tailTurns} turns`;
@@ -434,7 +460,7 @@ async function previewResumeSession(session, ctx) {
       if (scrollOffset > maxOffset) scrollOffset = maxOffset;
 
       const lines = [];
-      lines.push(`  ${c.bold('Preview:')} ${c.brand(session.project || '(unknown)')}  ${c.dim('Mode:')} ${c.brand(resumeModeLabel(mode))}  ${c.dim(formatCtxTokens(projectedTokensForChoice(mode, session.contextTokens)) + ' ctx')}`);
+      lines.push(`  ${c.bold('Preview:')} ${c.brand(session.project || '(unknown)')}  ${c.dim('Mode:')} ${c.brand(resumeModeLabel(mode))}  ${c.dim(formatCtxTokens(projectedTokensForChoice(mode, session.contextTokens, { resumeSummary: session.resumeSummary })) + ' ctx')}`);
       lines.push(`  ${c.dim('─'.repeat(60))}`);
       for (let i = scrollOffset; i < Math.min(scrollOffset + rows, totalLines); i++) {
         lines.push(fitAnsiLine(`  ${c.dim(contentLines[i] || '')}`, cols - 1));
@@ -460,7 +486,7 @@ async function previewResumeSession(session, ctx) {
       if (key === '') { scrollOffset += 1; render(); return; }
       if (key === '[5~') { scrollOffset = Math.max(0, scrollOffset - 10); render(); return; }
       if (key === '[6~') { scrollOffset += 10; render(); return; }
-      if (low === 'f') { mode = 'full'; history = rich(); scrollOffset = 0; render(); return; }
+      if (low === 'f') { mode = session.resumeSummary?.sourceMessageCount ? 'checkpoint-full' : 'full'; history = rich(); scrollOffset = 0; render(); return; }
       if (low === 's') { mode = 'summary'; history = rich(); scrollOffset = 0; render(); return; }
       if (low === '1') { mode = 'tail-10'; history = rich(); scrollOffset = 0; render(); return; }
       if (low === '2') { mode = 'tail-20'; history = rich(); scrollOffset = 0; render(); return; }
@@ -659,6 +685,120 @@ async function summarizeResumeTranscript({
   }
 }
 
+async function compactCurrentSession(ctx, rest = '') {
+  const tailCount = parseCompactTailCount(rest, 8);
+  const preparedLive = prepareCompactHistory({
+    agentHistory: session.agentHistory,
+    tailCount,
+  });
+  if (!preparedLive.ok) {
+    process.stderr.write(`  ${c.gray(`Nothing to compact — ${preparedLive.reason}.`)}\n`);
+    return;
+  }
+
+  const progress = startResumeProgress('compact');
+  progress.update('preparing compact summary', 18);
+  let sourceMessages = preparedLive.sourceMessages;
+  let priorSummary = preparedLive.previousSummary || '';
+  let previousSourceMessageCount = 0;
+  let fullMessageCount = preparedLive.beforeCount;
+  let projectPath = safeCwd();
+  let sourceFrom = 'live';
+  let summaryWarning = '';
+
+  try {
+    if (session.id && ctx.jsonlWriter?.flush) {
+      progress.update('reading transcript checkpoint', 28);
+      await ctx.jsonlWriter.flush();
+      const detail = await getSessionDetail(session.id, { filePath: ctx.jsonlWriter.transcriptPath });
+      if (detail) {
+        const richHistory = buildResumeHistory({ ...detail, recapTailTurns: 8 }, `tail-${tailCount}`);
+        if (richHistory.sourceMessages?.length) {
+          sourceMessages = richHistory.sourceMessages;
+          priorSummary = richHistory.priorSummary || '';
+          previousSourceMessageCount = richHistory.summaryCheckpointMessageCount || 0;
+          fullMessageCount = richHistory.fullMessageCount || sourceMessages.length;
+          projectPath = detail.meta?.project || safeCwd();
+          sourceFrom = 'transcript';
+        } else if (richHistory.priorSummary) {
+          priorSummary = richHistory.priorSummary;
+          previousSourceMessageCount = richHistory.summaryCheckpointMessageCount || 0;
+          fullMessageCount = richHistory.fullMessageCount || preparedLive.beforeCount;
+        }
+      }
+    }
+
+    if (!sourceMessages.length) {
+      progress.stop();
+      process.stderr.write(`  ${c.gray('Nothing new to compact.')}\n`);
+      return;
+    }
+
+    progress.update('summarizing compacted history', 46);
+    const backendSummary = await summarizeResumeTranscript({
+      auth: ctx.auth,
+      toolExecutor: ctx.toolExecutor,
+      sessionId: session.id,
+      projectPath,
+      messages: sourceMessages,
+    });
+    let summarySource = backendSummary?.summary ? (backendSummary.source || 'backend') : 'local fallback';
+    let deltaSummary = backendSummary?.summary || '';
+    if (!deltaSummary) {
+      summaryWarning = backendSummary?.reason || 'backend summary unavailable';
+      deltaSummary = localCompactSummary(sourceMessages);
+    }
+    const summary = combineResumeSummaries(priorSummary, deltaSummary);
+
+    progress.update('rewriting live context', 74);
+    const applied = applyCompactSummary({
+      prepared: { ...preparedLive, sourceMessages },
+      summary,
+      sessionId: session.id,
+      cwd: projectPath,
+      originalRequest: session.history.find(m => m.role === 'user')?.content || session.lastTask || '',
+      previousSourceMessageCount,
+    });
+    session.agentHistory = applied.agentHistory;
+    session.compactSummary = summary;
+    session.compactSourceMessageCount = applied.sourceMessageCount;
+
+    if (ctx.jsonlWriter) {
+      progress.update('writing summary checkpoint', 88);
+      ctx.jsonlWriter.writeKeplerEvent({
+        type: 'resume_summary',
+        data: {
+          session_id: session.id || null,
+          mode: 'compact',
+          mode_label: '/compact',
+          summary,
+          summary_source: summarySource,
+          summary_warning: summaryWarning || null,
+          source: sourceFrom,
+          source_message_count: applied.sourceMessageCount,
+          previous_source_message_count: previousSourceMessageCount,
+          full_message_count: fullMessageCount,
+          retained_tail_messages: applied.retainedCount,
+          live_before_messages: applied.beforeCount,
+          live_after_messages: applied.afterCount,
+        },
+      });
+      await ctx.jsonlWriter.flush?.();
+    }
+
+    progress.stop();
+    process.stderr.write(
+      `  ${c.green('✓')} ${c.dim(`Compacted context: ${applied.beforeCount} → ${applied.afterCount} live messages · retained ${applied.retainedCount} · summary ${summarySource}`)}\n`
+    );
+    if (summaryWarning) {
+      process.stderr.write(`  ${c.yellow('⚠')} ${c.dim(`backend summary unavailable — used local summary (${summaryWarning})`)}\n`);
+    }
+  } catch (err) {
+    progress.stop();
+    process.stderr.write(`  ${c.red(`Compact failed: ${err?.message || String(err)}`)}\n`);
+  }
+}
+
 function resumeTailTurnCount(mode = '') {
   const match = String(mode || '').match(/^tail-(\d+)$/);
   if (!match) return null;
@@ -1224,10 +1364,12 @@ function updateStatusBar() {
 // buffered head as a regular two-line shape first so the interleaving
 // content lands below it.
 let _pendingHead = null; // { callId, head, indent }
+let _lastRenderedBlock = null; // 'tool' | 'content' | null
 
 function flushPendingHead() {
   if (!_pendingHead) return;
-  process.stderr.write(`\n${_pendingHead.head}\n`);
+  process.stderr.write(`${_pendingHead.head}\n`);
+  _lastRenderedBlock = 'tool';
   _pendingHead = null;
 }
 
@@ -1312,7 +1454,8 @@ function renderToolResult(data, eventType = 'tool_result') {
     const cols = process.stderr.columns || 120;
     const combined = `${_pendingHead.head}  ${outcome}`;
     if (stripAnsi(combined).length <= cols) {
-      process.stderr.write(`\n${combined}\n`);
+      process.stderr.write(`${combined}\n`);
+      _lastRenderedBlock = 'tool';
       _pendingHead = null;
       return;
     }
@@ -1326,6 +1469,7 @@ function renderToolResult(data, eventType = 'tool_result') {
 
   // Two-line shape: gutter under the (already-printed or just-flushed) head.
   process.stderr.write(`${gutter}${outcome}\n`);
+  _lastRenderedBlock = 'tool';
 
   // Lint warnings stay visible alongside writes.
   if (hasLint) {
@@ -1448,6 +1592,7 @@ function startContentStream() {
   _streamedPartialText = '';
   _renderedToolResults.clear();
   _renderedContentThisTurn = false;
+  _lastRenderedBlock = null;
   stopSpinner();
 }
 
@@ -1472,12 +1617,14 @@ function flushContent() {
   // Any buffered tool head needs to land BEFORE this content so the order
   // is preserved on screen.
   flushPendingHead();
+  if (_lastRenderedBlock === 'tool') process.stderr.write('\n');
   const rendered = renderMarkdown(_streamBuffer);
   for (const line of rendered.split('\n')) {
     process.stdout.write(`  ${line}\n`);
   }
   _streamBuffer = '';
   _renderedContentThisTurn = true;
+  _lastRenderedBlock = 'content';
 }
 
 // ── Event Renderer ──
@@ -1529,11 +1676,13 @@ function renderEvent(event) {
         }
       }
       if (text) {
+        if (_lastRenderedBlock === 'tool') process.stderr.write('\n');
         const rendered = renderMarkdown(text);
         for (const line of rendered.split('\n')) {
           process.stdout.write(`  ${line}\n`);
         }
         _renderedContentThisTurn = true;
+        _lastRenderedBlock = 'content';
       }
       break;
     }
@@ -1760,9 +1909,15 @@ function renderEvent(event) {
     case 'error':
       stopSpinner();
       flushContent();
-      process.stderr.write(`\n  ${c.red('✗')} ${data?.message || 'Unknown error'}\n`);
-      if ((data?.message || '').includes('Authentication')) {
-        process.stderr.write(`  ${c.dim('Run /login to re-authenticate')}\n`);
+      {
+        const guidance = formatAgentErrorGuidance(data || {});
+        process.stderr.write(`\n  ${c.red('✗')} ${guidance.title}\n`);
+        for (const line of guidance.lines) {
+          process.stderr.write(`  ${c.dim(line)}\n`);
+        }
+        if (guidance.meta.length) {
+          process.stderr.write(`  ${c.dim(guidance.meta.join(' · '))}\n`);
+        }
       }
       break;
 
@@ -2576,10 +2731,7 @@ async function handleCommand(input, ctx) {
     }
 
     case '/compact': {
-      const before = session.agentHistory.length || session.history.length;
-      if (before <= 4) { process.stderr.write(`  ${c.gray('Nothing to compact.')}\n`); return; }
-      session.agentHistory.splice(2, session.agentHistory.length - 6);
-      process.stderr.write(`  ${c.gray(`Compacted agent context: ${before} → ${session.agentHistory.length} messages`)}\n`);
+      await compactCurrentSession(ctx, rest);
       return;
     }
 

package/src/ui/formatter.mjs

@@ -10,6 +10,7 @@
 
 import { toolDisplayLabel, toolDisplaySummary } from '../terminal/tool-display.mjs';
 import { formatMessageWindow } from '../core/rate-limit-display.mjs';
+import { formatAgentErrorGuidance } from '../core/error-guidance.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -309,16 +310,13 @@ export class EventFormatter {
     }
 
     _error(data) {
-        const msg = data?.message || 'Unknown error';
-        process.stderr.write(`\n  ${RED}✗ ${msg}${RESET}\n`);
-
-        // Helpful suggestions for common errors
-        if (msg.includes('Authentication') || msg.includes('token')) {
-            process.stderr.write(`  ${DIM}Run /login to re-authenticate${RESET}\n`);
-        } else if (msg.includes('API key') || msg.includes('OpenRouter')) {
-            process.stderr.write(`  ${DIM}Run /config to set up your provider${RESET}\n`);
-        } else if (msg.includes('Backend') || msg.includes('Network')) {
-            process.stderr.write(`  ${DIM}Check if the backend is running at ${this.sessionInfo?.backend || 'localhost:8150'}${RESET}\n`);
+        const guidance = formatAgentErrorGuidance(data || {});
+        process.stderr.write(`\n  ${RED}✗ ${guidance.title}${RESET}\n`);
+        for (const line of guidance.lines) {
+            process.stderr.write(`  ${DIM}${line}${RESET}\n`);
+        }
+        if (guidance.meta.length) {
+            process.stderr.write(`  ${DIM}${guidance.meta.join(' · ')}${RESET}\n`);
         }
     }