@skein-code/cli 0.3.11 → 0.3.12

package/dist/cli.js

@@ -220,7 +220,7 @@ function isSqliteBusy(error) {
 // package.json
 var package_default = {
   name: "@skein-code/cli",
-  version: "0.3.11",
+  version: "0.3.12",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,9 +236,9 @@ var package_default = {
   },
   skein: {
     releaseNotes: [
-      "Large tool results now use a language-aware dynamic token budget with status-preserving head and tail receipts",
-      "Complete captured output can be read back through redacted, expiring, session-scoped local artifacts",
-      "Shell and MCP source truncation is explicit, and session deletion removes retained output"
+      "Each model request records privacy-safe token partitions and actual-versus-estimated provenance",
+      "Local retrieval now selects focused, standard, broad, or maximum evidence budgets",
+      "Terminal and JSON diagnostics expose budget decisions without storing prompt or source content"
     ]
   },
   bin: {
@@ -2484,6 +2484,112 @@ function shouldUseProviderEnvironmentKey(provider, baseUrl) {
   return baseUrl.replace(/\/+$/u, "") === official[provider];
 }
 
+// src/context/budget.ts
+var tierTokens = {
+  focused: 2e3,
+  standard: 4e3,
+  broad: 8e3,
+  maximum: 12e3
+};
+function selectContextBudget(query, config, options = {}) {
+  if (options.trivial) return noContextBudget("trivial turn; retrieval skipped");
+  const configuredCeiling = positiveFloor(options.maxTokens ?? config.context.maxTokens);
+  const configuredTopK = positiveFloor(options.topK ?? config.context.topK);
+  if (configuredCeiling === 0 || configuredTopK === 0) {
+    return noContextBudget("retrieval disabled by the configured context ceiling");
+  }
+  const normalized = query.trim().toLocaleLowerCase();
+  const explicitPaths = countExplicitPaths(query);
+  const breadthSignals = countMatches(normalized, [
+    /\b(?:cross[- ]module|cross[- ]package|across modules|across packages|entire repository|whole repository|whole codebase|all modules|all packages|end[- ]to[- ]end)\b/gu,
+    /跨模块|跨包|全仓库|全代码库|整个(?:项目|仓库|代码库)|所有(?:模块|包)|端到端/gu
+  ]);
+  const exhaustiveSignals = countMatches(normalized, [
+    /\b(?:exhaustive|comprehensive|repository[- ]wide|codebase[- ]wide|all call sites|all usages|architecture migration|security audit)\b/gu,
+    /全面|完整审计|全量|全局迁移|所有调用|所有引用|架构迁移|安全审计/gu
+  ]);
+  const coordinationSignals = countMatches(normalized, [
+    /\b(?:and|then|also|plus|including|migrate|redesign|architecture|integration|workflow)\b/gu,
+    /并且|然后|同时|以及|包括|迁移|重设计|架构|集成|工作流/gu
+  ]);
+  let tier;
+  let reason;
+  if (breadthSignals > 0 && exhaustiveSignals > 0 && (coordinationSignals >= 2 || normalized.length >= 180)) {
+    tier = "maximum";
+    reason = "explicit repository-wide work with exhaustive, multi-part scope";
+  } else if (breadthSignals > 0 || exhaustiveSignals >= 2) {
+    tier = "broad";
+    reason = "cross-module or repository-wide evidence requested";
+  } else if (explicitPaths > 0 && coordinationSignals < 2) {
+    tier = "focused";
+    reason = "one or more explicit paths bound the evidence surface";
+  } else if ((options.intent === "explain" || options.intent === "review" || options.intent === "test") && normalized.length <= 160 && coordinationSignals < 2) {
+    tier = "focused";
+    reason = `short ${options.intent} request with a narrow evidence surface`;
+  } else {
+    tier = "standard";
+    reason = "ordinary implementation, debugging, or refactoring request";
+  }
+  const requestedTokens = tierTokens[tier];
+  const budgetTokens = Math.min(configuredCeiling, requestedTokens);
+  const baseBudgetTokens = Math.min(budgetTokens, tierTokens.focused);
+  const incrementalBudgetTokens = Math.max(0, budgetTokens - baseBudgetTokens);
+  const topKByTier = {
+    focused: 4,
+    standard: 8,
+    broad: 12,
+    maximum: 16
+  };
+  const topK = Math.min(configuredTopK, topKByTier[tier]);
+  const capped = budgetTokens < requestedTokens ? `; capped by configuration at ${budgetTokens} tokens` : "";
+  return {
+    tier,
+    budgetTokens,
+    baseBudgetTokens,
+    incrementalBudgetTokens,
+    topK,
+    reason: `${reason}${capped}`
+  };
+}
+function emptyPackedContext(decision, engine = "local") {
+  return {
+    text: "",
+    hits: [],
+    estimatedTokens: 0,
+    engine,
+    truncated: false,
+    budgetTier: decision.tier,
+    budgetTokens: decision.budgetTokens,
+    baseBudgetTokens: decision.baseBudgetTokens,
+    incrementalBudgetTokens: decision.incrementalBudgetTokens,
+    budgetReason: decision.reason,
+    candidateHits: 0,
+    selectedHits: 0,
+    duplicateHits: 0,
+    incrementalEvidenceTokens: 0
+  };
+}
+function noContextBudget(reason) {
+  return {
+    tier: "none",
+    budgetTokens: 0,
+    baseBudgetTokens: 0,
+    incrementalBudgetTokens: 0,
+    topK: 0,
+    reason
+  };
+}
+function positiveFloor(value) {
+  return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+function countMatches(value, patterns) {
+  return patterns.reduce((total, pattern) => total + [...value.matchAll(pattern)].length, 0);
+}
+function countExplicitPaths(value) {
+  const matches = value.match(/(?:^|[\s'"`(])@?(?:\.{0,2}[/\\]|[A-Za-z]:[/\\]|[\w.-]+[/\\])[\w@%+.,()[\]{}=-]+(?:[/\\][\w@%+.,()[\]{}=-]+)*(?:\.\w+)?/gu);
+  return matches?.length ?? 0;
+}
+
 // src/context/local-index.ts
 import { createHash as createHash5 } from "node:crypto";
 import { lstat as lstat8, readFile as readFile3, stat as stat3 } from "node:fs/promises";
@@ -2604,6 +2710,58 @@ async function pathExists(path) {
   }
 }
 
+// src/utils/tokens.ts
+function estimateTokens(value) {
+  let tokens2 = 0;
+  for (const character of value) tokens2 += estimatedTokenCost(character);
+  return Math.ceil(tokens2 - Number.EPSILON * Math.max(1, value.length) * 32);
+}
+function estimatedTokenCost(character) {
+  const codePoint = character.codePointAt(0) ?? 0;
+  if (codePoint <= 127) return 0.25;
+  if (isEmojiOrSupplementarySymbol(character, codePoint)) return 2;
+  if (/^[\p{P}\p{S}]$/u.test(character)) return 0.5;
+  if (isCjkCharacter(codePoint)) return 1;
+  return 2;
+}
+function sliceStartByTokens(value, budget) {
+  if (budget <= 0) return "";
+  let used = 0;
+  let end = 0;
+  for (const character of value) {
+    const cost = estimatedTokenCost(character);
+    if (used + cost > budget) break;
+    used += cost;
+    end += character.length;
+  }
+  return value.slice(0, end);
+}
+function sliceEndByTokens(value, budget) {
+  if (budget <= 0) return "";
+  let used = 0;
+  let start = value.length;
+  while (start > 0) {
+    let next = start - 1;
+    const code = value.charCodeAt(next);
+    if (code >= 56320 && code <= 57343 && next > 0) {
+      const previous = value.charCodeAt(next - 1);
+      if (previous >= 55296 && previous <= 56319) next -= 1;
+    }
+    const character = value.slice(next, start);
+    const cost = estimatedTokenCost(character);
+    if (used + cost > budget) break;
+    used += cost;
+    start = next;
+  }
+  return value.slice(start);
+}
+function isCjkCharacter(codePoint) {
+  return codePoint >= 11904 && codePoint <= 40959 || codePoint >= 44032 && codePoint <= 55215 || codePoint >= 63744 && codePoint <= 64255 || codePoint >= 131072 && codePoint <= 195103 || codePoint >= 12352 && codePoint <= 12543;
+}
+function isEmojiOrSupplementarySymbol(character, codePoint) {
+  return codePoint > 65535 || new RegExp("\\p{Extended_Pictographic}", "u").test(character);
+}
+
 // src/context/local-index.ts
 var contentHashSchema = z3.string().regex(/^[a-f\d]{64}$/u);
 var indexedChunkSchema = z3.object({
@@ -3045,17 +3203,31 @@ function packContextHits(hits, roots, maxTokens, engine) {
   const uniquePaths = new Set(hits.map((hit) => hit.path)).size;
   let estimatedTokens = 0;
   let truncated = false;
+  let duplicateHits = 0;
+  let perFileLimitHits = 0;
   for (const hit of hits) {
     const count = perFile.get(hit.path) ?? 0;
-    if (uniquePaths > 1 && count >= 2) continue;
-    if (selected.some((candidate) => hasSubstantialOverlap(candidate, hit))) continue;
+    if (uniquePaths > 1 && count >= 2) {
+      perFileLimitHits += 1;
+      continue;
+    }
+    if (selected.some((candidate) => hasSubstantialOverlap(candidate, hit))) {
+      duplicateHits += 1;
+      continue;
+    }
     const tokens2 = estimateTokens(hit.content);
     if (estimatedTokens + tokens2 > maxTokens) {
-      const remainingChars = Math.max(0, (maxTokens - estimatedTokens) * 4);
-      if (remainingChars >= 32) {
-        selected.push({ ...hit, content: hit.content.slice(0, remainingChars) });
+      const remainingTokens = Math.max(0, maxTokens - estimatedTokens);
+      const content = sliceStartByTokens(hit.content, remainingTokens);
+      if (content.length >= 32) {
+        const returnedLines = Math.max(1, content.split("\n").length);
+        selected.push({
+          ...hit,
+          content,
+          endLine: Math.min(hit.endLine, hit.startLine + returnedLines - 1)
+        });
         perFile.set(hit.path, count + 1);
-        estimatedTokens = maxTokens;
+        estimatedTokens += estimateTokens(content);
       }
       truncated = true;
       break;
@@ -3071,7 +3243,16 @@ function packContextHits(hits, roots, maxTokens, engine) {
 ${hit.content}
 </code>`;
   }).join("\n\n");
-  return { text, hits: selected, estimatedTokens, engine, truncated };
+  return {
+    text,
+    hits: selected,
+    estimatedTokens,
+    engine,
+    truncated,
+    candidateHits: hits.length,
+    selectedHits: selected.length,
+    duplicateHits: duplicateHits + perFileLimitHits
+  };
 }
 function cloneHits(hits) {
   return hits.map((hit) => ({ ...hit }));
@@ -3082,9 +3263,6 @@ function hashContent(content) {
 function createGeneration(files) {
   return createHash5("sha256").update(files.slice().sort((left, right) => left.absolutePath.localeCompare(right.absolutePath)).map((file) => `${file.absolutePath}\0${file.contentHash}`).join("\n"), "utf8").digest("hex").slice(0, 16);
 }
-function estimateTokens(content) {
-  return Math.ceil(content.length / 4);
-}
 function hasSubstantialOverlap(left, right) {
   if (left.path !== right.path) return false;
   const overlap = Math.max(0, Math.min(left.endLine, right.endLine) - Math.max(left.startLine, right.startLine) + 1);
@@ -3205,15 +3383,28 @@ var ContextEngine = class {
   config;
   local;
   degradation;
-  async pack(query) {
+  async pack(query, options = {}) {
+    const decision = selectContextBudget(query, this.config, options);
+    if (decision.budgetTokens === 0 || decision.topK === 0) {
+      this.degradation = void 0;
+      return emptyPackedContext(decision);
+    }
     try {
       const packed = await this.local.pack(
         query,
-        this.config.context.topK,
-        this.config.context.maxTokens
+        decision.topK,
+        decision.budgetTokens
       );
       this.degradation = void 0;
-      return packed;
+      return {
+        ...packed,
+        budgetTier: decision.tier,
+        budgetTokens: decision.budgetTokens,
+        baseBudgetTokens: decision.baseBudgetTokens,
+        incrementalBudgetTokens: decision.incrementalBudgetTokens,
+        budgetReason: decision.reason,
+        incrementalEvidenceTokens: Math.max(0, packed.estimatedTokens - decision.baseBudgetTokens)
+      };
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
       this.degradation = {
@@ -3223,11 +3414,7 @@ var ContextEngine = class {
       };
       const degradation = this.lastDegradation();
       return {
-        text: "",
-        hits: [],
-        estimatedTokens: 0,
-        engine: "local",
-        truncated: false,
+        ...emptyPackedContext(decision),
         ...degradation ? { degradation } : {}
       };
     }
@@ -3324,7 +3511,7 @@ var ContextManager = class {
   status(session, modelContextTokens) {
     const active = activeMessages(session);
     const activeTokens = estimateMessages(active);
-    const summaryTokens = estimateTokens2(session.contextSummary ?? "");
+    const summaryTokens = estimateTokens(session.contextSummary ?? "");
     const toolTokenCount = toolTokens(active);
     const contextLimit = Math.max(
       8e3,
@@ -3351,11 +3538,11 @@ var ContextManager = class {
     const active = activeMessages(session);
     const cut = compactionCut(active);
     if (cut === 0) {
-      return { omittedMessages: 0, summaryTokens: estimateTokens2(session.contextSummary ?? "") };
+      return { omittedMessages: 0, summaryTokens: estimateTokens(session.contextSummary ?? "") };
     }
     const older = active.slice(0, cut);
     if (!older.length) {
-      return { omittedMessages: 0, summaryTokens: estimateTokens2(session.contextSummary ?? "") };
+      return { omittedMessages: 0, summaryTokens: estimateTokens(session.contextSummary ?? "") };
     }
     const transcript = older.map(formatMessageForSummary).join("\n\n").slice(-14e4);
     const response = await provider.complete([
@@ -3376,7 +3563,7 @@ ${transcript}`)
     session.contextCompactions = (session.contextCompactions ?? 0) + 1;
     return {
       omittedMessages: older.length,
-      summaryTokens: estimateTokens2(session.contextSummary)
+      summaryTokens: estimateTokens(session.contextSummary)
     };
   }
   buildShortTermPrompt(session) {
@@ -3505,13 +3692,10 @@ function concise(value, max) {
   return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}\u2026`;
 }
 function estimateMessages(messages) {
-  return messages.reduce((sum, message2) => sum + estimateTokens2(message2.content) + estimateTokens2(JSON.stringify(message2.toolCalls ?? [])), 0);
+  return messages.reduce((sum, message2) => sum + estimateTokens(message2.content) + estimateTokens(JSON.stringify(message2.toolCalls ?? [])), 0);
 }
 function toolTokens(messages) {
-  return messages.filter((message2) => message2.role === "tool").reduce((sum, message2) => sum + estimateTokens2(message2.content), 0);
-}
-function estimateTokens2(value) {
-  return Math.ceil(value.length / 4);
+  return messages.filter((message2) => message2.role === "tool").reduce((sum, message2) => sum + estimateTokens(message2.content), 0);
 }
 
 // src/context/mentions.ts
@@ -5058,8 +5242,54 @@ var sessionSchema = z5.object({
   lastRun: lastRunSchema.optional(),
   usage: z5.object({
     inputTokens: z5.number().nonnegative(),
-    outputTokens: z5.number().nonnegative()
-  }).strict()
+    outputTokens: z5.number().nonnegative(),
+    source: z5.enum(["actual", "estimated", "mixed", "unknown"]).optional(),
+    inputSource: z5.enum(["actual", "estimated", "mixed", "unknown"]).optional(),
+    outputSource: z5.enum(["actual", "estimated", "mixed", "unknown"]).optional(),
+    actualInputTokens: z5.number().nonnegative().optional(),
+    actualOutputTokens: z5.number().nonnegative().optional(),
+    estimatedInputTokens: z5.number().nonnegative().optional(),
+    estimatedOutputTokens: z5.number().nonnegative().optional()
+  }).strict(),
+  tokenLedger: z5.array(z5.object({
+    requestId: z5.string().uuid(),
+    turn: z5.number().int().positive(),
+    recordedAt: z5.string().datetime(),
+    estimated: z5.object({
+      stableTokens: z5.number().nonnegative(),
+      dynamicTokens: z5.number().nonnegative(),
+      conversationTokens: z5.number().nonnegative(),
+      toolResultTokens: z5.number().nonnegative(),
+      retrievedTokens: z5.number().nonnegative(),
+      toolSchemaTokens: z5.number().nonnegative(),
+      estimatedInputTokens: z5.number().nonnegative(),
+      outputAllowanceTokens: z5.number().nonnegative(),
+      outputTokens: z5.number().nonnegative()
+    }).strict(),
+    actual: z5.object({
+      inputTokens: z5.number().nonnegative().optional(),
+      outputTokens: z5.number().nonnegative().optional()
+    }).strict(),
+    inputSource: z5.enum(["actual", "estimated"]),
+    outputSource: z5.enum(["actual", "estimated"]),
+    tools: z5.object({
+      loaded: z5.array(z5.string()),
+      deferredCount: z5.number().int().nonnegative()
+    }).strict(),
+    retrieval: z5.object({
+      engine: z5.string(),
+      budgetTier: z5.enum(["none", "focused", "standard", "broad", "maximum"]).optional(),
+      budgetTokens: z5.number().nonnegative().optional(),
+      candidateHits: z5.number().int().nonnegative().optional(),
+      selectedHits: z5.number().int().nonnegative().optional(),
+      duplicateHits: z5.number().int().nonnegative().optional(),
+      incrementalEvidenceTokens: z5.number().nonnegative().optional(),
+      discarded: z5.array(z5.object({
+        reason: z5.enum(["overlapping-span", "budget-cap"]),
+        count: z5.number().int().positive()
+      }).strict())
+    }).strict()
+  }).strict()).max(256).optional()
 }).strict();
 var SessionStore = class {
   workspace;
@@ -8331,11 +8561,7 @@ function dynamicToolOutputBudget(contextWindowTokens, activeContextTokens, remai
   return clamp2(budget, MIN_TOOL_OUTPUT_TOKENS, MAX_TOOL_OUTPUT_TOKENS);
 }
 function estimateToolOutputTokens(value) {
-  let tokens2 = 0;
-  for (const character of value) {
-    tokens2 += tokenCost(character);
-  }
-  return Math.max(1, Math.ceil(tokens2));
+  return Math.max(1, estimateTokens(value));
 }
 function formatReceipt(options, metadata, preview) {
   const lines = [
@@ -8399,35 +8625,6 @@ function sanitizeToolOutput(value) {
   const text = stripAnsi(value).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "");
   return { text, sanitized: text !== value };
 }
-function sliceStartByTokens(value, budget) {
-  let used = 0;
-  let end = 0;
-  for (const character of value) {
-    const cost = tokenCost(character);
-    if (used + cost > budget) break;
-    used += cost;
-    end += character.length;
-  }
-  return value.slice(0, end);
-}
-function sliceEndByTokens(value, budget) {
-  let used = 0;
-  let start = value.length;
-  while (start > 0) {
-    let next = start - 1;
-    const code = value.charCodeAt(next);
-    if (code >= 56320 && code <= 57343 && next > 0) {
-      const previous = value.charCodeAt(next - 1);
-      if (previous >= 55296 && previous <= 56319) next -= 1;
-    }
-    const character = value.slice(next, start);
-    const cost = tokenCost(character);
-    if (used + cost > budget) break;
-    used += cost;
-    start = next;
-  }
-  return value.slice(start);
-}
 function boundedPreview(value, budget) {
   if (budget <= 0) return "";
   if (estimateToolOutputTokens(value) <= budget) return value;
@@ -8452,15 +8649,6 @@ ${tail}`;
   }
   return best || sliceStartByTokens(value, budget);
 }
-function tokenCost(character) {
-  const code = character.codePointAt(0) ?? 0;
-  if (isCjkCharacter(character) || code > 127) return 2;
-  return /[A-Z0-9\p{P}\p{S}]/u.test(character) ? 0.5 : 0.25;
-}
-function isCjkCharacter(character) {
-  const code = character.codePointAt(0) ?? 0;
-  return code >= 11904 && code <= 40959 || code >= 44032 && code <= 55215 || code >= 63744 && code <= 64255 || code >= 131072 && code <= 195103;
-}
 function clamp2(value, minimum, maximum) {
   return Math.max(minimum, Math.min(maximum, value));
 }
@@ -8468,7 +8656,7 @@ function boundedInlineByTokens(value, maxTokens) {
   const normalized = value.replace(/[\r\n\t]+/gu, " ").trim();
   if (estimateToolOutputTokens(normalized) <= maxTokens) return normalized;
   const suffix = "\u2026";
-  return `${sliceStartByTokens(normalized, Math.max(0, maxTokens - tokenCost(suffix)))}${suffix}`;
+  return `${sliceStartByTokens(normalized, Math.max(0, maxTokens - estimatedTokenCost(suffix)))}${suffix}`;
 }
 
 // src/agent/rules.ts
@@ -8543,9 +8731,6 @@ import { readFile as readFile13, stat as stat9 } from "node:fs/promises";
 var MAX_SOURCE_CHARS = 6e4;
 var MAX_PINNED_CHARS = 16e4;
 var MAX_CONTEXT_SOURCES = 32;
-function estimateTokens3(value) {
-  return Math.ceil(value.length / 4);
-}
 function sources(session) {
   return session.contextSources ?? (session.contextSources = []);
 }
@@ -8553,7 +8738,7 @@ async function pinContextSource(session, workspace, requested) {
   const resolved = await workspace.resolvePath(requested, { expect: "file" });
   const info = await stat9(resolved);
   const alias = workspace.display(resolved);
-  const tokens2 = estimateTokens3((await readFile13(resolved, "utf8")).slice(0, MAX_SOURCE_CHARS));
+  const tokens2 = estimateTokens((await readFile13(resolved, "utf8")).slice(0, MAX_SOURCE_CHARS));
   const list2 = sources(session);
   const existing = list2.find((source2) => source2.path === alias);
   if (existing) {
@@ -8605,7 +8790,7 @@ async function resolvePinnedContent(session, workspace) {
       const safe = await workspace.resolvePath(source.path, { expect: "file" });
       const raw = await readFile13(safe, "utf8");
       const capped = raw.slice(0, Math.min(MAX_SOURCE_CHARS, remaining));
-      source.tokens = estimateTokens3(capped);
+      source.tokens = estimateTokens(capped);
       resolved.push({
         path: source.path,
         content: capped,
@@ -8771,13 +8956,20 @@ var AgentRunner = class {
         this.session.title = titleFromInput(request);
       }
       this.contextManager.startTurn(this.session, request);
-      this.session.messages.push(message("user", request));
+      const userMessage = message("user", request);
+      this.session.messages.push(userMessage);
       await this.persist();
       const trivialTurn = isTrivialTurn(request);
-      const packed = await this.packContext(request);
+      const turnDirective = buildTurnDirective(request, {
+        agents: Boolean(this.config.agents?.enabled)
+      });
+      const packed = trivialTurn ? emptyPackedContext(selectContextBudget(request, this.config, {
+        intent: turnDirective.intent,
+        trivial: true
+      })) : await this.packContext(request, { intent: turnDirective.intent });
       if (!trivialTurn) await emit({ type: "context", packed });
       const mentions = await this.packMentions(request);
-      const retrievedContext = buildRetrievedContext(
+      const retrievedContext = trivialTurn && !mentions.length ? "" : buildRetrievedContext(
         packed,
         mentions,
         this.workspace.primaryRoot,
@@ -8803,9 +8995,6 @@ var AgentRunner = class {
           scope: augmentation.memoryScope ?? "session"
         });
       }
-      const turnDirective = buildTurnDirective(request, {
-        agents: Boolean(this.config.agents?.enabled)
-      });
       const contractEnabled = shouldUseTaskContract(
         request,
         turnDirective.intent,
@@ -8829,21 +9018,6 @@ var AgentRunner = class {
         ...augmentation.skills?.length ? [`skills:${augmentation.skills.length}`] : [],
         ...augmentation.memoryCount ? [`memory:${augmentation.memoryCount}`] : []
       ];
-      if (!trivialTurn) await emit({
-        type: "prompt",
-        intent: turnDirective.intent,
-        sections: promptSections,
-        estimatedTokens: Math.ceil([
-          turnDirective.text,
-          buildSessionStatePrompt(this.session),
-          this.contextManager.buildShortTermPrompt(this.session),
-          options.turnInstructions ?? "",
-          augmentation.text,
-          retrievedContext,
-          pinnedContext,
-          workspaceRules
-        ].join("\n").length / 4)
-      });
       let verificationAttempted = false;
       const maxTurns = options.maxTurns ?? this.config.agent.maxTurns;
       const contextBudget = Math.max(24e3, Math.min(1e5, this.config.context.maxTokens * 3));
@@ -8858,16 +9032,17 @@ var AgentRunner = class {
         }
         this.applySteering();
         await emit({ type: "thinking", turn });
+        const dynamicPrompt = [
+          buildSessionStatePrompt(this.session),
+          turnDirective.text,
+          this.contextManager.buildShortTermPrompt(this.session),
+          pinnedContext,
+          options.turnInstructions ?? "",
+          augmentation.text
+        ].filter(Boolean).join("\n\n");
         const messages = packConversation(
           stableSystemPrompt,
-          [
-            buildSessionStatePrompt(this.session),
-            turnDirective.text,
-            this.contextManager.buildShortTermPrompt(this.session),
-            pinnedContext,
-            options.turnInstructions ?? "",
-            augmentation.text
-          ].filter(Boolean).join("\n\n"),
+          dynamicPrompt,
           retrievedContext,
           activeMessages(this.session),
           contextBudget
@@ -8887,6 +9062,23 @@ var AgentRunner = class {
           this.config.model.maxTokens ?? 8192,
           availableTokens - estimatedInputTokens
         ));
+        const breakdown = promptTokenBreakdown(
+          messages,
+          stableSystemPrompt,
+          dynamicPrompt,
+          retrievedContext,
+          visibleTools,
+          maxOutputTokens
+        );
+        if (!trivialTurn) {
+          await emit({
+            type: "prompt",
+            intent: turnDirective.intent,
+            sections: promptSections,
+            estimatedTokens: breakdown.estimatedInputTokens,
+            breakdown
+          });
+        }
         const assistantId = randomUUID12();
         const response = await this.completeModel(
           messages,
@@ -8902,17 +9094,49 @@ var AgentRunner = class {
         assistantMessage.id = assistantId;
         this.session.messages.push(assistantMessage);
         if (response.content) await emit({ type: "assistant", id: assistantId, content: response.content });
-        const inputTokens = response.usage?.inputTokens ?? estimatedInputTokens;
-        const outputTokens = response.usage?.outputTokens ?? estimateResponseTokens(response);
-        this.session.usage.inputTokens += inputTokens;
-        this.session.usage.outputTokens += outputTokens;
-        if (inputTokens || outputTokens) {
-          await emit({
-            type: "usage",
-            inputTokens: this.session.usage.inputTokens,
-            outputTokens: this.session.usage.outputTokens
-          });
-        }
+        const turnUsage = recordTokenUsage(
+          this.session,
+          response.usage,
+          estimatedInputTokens,
+          estimateResponseTokens(response)
+        );
+        const { inputTokens, outputTokens } = turnUsage;
+        const actualInputTokens = validTokenCount(response.usage?.inputTokens);
+        const actualOutputTokens = validTokenCount(response.usage?.outputTokens);
+        const receipt = recordTokenLedger(this.session, {
+          requestId: userMessage.id,
+          turn,
+          recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          estimated: {
+            ...breakdown,
+            outputTokens: estimateResponseTokens(response)
+          },
+          actual: {
+            ...actualInputTokens === void 0 ? {} : { inputTokens: actualInputTokens },
+            ...actualOutputTokens === void 0 ? {} : { outputTokens: actualOutputTokens }
+          },
+          inputSource: actualInputTokens === void 0 ? "estimated" : "actual",
+          outputSource: actualOutputTokens === void 0 ? "estimated" : "actual",
+          tools: { loaded: visibleTools.map((tool) => tool.name), deferredCount: 0 },
+          retrieval: tokenRetrievalReceipt(packed)
+        });
+        await emit({
+          type: "usage",
+          inputTokens: this.session.usage.inputTokens,
+          outputTokens: this.session.usage.outputTokens,
+          source: this.session.usage.source ?? "unknown",
+          inputSource: this.session.usage.inputSource ?? "unknown",
+          outputSource: this.session.usage.outputSource ?? "unknown",
+          actual: {
+            inputTokens: this.session.usage.actualInputTokens ?? 0,
+            outputTokens: this.session.usage.actualOutputTokens ?? 0
+          },
+          estimated: {
+            inputTokens: this.session.usage.estimatedInputTokens ?? 0,
+            outputTokens: this.session.usage.estimatedOutputTokens ?? 0
+          },
+          receipt
+        });
         await this.persist();
         if (this.session.usage.inputTokens + this.session.usage.outputTokens >= this.config.agent.maxSessionTokens) {
           for (const call of response.toolCalls) {
@@ -9291,8 +9515,8 @@ ${completeContent}`;
       toolCalls: toolCalls.map((call) => ({ id: call.id, name: call.name }))
     }, signal);
   }
-  async packContext(input2) {
-    return this.contextEngine.pack(input2);
+  async packContext(input2, options) {
+    return this.contextEngine.pack(input2, options);
   }
   async packMentions(input2) {
     try {
@@ -9410,14 +9634,14 @@ function packConversation(systemPrompt, dynamicPrompt, retrievedContext, history
   const system = message("system", systemPrompt);
   const dynamic = dynamicPrompt ? message("system", dynamicPrompt) : void 0;
   const context = retrievedContext ? message("system", retrievedContext) : void 0;
-  const reserved = estimateTokens4(system.content) + estimateTokens4(dynamic?.content ?? "") + estimateTokens4(context?.content ?? "");
+  const reserved = estimateTokens(system.content) + estimateTokens(dynamic?.content ?? "") + estimateTokens(context?.content ?? "");
   const budget = Math.max(4e3, tokenBudget - reserved);
   const groups = groupMessages(clearOldToolResults(history));
   const selected = [];
   let used = 0;
   for (let index = groups.length - 1; index >= 0; index -= 1) {
     const group = groups[index] ?? [];
-    const cost = group.reduce((sum, item) => sum + estimateTokens4(item.content) + estimateTokens4(JSON.stringify(item.toolCalls ?? [])), 0);
+    const cost = group.reduce((sum, item) => sum + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])), 0);
     if (selected.length && used + cost > budget) break;
     selected.unshift(group);
     used += cost;
@@ -9455,17 +9679,114 @@ function groupMessages(messages) {
   }
   return groups;
 }
-function estimateTokens4(input2) {
-  return Math.ceil(input2.length / 4);
-}
 function estimateMessages2(messages) {
-  return messages.reduce((total, item) => total + estimateTokens4(item.content) + estimateTokens4(JSON.stringify(item.toolCalls ?? [])), 0);
+  return messages.reduce((total, item) => total + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])), 0);
 }
 function estimateToolDefinitions(tools) {
-  return estimateTokens4(JSON.stringify(tools));
+  return estimateTokens(JSON.stringify(tools));
 }
 function estimateResponseTokens(response) {
-  return estimateTokens4(response.content) + estimateTokens4(JSON.stringify(response.toolCalls));
+  return estimateTokens(response.content) + estimateTokens(JSON.stringify(response.toolCalls));
+}
+function promptTokenBreakdown(messages, stablePrompt, dynamicPrompt, retrievedContext, tools, outputAllowanceTokens) {
+  const stableTokens = estimateTokens(stablePrompt);
+  const dynamicTokens = estimateTokens(dynamicPrompt);
+  const retrievedTokens = estimateTokens(retrievedContext);
+  const messageTokens = estimateMessages2(messages);
+  const toolSchemaTokens = estimateToolDefinitions(tools);
+  const toolResultTokens = messages.filter((message2) => message2.role === "tool").reduce((total, message2) => total + estimateTokens(message2.content), 0);
+  return {
+    stableTokens,
+    dynamicTokens,
+    conversationTokens: Math.max(0, messageTokens - stableTokens - dynamicTokens - retrievedTokens - toolResultTokens),
+    toolResultTokens,
+    retrievedTokens,
+    toolSchemaTokens,
+    estimatedInputTokens: messageTokens + toolSchemaTokens,
+    outputAllowanceTokens
+  };
+}
+function tokenRetrievalReceipt(packed) {
+  const discarded = [];
+  if ((packed.duplicateHits ?? 0) > 0) {
+    discarded.push({ reason: "overlapping-span", count: packed.duplicateHits ?? 0 });
+  }
+  if (packed.truncated) discarded.push({ reason: "budget-cap", count: 1 });
+  return {
+    engine: packed.engine,
+    ...packed.budgetTier ? { budgetTier: packed.budgetTier } : {},
+    ...packed.budgetTokens === void 0 ? {} : { budgetTokens: packed.budgetTokens },
+    ...packed.candidateHits === void 0 ? {} : { candidateHits: packed.candidateHits },
+    ...packed.selectedHits === void 0 ? {} : { selectedHits: packed.selectedHits },
+    ...packed.duplicateHits === void 0 ? {} : { duplicateHits: packed.duplicateHits },
+    ...packed.incrementalEvidenceTokens === void 0 ? {} : { incrementalEvidenceTokens: packed.incrementalEvidenceTokens },
+    discarded
+  };
+}
+function recordTokenLedger(session, entry) {
+  const ledger = session.tokenLedger ?? (session.tokenLedger = []);
+  ledger.push(entry);
+  if (ledger.length > 256) ledger.splice(0, ledger.length - 256);
+  return entry;
+}
+function recordTokenUsage(session, providerUsage, estimatedInputTokens, estimatedOutputTokens) {
+  const inputActual = validTokenCount(providerUsage?.inputTokens);
+  const outputActual = validTokenCount(providerUsage?.outputTokens);
+  const priorInputSource = existingMeasurementSource(session, "input");
+  const priorOutputSource = existingMeasurementSource(session, "output");
+  const inputTokens = inputActual ?? estimatedInputTokens;
+  const outputTokens = outputActual ?? estimatedOutputTokens;
+  session.usage.inputTokens += inputTokens;
+  session.usage.outputTokens += outputTokens;
+  if (inputActual !== void 0) {
+    session.usage.actualInputTokens = (session.usage.actualInputTokens ?? 0) + inputActual;
+  } else {
+    session.usage.estimatedInputTokens = (session.usage.estimatedInputTokens ?? 0) + inputTokens;
+  }
+  if (outputActual !== void 0) {
+    session.usage.actualOutputTokens = (session.usage.actualOutputTokens ?? 0) + outputActual;
+  } else {
+    session.usage.estimatedOutputTokens = (session.usage.estimatedOutputTokens ?? 0) + outputTokens;
+  }
+  session.usage.inputSource = mergeMeasurementSource(
+    priorInputSource,
+    inputActual === void 0 ? "estimated" : "actual",
+    session.usage.inputTokens
+  );
+  session.usage.outputSource = mergeMeasurementSource(
+    priorOutputSource,
+    outputActual === void 0 ? "estimated" : "actual",
+    session.usage.outputTokens
+  );
+  session.usage.source = combineMeasurementSources(
+    session.usage.inputSource,
+    session.usage.outputSource,
+    session.usage.inputTokens,
+    session.usage.outputTokens
+  );
+  return { inputTokens, outputTokens };
+}
+function validTokenCount(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : void 0;
+}
+function existingMeasurementSource(session, channel) {
+  const source = channel === "input" ? session.usage.inputSource : session.usage.outputSource;
+  if (source) return source;
+  const total = channel === "input" ? session.usage.inputTokens : session.usage.outputTokens;
+  return total > 0 ? "unknown" : void 0;
+}
+function mergeMeasurementSource(previous, current, total) {
+  if (total === 0 && !previous) return current;
+  if (!previous) return current;
+  return previous === current ? current : "mixed";
+}
+function combineMeasurementSources(input2, output2, inputTokens, outputTokens) {
+  const active = [
+    ...inputTokens > 0 ? [input2] : [],
+    ...outputTokens > 0 ? [output2] : []
+  ];
+  if (!active.length) return "unknown";
+  return active.every((source) => source === active[0]) ? active[0] ?? "unknown" : "mixed";
 }
 function uniqueCategories(categories) {
   return [...new Set(categories)];
@@ -12136,9 +12457,10 @@ var HeadlessReporter = class {
     }
     if (!this.options.quiet && !this.options.compact) {
       const usage = session.usage.inputTokens + session.usage.outputTokens;
+      const usageLabel = tokenUsageLabel(session.usage);
       process.stderr.write(this.paint.dim(
         `
-${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.separator} ${usage.toLocaleString()} tokens ${this.glyphs.separator} session ${session.id.slice(0, 8)}
+${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.separator} ${usage.toLocaleString()} tokens (${usageLabel}) ${this.glyphs.separator} session ${session.id.slice(0, 8)}
 `
       ));
     }
@@ -12162,16 +12484,19 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         if (!compact2) process.stderr.write(this.paint.dim(`${this.glyphs.meta} reasoning ${this.glyphs.separator} turn ${event.turn}
 `));
         break;
-      case "context":
+      case "context": {
+        const budget = event.packed.budgetTokens === void 0 ? "" : ` ${this.glyphs.separator} ${event.packed.budgetTier ?? "adaptive"} ${event.packed.budgetTokens} budget`;
         process.stderr.write(this.paint.cyan(
-          `${this.glyphs.meta} context ${this.glyphs.separator} ${event.packed.engine} ${this.glyphs.separator} ${event.packed.hits.length} spans ${this.glyphs.separator} ~${event.packed.estimatedTokens} tokens${event.packed.degradation ? ` ${this.glyphs.separator} ${event.packed.degradation.summary}` : ""}
+          `${this.glyphs.meta} context ${this.glyphs.separator} ${event.packed.engine} ${this.glyphs.separator} ${event.packed.hits.length} spans ${this.glyphs.separator} ~${event.packed.estimatedTokens} tokens${budget}${event.packed.degradation ? ` ${this.glyphs.separator} ${event.packed.degradation.summary}` : ""}
 `
         ));
         break;
+      }
       case "prompt":
         if (!compact2) {
+          const partition = event.breakdown ? ` ${this.glyphs.separator} stable ${event.breakdown.stableTokens} ${this.glyphs.separator} dynamic ${event.breakdown.dynamicTokens} ${this.glyphs.separator} history ${event.breakdown.conversationTokens} ${this.glyphs.separator} tool results ${event.breakdown.toolResultTokens} ${this.glyphs.separator} retrieved ${event.breakdown.retrievedTokens} ${this.glyphs.separator} tools ${event.breakdown.toolSchemaTokens} ${this.glyphs.separator} output cap ${event.breakdown.outputAllowanceTokens}` : "";
           process.stderr.write(this.paint.dim(
-            `${this.glyphs.meta} prompt ${this.glyphs.separator} ${event.intent} ${this.glyphs.separator} ${event.sections.join(" + ")} ${this.glyphs.separator} ~${event.estimatedTokens} tokens
+            `${this.glyphs.meta} prompt ${this.glyphs.separator} ${event.intent} ${this.glyphs.separator} ~${event.estimatedTokens} estimated tokens${partition}
 `
           ));
         }
@@ -12303,9 +12628,14 @@ function sessionSummary(session) {
     ...session.taskContract ? { taskContract: session.taskContract } : {},
     changedFiles: session.changedFiles,
     ...session.lastRun ? { lastRun: session.lastRun } : {},
+    ...session.tokenLedger?.length ? { tokenLedger: session.tokenLedger } : {},
     usage: session.usage
   };
 }
+function tokenUsageLabel(usage) {
+  if (usage.source) return usage.source;
+  return usage.inputTokens + usage.outputTokens > 0 ? "unknown source" : "no usage";
+}
 function formatToolDetail(call, paint = chalk2, glyphs = resolveCliGlyphs()) {
   const environment = call.name === "shell" && typeof call.arguments.env === "object" && call.arguments.env !== null && !Array.isArray(call.arguments.env) ? Object.keys(call.arguments.env).sort() : [];
   const environmentDetail = environment.length ? ` ${glyphs.separator} env ${environment.join(", ")}` : "";
@@ -13030,10 +13360,11 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
             width,
             glyph: glyphs.context,
             label: "context",
-            detail: `${sanitizeInlineTerminalText(item.engine)} ${glyphs.separator} ${item.hits} spans ${glyphs.separator} ~${formatTokens(item.tokens)}${item.truncated ? ` ${glyphs.separator} truncated` : ""}`,
+            detail: `${sanitizeInlineTerminalText(item.engine)} ${glyphs.separator} ${item.hits} spans ${glyphs.separator} ~${formatTokens(item.tokens)} estimated${item.budgetTokens === void 0 ? "" : ` ${glyphs.separator} ${item.budgetTier ?? "adaptive"} ${formatTokens(item.budgetTokens)} budget`}${item.truncated ? ` ${glyphs.separator} truncated` : ""}`,
             labelColor: theme.accent
           }
         ),
+        !compact2 && item.budgetReason ? /* @__PURE__ */ jsx(Text, { color: theme.dim, children: truncateDisplay(`${glyphs.branchLast} ${sanitizeInlineTerminalText(item.budgetReason)}`, innerWidth) }) : null,
         spans.slice(0, spanLimit).map((span, spanIndex) => {
           const lines = span.startLine === span.endLine ? `${span.startLine}` : `${span.startLine}-${span.endLine}`;
           const location = `${compactDisplayPath(sanitizeInlineTerminalText(span.path), 44)}:${lines}`;
@@ -13055,13 +13386,14 @@ function Timeline({ items, width = 80, glyphMode = "auto", showToolOutput = fals
       ] }, item.id);
     }
     if (item.kind === "prompt") {
+      const detail = item.breakdown ? `~${formatTokens(item.tokens)} estimated ${glyphs.separator} stable ${formatTokens(item.breakdown.stableTokens)} ${glyphs.separator} dynamic ${formatTokens(item.breakdown.dynamicTokens)} ${glyphs.separator} history ${formatTokens(item.breakdown.conversationTokens)} ${glyphs.separator} tool results ${formatTokens(item.breakdown.toolResultTokens)} ${glyphs.separator} retrieved ${formatTokens(item.breakdown.retrievedTokens)} ${glyphs.separator} tools ${formatTokens(item.breakdown.toolSchemaTokens)} ${glyphs.separator} output cap ${formatTokens(item.breakdown.outputAllowanceTokens)}` : `${item.sections.map(sanitizeInlineTerminalText).join(` ${glyphs.separator} `)} ${glyphs.separator} ~${formatTokens(item.tokens)} estimated`;
       return /* @__PURE__ */ jsx(
         MetaRow,
         {
           width,
           glyph: glyphs.pending,
           label: `prompt/${sanitizeInlineTerminalText(item.intent)}`,
-          detail: `${item.sections.map(sanitizeInlineTerminalText).join(` ${glyphs.separator} `)} ${glyphs.separator} ~${formatTokens(item.tokens)}`
+          detail
         },
         item.id
       );
@@ -15176,6 +15508,9 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
           engine: event.packed.engine,
           hits: event.packed.hits.length,
           tokens: event.packed.estimatedTokens,
+          ...event.packed.budgetTier ? { budgetTier: event.packed.budgetTier } : {},
+          ...event.packed.budgetTokens !== void 0 ? { budgetTokens: event.packed.budgetTokens } : {},
+          ...event.packed.budgetReason ? { budgetReason: event.packed.budgetReason } : {},
           truncated: event.packed.truncated,
           spans: event.packed.hits.slice(0, 5).map((hit) => ({
             path: relative8(runner.workspace.primaryRoot, hit.path) || hit.path,
@@ -15189,7 +15524,14 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         setActivity({ label: "Assembling relevant context", startedAt: Date.now() });
         break;
       case "prompt":
-        append({ id: nextId(), kind: "prompt", intent: event.intent, sections: event.sections, tokens: event.estimatedTokens });
+        append({
+          id: nextId(),
+          kind: "prompt",
+          intent: event.intent,
+          sections: event.sections,
+          tokens: event.estimatedTokens,
+          ...event.breakdown ? { breakdown: event.breakdown } : {}
+        });
         setActivity({ label: "Preparing the model prompt", startedAt: Date.now() });
         break;
       case "assistant_delta":
@@ -15736,7 +16078,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         { label: config.agents?.enabled ? `${config.agents.maxConcurrent} concurrent` : "disabled", detail: "expert delegation" },
         {
           label: `${usage.inputTokens.toLocaleString()} in ${separator} ${usage.outputTokens.toLocaleString()} out`,
-          detail: `session tokens${separator}${(usage.inputTokens + usage.outputTokens).toLocaleString()} total`
+          detail: `session tokens${separator}${(usage.inputTokens + usage.outputTokens).toLocaleString()} total${separator}${usage.source ?? "unknown source"}`
         },
         {
           label: `${Math.round(status.pressure * 100)}% context pressure`,
@@ -18871,7 +19213,7 @@ program.command("context").description("Pack task-oriented context under a token
 
 `);
   process.stderr.write(chalk4.dim(
-    `${cliGlyphs.meta} ${packed.engine} ${cliGlyphs.separator} ${packed.hits.length} spans ${cliGlyphs.separator} ~${packed.estimatedTokens} tokens${packed.truncated ? ` ${cliGlyphs.separator} capped` : ""}${packed.degradation ? ` ${cliGlyphs.separator} ${packed.degradation.summary}` : ""}
+    `${cliGlyphs.meta} ${packed.engine} ${cliGlyphs.separator} ${packed.hits.length} spans ${cliGlyphs.separator} ~${packed.estimatedTokens} estimated tokens${packed.budgetTokens === void 0 ? "" : ` ${cliGlyphs.separator} ${packed.budgetTier ?? "adaptive"} ${packed.budgetTokens} budget`}${packed.truncated ? ` ${cliGlyphs.separator} capped` : ""}${packed.degradation ? ` ${cliGlyphs.separator} ${packed.degradation.summary}` : ""}
 `
   ));
 });