@serkanalgur/opencode-nexus 2.4.1 → 2.6.0

package/dist/index.js

@@ -8451,7 +8451,7 @@ function describeFile(file) {
 }
 function formatConfigLoadLog(info) {
   const models = Object.entries(info.models).map(([role, model]) => `${role}=${model}`).join(" ");
-  const override = info.sessionOverride ? " (+session override: storage; disk edits to models are IGNORED while a preset is set — clear the preset in the TUI to hand control back to disk)" : "";
+  const override = info.sessionOverride ? ' (+session override: storage; disk edits to models are IGNORED while a preset is set — call the preset tool with mode "clear", or reset in the TUI, to hand control back to disk)' : "";
   return `[nexus] config loaded (#${info.loadCount} trigger=${info.trigger} at=${info.loadedAt}) ` + `project=${info.project.path} [${describeFile(info.project)}] ` + `global=${info.global.path} [${describeFile(info.global)}] ` + `models:${override} ${models}`;
 }
 var DEFAULT_CONFIG = {
@@ -8668,7 +8668,9 @@ class NexusConfigManager {
     return result;
   }
   resetToDefaults() {
+    const hadOverride = this.storageConfig !== null;
     this.storageConfig = null;
+    return hadOverride;
   }
   applyPreset(name) {
     const preset = PRESETS[name];
@@ -9797,10 +9799,20 @@ class PerformanceTracker {
     this.maxEntries = maxEntries;
   }
   record(entry) {
-    this.entries.push({ ...entry, timestamp: new Date });
+    const id = `perf-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`;
+    this.entries.push({ ...entry, id, timestamp: new Date });
     if (this.entries.length > this.maxEntries) {
       this.entries = this.entries.slice(-this.maxEntries);
     }
+    return id;
+  }
+  adjust(id, { cost }) {
+    const entry = this.entries.find((e) => e.id === id);
+    if (!entry)
+      return false;
+    if (cost !== undefined)
+      entry.cost += cost;
+    return true;
   }
   getScores() {
     const groups = new Map;
@@ -9818,11 +9830,28 @@ class PerformanceTracker {
       const successRate = total > 0 ? successful / total : 0;
       const avgDuration = entries.reduce((s, e) => s + e.duration, 0) / total;
       const avgCost = entries.reduce((s, e) => s + e.cost, 0) / total;
-      const costEfficiency = avgCost > 0 ? successRate / avgCost : 0;
+      const measured = entries.filter((e) => e.costProvenance.usage === "measured");
+      const measuredTasks = measured.length;
+      const estimatedTasks = total - measuredTasks;
+      const measuredSuccessRate = measuredTasks > 0 ? measured.filter((e) => e.success).length / measuredTasks : 0;
+      const measuredAvgCost = measuredTasks > 0 ? measured.reduce((s, e) => s + e.cost, 0) / measuredTasks : 0;
+      const costEfficiency = measuredAvgCost > 0 ? measuredSuccessRate / measuredAvgCost : 0;
       const speedScore = Math.max(0, 1 - avgDuration / 30000);
       const costScore = Math.min(1, costEfficiency * 100);
       const overallScore = successRate * 40 + speedScore * 30 + costScore * 30;
-      scores.push({ model, role, totalTasks: total, successRate, avgDuration, avgCost, costEfficiency, overallScore });
+      scores.push({
+        model,
+        role,
+        totalTasks: total,
+        successRate,
+        avgDuration,
+        avgCost,
+        costEfficiency,
+        overallScore,
+        measuredTasks,
+        estimatedTasks,
+        costBasis: measuredTasks > 0 ? "measured" : "none"
+      });
     }
     return scores.sort((a, b) => b.overallScore - a.overallScore);
   }
@@ -9858,6 +9887,16 @@ class ExecutionHistory {
     }
     return full;
   }
+  adjust(id, { cost, tokensUsed }) {
+    const record = this.records.find((r) => r.id === id);
+    if (!record)
+      return false;
+    if (cost !== undefined)
+      record.cost += cost;
+    if (tokensUsed !== undefined)
+      record.tokensUsed += tokensUsed;
+    return true;
+  }
   getAll() {
     return [...this.records];
   }
@@ -9879,7 +9918,17 @@ class ExecutionHistory {
     for (const r of this.records) {
       byRole[r.role] = (byRole[r.role] || 0) + 1;
     }
-    return { total, successRate: total > 0 ? successful / total : 0, totalCost, avgDuration, byRole };
+    const costSplit = this.records.reduce((split, r) => {
+      if (r.costProvenance.usage === "measured") {
+        split.measuredCost += r.cost;
+        split.measuredEntries++;
+      } else {
+        split.estimatedCost += r.cost;
+        split.estimatedEntries++;
+      }
+      return split;
+    }, { measuredCost: 0, estimatedCost: 0, measuredEntries: 0, estimatedEntries: 0 });
+    return { total, successRate: total > 0 ? successful / total : 0, totalCost, costSplit, avgDuration, byRole };
   }
   clear() {
     this.records = [];
@@ -9920,33 +9969,122 @@ class CustomRoleManager {
 }
 
 // src/forecast.ts
+var CACHE_READ_MULTIPLE = 0.1;
+var CACHE_WRITE_MULTIPLE = 1.25;
+function per1kPricing(input, output) {
+  return {
+    input,
+    output,
+    cacheRead: input * CACHE_READ_MULTIPLE,
+    cacheWrite: input * CACHE_WRITE_MULTIPLE
+  };
+}
+function untiered(rates) {
+  return { tiers: [{ rates }] };
+}
+var FALLBACK_PRICING_PER_1K = {
+  "claude-sonnet-4-6": untiered(per1kPricing(0.015, 0.075)),
+  "claude-opus-4-7": untiered(per1kPricing(0.075, 0.375)),
+  "claude-haiku-4-5": untiered(per1kPricing(0.001, 0.005)),
+  "gpt-5-mini": untiered(per1kPricing(0.00015, 0.0006)),
+  "gpt-5": untiered(per1kPricing(0.0025, 0.01)),
+  "gemini-2.5-flash": untiered(per1kPricing(0.000075, 0.0003)),
+  "minimax-m2.5-free": untiered(per1kPricing(0, 0))
+};
+var UNKNOWN_PRICING_PER_1K = untiered(per1kPricing(0.01, 0.05));
+var per1k = (rate, tokens) => rate * tokens / 1000;
+function bareModelId(ref) {
+  return ref.slice(ref.indexOf("/") + 1);
+}
+function totalTokens(usage) {
+  return usage.input + usage.output + usage.reasoning + usage.cache.read + usage.cache.write;
+}
+function promptSizeOf(usage) {
+  return usage.input + usage.cache.read + usage.cache.write;
+}
+var ZERO_RATES = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+function selectTier(tiers, promptSize) {
+  let best;
+  let bestThreshold = Number.NEGATIVE_INFINITY;
+  for (const tier of tiers) {
+    const { threshold } = tier;
+    if (threshold === undefined)
+      continue;
+    if (!(promptSize > threshold))
+      continue;
+    if (threshold > bestThreshold) {
+      best = tier;
+      bestThreshold = threshold;
+    }
+  }
+  if (best)
+    return best;
+  const base = tiers.find((t) => t.threshold === undefined);
+  return base ?? { rates: ZERO_RATES };
+}
+function priceUsage(usage, pricing) {
+  return priceTokens(usage, selectTier(pricing.tiers, promptSizeOf(usage)).rates);
+}
+function priceUsageAtSettledTier(increment, pricing, settledUsage) {
+  return priceTokens(increment, selectTier(pricing.tiers, promptSizeOf(settledUsage)).rates);
+}
+function priceTokens(usage, pricing) {
+  const inputCost = per1k(pricing.input, usage.input);
+  const outputCost = per1k(pricing.output, usage.output + usage.reasoning);
+  const cacheCost = per1k(pricing.cacheRead, usage.cache.read) + per1k(pricing.cacheWrite, usage.cache.write);
+  return { inputCost, outputCost, cacheCost, total: inputCost + outputCost + cacheCost };
+}
+
 class CostForecaster {
-  modelPricing = new Map;
-  constructor() {
-    this.modelPricing.set("claude-sonnet-4-6", { input: 0.000015, output: 0.000075 });
-    this.modelPricing.set("claude-opus-4-7", { input: 0.000075, output: 0.000375 });
-    this.modelPricing.set("claude-haiku-4-5", { input: 0.000001, output: 0.000005 });
-    this.modelPricing.set("gpt-5-mini", { input: 0.00000015, output: 0.0000006 });
-    this.modelPricing.set("gpt-5", { input: 0.0000025, output: 0.00001 });
-    this.modelPricing.set("gemini-2.5-flash", { input: 0.000000075, output: 0.0000003 });
+  resolvePricing;
+  constructor(pricing) {
+    this.resolvePricing = pricing;
+  }
+  priceFor(model, provider, promptSize) {
+    const { pricing, source } = this.tiersFor(model, provider);
+    return { pricing: selectTier(pricing.tiers, promptSize ?? 0).rates, source };
+  }
+  tiersFor(model, provider) {
+    const real = this.resolvePricing?.(model, provider);
+    if (real)
+      return { pricing: real, source: "model-costs" };
+    const bare = bareModelId(model);
+    const fallback = FALLBACK_PRICING_PER_1K[model] ?? FALLBACK_PRICING_PER_1K[bare];
+    if (fallback)
+      return { pricing: fallback, source: "fallback-table" };
+    return { pricing: UNKNOWN_PRICING_PER_1K, source: "unknown-model" };
+  }
+  measureCost(usage, model, provider) {
+    const { pricing, source } = this.tiersFor(model, provider);
+    return {
+      cost: priceUsage(usage, pricing).total,
+      tokens: totalTokens(usage),
+      pricingSource: source,
+      ...source === "model-costs" ? { confidence: 1 } : {}
+    };
   }
-  updatePricing(modelId, input, output) {
-    this.modelPricing.set(modelId, { input, output });
+  costOf(usage, model, provider) {
+    return priceUsage(usage, this.tiersFor(model, provider).pricing).total;
   }
-  estimateTokens(task, complexity) {
+  estimateTokensFor(complexity, fileCount) {
     const baseInput = 700;
     const complexityMultiplier = 1 + complexity.overall / 100 * 3;
-    const fileMultiplier = 1 + task.files.include.length * 0.2;
+    const fileMultiplier = 1 + fileCount * 0.2;
     const input = Math.round(baseInput * complexityMultiplier * fileMultiplier);
     const output = Math.round(input * 0.5);
     return { input, output };
   }
+  estimateTokens(task, complexity) {
+    return this.estimateTokensFor(complexity, task.files.include.length);
+  }
+  estimateCost(complexity, model, provider) {
+    const { input, output } = this.estimateTokensFor(complexity, 0);
+    return this.costOf({ input, output, reasoning: 0, cache: { read: 0, write: 0 } }, model, provider);
+  }
   forecastTask(task, role, modelId, complexity) {
     const { input, output } = this.estimateTokens(task, complexity);
-    const pricing = this.modelPricing.get(modelId) || { input: 0.00001, output: 0.00005 };
-    const inputCost = input * pricing.input;
-    const outputCost = output * pricing.output;
-    const overhead = 0.0001;
+    const { pricing, source } = this.tiersFor(modelId);
+    const breakdown = priceUsage({ input, output, reasoning: 0, cache: { read: 0, write: 0 } }, pricing);
     return {
       taskId: task.id,
       taskName: task.name,
@@ -9954,9 +10092,15 @@ class CostForecaster {
       model: modelId,
       estimatedInputTokens: input,
       estimatedOutputTokens: output,
-      estimatedCost: inputCost + outputCost + overhead,
-      confidence: 0.6 + Math.random() * 0.3,
-      breakdown: { inputCost, outputCost, overhead }
+      estimatedCost: breakdown.total,
+      source: "estimated",
+      pricingSource: source,
+      confidence: undefined,
+      breakdown: {
+        inputCost: breakdown.inputCost,
+        outputCost: breakdown.outputCost,
+        cacheCost: breakdown.cacheCost
+      }
     };
   }
   forecastAll(tasks, budgetRemaining) {
@@ -10149,6 +10293,13 @@ ${lines.join(`
 }
 
 // src/orchestrator.ts
+class TaskTimeoutError extends Error {
+  constructor(message = "Task timed out") {
+    super(message);
+    this.name = "TaskTimeoutError";
+  }
+}
+var DELTA_READ_BACKOFF_MS = [1000, 2000, 4000];
 function assistantMessageText(message) {
   if (message.type !== "assistant")
     return "";
@@ -10164,6 +10315,15 @@ function lastAssistantText(messages) {
   }
   return "";
 }
+function sumBy(records, select) {
+  let total = 0;
+  for (const record of records.values())
+    total += select(record);
+  return total;
+}
+function baseInputRate(cost) {
+  return selectTier(cost.tiers, 0).rates.input;
+}
 var DEFAULT_ESCALATION = {
   maxRetries: 3,
   retryDelay: 1000,
@@ -10209,7 +10369,14 @@ class NexusOrchestrator {
   onStateChange = null;
   stateChangeTimer = null;
   costHistory = [];
+  tokensByModel = new Map;
+  costProvenance = new Map;
   cleanupInterval = null;
+  deltaLedgers = new Map;
+  uncollected = new Map;
+  deltaTimers = new Set;
+  shuttingDown = false;
+  deltaReadBackoffMs = DELTA_READ_BACKOFF_MS;
   get healthMonitor() {
     return this._healthMonitor;
   }
@@ -10226,6 +10393,7 @@ class NexusOrchestrator {
     this.messageRouter = new MessageRouter;
     this.escalationPolicy = {
       ...DEFAULT_ESCALATION,
+      fallbackModels: [...DEFAULT_ESCALATION.fallbackModels],
       maxRetries: this.config.selfHealing.maxRetries,
       retryDelay: this.config.selfHealing.retryDelay,
       enableRespawn: this.config.selfHealing.contextTransfer
@@ -10235,7 +10403,7 @@ class NexusOrchestrator {
     this.performanceTracker = new PerformanceTracker;
     this.executionHistory = new ExecutionHistory;
     this.customRoles = new CustomRoleManager;
-    this.forecaster = new CostForecaster;
+    this.forecaster = new CostForecaster((model, provider) => this.getModelCost(model, provider));
   }
   async initialize(ctx, onStateChange) {
     this.ctx = ctx;
@@ -10269,23 +10437,40 @@ class NexusOrchestrator {
       for (const model of data) {
         if (!model?.cost || !Array.isArray(model.cost) || model.cost.length === 0)
           continue;
-        const baseCost = model.cost[0];
         this.modelCosts.set(`${model.providerID}/${model.id}`, {
-          input: per1k(baseCost.input),
-          output: per1k(baseCost.output),
-          cacheRead: per1k(baseCost.cache?.read),
-          cacheWrite: per1k(baseCost.cache?.write)
+          tiers: this.normaliseTiers(model.cost, per1k)
         });
       }
     } catch {}
   }
+  normaliseTiers(cost, per1k) {
+    const rates = (row) => ({
+      input: per1k(row.input),
+      output: per1k(row.output),
+      cacheRead: per1k(row.cache?.read),
+      cacheWrite: per1k(row.cache?.write)
+    });
+    const kept = cost.filter((row) => row?.tier === undefined || row.tier?.type === "context").map((row) => ({
+      ...row.tier?.type === "context" && typeof row.tier.size === "number" ? { threshold: row.tier.size } : {},
+      rates: rates(row)
+    }));
+    if (kept.length === 0)
+      return [{ rates: rates(cost[0]) }];
+    const base = kept.find((t) => t.threshold === undefined);
+    const contextual = kept.filter((t) => t.threshold !== undefined).sort((a, b) => a.threshold - b.threshold);
+    return base ? [{ rates: { ...base.rates } }, ...contextual] : [{ rates: { ...kept[0].rates } }, ...contextual];
+  }
   setModelCosts(costs) {
     for (const [model, cost] of Object.entries(costs)) {
       this.modelCosts.set(model, {
-        input: cost.input,
-        output: cost.output,
-        cacheRead: cost.cacheRead || 0,
-        cacheWrite: cost.cacheWrite || 0
+        tiers: [{
+          rates: {
+            input: cost.input,
+            output: cost.output,
+            cacheRead: cost.cacheRead || 0,
+            cacheWrite: cost.cacheWrite || 0
+          }
+        }]
       });
     }
   }
@@ -10403,10 +10588,14 @@ class NexusOrchestrator {
         enabled: true,
         patternStorage: "memory",
         minConfidence: 0.7
+      },
+      cost: {
+        timeoutDeltaGraceMs: 60000
       }
     };
+    const { cost: defaultCost, ...restDefaults } = defaults;
     return {
-      ...defaults,
+      ...restDefaults,
       ...partial,
       budget: { ...defaults.budget, ...partial?.budget },
       agents: { ...defaults.agents, ...partial?.agents },
@@ -10415,7 +10604,8 @@ class NexusOrchestrator {
       memory: { ...defaults.memory, ...partial?.memory },
       dashboard: { ...defaults.dashboard, ...partial?.dashboard },
       security: { ...defaults.security, ...partial?.security },
-      learning: { ...defaults.learning, ...partial?.learning }
+      learning: { ...defaults.learning, ...partial?.learning },
+      ...partial?.cost ? { cost: { ...defaultCost, ...partial.cost } } : {}
     };
   }
   notifyStateChange() {
@@ -10469,6 +10659,7 @@ class NexusOrchestrator {
         success: true,
         tasks: results,
         totalCost: this.totalSpent,
+        ...this.spendSplit(),
         totalDuration,
         agentsUsed: this.agents.size
       };
@@ -10478,6 +10669,7 @@ class NexusOrchestrator {
         success: false,
         tasks: [],
         totalCost: this.totalSpent,
+        ...this.spendSplit(),
         totalDuration: Date.now() - startTime,
         agentsUsed: this.agents.size
       };
@@ -10590,14 +10782,17 @@ class NexusOrchestrator {
       await this.sleep(this.config.schedulerInterval);
     }
   }
-  async spawnAndExecute(node, transferContext) {
+  selectQualifiedModel(node) {
     const complexity = this.analyzeComplexity(node.task);
     const model = this.selectModel(node.task.requiredRole, complexity);
     if (!model.provider || !model.model) {
       const missing = !model.provider && !model.model ? "provider and model" : !model.provider ? "provider" : "model";
       throw new Error(`Model selection for role "${node.task.requiredRole}" is missing its ${missing}: ` + `got { provider: ${JSON.stringify(model.provider)}, model: ${JSON.stringify(model.model)} }. ` + `Cannot build a "providerID/modelID" reference.`);
     }
-    const qualifiedModel = `${model.provider}/${model.model}`;
+    return `${model.provider}/${model.model}`;
+  }
+  async spawnAndExecute(node, options = {}) {
+    const qualifiedModel = options.modelOverride ?? this.selectQualifiedModel(node);
     const agent = await this.spawnAgent({
       role: node.task.requiredRole,
       task: node.task,
@@ -10607,7 +10802,7 @@ class NexusOrchestrator {
     node.status = "running";
     node.task.assignedAgent = agent.id;
     this.notifyStateChange();
-    await this.executeTask(agent, node, transferContext);
+    await this.executeTask(agent, node, options.transferContext);
   }
   async executeTask(agent, node, transferContext) {
     if (!this.ctx || !agent.sessionID) {
@@ -10624,6 +10819,9 @@ class NexusOrchestrator {
     }
     const startTime = Date.now();
     const timeout = node.task.timeout || this.config.defaultTimeout;
+    let timeoutTimer = null;
+    let waitGuard = null;
+    let waitAbort = null;
     try {
       const rolePrompt = this.buildRolePrompt(node.task.requiredRole);
       let taskPrompt = `${rolePrompt}
@@ -10655,32 +10853,38 @@ Please continue from where the previous agent left off.`;
         sessionID: agent.sessionID,
         text: taskPrompt
       });
-      const waitPromise = this.ctx.session.wait({ sessionID: agent.sessionID });
-      const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Task timed out")), timeout));
+      waitAbort = new AbortController;
+      const waitPromise = this.ctx.session.wait({ sessionID: agent.sessionID }, { signal: waitAbort.signal });
+      waitGuard = waitPromise.then(() => ({ outcome: "idle" }), () => ({ outcome: "poll-failed" }));
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutTimer = setTimeout(() => reject(new TaskTimeoutError), timeout);
+      });
       await Promise.race([waitPromise, timeoutPromise]);
       const messages = await this.ctx.session.context({ sessionID: agent.sessionID });
       const output = lastAssistantText(messages) || "Task completed (no output captured)";
       const duration = Date.now() - startTime;
+      const cost = await this.safeAccountTaskCost(agent, node.task);
       const result = {
         success: true,
         output,
         duration,
-        tokensUsed: 0,
-        cost: this.estimateModelCost(agent.model.model, agent.model.provider)
+        tokensUsed: cost.tokensUsed,
+        cost: cost.cost,
+        costProvenance: cost.provenance
       };
       this.dag.markComplete(node.id, result);
       this.todoEnforcer.completeTask(agent.id);
       agent.metrics.tasksCompleted++;
       agent.metrics.totalCost += result.cost;
-      this.totalSpent += result.cost;
-      this.costByAgent.set(agent.id, (this.costByAgent.get(agent.id) || 0) + result.cost);
-      this.checkBudget();
+      agent.metrics.totalTokens += result.tokensUsed;
+      this.trackCost(agent.id, `${agent.model.provider}/${agent.model.model}`, result.cost, result.tokensUsed, result.costProvenance);
       this.performanceTracker.record({
         model: agent.model.model,
         role: node.task.requiredRole,
         success: result.success,
         duration: result.duration,
         cost: result.cost,
+        costProvenance: result.costProvenance,
         tokensUsed: result.tokensUsed
       });
       this.executionHistory.record({
@@ -10690,6 +10894,7 @@ Please continue from where the previous agent left off.`;
         model: agent.model.model,
         status: "success",
         cost: result.cost,
+        costProvenance: result.costProvenance,
         duration: result.duration,
         tokensUsed: result.tokensUsed,
         startedAt: new Date(startTime),
@@ -10716,14 +10921,20 @@ Please continue from where the previous agent left off.`;
     } catch (error) {
       const duration = Date.now() - startTime;
       const errorMessage = error.message || "Task failed";
+      const cost = await this.safeAccountTaskCost(agent, node.task);
       const result = {
         success: false,
         error: errorMessage,
         duration,
-        tokensUsed: 0,
-        cost: 0
+        tokensUsed: cost.tokensUsed,
+        cost: cost.cost,
+        costProvenance: cost.provenance
       };
       this.dag.markFailed(node.id, new Error(errorMessage));
+      node.result = result;
+      this.trackCost(agent.id, `${agent.model.provider}/${agent.model.model}`, result.cost, result.tokensUsed, result.costProvenance);
+      agent.metrics.totalCost += result.cost;
+      agent.metrics.totalTokens += result.tokensUsed;
       this.todoEnforcer.completeTask(agent.id);
       agent.metrics.tasksFailed++;
       agent.status = "failed";
@@ -10737,27 +10948,41 @@ Please continue from where the previous agent left off.`;
         duration,
         sessionID: agent.sessionID
       });
-      this.performanceTracker.record({
+      const performanceId = this.performanceTracker.record({
         model: agent.model.model,
         role: node.task.requiredRole,
         success: result.success,
         duration: result.duration,
         cost: result.cost,
+        costProvenance: result.costProvenance,
         tokensUsed: result.tokensUsed
       });
-      this.executionHistory.record({
+      const historyId = this.executionHistory.record({
         taskId: node.id,
         taskName: node.task.name,
         role: node.task.requiredRole,
         model: agent.model.model,
         status: "failed",
         cost: result.cost,
+        costProvenance: result.costProvenance,
         duration: result.duration,
         tokensUsed: result.tokensUsed,
         startedAt: new Date(startTime),
         completedAt: new Date,
         error: errorMessage
-      });
+      }).id;
+      if (error instanceof TaskTimeoutError && cost.usage && waitGuard && agent.sessionID) {
+        this.armTimeoutDelta(agent, node, {
+          usage: cost.usage,
+          idleAt: cost.idleAt,
+          result,
+          waitGuard,
+          abort: waitAbort,
+          historyId,
+          performanceId,
+          timeout
+        });
+      }
       if (this.notifications?.isEnabled()) {
         this.notifications.notify({ title: "Nexus: Task Failed", body: `${node.task.name} failed: ${errorMessage}`, sound: true });
       }
@@ -10765,6 +10990,10 @@ Please continue from where the previous agent left off.`;
         await this.handleFailure(agent, node, new Error(errorMessage));
       }
     } finally {
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
       if (agent.status !== "terminated" && agent.status !== "failed") {
         agent.status = "idle";
       }
@@ -10772,6 +11001,200 @@ Please continue from where the previous agent left off.`;
       this.notifyStateChange();
     }
   }
+  armTimeoutDelta(agent, node, args) {
+    const sessionID = agent.sessionID;
+    if (!sessionID)
+      return;
+    const model = `${agent.model.provider}/${agent.model.model}`;
+    if (this.shuttingDown)
+      return;
+    if (this.deltaLedgers.has(sessionID))
+      return;
+    const ledger = {
+      sessionID,
+      taskId: node.id,
+      agentId: agent.id,
+      agent,
+      node,
+      result: args.result,
+      model,
+      provider: agent.model.provider,
+      charged: args.usage,
+      idleAtTimeout: args.idleAt,
+      pending: false,
+      historyId: args.historyId,
+      performanceId: args.performanceId,
+      abort: args.abort ?? new AbortController
+    };
+    this.deltaLedgers.set(sessionID, ledger);
+    const graceMs = this.config.cost?.timeoutDeltaGraceMs ?? Math.min(180000, Math.max(30000, args.timeout / 2));
+    const timer = setTimeout(() => {
+      this.deltaTimers.delete(timer);
+      this.settleTimeoutDelta(ledger, "deadline").catch(() => {});
+    }, graceMs);
+    timer.unref?.();
+    this.deltaTimers.add(timer);
+    (async () => {
+      try {
+        const { outcome } = await args.waitGuard;
+        if (outcome === "idle")
+          await this.settleTimeoutDelta(ledger, "session-idle");
+        else
+          await this.settleTimeoutDelta(ledger, "poll-failed");
+      } catch {}
+    })();
+  }
+  async settleTimeoutDelta(ledger, trigger) {
+    if (ledger.pending)
+      return;
+    if (this.deltaLedgers.get(ledger.sessionID) !== ledger)
+      return;
+    ledger.pending = true;
+    try {
+      let reason = trigger === "shutdown" ? "shutdown" : trigger === "session-idle" ? "session-idle" : "abandoned";
+      let now;
+      if (trigger === "deadline" || trigger === "poll-failed") {
+        const probe = await this.readSessionTokens(ledger.sessionID);
+        if (!probe.read || probe.idleAt <= ledger.idleAtTimeout) {
+          this.abandonTimeoutDelta(ledger, probe.read ? probe.usage : undefined, reason);
+          return;
+        }
+        now = probe.usage;
+        reason = "session-idle";
+      } else {
+        const read = trigger === "shutdown" ? await this.readSessionTokens(ledger.sessionID) : await this.readSessionTokensWithRetry(ledger.sessionID);
+        if (!read.read) {
+          this.abandonTimeoutDelta(ledger, undefined, reason);
+          return;
+        }
+        now = read.usage;
+      }
+      const delta = {
+        input: Math.max(0, now.input - ledger.charged.input),
+        output: Math.max(0, now.output - ledger.charged.output),
+        reasoning: Math.max(0, now.reasoning - ledger.charged.reasoning),
+        cache: {
+          read: Math.max(0, now.cache.read - ledger.charged.cache.read),
+          write: Math.max(0, now.cache.write - ledger.charged.cache.write)
+        }
+      };
+      const deltaTokens = totalTokens(delta);
+      if (deltaTokens === 0) {
+        this.emit("cost:delta", {
+          taskId: ledger.taskId,
+          nodeId: ledger.taskId,
+          agentId: ledger.agentId,
+          sessionID: ledger.sessionID,
+          model: ledger.model,
+          deltaCost: 0,
+          deltaTokens: 0,
+          sessionTotalCost: priceUsage(ledger.charged, this.forecaster.tiersFor(ledger.model, ledger.provider).pricing).total,
+          reason,
+          settledTier: this.settledTierOf(ledger, ledger.charged)
+        });
+        return;
+      }
+      const { pricing, source } = this.forecaster.tiersFor(ledger.model, ledger.provider);
+      const deltaCost = priceUsageAtSettledTier(delta, pricing, now).total;
+      const provenance = { usage: "measured", pricing: source };
+      ledger.charged = now;
+      let historyAdjusted = false;
+      let performanceAdjusted = false;
+      let nodeAdjusted = false;
+      let agentAdjusted = false;
+      let error;
+      try {
+        this.trackCost(ledger.agentId, ledger.model, deltaCost, deltaTokens, provenance);
+        historyAdjusted = this.executionHistory.adjust(ledger.historyId, {
+          cost: deltaCost,
+          tokensUsed: deltaTokens
+        });
+        performanceAdjusted = this.performanceTracker.adjust(ledger.performanceId, { cost: deltaCost });
+        ledger.agent.metrics.totalCost += deltaCost;
+        ledger.agent.metrics.totalTokens += deltaTokens;
+        agentAdjusted = true;
+        if (ledger.node.result === ledger.result) {
+          ledger.result.cost += deltaCost;
+          ledger.result.tokensUsed += deltaTokens;
+          nodeAdjusted = true;
+        }
+        this.uncollected.delete(ledger.sessionID);
+      } catch (thrown) {
+        error = thrown instanceof Error ? thrown.message : String(thrown);
+      }
+      this.emit("cost:delta", {
+        taskId: ledger.taskId,
+        nodeId: ledger.taskId,
+        agentId: ledger.agentId,
+        sessionID: ledger.sessionID,
+        model: ledger.model,
+        deltaCost,
+        deltaTokens,
+        sessionTotalCost: priceUsage(now, pricing).total,
+        reason,
+        settledTier: this.settledTierOf(ledger, now),
+        recordsAdjusted: { history: historyAdjusted, performance: performanceAdjusted, node: nodeAdjusted, agent: agentAdjusted },
+        ...error === undefined ? {} : { error }
+      });
+    } finally {
+      this.deltaLedgers.delete(ledger.sessionID);
+      ledger.pending = false;
+      ledger.abort.abort();
+    }
+  }
+  abandonTimeoutDelta(ledger, probeUsage, reason) {
+    const eventReason = reason === "shutdown" ? "shutdown" : "abandoned";
+    const known = probeUsage ?? ledger.charged;
+    const { pricing } = this.forecaster.tiersFor(ledger.model, ledger.provider);
+    const observedIncrement = {
+      input: Math.max(0, known.input - ledger.charged.input),
+      output: Math.max(0, known.output - ledger.charged.output),
+      reasoning: Math.max(0, known.reasoning - ledger.charged.reasoning),
+      cache: {
+        read: Math.max(0, known.cache.read - ledger.charged.cache.read),
+        write: Math.max(0, known.cache.write - ledger.charged.cache.write)
+      }
+    };
+    const observedUncollected = totalTokens(observedIncrement) > 0 ? priceUsageAtSettledTier(observedIncrement, pricing, known).total : 0;
+    this.uncollected.set(ledger.sessionID, {
+      sessionID: ledger.sessionID,
+      taskId: ledger.taskId,
+      agentId: ledger.agentId,
+      model: ledger.model,
+      lastKnownTokens: totalTokens(known),
+      observedUncollected
+    });
+    this.emit("cost:delta", {
+      taskId: ledger.taskId,
+      nodeId: ledger.taskId,
+      agentId: ledger.agentId,
+      sessionID: ledger.sessionID,
+      model: ledger.model,
+      deltaCost: 0,
+      deltaTokens: 0,
+      sessionTotalCost: priceUsage(known, pricing).total,
+      reason: eventReason,
+      settledTier: this.settledTierOf(ledger, known),
+      uncollected: { lastKnownTokens: totalTokens(known), observedUncollected }
+    });
+  }
+  settledTierOf(ledger, usage) {
+    const { pricing, source } = this.forecaster.tiersFor(ledger.model, ledger.provider);
+    const promptSize = promptSizeOf(usage);
+    return {
+      pricing: source,
+      promptSizeAtSettlement: promptSize,
+      threshold: selectTier(pricing.tiers, promptSize).threshold ?? null
+    };
+  }
+  async flushTimeoutDeltas() {
+    for (const timer of this.deltaTimers)
+      clearTimeout(timer);
+    this.deltaTimers.clear();
+    for (const ledger of [...this.deltaLedgers.values()]) {
+      await this.settleTimeoutDelta(ledger, "shutdown").catch(() => {});
+    }
+  }
   buildRolePrompt(role) {
     if (this.customRoles.has(role)) {
       return this.customRoles.getPrompt(role) || `You are a ${role}. Complete the assigned task professionally.`;
@@ -10834,16 +11257,25 @@ Please continue from where the previous agent left off.`;
       await this.terminateAgent(agent.id);
       node.status = "pending";
       this.notifyStateChange();
-      await this.spawnAndExecute(node, context);
+      await this.spawnAndExecute(node, { transferContext: context });
       return;
     }
-    if (policy.fallbackModels.length > 0) {
-      const fallbackModel = policy.fallbackModels.shift();
+    const failedRef = `${agent.model.provider}/${agent.model.model}`;
+    const hasUsableFallback = policy.fallbackModels.some((m) => m !== failedRef);
+    if (policy.fallbackModels.length > 0 && hasUsableFallback) {
+      let fallbackModel;
+      while (policy.fallbackModels.length > 0) {
+        const candidate = policy.fallbackModels.shift();
+        if (candidate !== failedRef) {
+          fallbackModel = candidate;
+          break;
+        }
+      }
       if (fallbackModel) {
         await this.terminateAgent(agent.id);
         node.status = "pending";
         this.notifyStateChange();
-        await this.spawnAgent({ role: node.task.requiredRole, model: fallbackModel });
+        await this.spawnAndExecute(node, { modelOverride: fallbackModel });
         return;
       }
     }
@@ -11077,32 +11509,16 @@ Please continue from where the previous agent left off.`;
       if (qualified)
         return qualified;
     }
-    const bare = model.slice(model.indexOf("/") + 1);
+    const bare = bareModelId(model);
     let best;
     for (const [key, cost] of this.modelCosts) {
-      if (key.slice(key.indexOf("/") + 1) !== bare)
+      if (bareModelId(key) !== bare)
         continue;
-      if (!best || cost.input < best.input)
+      if (!best || baseInputRate(cost) < baseInputRate(best))
         best = cost;
     }
     return best;
   }
-  estimateModelCost(model, provider) {
-    const realCost = this.getModelCost(model, provider);
-    if (realCost) {
-      return (realCost.input + realCost.output) / 2;
-    }
-    const costs = {
-      "claude-sonnet-4-6": 0.15,
-      "claude-opus-4-7": 15,
-      "claude-haiku-4-5": 0.8,
-      "gpt-5-mini": 0.05,
-      "gpt-5": 2.5,
-      "gemini-2.5-flash": 0.075,
-      "minimax-m2.5-free": 0
-    };
-    return costs[model] || 0.1;
-  }
   estimateModelQuality(model) {
     const quality = {
       "claude-opus-4-7": 0.95,
@@ -11127,13 +11543,17 @@ Please continue from where the previous agent left off.`;
     };
     return speeds[model] || 0.5;
   }
-  scoreModel(modelId, role, complexity) {
+  scoreModel(modelId, role, complexity, estimates) {
     const [provider, ...parts] = modelId.split("/");
     const model = parts.join("/");
-    const cost = this.estimateModelCost(model, provider);
+    const estimate = estimates?.get(modelId) ?? this.forecaster.estimateCost(complexity, model, provider);
+    let maxEstimate = 0;
+    for (const value of estimates?.values() ?? []) {
+      if (value > maxEstimate)
+        maxEstimate = value;
+    }
+    const costScore = maxEstimate === 0 ? 1 : 1 - estimate / maxEstimate;
     const quality = this.estimateModelQuality(model);
-    const maxCost = 15;
-    const costScore = 1 - cost / maxCost;
     const speedScore = this.estimateModelSpeed(model);
     const qualityWeight = complexity.overall > 70 ? 0.6 : complexity.overall > 40 ? 0.4 : 0.2;
     const costWeight = 1 - qualityWeight;
@@ -11145,7 +11565,7 @@ Please continue from where the previous agent left off.`;
       qualityScore: quality,
       speedScore,
       overallScore,
-      reasoning: `Score: ${overallScore.toFixed(2)} (quality: ${quality.toFixed(2)}, cost: ${costScore.toFixed(2)}, speed: ${speedScore.toFixed(2)})`
+      reasoning: `Score: ${overallScore.toFixed(2)} (quality: ${quality.toFixed(2)}, cost: ${costScore.toFixed(2)} [~$${estimate.toFixed(4)}/task], speed: ${speedScore.toFixed(2)})`
     };
   }
   selectBestModel(role, complexity) {
@@ -11159,31 +11579,127 @@ Please continue from where the previous agent left off.`;
       "opencode/minimax-m2.5-free"
     ];
     const unique = [...new Set(candidates)];
-    const scored = unique.map((m) => this.scoreModel(m, role, complexity));
+    const estimates = new Map;
+    for (const ref of unique) {
+      const [provider, ...parts] = ref.split("/");
+      estimates.set(ref, this.forecaster.estimateCost(complexity, parts.join("/"), provider));
+    }
+    const scored = unique.map((ref) => ({ ref, score: this.scoreModel(ref, role, complexity, estimates) }));
     const budgetRemaining = this.budget.maxTotalCost - this.totalSpent;
-    const affordable = scored.filter((s) => {
-      const cost = this.estimateModelCost(s.model, s.provider);
-      return cost <= budgetRemaining || cost === 0;
+    const affordable = scored.filter(({ ref }) => {
+      const estimate = estimates.get(ref) ?? 0;
+      return estimate <= budgetRemaining || estimate === 0;
     });
-    const best = (affordable.length > 0 ? affordable : scored).sort((a, b) => b.overallScore - a.overallScore)[0];
+    const best = (affordable.length > 0 ? affordable : scored).sort((a, b) => b.score.overallScore - a.score.overallScore)[0];
     return {
-      provider: best.provider,
-      model: best.model,
-      estimatedCost: this.estimateModelCost(best.model, best.provider),
-      estimatedQuality: best.qualityScore,
-      reasoning: best.reasoning
+      provider: best.score.provider,
+      model: best.score.model,
+      estimatedCost: estimates.get(best.ref) ?? 0,
+      estimatedQuality: best.score.qualityScore,
+      reasoning: best.score.reasoning
     };
   }
-  trackCost(agentId, model, cost, tokens) {
+  trackCost(agentId, model, cost, tokens, provenance) {
     this.totalSpent += cost;
     const agentCost = this.costByAgent.get(agentId) || 0;
     this.costByAgent.set(agentId, agentCost + cost);
     const modelCost = this.costByModel.get(model) || 0;
     this.costByModel.set(model, modelCost + cost);
-    this.costHistory.push({ timestamp: Date.now(), cost, agentId });
+    this.tokensByModel.set(model, (this.tokensByModel.get(model) || 0) + tokens);
+    this.recordProvenance(model, cost, provenance);
+    this.costHistory.push({ timestamp: Date.now(), cost, agentId, model, tokens, provenance });
     this.checkBudget();
     this.notifyStateChange();
   }
+  recordProvenance(model, cost, provenance) {
+    const measured = provenance.usage === "measured";
+    const prior = this.costProvenance.get(model) ?? {
+      usage: provenance.usage,
+      pricing: provenance.pricing,
+      measuredEntries: 0,
+      estimatedEntries: 0,
+      measuredSpend: 0,
+      estimatedSpend: 0
+    };
+    prior.usage = provenance.usage;
+    prior.pricing = provenance.pricing;
+    if (measured) {
+      prior.measuredEntries++;
+      prior.measuredSpend += cost;
+    } else {
+      prior.estimatedEntries++;
+      prior.estimatedSpend += cost;
+    }
+    this.costProvenance.set(model, prior);
+  }
+  spendSplit() {
+    return {
+      measuredSpend: sumBy(this.costProvenance, (p) => p.measuredSpend),
+      estimatedSpend: sumBy(this.costProvenance, (p) => p.estimatedSpend)
+    };
+  }
+  safeAccountTaskCost(agent, task) {
+    return this.accountTaskCost(agent, task).catch(() => ({
+      cost: 0,
+      tokensUsed: 0,
+      provenance: { usage: "estimated", pricing: "unknown-model" },
+      usage: null,
+      idleAt: 0
+    }));
+  }
+  async accountTaskCost(agent, task) {
+    const model = `${agent.model.provider}/${agent.model.model}`;
+    const read = agent.sessionID ? await this.readSessionTokens(agent.sessionID) : { read: false };
+    if (read.read) {
+      const measured = this.forecaster.measureCost(read.usage, model, agent.model.provider);
+      return {
+        cost: measured.cost,
+        tokensUsed: measured.tokens,
+        provenance: { usage: "measured", pricing: measured.pricingSource },
+        usage: read.usage,
+        idleAt: read.idleAt
+      };
+    }
+    const predicted = this.forecaster.forecastTask(task, task.requiredRole, model, task.complexity);
+    return {
+      cost: predicted.estimatedCost,
+      tokensUsed: predicted.estimatedInputTokens + predicted.estimatedOutputTokens,
+      provenance: { usage: "estimated", pricing: predicted.pricingSource },
+      usage: null,
+      idleAt: 0
+    };
+  }
+  async readSessionTokens(sessionID) {
+    const finite = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+    try {
+      const session = await this.ctx?.session.get({ sessionID });
+      const tokens = session?.tokens;
+      if (!tokens)
+        return { read: false };
+      return {
+        read: true,
+        idleAt: typeof session?.time?.idle === "number" && Number.isFinite(session.time.idle) ? session.time.idle : 0,
+        usage: {
+          input: finite(tokens.input),
+          output: finite(tokens.output),
+          reasoning: finite(tokens.reasoning),
+          cache: { read: finite(tokens.cache?.read), write: finite(tokens.cache?.write) }
+        }
+      };
+    } catch {
+      return { read: false };
+    }
+  }
+  async readSessionTokensWithRetry(sessionID) {
+    for (let attempt = 0;attempt < this.deltaReadBackoffMs.length; attempt++) {
+      if (attempt > 0)
+        await this.sleep(this.deltaReadBackoffMs[attempt] ?? 0);
+      const read = await this.readSessionTokens(sessionID);
+      if (read.read)
+        return read;
+    }
+    return { read: false };
+  }
   checkBudget() {
     const remaining = this.budget.maxTotalCost - this.totalSpent;
     const remainingPercent = remaining / this.budget.maxTotalCost;
@@ -11250,8 +11766,9 @@ Please continue from where the previous agent left off.`;
       global: loadInfo?.global ?? null,
       models: this.configManager.getResolvedModels()
     };
+    const spend = this.spendSplit();
     if (detailed)
-      return JSON.stringify({ ...state, budgetExceeded: this.budgetExceeded, config }, null, 2);
+      return JSON.stringify({ ...state, ...spend, budgetExceeded: this.budgetExceeded, config }, null, 2);
     return JSON.stringify({
       running: state.running,
       paused: state.paused,
@@ -11259,6 +11776,7 @@ Please continue from where the previous agent left off.`;
       agents: state.agents.length,
       tasks: state.tasks.length,
       totalCost: state.totalSpent,
+      ...spend,
       budgetRemaining: state.budgetRemaining,
       config
     }, null, 2);
@@ -11273,10 +11791,25 @@ Please continue from where the previous agent left off.`;
     return JSON.stringify({
       totalSpent: state.totalSpent,
       budgetRemaining: state.budgetRemaining,
+      ...this.spendSplit(),
       byAgent: Object.fromEntries(this.costByAgent),
-      byModel: Object.fromEntries(this.costByModel)
+      byModel: Object.fromEntries(this.costByModel),
+      tokensByModel: Object.fromEntries(this.tokensByModel),
+      provenance: Object.fromEntries(this.costProvenance),
+      measuredEntries: sumBy(this.costProvenance, (p) => p.measuredEntries),
+      estimatedEntries: sumBy(this.costProvenance, (p) => p.estimatedEntries),
+      uncollected: this.uncollectedSummary()
     }, null, 2);
   }
+  uncollectedSummary() {
+    const all = [...this.uncollected.values()];
+    return {
+      sessions: all.length,
+      lastKnownTokens: all.reduce((sum, u) => sum + u.lastKnownTokens, 0),
+      observedUncollected: all.reduce((sum, u) => sum + u.observedUncollected, 0),
+      taskIds: all.map((u) => u.taskId)
+    };
+  }
   pause() {
     this.paused = true;
     this.emit("orchestrator:paused", {});
@@ -11294,6 +11827,7 @@ Please continue from where the previous agent left off.`;
     this.budgetExceeded = false;
   }
   async shutdown() {
+    this.shuttingDown = true;
     await this.moduleRegistry.teardownAll();
     this._healthMonitor?.stop();
     this.stopDashboard();
@@ -11306,6 +11840,7 @@ Please continue from where the previous agent left off.`;
       clearTimeout(this.stateChangeTimer);
       this.stateChangeTimer = null;
     }
+    await this.flushTimeoutDeltas();
     this.agents.forEach((agent) => {
       agent.status = "terminated";
     });
@@ -11671,8 +12206,18 @@ class AstGrep {
 
 // src/index.ts
 import { writeFileSync as writeFileSync2, readFileSync as readFileSync3, mkdirSync as mkdirSync4, existsSync as existsSync3, statSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join as join6, resolve as resolve3, basename, dirname as dirname4 } from "node:path";
 import { homedir as homedir2 } from "node:os";
+function renderCost(cost, provenance) {
+  return provenance.usage === "measured" ? `$${cost.toFixed(4)} measured` : `$${cost.toFixed(4)} estimated`;
+}
+function renderCostBasis(score) {
+  if (score.costBasis === "none") {
+    return "cost unscored: 0 measured tasks, 0% of score from cost";
+  }
+  return `avg=$${score.avgCost.toFixed(4)} (${score.measuredTasks}/${score.totalTasks} measured)`;
+}
 var CONFIG_RELOAD_DEBOUNCE_MS = 150;
 var CONFIG_POLL_INTERVAL_MS = 2000;
 function isNexusConfigFile(file, eventDirectory, projectDirectory, projectPath, globalPath) {
@@ -11687,6 +12232,8 @@ var watchedContexts = new WeakSet;
 var MAX_RELOAD_WAIT_MS = 1000;
 var MIN_INTERVAL_MS = 25;
 var clampInterval = (ms, fallback) => Number.isFinite(ms) && ms >= MIN_INTERVAL_MS ? ms : fallback;
+var ABSENT = "absent";
+var UNREADABLE = "unreadable";
 function watchConfigFiles(ctx, orchestrator, debounceMs = CONFIG_RELOAD_DEBOUNCE_MS, pollMs = CONFIG_POLL_INTERVAL_MS) {
   if (watchedContexts.has(ctx))
     return () => {};
@@ -11706,15 +12253,24 @@ function watchConfigFiles(ctx, orchestrator, debounceMs = CONFIG_RELOAD_DEBOUNCE
     clearTimeout(debounceTimer);
     debounceTimer = null;
   };
+  const digestOf = (filePath) => {
+    try {
+      return createHash("sha1").update(readFileSync3(filePath)).digest("hex");
+    } catch {
+      return UNREADABLE;
+    }
+  };
   const stampOf = (filePath) => {
+    let stat;
     try {
       const stats = statSync(filePath);
       if (!stats.isFile())
-        return "absent";
-      return `${stats.mtimeMs}:${stats.size}`;
+        return ABSENT;
+      stat = `${stats.mtimeMs}:${stats.size}`;
     } catch {
-      return "absent";
+      return ABSENT;
     }
+    return `${stat}|${digestOf(filePath)}`;
   };
   const lastSeen = new Map(watchedPaths.map((p) => [p, stampOf(p)]));
   const runReload = (trigger) => {
@@ -11963,6 +12519,19 @@ Before marking a task complete:
 4. Follows project conventions
 5. Has appropriate test coverage
 `;
+function clearPresetOverride(orchestrator) {
+  const configManager = orchestrator.configManager;
+  const hadOverride = configManager.resetToDefaults();
+  const models = configManager.getResolvedModels();
+  const resolved = Object.entries(models).map(([role, model]) => `${role}=${model}`).join(" ");
+  return {
+    content: hadOverride ? `Cleared the session preset override. nexus.jsonc is in control again — no config file was modified.
+` + `Resolved models now: ${resolved}
+` + `sessionOverride: false` : `No session preset override was set, so nothing was cleared — nexus.jsonc was already in control. No config file was modified.
+` + `Resolved models now: ${resolved}
+` + `sessionOverride: false`
+  };
+}
 var src_default = define({
   id: "nexus",
   async setup(ctx) {
@@ -12444,23 +13013,35 @@ You are a technical writer who creates documentation that developers actually wa
       });
       editor.add({
         name: "preset",
-        description: "Apply a preset configuration",
+        description: "Apply a session preset (model/budget selection), or clear it with mode 'clear' to hand control back to nexus.jsonc. A preset shadows the config file's models, so call mode 'clear' if the user edited nexus.jsonc but no model changed.",
         input: {
           type: "object",
           properties: {
-            name: { type: "string", description: "Preset name (minimal, balanced, enterprise, cost-optimized)" }
+            mode: {
+              type: "string",
+              enum: ["apply", "clear"],
+              description: "'apply' (default) applies the named preset for this session. 'clear' drops the session preset override so nexus.jsonc is in control again — use it whenever edits to nexus.jsonc appear to have no effect."
+            },
+            name: {
+              type: "string",
+              description: "Preset name (minimal, balanced, enterprise, cost-optimized). Required for mode 'apply'; ignored by 'clear'."
+            }
           },
-          required: ["name"],
           additionalProperties: false
         },
         options: { codemode: true },
         execute: async (input) => {
-          const { name } = input;
+          const { mode, name } = input;
+          if (mode === "clear")
+            return clearPresetOverride(orchestrator);
+          if (!name) {
+            return { content: `Error: mode 'apply' needs a \`name\` (${orchestrator.configManager.listPresets().join(", ")}). To hand control back to nexus.jsonc instead, call preset with mode: 'clear'.` };
+          }
           try {
             orchestrator.configManager.applyPreset(name);
             return {
               content: `Applied preset: ${PRESETS[name]?.name || name}
-` + `⚠️ This preset now overrides the \`models\` section of nexus.jsonc. ` + `Edits to models in the config file will NOT take effect until the preset is cleared. ` + `Clear it from the TUI (config manager) to hand control back to disk. ` + `Budget and self-healing values from the file still apply.`
+` + `⚠️ This preset now overrides the \`models\` section of nexus.jsonc. ` + `Edits to models in the config file will NOT take effect until the preset is cleared. ` + `Clear it with this tool (mode: 'clear'), or from the TUI (config manager), to hand control back to disk. ` + `Budget and self-healing values from the file still apply.`
             };
           } catch (error) {
             return { content: `Error: ${error.message}` };
@@ -12515,6 +13096,8 @@ You are a technical writer who creates documentation that developers actually wa
         execute: async (input) => {
           const { model, setInput, setOutput } = input;
           const per1k = (v) => `$${v}/1K tokens`;
+          const renderTiers = (cost) => cost.tiers.map((t) => t.threshold === undefined ? `base: in=${per1k(t.rates.input)}, out=${per1k(t.rates.output)}, cache_read=${per1k(t.rates.cacheRead)}, cache_write=${per1k(t.rates.cacheWrite)}` : `over ${t.threshold} prompt tokens: in=${per1k(t.rates.input)}, out=${per1k(t.rates.output)}, cache_read=${per1k(t.rates.cacheRead)}, cache_write=${per1k(t.rates.cacheWrite)}`).join(`
+            `);
           if (model && setInput !== undefined && setOutput !== undefined) {
             orchestrator.setModelCosts({ [model]: { input: setInput, output: setOutput } });
             return { content: `Set ${model}: input=${per1k(setInput)}, output=${per1k(setOutput)}` };
@@ -12522,20 +13105,23 @@ You are a technical writer who creates documentation that developers actually wa
           if (model) {
             const cost = orchestrator.getModelCost(model);
             if (cost) {
-              return { content: `${model}: input=${per1k(cost.input)}, output=${per1k(cost.output)}, cache_read=${per1k(cost.cacheRead)}, cache_write=${per1k(cost.cacheWrite)}` };
+              return { content: `${model} (real pricing, from OpenCode):
+            ${renderTiers(cost)}` };
             }
-            const estimate = orchestrator["estimateModelCost"](model);
-            return { content: `${model}: no real pricing data (estimated $${estimate}/1K tokens)` };
+            const { pricing, source } = orchestrator.forecaster.priceFor(model);
+            const label = source === "model-costs" ? "real pricing" : source === "fallback-table" ? "ESTIMATE (fallback table, not provider pricing)" : "ESTIMATE (unknown model — no table knows this rate)";
+            return { content: `${model}: no real pricing data.
+            ${label}: in=${per1k(pricing.input)}, out=${per1k(pricing.output)}, cache_read=${per1k(pricing.cacheRead)}, cache_write=${per1k(pricing.cacheWrite)}` };
           }
           if (orchestrator.modelCosts.size > 0) {
             const lines = ["\uD83D\uDCCA Model Pricing (from OpenCode, per 1K tokens):"];
             for (const [id, cost] of orchestrator.modelCosts) {
-              lines.push(`  ${id}: ${per1k(cost.input)} in, ${per1k(cost.output)} out`);
+              lines.push(`  ${id}: ${renderTiers(cost)}`);
             }
             return { content: lines.join(`
 `) };
           }
-          return { content: "No real pricing data loaded. Using hardcoded estimates." };
+          return { content: "No real pricing data loaded. Using labelled fallback estimates." };
         }
       });
       editor.add({
@@ -12765,7 +13351,7 @@ You are a technical writer who creates documentation that developers actually wa
           const scores = orchestrator.performanceTracker.getScores();
           if (scores.length === 0)
             return { content: "No performance data yet. Scores build up as tasks are executed." };
-          const lines = scores.map((s) => `${s.role}/${s.model}: score=${s.overallScore.toFixed(1)} success=${(s.successRate * 100).toFixed(0)}% avg=$${s.avgCost.toFixed(4)} (${s.totalTasks} tasks)`);
+          const lines = scores.map((s) => `${s.role}/${s.model}: score=${s.overallScore.toFixed(1)} success=${(s.successRate * 100).toFixed(0)}% ${renderCostBasis(s)} (${s.totalTasks} tasks)`);
           return { content: lines.join(`
 `) };
         }
@@ -12787,7 +13373,7 @@ You are a technical writer who creates documentation that developers actually wa
           const best = orchestrator.performanceTracker.getBestModel(role);
           if (!best)
             return { content: `No performance data for role '${role}' yet.` };
-          return { content: `Best for ${role}: ${best.model} (score: ${best.overallScore.toFixed(1)}, success: ${(best.successRate * 100).toFixed(0)}%, avg cost: $${best.avgCost.toFixed(4)})` };
+          return { content: `Best for ${role}: ${best.model} (score: ${best.overallScore.toFixed(1)}, success: ${(best.successRate * 100).toFixed(0)}%, ${renderCostBasis(best)})` };
         }
       });
       editor.add({
@@ -12826,7 +13412,7 @@ You are a technical writer who creates documentation that developers actually wa
           const records = count ? orchestrator.executionHistory.getRecent(count) : orchestrator.executionHistory.getAll();
           if (records.length === 0)
             return { content: "No execution history yet." };
-          const lines = records.map((r) => `${r.status === "success" ? "✅" : "❌"} ${r.taskName} (${r.role}) — $${r.cost.toFixed(4)} — ${r.duration}ms`);
+          const lines = records.map((r) => `${r.status === "success" ? "✅" : "❌"} ${r.taskName} (${r.role}) — ${renderCost(r.cost, r.costProvenance)} — ${r.duration}ms`);
           return { content: lines.join(`
 `) };
         }
@@ -12842,7 +13428,7 @@ You are a technical writer who creates documentation that developers actually wa
         options: { codemode: true },
         execute: async () => {
           const stats = orchestrator.executionHistory.getStats();
-          return { content: `Total: ${stats.total} | Success: ${(stats.successRate * 100).toFixed(1)}% | Cost: $${stats.totalCost.toFixed(4)} | Avg: ${stats.avgDuration.toFixed(0)}ms
+          return { content: `Total: ${stats.total} | Success: ${(stats.successRate * 100).toFixed(1)}% | Cost: $${stats.totalCost.toFixed(4)} (measured $${stats.costSplit.measuredCost.toFixed(4)} over ${stats.costSplit.measuredEntries} tasks, estimated $${stats.costSplit.estimatedCost.toFixed(4)} over ${stats.costSplit.estimatedEntries} tasks) | Avg: ${stats.avgDuration.toFixed(0)}ms
 By role: ${JSON.stringify(stats.byRole)}` };
         }
       });