@mindot/will 0.7.0 → 0.9.0

package/src/cognition/utilities/token.tracker.ts

@@ -16,6 +16,7 @@
  * Exposes as metrics so the orchestrator and runner can log costs,
  * and the ParameterOptimizer can factor cost into optimization decisions.
  */
+import { logger } from '#core/logger'
 import type {
   Duration,
   Tick,
@@ -31,56 +32,51 @@ import { wallClock } from '#core/wall.clock'
 // transport layer (determinism contract). The tracker exposes a neutral
 // onRecord() sink; the stem bridges records onto the transport.
 
+// ── Attribution axes ──────────────────────────────────────
+//
+// Typed rather than free strings so a deviation is caught at the call site
+// instead of surfacing as a silently-unmatched routing rule or a cost bucket
+// nobody notices is empty. These live here (not in #llm) because cognition is
+// the lower layer — #llm already imports from this module, and the reverse
+// would be circular.
+
+/** Top-level cost bucket for an LLM call. */
+export type LLMCallCategory =
+  | 'executive'       // the master consciousness and its facets
+  | 'summarizer'      // rolling memory consolidation
+  | 'embedding'       // semantic-memory vectorisation
+  | 'identity-guard'  // creation-time persona review
+
+/** The actor/subsystem doing the work. */
+export type LLMCallAttribute =
+  | 'master'   // the executive itself
+  | 'facet'    // a spawned focus (conversation, planning, outreach, supervision)
+  | 'memory'   // consolidation / embedding
+  | 'guard'    // a safety reviewer
+
+/** The specific cognitive process being paid for. */
+export type LLMCallProcess =
+  | 'cog'                 // background cogs' call
+  | 'decision'           // the master's fused decision call
+  | 'ideation'           // the deliberate path's propose pass
+
+/** The specific cognitive function being paid for. */
+export type LLMCallFunction =
+  | '-'                  // no-specific function
+  | 'deliberation'       // action choice under contest
+  | 'conversation'       // a live reply
+  | 'outreach'           // an unprompted message
+  | 'planning'           // plan formation / revision
+  | 'supervision'        // plan-step supervision
+  | 'consolidation'      // rolling summary
+  | 'recall'             // embedding a query
+  | 'index'              // embedding a write
+  | 'identity-coherence' // persona review
+
 /** One attributed ledger record (5-axis attribution + tokens + cost). */
 export type TokenLedgerRecord = Record<string, unknown>
 export type TokenRecordListener = ( record: TokenLedgerRecord ) => void
 
-// ── Pricing table (USD per 1M tokens) ─────────────────────
-
-const MODEL_PRICING: Record<string, { input: number; output: number }> = {
-  // OpenAI
-  'openai/gpt-4o':              { input: 2.50,  output: 10.00 },
-  'openai/gpt-4o-mini':         { input: 0.15,  output: 0.60  },
-  'openai/gpt-4-turbo':         { input: 10.00, output: 30.00 },
-  'openai/gpt-3.5-turbo':       { input: 0.50,  output: 1.50  },
-  
-  // Anthropic (Claude 4.x family — prices per 1M tokens)
-  'anthropic/claude-haiku-4-5':  { input: 1.00,  output: 5.00  },
-  'anthropic/claude-sonnet-4-5': { input: 3.00,  output: 15.00 },
-  'anthropic/claude-sonnet-4-6': { input: 3.00,  output: 15.00 },
-  'anthropic/claude-opus-4-7':   { input: 5.00,  output: 25.00 },
-  // Legacy aliases kept for backward compat
-  'anthropic/claude-haiku-4':    { input: 1.00,  output: 5.00  },
-  'anthropic/claude-opus-4':     { input: 5.00,  output: 25.00 },
-  
-  // Z.ai (GLM-5 family). `glm-5.2[1m]` is the same model asking for its 1M
-  // context window — same rate, so it gets its own row rather than relying on
-  // the normalizer (a future long-context tier would price differently).
-  'glm/glm-5.2':                { input: 1.40,  output: 4.40  },
-  'glm/glm-5.2[1m]':            { input: 1.40,  output: 4.40  },
-
-  // Google
-  'google/gemini-2.0-flash':    { input: 0.10,  output: 0.40  },
-  'google/gemini-2.0-pro':      { input: 1.25,  output: 5.00  },
-  
-  // Meta (via Groq/Replicate)
-  'meta/llama-3.3-70b':         { input: 0.59,  output: 0.79  },
-  'meta/llama-4-maverick':      { input: 0.20,  output: 0.60  },
-  
-  // DeepSeek
-  'deepseek/deepseek-v3':       { input: 0.27,  output: 1.10  },
-  'deepseek/deepseek-r1':       { input: 0.55,  output: 2.19  },
-
-  // Embeddings (input-only — no completion tokens). Priced per 1M input tokens.
-  'openai/text-embedding-3-small': { input: 0.02, output: 0 },
-  'openai/text-embedding-3-large': { input: 0.13, output: 0 },
-  'google/text-embedding-004':     { input: 0,    output: 0 },  // free tier
-  'google/gemini-embedding-001':   { input: 0,    output: 0 },  // free tier
-
-  // Fallback for unknown models
-  '__default__':                { input: 3.00,  output: 15.00 },
-}
-
 // ── Prompt-cache pricing (Anthropic) ──────────────────────
 // `input_tokens` in the API usage already EXCLUDES cached tokens, so the full
 // input cost is: fresh input ×1 + cache reads ×0.1 + cache writes ×1.25.
@@ -88,40 +84,83 @@ const CACHE_READ_MULT  = 0.1
 const CACHE_WRITE_MULT = 1.25
 
 /**
- * Normalize a model id to its bare, dateless form so a raw provider model string
- * ("claude-sonnet-4-5-20250929", "anthropic/claude-haiku-4-5") resolves to the
- * right pricing row. Without this, every non-default id missed the `provider/model`
- * keys and silently fell through to __default__ ($3/$15) — pricing Haiku ~3× and
- * DeepSeek ~11× too high, and breaking the self-hosting margin telemetry entirely.
+ * Normalize a model id to its bare form so a raw provider string
+ * ("claude-sonnet-5-20260114", "anthropic/claude-haiku-4-5", "glm-5.2[1m]")
+ * matches a host price keyed plainly — and vice versa. Exact keys are tried
+ * first, so a host that prices a long-context variant differently just lists it
+ * verbatim and that wins.
  */
 function normalizeModelKey( model: string ): string {
   let m = model.toLowerCase().trim()
   const slash = m.lastIndexOf('/')
-  if( slash >= 0 ) m = m.slice( slash + 1 )   // drop "provider/" prefix
-  return m.replace( /[-@]\d{6,8}$/, '')        // drop trailing -YYYYMMDD date stamp
+  if( slash >= 0 ) m = m.slice( slash + 1 )    // drop "provider/" prefix
+  m = m.replace( /\[[^\]]*\]$/, '')             // drop a trailing qualifier, e.g. "[1m]"
+  return m.replace( /[-@]\d{6,8}$/, '')         // drop trailing -YYYYMMDD date stamp
 }
+/** USD per 1M tokens for one model. */
+export interface ModelPrice { input: number; output: number }
+
+/**
+ * Host-supplied prices, keyed by model id. Matching is exact first, then
+ * normalized (provider prefix, date stamp and context qualifier stripped), so
+ * `claude-sonnet-5` matches `claude-sonnet-5-20260114`.
+ *
+ * Prices belong to the host: they change on a vendor's schedule, differ per
+ * account, and are ~0 for a self-hosted model. The engine ships none.
+ */
+export type PriceTable = Record<string, ModelPrice>
+
+/** Models already warned about as unpriced — one line each, not one per call. */
+const _unpricedWarned = new Set<string>()
 
-// Pre-index the pricing table by normalized model name for O(1), date-insensitive
-// lookup. Built once at module load.
-const PRICING_BY_NORM: Record<string, { input: number; output: number }> = ( () => {
-  const out: Record<string, { input: number; output: number }> = {}
-  for( const [ key, price ] of Object.entries( MODEL_PRICING ) ){
-    if( key === '__default__') continue
-    out[ normalizeModelKey( key ) ] = price
+/**
+ * Resolve the price for a model id from the host's table.
+ *
+ * The engine ships no prices at all. A table baked into a release is wrong the
+ * week a vendor changes a rate, differs per account, and is meaningless for a
+ * self-hosted model — and a *partial* table is worse than none, because some
+ * models then report plausible-but-stale numbers while others honestly report
+ * nothing. Prices live with the host, next to the routing policy they inform.
+ *
+ * `null` does NOT mean free — it means *unknown*, and the caller reports zero
+ * cost with `priced: false` so the gap stays visible rather than confidently
+ * wrong. (The removed built-in default priced every unrecognised model at
+ * Sonnet's rate, overstating a budget model's output by ~54×.)
+ */
+export function resolvePricing( model: string, hostPrices?: PriceTable ): ModelPrice | null {
+  if( !hostPrices ) return null
+
+  const exact = hostPrices[ model ]
+  if( exact ) return exact
+
+  // A host table keyed by bare ids still matches a dated / provider-prefixed
+  // model id, and vice versa.
+  const norm = normalizeModelKey( model )
+  if( hostPrices[ norm ] ) return hostPrices[ norm ]
+
+  for( const [ key, price ] of Object.entries( hostPrices ) ){
+    if( normalizeModelKey( key ) === norm ) return price
   }
-  return out
-} )()
-
-/** Resolve the pricing row for any model id (exact, normalized, then default). */
-export function resolvePricing( model: string ): { input: number; output: number } {
-  return PRICING_BY_NORM[ normalizeModelKey( model ) ]
-      ?? MODEL_PRICING[ model ]
-      ?? MODEL_PRICING['__default__']!
+
+  return null
 }
 
 export interface TokenUsage {
   /** Model identifier (e.g., 'openai/gpt-4o') */
   model: string
+  /**
+   * The provider that actually served this call.
+   *
+   * Not derivable from `model`: routing is what makes the same model id
+   * reachable from several places — `deepseek-v3` direct, through a gateway, or
+   * self-hosted — at prices that differ by orders of magnitude. Without this a
+   * host billing across a multi-vendor routing table can attribute spend to a
+   * model but never to the vendor it actually paid.
+   *
+   * Optional because a caller recording usage directly (outside the LLM
+   * director) may not know it; absent means unattributed, not "the default".
+   */
+  provider?: string
   /** Input/prompt tokens consumed */
   promptTokens: number
   /** Output/completion tokens consumed */
@@ -132,16 +171,36 @@ export interface TokenUsage {
   cacheReadTokens?: number
   /** Anthropic prompt-cache write tokens (billed at 1.25× input). Optional. */
   cacheWriteTokens?: number
-  /** Estimated cost in USD */
+  /** Estimated cost in USD. Zero when `priced` is false — unknown, not free. */
   estimatedCostUsd: number
+  /**
+   * Whether a price was found for this model. False ⇒ `estimatedCostUsd` is 0
+   * because nothing priced it, NOT because the call was free. A consumer
+   * summing costs should surface unpriced calls rather than fold them in as
+   * zero.
+   */
+  priced: boolean
+
+  /**
+   * How much this call demanded, 0..1 — the cognitive measure the router saw.
+   *
+   * Recorded so routing can be ANSWERED rather than argued. Every call computes
+   * this, routes on it, and until now threw it away — which left questions like
+   * "is deliberation being rated by the tick's mood rather than the stakes of
+   * its own choice?" with no dataset at all.
+   *
+   * Absent means UNMEASURED, never zero. It must stay nullable all the way to
+   * storage: a call that never reported demand and a call that reported 0.0 are
+   * different facts, and collapsing them would put a floor of invented
+   * confidence under exactly the analysis this exists to enable.
+   */
+  demand?: number
 
   // ── 5-axis cost attribution ──────────────────────────────
-  /** Top-level cost bucket: 'executive' | 'summarizer' | 'embedding' | 'identity-guard' | … */
-  category: string
-  /** Actor/subsystem doing the work: 'master' | 'facet' | 'memory' | 'guard' | … */
-  attribute: string
-  /** Cognitive function: 'decision' | 'ideation' | 'conversation' | 'planning' | 'deliberation' | 'outreach' | 'consolidation' | 'recall' | 'index' | 'identity-coherence' | … */
-  function: string
+  category:  LLMCallCategory
+  attribute: LLMCallAttribute
+  process:  LLMCallProcess
+  function:  LLMCallFunction
   /** Optional specific id or namespace: facet id, entity id, model name. */
   scope?: string
   /** Human-readable label — auto-composed from the axes when the caller omits it. */
@@ -157,15 +216,29 @@ export interface TokenUsage {
 }
 
 /** What callers pass to {@link TokenTracker.recordUsage} — cost and label are derived. */
-export type RecordUsageInput = Omit<TokenUsage, 'estimatedCostUsd' | 'label'> & { label?: string }
+export type RecordUsageInput = Omit<TokenUsage, 'estimatedCostUsd' | 'label' | 'priced'> & { label?: string }
 
-/** Compose a stable, readable label from the attribution axes. */
-function composeLabel( m: { category: string; attribute: string; function: string; scope?: string } ): string {
-  const base = `${m.category}/${m.attribute}/${m.function}`
+/**
+ * Compose a stable, readable label from the attribution axes.
+ *
+ * `function` carries '-' when the call has no specific one (the master's own
+ * decision/ideation passes), so it is dropped rather than rendered — a label of
+ * `executive/master/-` names nothing. Process always shows: it is what
+ * distinguishes the propose pass from the decision it feeds.
+ */
+function composeLabel( m: { category: LLMCallCategory; attribute: LLMCallAttribute; process: LLMCallProcess; function: LLMCallFunction; scope?: string } ): string {
+  const base = [ m.category, m.attribute, m.process, m.function === '-' ? '' : m.function ]
+    .filter( Boolean ).join('/')
   return m.scope ? `${base}#${m.scope}` : base
 }
 
 export interface TokenTrackerConfig {
+  /**
+   * Host-supplied model prices (USD per 1M tokens), merged from the per-provider
+   * `prices` maps in `WillLLMConfig.providers`. These win over the built-in
+   * fallback table. Omitted ⇒ fallback only.
+   */
+  prices?: PriceTable
   /** Whether to emit cost events */
   emitCostEvents?: boolean
   /** Cost threshold for warning events */
@@ -186,6 +259,7 @@ export class TokenTracker implements SimulationEngine {
   
   private _emitCostEvents: boolean
   private _costWarningThreshold: number
+  private _prices: PriceTable | undefined
 
   // All recorded usage for the simulation run
   private _usageLog: TokenUsage[] = []
@@ -200,6 +274,17 @@ export class TokenTracker implements SimulationEngine {
   private _categoryTokens = new Map<string, { prompt: number; completion: number }>()
   private _functionCosts  = new Map<string, number>()
   private _functionTokens = new Map<string, { prompt: number; completion: number }>()
+  // Split out of the function axis: `decision` vs `ideation` is which PROCESS ran,
+  // not which function it served. Without its own bucket the deliberate path's
+  // propose pass became invisible in cost reporting — every master call landing in
+  // the '-' function bucket regardless of whether it deliberated.
+  private _processCosts   = new Map<string, number>()
+  private _processTokens  = new Map<string, { prompt: number; completion: number }>()
+  // Per-provider spend. The axis a host actually reconciles against invoices —
+  // "which vendor did we pay?" is not answerable from the model id once routing
+  // can reach one model through several of them.
+  private _providerCosts  = new Map<string, number>()
+  private _providerTokens = new Map<string, { prompt: number; completion: number }>()
 
   // Per-tick costs (for spike detection)
   private _tickCosts: number[] = []
@@ -219,6 +304,7 @@ export class TokenTracker implements SimulationEngine {
   constructor( config: TokenTrackerConfig = {} ){
     this._emitCostEvents        = config.emitCostEvents        ?? true
     this._costWarningThreshold  = config.costWarningThresholdUsd ?? 0.05
+    this._prices                = config.prices
     this._ledgerPath = ( config.writeLedger && config.willId )
       ? `./data/wills/${config.willId}/debug/token-report.jsonl`
       : null
@@ -231,18 +317,31 @@ export class TokenTracker implements SimulationEngine {
    * Called by LLMDirector.call after each completion (src/llm/index.ts).
    */
   recordUsage( usage: RecordUsageInput ): void {
-    const pricing    = resolvePricing( usage.model )
+    const pricing    = resolvePricing( usage.model, this._prices )
     const cacheRead  = usage.cacheReadTokens  ?? 0
     const cacheWrite = usage.cacheWriteTokens ?? 0
-    const costUsd =
-      ( usage.promptTokens     / 1_000_000 ) * pricing.input  +
-      ( usage.completionTokens / 1_000_000 ) * pricing.output +
-      ( cacheRead              / 1_000_000 ) * pricing.input * CACHE_READ_MULT  +
-      ( cacheWrite             / 1_000_000 ) * pricing.input * CACHE_WRITE_MULT
+
+    // No price ⇒ cost 0 and `priced: false`. Warn once per model id so an
+    // unconfigured provider is visible without flooding the log.
+    if( !pricing && !_unpricedWarned.has( usage.model ) ){
+      _unpricedWarned.add( usage.model )
+      logger.warn(
+        `[tokens] no price for "${usage.model}" — reporting cost 0 for it. ` +
+        `Supply one via llm.providers.<provider>.prices to get cost telemetry.`
+      )
+    }
+
+    const costUsd = pricing
+      ? ( usage.promptTokens     / 1_000_000 ) * pricing.input  +
+        ( usage.completionTokens / 1_000_000 ) * pricing.output +
+        ( cacheRead              / 1_000_000 ) * pricing.input * CACHE_READ_MULT  +
+        ( cacheWrite             / 1_000_000 ) * pricing.input * CACHE_WRITE_MULT
+      : 0
 
     const full: TokenUsage = {
       ...usage,
       label:            usage.label ?? composeLabel( usage ),
+      priced:           pricing !== null,
       estimatedCostUsd: Math.round( costUsd * 1_000_000 ) / 1_000_000, // round to micro-dollars
     }
 
@@ -256,6 +355,10 @@ export class TokenTracker implements SimulationEngine {
     // Per-axis breakdowns — the repartition surface (category × function).
     this._accumulate( this._categoryCosts, this._categoryTokens, full.category, full )
     this._accumulate( this._functionCosts, this._functionTokens, full.function, full )
+    this._accumulate( this._processCosts,  this._processTokens,  full.process,  full )
+    // Unattributed rather than guessed: a caller that did not say which
+    // provider served the call must not be silently folded into the default.
+    this._accumulate( this._providerCosts, this._providerTokens, full.provider ?? 'unattributed', full )
 
     // Complete attributed ledger record (every call, all axes + cost): notify
     // record listeners (the stem forwards them onto the transport) and mirror to
@@ -280,8 +383,10 @@ export class TokenTracker implements SimulationEngine {
       tick:          full.tick,
       ts:            new Date( wallClock() ).toISOString(), // determinism-ok: ledger timestamp is telemetry, never replay state
       model:         full.model,
+      provider:      full.provider,
       category:      full.category,
       attribute:     full.attribute,
+      process:       full.process,
       function:      full.function,
       scope:         full.scope,
       label:         full.label,
@@ -291,6 +396,13 @@ export class TokenTracker implements SimulationEngine {
       cacheWriteTok: full.cacheWriteTokens ?? 0,
       estPromptTok:  full.estPromptTokens,
       costUsd:       full.estimatedCostUsd,
+      // Whether costUsd came from a real price. False ⇒ 0 because nothing
+      // priced this model, NOT because the call was free — a consumer summing
+      // spend must not fold unpriced calls in as zero.
+      priced:        full.priced,
+      // Undefined stays undefined — see TokenUsage.demand. A consumer that
+      // coerces this to 0 has silently invented a measurement.
+      demand:        full.demand,
       latencyMs:     full.latencyMs,
     }
 
@@ -347,31 +459,34 @@ export class TokenTracker implements SimulationEngine {
     if( this._tickCosts.length > this._maxTickCostSamples )
       this._tickCosts.shift()
 
-    // Metrics
+    // Metrics — TOKENS ONLY (W8c).
+    //
+    // Token counts are a physical, deterministic fact of a call and belong in
+    // state. Dollars are the host's accounting over that fact: prices differ per
+    // account, change on a vendor's schedule, and are ~0 self-hosted. Nothing in
+    // cognition ever read them (the sole consumer was a console runner), yet
+    // while they sat in state a host editing its price table changed state bytes
+    // and broke replay-equivalence over a number that influenced nothing.
+    //
+    // Cost still reaches the host every call on the ledger path
+    // (`onRecord` → the stem's transport bridge), which is where it was already
+    // being consumed. See `totalCostUsd` / `costBreakdown()` for in-process reads.
     commands.metrics!.push(
       [ 'llm.prompt_tokens_total',      this._totalPromptTokens ],
       [ 'llm.completion_tokens_total',  this._totalCompletionTokens ],
-      [ 'llm.cost_total_usd',           this._totalCost ],
-      [ 'llm.cost_this_tick_usd',       tickCost ],
-      [ 'llm.cost_avg_per_tick_usd',    this._averageTickCost() ],
       [ 'llm.total_calls',              this._usageLog.length ],
     )
 
-    // Per-axis cost + token breakdown — the transparency surface for
-    // "how much goes into conversation vs executive vs embedding" (by category)
-    // and "decision vs ideation vs conversation vs planning…" (by function).
-    for( const [ cat, cost ] of this._categoryCosts ){
-      commands.metrics!.push([ `llm.cost.${cat}`, cost ])
-    }
+    // Per-axis TOKEN breakdown — the transparency surface for "how much goes
+    // into conversation vs executive vs embedding". The matching cost
+    // breakdown is host-side now (W8c); `costBreakdown()` still exposes it
+    // in-process for anyone holding the tracker.
     for( const [ cat, tok ] of this._categoryTokens ){
       commands.metrics!.push(
         [ `llm.prompt_tokens.${cat}`,     tok.prompt ],
         [ `llm.completion_tokens.${cat}`, tok.completion ],
       )
     }
-    for( const [ fn, cost ] of this._functionCosts ){
-      commands.metrics!.push([ `llm.cost.fn.${fn}`, cost ])
-    }
 
     // Cost warning event
     if( tickCost > this._costWarningThreshold 
@@ -386,6 +501,7 @@ export class TokenTracker implements SimulationEngine {
           totalCost: this._totalCost,
           categoryBreakdown: Object.fromEntries( this._categoryCosts ),
           functionBreakdown: Object.fromEntries( this._functionCosts ),
+          processBreakdown:  Object.fromEntries( this._processCosts ),
         },
       })
     }
@@ -427,6 +543,34 @@ export class TokenTracker implements SimulationEngine {
     return this._functionTokens
   }
 
+  /** Cost broken down by process ('decision' | 'ideation' | 'cog'). */
+  get processBreakdown(): ReadonlyMap<string, number> {
+    return this._processCosts
+  }
+
+  /** Token counts (prompt + completion) broken down by process. */
+  get processTokenBreakdown(): ReadonlyMap<string, { prompt: number; completion: number }> {
+    return this._processTokens
+  }
+
+  /**
+   * Cost broken down by provider ('anthropic' | 'glm' | 'moonshot' | …), plus
+   * an `unattributed` bucket for usage recorded without one.
+   *
+   * This is the axis a host reconciles against vendor invoices. Calls whose
+   * model went unpriced contribute 0 here, so compare against
+   * `getUsageLog()`'s `priced` flag before treating a small number as a small
+   * bill.
+   */
+  get providerBreakdown(): ReadonlyMap<string, number> {
+    return this._providerCosts
+  }
+
+  /** Token counts (prompt + completion) broken down by provider. */
+  get providerTokenBreakdown(): ReadonlyMap<string, { prompt: number; completion: number }> {
+    return this._providerTokens
+  }
+
   /** Cost per call average */
   get averageCostPerCall(): number {
     if( this._usageLog.length === 0 ) return 0
@@ -461,6 +605,10 @@ export class TokenTracker implements SimulationEngine {
     this._categoryTokens.clear()
     this._functionCosts.clear()
     this._functionTokens.clear()
+    this._processCosts.clear()
+    this._processTokens.clear()
+    this._providerCosts.clear()
+    this._providerTokens.clear()
     this._tickCosts = []
   }
 

package/src/core/orchestrator.ts

@@ -62,6 +62,13 @@ export interface SimulationEngine {
 }
 
 
+/**
+ * Fraction of one tick interval a single non-async engine may consume before the
+ * orchestrator says so. Half a tick is generous for work that is meant to be
+ * in-memory, and low enough to fire long before tick-denominated deadlines drift.
+ */
+const SLOW_ENGINE_FRACTION = 0.5
+
 // ── Middleware ───────────────────────────────────────────────
 
 export type TickMiddleware = (
@@ -384,6 +391,35 @@ export class DefaultOrchestrator implements Orchestrator {
    * calls _executeTick() which handles pause/stop checks internally.
    * The orchestrator is the sole driver of ticks.
    */
+  /**
+   * A plain SimulationEngine's `react()` is implicitly "finish inside the tick" —
+   * only an AsyncEngine is allowed to span ticks, and it does so by LAUNCHING work
+   * and landing it later (see async.engine.ts: "react() never awaits LLM calls").
+   * Nothing enforces that on everyone else, and the failure is silent and severe:
+   * every agency deadline is denominated in TICKS, so an engine that awaits network
+   * I/O does not merely run slowly, it rescales time for the whole mind.
+   *
+   * Measured: one rate-limited embedding call awaited inside EpisodicConsolidator
+   * made two consecutive ticks take 64.9s and 63.5s. `AWAIT_TIMEOUT` — 15 ticks,
+   * normally ~15s — silently became 15 minutes, so a communicate intent sat
+   * 'awaiting' forever and the serial selector never chose anything again. 45
+   * executive decisions produced one intent and zero delivered messages, with no
+   * error anywhere. This turns that into a line in the log the first time it happens.
+   */
+  private _warnIfSlow( engine: SimulationEngine, elapsedMs: number ): void {
+    // AsyncEngines are exempt by design — spanning ticks is their contract.
+    if( ( engine as { hasPendingWork?: unknown } ).hasPendingWork !== undefined ) return
+
+    const budget = ( this._config.tickIntervalMs ?? 1000 ) * SLOW_ENGINE_FRACTION
+    if( elapsedMs <= budget ) return
+
+    logger.warn(
+      `[Orchestrator] Engine "${ engine.name }" held the tick for ${ Math.round( elapsedMs ) }ms ` +
+      `at tick ${ this._currentTick } (budget ${ Math.round( budget ) }ms). A non-async engine must not ` +
+      `await network I/O — tick-denominated deadlines elsewhere are being stretched by this.`
+    )
+  }
+
   private _runLoop( context: SimulationContext ): void {
     if( this._tickTimer ) return
 
@@ -478,6 +514,7 @@ export class DefaultOrchestrator implements Orchestrator {
     const allResults: EngineResult[] = []
 
     const runEngine = async ( engine: SimulationEngine ): Promise<void> => {
+      const startedAt = wallClock()
       try {
         const result = await engine.react?.( this._clock.delta, this._currentTick, snapshot, engineContext )
         if( result ) allResults.push( result )
@@ -494,6 +531,7 @@ export class DefaultOrchestrator implements Orchestrator {
           )
         }
       }
+      finally { this._warnIfSlow( engine, wallClock() - startedAt ) }
     }
 
     for( const engine of this._enginesTick() )