sigrank 0.15.5 → 0.16.0

package/tools.mjs

@@ -8,7 +8,8 @@
  * narration card in ./narrate.mjs. Token-only, no transcript content.
  */
 
-import { cascade, parsePillars } from './cascade.mjs'
+import { cascade, parsePillars, detectMode, qualityScore, MODE_EXPECTED_YIELD } from './cascade.mjs'
+import { computeBadges } from './badges.mjs'
 import { narrate } from './narrate.mjs'
 import { tokenpull as pullLocal, tokenpullCodex as pullCodex, tokenpullAny } from './tokenpull.mjs'
 import { ALL_PLATFORMS } from './adapters.mjs'
@@ -325,6 +326,55 @@ const SIMULATE_OUTPUT = {
   },
 }
 
+const DIAGNOSE_OUTPUT = {
+  type: 'object',
+  properties: {
+    pillars: { type: 'object', description: 'The 4 raw token pillars' },
+    cascade: CASCADE_OUTPUT,
+    diagnosis: {
+      type: 'array',
+      description: 'Ranked list of efficiency leaks found, worst first',
+      items: {
+        type: 'object',
+        properties: {
+          metric: { type: 'string', description: 'Which metric is underperforming' },
+          severity: { type: 'string', enum: ['critical', 'warning', 'info'], description: 'How bad the leak is' },
+          finding: { type: 'string', description: 'What the analysis found' },
+          recommendation: { type: 'string', description: 'What to do about it' },
+          estimated_yield_impact: { type: 'string', description: 'Estimated Υ improvement if fixed' },
+        },
+      },
+    },
+    summary: { type: 'string', description: 'One-line summary of the operator\'s cascade health' },
+  },
+}
+
+const SUGGEST_OUTPUT = {
+  type: 'object',
+  properties: {
+    suggestions: {
+      type: 'array',
+      description: 'Ranked recommendations, highest Υ impact first',
+      items: {
+        type: 'object',
+        properties: {
+          rank: { type: 'number', description: '1-based rank by Υ impact' },
+          action: { type: 'string', description: 'What to change' },
+          pillar: { type: 'string', description: 'Which pillar to adjust' },
+          delta: { type: 'string', description: 'How much to change it' },
+          simulated_yield: { type: 'number', description: 'Projected Υ after the change' },
+          yield_delta: { type: 'number', description: 'Υ change vs current' },
+          class_after: { type: 'string', description: 'Projected class after the change' },
+          rationale: { type: 'string', description: 'Why this helps' },
+        },
+      },
+    },
+    current_yield: { type: 'number', description: 'Current Υ before any changes' },
+    current_class: { type: 'string', description: 'Current class tier' },
+    best_single_change: { type: 'string', description: 'The single highest-impact change' },
+  },
+}
+
 export const TOOLS = [
   {
     name: 'rank_paste',
@@ -563,6 +613,83 @@ export const TOOLS = [
     },
     outputSchema: SIMULATE_OUTPUT,
   },
+  {
+    name: 'diagnose_cascade',
+    description:
+      "Analyzes your token cascade and diagnoses where you're leaking efficiency. Takes your 4 pillars (input/output/cacheCreate/cacheRead) and produces a ranked list of efficiency leaks with severity (critical/warning/info), findings, and recommendations. Checks: cache leverage (are you rereading what you wrote?), velocity (are you generating enough output per input?), SNR (is your signal drowning in noise?), cache creation ratio (are you over-committing?), input bloat (is fresh input too high?), and 10xDEV (is the full cascade compounding?). Each finding includes an estimated Υ impact. Pure local math — no network, no submission. Use this BEFORE simulate_change to understand what's wrong, then use simulate_change to test fixes. Accepts the same input formats as rank_paste (JSON or 4 whitespace numbers).",
+    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+        },
+      },
+      required: ['text'],
+    },
+    outputSchema: DIAGNOSE_OUTPUT,
+  },
+  {
+    name: 'suggest_improvements',
+    description:
+      "Generates ranked, simulated improvement suggestions for your token cascade. Takes your 4 pillars, tests multiple improvement strategies (increase cache reads, reduce fresh input, increase output, optimize cache creation), simulates each with the canonical cascade engine, and returns them ranked by Υ yield impact. Each suggestion includes: the action, which pillar to change, how much to change it, the projected Υ after the change, the yield delta, the projected class tier, and a rationale. Also returns the single highest-impact change (best_single_change). Pure local math — no network, no submission. Use this after diagnose_cascade to get actionable next steps, then use simulate_change to fine-tune before committing. Accepts the same input formats as rank_paste.",
+    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+        },
+      },
+      required: ['text'],
+    },
+    outputSchema: SUGGEST_OUTPUT,
+  },
+  {
+    name: 'self_improve',
+    description:
+      "Runs the full self-improvement cycle in one call: (1) gets your current token pillars — either from the provided text or by running tokenpull on your local logs, (2) diagnoses where you're leaking efficiency (diagnose_cascade), (3) generates ranked improvement suggestions (suggest_improvements), (4) simulates the top suggestion (simulate_change), and (5) returns the complete cycle: diagnosis + suggestions + the simulated impact of the best change. This is the 'one-click optimize' tool — call it at the end of a session to see what to improve next time. If you provide pillars in `text`, it skips the tokenpull step. If you omit `text`, it runs tokenpull first (requires local ccusage logs). Pure local math — no network, no submission. The `scope` parameter adds mode detection (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) and scoped analysis: 'daily' (default — current behavior + mode), 'weekly' (compound into weekly snapshots + report artifact), 'trend' (30d/90d trajectory analysis).",
+    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Optional: token pillars — ccusage JSON or "input output cacheCreate cacheRead". If omitted, runs tokenpull to get current pillars from local logs.',
+        },
+        window: {
+          type: 'string',
+          enum: ['7d', '30d', '90d', 'all'],
+          description: 'Which time window to pull when running tokenpull (default: 30d). Ignored if `text` is provided.',
+        },
+        scope: {
+          type: 'string',
+          enum: ['daily', 'weekly', 'trend'],
+          description: 'Analysis scope: "daily" (default — current behavior + mode detection), "weekly" (compound daily rows into weekly snapshots + report artifact with badges), "trend" (30d/90d trajectory + phase patterns). Daily modes never leave the machine — only weekly distribution goes in submitted reports.',
+        },
+      },
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        pillars: { type: 'object', description: 'The 4 raw token pillars used' },
+        current_cascade: CASCADE_OUTPUT,
+        diagnosis: { type: 'array', description: 'Efficiency leaks found (from diagnose_cascade)' },
+        suggestions: { type: 'array', description: 'Ranked improvements (from suggest_improvements)' },
+        best_simulation: { type: 'object', description: 'Simulated result of the top suggestion' },
+        cycle_summary: { type: 'string', description: 'One-line summary of the full cycle' },
+        // Scope-specific fields
+        mode: { type: 'object', description: 'Detected mode { mode, confidence } — present when scope is daily/weekly/trend' },
+        quality_score: { type: 'number', description: 'Yield relative to mode expectation (daily scope)' },
+        assessment: { type: 'string', description: 'One-line assessment for daily scope' },
+        advice: { type: 'string', description: 'Advice for next session (daily scope)' },
+        report: { type: 'object', description: 'Weekly report artifact (weekly scope)' },
+        trend: { type: 'object', description: 'Trend analysis (trend scope)' },
+      },
+    },
+  },
 ]
 
 // tokenpull window key → the board's window_type enum.
@@ -720,7 +847,8 @@ export async function callTool(name, args, opts = {}) {
           msgs += w.messages || 0
         }
         if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0) continue // skip empty window
-        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now, dryRun: !!args?.dry_run })
+        const report = _computeReportBlock(sum)
+        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now, dryRun: !!args?.dry_run, report })
         out.push({ window: wk, pillars: sum, ...r })
       }
       return { platform: 'multi', codename: id.codename, operator_id: id.operator_id, sources: detected.map((d) => d.platform), windows: out }
@@ -730,12 +858,16 @@ export async function callTool(name, args, opts = {}) {
     const targets = args?.window ? pulled.windows.filter((w) => w.window === args.window) : pulled.windows
     const out = []
     for (const w of targets) {
+      // Compute the cascade report block (mode + badges + health) for this window.
+      // Pure math, computed locally, submitted alongside the 4 token pillars.
+      const report = _computeReportBlock(w.pillars)
       const r = await submitSignedWindow(w.window, w.pillars, w.messages, id, {
         apiBase,
         fetchImpl: doFetch,
         platform: pulled.platform,
         now: opts.now,
         dryRun: !!args?.dry_run,
+        report,
       })
       out.push({ window: w.window, pillars: w.pillars, ...r })
     }
@@ -1097,5 +1229,742 @@ export async function callTool(name, args, opts = {}) {
     }
   }
 
+  if (name === 'diagnose_cascade') {
+    if (!args?.text) throw new Error('diagnose_cascade requires a non-empty `text` argument (token pillars).')
+    if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+      return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+    }
+
+    const p = parsePillars(args.text)
+    const result = withParseWarnings(p, cascade(p))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p
+    const diagnosis = []
+
+    // Cache leverage check — the #1 cascade efficiency signal
+    const leverage = result.leverage
+    if (leverage !== null) {
+      if (leverage < 10) {
+        diagnosis.push({
+          metric: 'cache_leverage',
+          severity: 'critical',
+          finding: `Cache leverage is ${leverage}× — you're reading only ${leverage}× your fresh input from cache. TRANSMITTER-class operators hit 200×+.`,
+          recommendation: 'Increase context reuse: load prior session context, use longer conversation threads, reference earlier outputs.',
+          estimated_yield_impact: `+${Math.round((1 - leverage / 50) * 100)}% Υ potential`,
+        })
+      } else if (leverage < 50) {
+        diagnosis.push({
+          metric: 'cache_leverage',
+          severity: 'warning',
+          finding: `Cache leverage is ${leverage}× — decent but below the ARCH+ threshold (~100×+).`,
+          recommendation: 'Push cache reads higher by reusing prior context more aggressively.',
+          estimated_yield_impact: `+${Math.round((1 - leverage / 100) * 50)}% Υ potential`,
+        })
+      }
+    }
+
+    // Velocity check — output per input
+    const velocity = result.velocity
+    if (velocity !== null) {
+      if (velocity < 0.5) {
+        diagnosis.push({
+          metric: 'velocity',
+          severity: 'critical',
+          finding: `Velocity is ${velocity} — generating only ${velocity}× your input as output. You're reading more than you produce.`,
+          recommendation: 'Increase output: ask the agent to generate more code/text per turn, reduce over-reading.',
+          estimated_yield_impact: `+${Math.round((0.5 - velocity) * 100)}% Υ per 0.1 velocity gain`,
+        })
+      } else if (velocity < 1.0) {
+        diagnosis.push({
+          metric: 'velocity',
+          severity: 'warning',
+          finding: `Velocity is ${velocity} — below 1.0 (output < input). Healthy operators hit 1.5×+.`,
+          recommendation: 'Generate more output per input token — larger edits, more complete responses.',
+          estimated_yield_impact: `+${Math.round((1 - velocity) * 30)}% Υ potential`,
+        })
+      }
+    }
+
+    // SNR check — signal-to-noise
+    const snr = result.snr
+    if (snr !== null && snr < 0.3) {
+      diagnosis.push({
+        metric: 'snr',
+        severity: 'warning',
+        finding: `SNR is ${snr} — less than 30% of your token flow is output. Input is dominating.`,
+        recommendation: 'Reduce fresh input (reuse context) or increase output generation.',
+        estimated_yield_impact: 'Indirect — improves both velocity and leverage',
+      })
+    }
+
+    // Cache creation ratio — are you over-committing?
+    if (cw > 0 && o > 0) {
+      const commitRatio = cw / o
+      if (commitRatio > 20) {
+        diagnosis.push({
+          metric: 'cache_creation',
+          severity: 'info',
+          finding: `Cache creation is ${commitRatio.toFixed(1)}× your output — high commitment. This is fine if you're rereading it (check leverage), but wasteful if not.`,
+          recommendation: "Ensure you're rereading committed context. If leverage is low, you're writing cache you never read.",
+          estimated_yield_impact: 'Cost reduction, not Υ directly',
+        })
+      }
+    }
+
+    // Input bloat — is fresh input too high relative to total?
+    const total = i + o + cw + cr
+    if (total > 0) {
+      const inputPct = (i / total) * 100
+      if (inputPct > 10) {
+        diagnosis.push({
+          metric: 'input_bloat',
+          severity: 'warning',
+          finding: `Fresh input is ${inputPct.toFixed(1)}% of your total token flow — high. Efficient operators keep input under 1% by leaning on cache.`,
+          recommendation: 'Reduce fresh input by reusing prior context instead of re-pasting it.',
+          estimated_yield_impact: `+${Math.round((inputPct - 1) * 5)}% Υ potential`,
+        })
+      }
+    }
+
+    // 10xDEV check — is the full cascade compounding?
+    if (result.dev10x === null && cw === 0) {
+      diagnosis.push({
+        metric: '10xdev',
+        severity: 'critical',
+        finding: "No cache creation — the cascade cannot compound. You're operating in a non-compounding mode (like ChatGPT without prompt caching).",
+        recommendation: 'Switch to a platform with prompt caching (Claude Code) or enable caching if available.',
+        estimated_yield_impact: 'Enables the full cascade — potentially 10×+ Υ',
+      })
+    } else if (result.dev10x !== null && result.dev10x < 1.0) {
+      diagnosis.push({
+        metric: '10xdev',
+        severity: 'info',
+        finding: `10xDEV is ${result.dev10x} — below 1.0 (BASE threshold). The cascade is compounding but not strongly.`,
+        recommendation: 'Improve both leverage AND velocity — 10xDEV = log10(transmission × commitment × reuse).',
+        estimated_yield_impact: 'Class tier improvement',
+      })
+    }
+
+    // Sort by severity (critical > warning > info)
+    const sevOrder = { critical: 0, warning: 1, info: 2 }
+    diagnosis.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity])
+
+    const healthScore = diagnosis.filter((d) => d.severity === 'critical').length
+    const summary = healthScore === 0
+      ? `Cascade is healthy — Υ ${result.yield}, class ${result.class}. ${diagnosis.length} minor optimizations available.`
+      : `Cascade has ${healthScore} critical leak${healthScore > 1 ? 's' : ''} — Υ ${result.yield}, class ${result.class}. Fix the critical items first.`
+
+    return {
+      pillars: p,
+      cascade: {
+        yield_: result.yield,
+        snr: result.snr,
+        leverage: result.leverage,
+        velocity: result.velocity,
+        tenx_dev: result.dev10x,
+        class: result.class,
+        warnings: result.warnings,
+      },
+      diagnosis,
+      summary,
+    }
+  }
+
+  if (name === 'suggest_improvements') {
+    if (!args?.text) throw new Error('suggest_improvements requires a non-empty `text` argument (token pillars).')
+    if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+      return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+    }
+
+    const p = parsePillars(args.text)
+    const current = withParseWarnings(p, cascade(p))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p
+
+    // Generate candidate improvements, simulate each, rank by Υ impact
+    const candidates = []
+
+    // Strategy 1: Increase cache reads (the #1 lever)
+    const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : []
+    for (const mult of crBoosts) {
+      const sim = cascade({ ...p, cacheRead: Math.round(cr * mult) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Increase cache reads by ${Math.round((mult - 1) * 100)}%`,
+          pillar: 'cacheRead',
+          delta: `+${Math.round(cr * (mult - 1)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Cache reads are the strongest Υ multiplier. More reuse = higher leverage = higher yield.',
+        })
+      }
+    }
+    // For zero-cache operators, suggest enabling caching with a starter amount
+    if (cr === 0 && cw === 0) {
+      const starterAmounts = [Math.round(i * 10), Math.round(i * 50), Math.round(i * 100)]
+      for (const amt of starterAmounts) {
+        const sim = cascade({ ...p, cacheCreate: Math.round(amt * 0.5), cacheRead: amt })
+        if (sim.yield !== null && sim.yield > 0) {
+          candidates.push({
+            action: `Enable caching with ${amt.toLocaleString()} cache reads`,
+            pillar: 'cacheRead',
+            delta: `+${amt.toLocaleString()}`,
+            simulated_yield: sim.yield,
+            yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+            class_after: sim.class,
+            rationale: 'You have no cache — enabling it unlocks the cascade. Start by reusing prior context.',
+          })
+        }
+      }
+    }
+
+    // Strategy 2: Reduce fresh input (Υ = Cr·O/I² — input is squared in the denominator)
+    const inputReductions = [0.9, 0.75, 0.5]
+    for (const mult of inputReductions) {
+      const newInput = Math.round(i * mult)
+      if (newInput < 1) continue
+      const sim = cascade({ ...p, input: newInput })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Reduce fresh input by ${Math.round((1 - mult) * 100)}%`,
+          pillar: 'input',
+          delta: `-${Math.round(i * (1 - mult)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Input is squared in the Υ denominator (Υ = Cr·O/I²). Reducing input has a quadratic payoff.',
+        })
+      }
+    }
+
+    // Strategy 3: Increase output
+    const outputBoosts = [1.25, 1.5, 2]
+    for (const mult of outputBoosts) {
+      const sim = cascade({ ...p, output: Math.round(o * mult) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Increase output by ${Math.round((mult - 1) * 100)}%`,
+          pillar: 'output',
+          delta: `+${Math.round(o * (mult - 1)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Output is a linear multiplier in Υ. More output per session = higher yield.',
+        })
+      }
+    }
+
+    // Strategy 4: Optimize cache creation (reduce if over-committing)
+    if (cw > o * 10) {
+      const sim = cascade({ ...p, cacheCreate: Math.round(o * 5) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: 'Reduce cache creation to 5× output',
+          pillar: 'cacheCreate',
+          delta: `-${Math.round(cw - o * 5).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'You\'re over-committing cache (cw >> output). Trimming to a healthy ratio reduces cost without hurting yield.',
+        })
+      }
+    }
+
+    // Sort by yield_delta descending, take top 8
+    candidates.sort((a, b) => b.yield_delta - a.yield_delta)
+    const top = candidates.slice(0, 8).map((c, idx) => ({ rank: idx + 1, ...c }))
+
+    const best = top[0]
+    return {
+      suggestions: top,
+      current_yield: current.yield,
+      current_class: current.class,
+      best_single_change: best
+        ? `${best.action} (Υ ${current.yield} → ${best.simulated_yield}, +${best.yield_delta} yield, class ${best.class_after})`
+        : 'No improvements found — your cascade is already optimized.',
+    }
+  }
+
+  if (name === 'self_improve') {
+    // The full self-improvement cycle: pull → diagnose → suggest → simulate.
+    // If text is provided, use it as pillars. If not, run tokenpull first.
+    let pillars
+    let pulledFrom = 'provided'
+
+    if (args?.text) {
+      if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+        return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+      }
+      pillars = parsePillars(args.text)
+    } else {
+      // Run tokenpull to get current pillars from local logs
+      const windowType = args?.window || '30d'
+      try {
+        const pullResult = await callTool('tokenpull', { window: windowType }, opts)
+        if (pullResult?.status === 'error' || !pullResult?.windows?.length) {
+          return {
+            status: 'error',
+            reason: 'tokenpull_failed',
+            detail: 'Could not pull pillars from local logs. Provide pillars via `text` argument instead.',
+            pull_result: pullResult,
+          }
+        }
+        // Use the first window's pillars
+        const w = pullResult.windows[0]
+        pillars = w.pillars
+        pulledFrom = `tokenpull ${w.window || windowType}`
+      } catch (e) {
+        return {
+          status: 'error',
+          reason: 'tokenpull_error',
+          detail: String(e.message || e),
+          hint: 'Provide pillars via `text` argument instead.',
+        }
+      }
+    }
+
+    const currentResult = withParseWarnings(pillars, cascade(pillars))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = pillars
+
+    // ── Step 1: Diagnose ──────────────────────────────────────────────
+    const diagnosis = []
+    const leverage = currentResult.leverage
+    if (leverage !== null && leverage < 10) {
+      diagnosis.push({
+        metric: 'cache_leverage', severity: 'critical',
+        finding: `Cache leverage is ${leverage}× — TRANSMITTER-class operators hit 200×+.`,
+        recommendation: 'Increase context reuse: load prior session context, use longer threads.',
+      })
+    } else if (leverage !== null && leverage < 50) {
+      diagnosis.push({
+        metric: 'cache_leverage', severity: 'warning',
+        finding: `Cache leverage is ${leverage}× — below ARCH+ threshold (~100×+).`,
+        recommendation: 'Push cache reads higher by reusing prior context.',
+      })
+    }
+
+    const velocity = currentResult.velocity
+    if (velocity !== null && velocity < 0.5) {
+      diagnosis.push({
+        metric: 'velocity', severity: 'critical',
+        finding: `Velocity is ${velocity} — generating only ${velocity}× input as output.`,
+        recommendation: 'Increase output per turn, reduce over-reading.',
+      })
+    } else if (velocity !== null && velocity < 1.0) {
+      diagnosis.push({
+        metric: 'velocity', severity: 'warning',
+        finding: `Velocity is ${velocity} — below 1.0. Healthy operators hit 1.5×+.`,
+        recommendation: 'Generate more output per input token.',
+      })
+    }
+
+    if (currentResult.dev10x === null && cw === 0) {
+      diagnosis.push({
+        metric: '10xdev', severity: 'critical',
+        finding: 'No cache creation — cascade cannot compound.',
+        recommendation: 'Switch to a platform with prompt caching (Claude Code).',
+      })
+    }
+
+    const total = i + o + cw + cr
+    if (total > 0 && (i / total) * 100 > 10) {
+      diagnosis.push({
+        metric: 'input_bloat', severity: 'warning',
+        finding: `Fresh input is ${((i / total) * 100).toFixed(1)}% of total flow — efficient operators keep it under 1%.`,
+        recommendation: 'Reduce fresh input by reusing prior context.',
+      })
+    }
+
+    // ── Step 2: Suggest (generate + simulate candidates) ──────────────
+    const candidates = []
+    // If cacheRead is 0, suggest absolute amounts instead of percentage boosts
+    const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : []
+    for (const mult of crBoosts) {
+      const sim = cascade({ ...pillars, cacheRead: Math.round(cr * mult) })
+      if (sim.yield !== null) candidates.push({
+        action: `Increase cache reads by ${Math.round((mult - 1) * 100)}%`,
+        pillar: 'cacheRead', delta: `+${Math.round(cr * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Cache reads are the strongest Υ multiplier.',
+      })
+    }
+    // For zero-cache operators, suggest enabling caching with a starter amount
+    if (cr === 0 && cw === 0) {
+      const starterAmounts = [Math.round(i * 10), Math.round(i * 50), Math.round(i * 100)]
+      for (const amt of starterAmounts) {
+        const sim = cascade({ ...pillars, cacheCreate: Math.round(amt * 0.5), cacheRead: amt })
+        if (sim.yield !== null && sim.yield > 0) candidates.push({
+          action: `Enable caching with ${amt.toLocaleString()} cache reads`,
+          pillar: 'cacheRead', delta: `+${amt.toLocaleString()}`,
+          simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+          class_after: sim.class, rationale: 'You have no cache — enabling it unlocks the cascade. Start by reusing prior context.',
+        })
+      }
+    }
+    for (const mult of [0.9, 0.75, 0.5]) {
+      const newInput = Math.round(i * mult)
+      if (newInput < 1) continue
+      const sim = cascade({ ...pillars, input: newInput })
+      if (sim.yield !== null) candidates.push({
+        action: `Reduce fresh input by ${Math.round((1 - mult) * 100)}%`,
+        pillar: 'input', delta: `-${Math.round(i * (1 - mult)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Input is squared in Υ denominator — quadratic payoff.',
+      })
+    }
+    for (const mult of [1.25, 1.5, 2]) {
+      const sim = cascade({ ...pillars, output: Math.round(o * mult) })
+      if (sim.yield !== null) candidates.push({
+        action: `Increase output by ${Math.round((mult - 1) * 100)}%`,
+        pillar: 'output', delta: `+${Math.round(o * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Output is a linear multiplier in Υ.',
+      })
+    }
+    candidates.sort((a, b) => b.yield_delta - a.yield_delta)
+    const suggestions = candidates.slice(0, 8).map((c, idx) => ({ rank: idx + 1, ...c }))
+
+    // ── Step 3: Simulate the top suggestion ───────────────────────────
+    const best = suggestions[0]
+    let bestSimulation = null
+    if (best) {
+      const simPillars = { ...pillars }
+      const delta = parseInt(best.delta.replace(/[+\-,]/g, ''), 10)
+      if (best.pillar === 'cacheRead') simPillars.cacheRead = cr + delta
+      else if (best.pillar === 'input') simPillars.input = Math.max(i - delta, 1)
+      else if (best.pillar === 'output') simPillars.output = o + delta
+      const simResult = cascade(simPillars)
+      bestSimulation = {
+        action: best.action,
+        current_yield: currentResult.yield,
+        simulated_yield: simResult.yield,
+        yield_delta: best.yield_delta,
+        current_class: currentResult.class,
+        simulated_class: simResult.class,
+        class_changed: currentResult.class !== simResult.class,
+      }
+    }
+
+    // ── Step 4: Cycle summary ─────────────────────────────────────────
+    const criticalCount = diagnosis.filter((d) => d.severity === 'critical').length
+    const cycleSummary = best
+      ? `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${criticalCount} critical, ${diagnosis.length - criticalCount} other findings. Best: ${best.action} → Υ ${best.simulated_yield} (+${best.yield_delta}).`
+      : `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${diagnosis.length} findings. No improvements suggested — cascade is optimized.`
+
+    // ── Step 5: Scope-specific analysis ───────────────────────────────
+    const scope = args?.scope || 'daily'
+    const modeInfo = currentResult.mode // { mode, confidence }
+    const scopeResult = {}
+
+    if (scope === 'daily') {
+      // Daily: mode + quality score + assessment + advice
+      const qs = qualityScore(currentResult.yield ?? 0, modeInfo.mode)
+      const expected = MODE_EXPECTED_YIELD[modeInfo.mode] ?? 0
+      const assessment = _dailyAssessment(modeInfo.mode, currentResult.yield, qs, expected)
+      const advice = _dailyAdvice(modeInfo.mode, currentResult.yield, qs)
+      scopeResult.mode = modeInfo
+      scopeResult.quality_score = Math.round(qs * 100) / 100
+      scopeResult.assessment = assessment
+      scopeResult.advice = advice
+    }
+
+    if (scope === 'weekly' || scope === 'trend') {
+      // Pull daily rows from ccusage to build weekly snapshots
+      const dailyRows = await _pullDailyRows(opts)
+      const weeklySnapshots = _compoundWeekly(dailyRows)
+      const modeDistribution = _modeDistribution(weeklySnapshots)
+      const modeWeightedYield = _modeWeightedYield(weeklySnapshots)
+
+      // Compute badges
+      const historyForBadges = weeklySnapshots.map(w => ({
+        date: w.weekStart,
+        mode: w.mode,
+        yield: w.yield,
+        pillars: w.pillars,
+      }))
+      const badges = computeBadges({
+        pillars,
+        cascade: currentResult,
+        history: historyForBadges,
+        isVerified: false, // set by submit_verified
+        rank: null, // server-side
+      })
+
+      if (scope === 'weekly') {
+        scopeResult.mode = modeInfo
+        // Strip dailyModes from weekly_snapshots — privacy boundary (daily modes never leave the machine)
+        const safeSnapshots = weeklySnapshots.map(({ dailyModes, ...rest }) => rest)
+        scopeResult.report = {
+          current_mode: modeInfo.mode,
+          mode_confidence: modeInfo.confidence,
+          mode_distribution: modeDistribution,
+          mode_weighted_yield: modeWeightedYield,
+          peak_yield: _peakYield(weeklySnapshots),
+          health_score: _healthScore(weeklySnapshots, modeWeightedYield),
+          weekly_snapshots: safeSnapshots,
+          badges,
+        }
+      }
+
+      if (scope === 'trend') {
+        const yield7d = _yieldForDays(weeklySnapshots, 7)
+        const yield30d = _yieldForDays(weeklySnapshots, 30)
+        const yield90d = _yieldForDays(weeklySnapshots, 90)
+        const trajectory = _trajectory(yield7d, yield30d, yield90d)
+        scopeResult.mode = modeInfo
+        scopeResult.trend = {
+          yield_7d: yield7d,
+          yield_30d: yield30d,
+          yield_90d: yield90d,
+          trajectory,
+          mode_distribution: modeDistribution,
+          phase_pattern: _phasePattern(weeklySnapshots),
+        }
+      }
+    }
+
+    return {
+      pillars,
+      current_cascade: {
+        yield_: currentResult.yield,
+        snr: currentResult.snr,
+        leverage: currentResult.leverage,
+        velocity: currentResult.velocity,
+        tenx_dev: currentResult.dev10x,
+        class: currentResult.class,
+        mode: modeInfo,
+        warnings: currentResult.warnings,
+      },
+      diagnosis,
+      suggestions,
+      best_simulation: bestSimulation,
+      cycle_summary: cycleSummary,
+      ...scopeResult,
+    }
+  }
+
   throw new Error(`Unknown tool: ${name}`)
 }
+
+// ── self_improve scope helpers ──────────────────────────────────────────────
+
+/** Pull daily rows from ccusage to build mode history. Returns array of { date, pillars, yield, mode }. */
+async function _pullDailyRows(opts = {}) {
+  try {
+    const raw = await execFileAsync('ccusage', ['claude', 'daily', '--json'], 15000)
+    const rows = JSON.parse(raw)?.daily ?? JSON.parse(raw)
+    if (!Array.isArray(rows)) return []
+    return rows.map(r => {
+      const pillars = {
+        input: r.inputTokens ?? r.input_tokens ?? 0,
+        output: r.outputTokens ?? r.output_tokens ?? 0,
+        cacheCreate: r.cacheCreationTokens ?? r.cache_create_tokens ?? 0,
+        cacheRead: r.cacheReadTokens ?? r.cache_read_tokens ?? 0,
+      }
+      const cas = cascade(pillars)
+      const mode = detectMode(pillars)
+      return {
+        date: r.date ?? r.day ?? null,
+        pillars,
+        yield: cas.yield ?? 0,
+        mode: mode.mode,
+        mode_confidence: mode.confidence,
+      }
+    }).filter(r => r.date)
+  } catch {
+    return []
+  }
+}
+
+/** Compound daily rows into weekly snapshots. Each week = 7 days, starting Monday. */
+function _compoundWeekly(dailyRows) {
+  if (!dailyRows || dailyRows.length === 0) return []
+  // Group by ISO week (week starts Monday)
+  const weeks = new Map()
+  for (const row of dailyRows) {
+    const d = new Date(row.date)
+    const day = d.getDay() || 7 // Sunday=0 → 7
+    const monday = new Date(d)
+    monday.setDate(d.getDate() - day + 1)
+    const weekKey = monday.toISOString().slice(0, 10)
+    if (!weeks.has(weekKey)) {
+      weeks.set(weekKey, { weekStart: weekKey, days: [] })
+    }
+    weeks.get(weekKey).days.push(row)
+  }
+  // Compound each week
+  return Array.from(weeks.values()).map(w => {
+    const pillars = w.days.reduce((acc, d) => ({
+      input: acc.input + d.pillars.input,
+      output: acc.output + d.pillars.output,
+      cacheCreate: acc.cacheCreate + d.pillars.cacheCreate,
+      cacheRead: acc.cacheRead + d.pillars.cacheRead,
+    }), { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 })
+    const cas = cascade(pillars)
+    const mode = detectMode(pillars)
+    return {
+      weekStart: w.weekStart,
+      pillars,
+      yield: cas.yield ?? 0,
+      mode: mode.mode,
+      mode_confidence: mode.confidence,
+      dayCount: w.days.length,
+      dailyModes: w.days.map(d => d.mode), // stays local — not in submitted report
+    }
+  }).sort((a, b) => a.weekStart.localeCompare(b.weekStart))
+}
+
+/** Compute mode distribution from weekly snapshots (weekly granularity = privacy boundary). */
+function _modeDistribution(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return {}
+  const counts = { BUILD: 0, EDIT: 0, DEBUG: 0, MAINTAIN: 0, IDLE: 0 }
+  for (const w of weeklySnapshots) {
+    counts[w.mode] = (counts[w.mode] || 0) + 1
+  }
+  const total = weeklySnapshots.length
+  const dist = {}
+  for (const [mode, count] of Object.entries(counts)) {
+    if (count > 0) dist[mode] = Math.round((count / total) * 100) / 100
+  }
+  return dist
+}
+
+/** Mode-weighted yield — average yield weighted by mode distribution. */
+function _modeWeightedYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  const total = weeklySnapshots.length
+  const sum = weeklySnapshots.reduce((acc, w) => acc + (w.yield || 0), 0)
+  return Math.round(sum / total)
+}
+
+/** Peak yield across all weekly snapshots. */
+function _peakYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  return Math.max(...weeklySnapshots.map(w => w.yield || 0))
+}
+
+/** Health score (0-100) — weighted composite of consistency, momentum, quality. */
+function _healthScore(weeklySnapshots, modeWeightedYield) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  // Simplified Phase 1 formula:
+  //  40% — consistency (how often in MAINTAIN)
+  //  30% — momentum (recent yield vs older yield)
+  //  30% — quality (mode-weighted yield relative to MAINTAIN expected)
+  const dist = _modeDistribution(weeklySnapshots)
+  const maintainShare = dist.MAINTAIN || 0
+  const consistency = Math.min(maintainShare, 1) * 40
+
+  // Momentum: compare last 3 weeks to first 3 weeks
+  const recent = weeklySnapshots.slice(-3)
+  const older = weeklySnapshots.slice(0, 3)
+  const recentAvg = recent.reduce((a, w) => a + (w.yield || 0), 0) / (recent.length || 1)
+  const olderAvg = older.reduce((a, w) => a + (w.yield || 0), 0) / (older.length || 1)
+  const momentumRatio = olderAvg > 0 ? recentAvg / olderAvg : 1
+  const momentum = Math.min(momentumRatio, 2) / 2 * 30
+
+  // Quality: mode-weighted yield vs MAINTAIN expected (5000)
+  const quality = Math.min(modeWeightedYield / 5000, 1) * 30
+
+  return Math.round(consistency + momentum + quality)
+}
+
+/** Yield for the last N days (from weekly snapshots — approximates by summing recent weeks). */
+function _yieldForDays(weeklySnapshots, days) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  const weeksNeeded = Math.ceil(days / 7)
+  const recent = weeklySnapshots.slice(-weeksNeeded)
+  if (recent.length === 0) return 0
+  const sum = recent.reduce((a, w) => a + (w.yield || 0), 0)
+  return Math.round(sum / recent.length) // average weekly yield
+}
+
+/** Trajectory description from 7d/30d/90d yields. */
+function _trajectory(y7, y30, y90) {
+  if (y90 === 0) return 'insufficient_data'
+  const r7v30 = y30 > 0 ? y7 / y30 : 1
+  const r30v90 = y90 > 0 ? y30 / y90 : 1
+  if (r7v30 > 1.2 && r30v90 > 1.0) return 'accelerating'
+  if (r7v30 > 1.2) return 'recent_surge'
+  if (r7v30 < 0.8 && r30v90 < 0.8) return 'declining'
+  if (r7v30 < 0.8) return 'recent_dip'
+  if (r30v90 > 1.1) return 'steady_growth'
+  return 'stable'
+}
+
+/** Phase pattern description from mode distribution over time. */
+function _phasePattern(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length < 2) return 'insufficient_data'
+  const modes = weeklySnapshots.map(w => w.mode)
+  const transitions = []
+  for (let i = 1; i < modes.length; i++) {
+    if (modes[i] !== modes[i - 1]) {
+      transitions.push(`${modes[i - 1]}→${modes[i]}`)
+    }
+  }
+  if (transitions.length === 0) return `consistent_${modes[0].toLowerCase()}`
+  // Check for smooth transitions (BUILD→MAINTAIN without DEBUG)
+  const smooth = transitions.every(t => !t.includes('DEBUG'))
+  if (smooth && transitions.some(t => t === 'BUILD→MAINTAIN')) return 'smooth_ramp'
+  if (transitions.filter(t => t.includes('DEBUG')).length > 2) return 'erratic'
+  return 'cyclical'
+}
+
+/** Daily assessment string. */
+function _dailyAssessment(mode, yieldVal, qualityScoreVal, expectedYield) {
+  const qsPct = Math.round(qualityScoreVal * 100)
+  if (mode === 'IDLE') return 'You\'re idle — no significant token activity today.'
+  if (mode === 'MAINTAIN') {
+    if (qualityScoreVal >= 0.5) return `You're in MAINTAIN mode. Yield ${yieldVal} is ${qsPct}% of MAINTAIN norm. The cascade is compounding.`
+    return `You're in MAINTAIN mode but yield ${yieldVal} is only ${qsPct}% of expected (${expectedYield}). You may be coasting — push for more output.`
+  }
+  if (mode === 'BUILD') {
+    if (qualityScoreVal >= 0.5) return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of BUILD norm. Greenfield work — expected to be low.`
+    return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Building is slow — keep going.`
+  }
+  if (mode === 'EDIT') {
+    if (qualityScoreVal >= 0.5) return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of EDIT norm. Fresh input but producing — good.`
+    return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Push for more output per input.`
+  }
+  if (mode === 'DEBUG') {
+    if (qualityScoreVal >= 0.5) return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of DEBUG norm. Investigating — yield is expected to be low.`
+    return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Debugging is slow — consider loading prior context.`
+  }
+  return `Mode: ${mode}. Yield: ${yieldVal}. Quality: ${qsPct}%.`
+}
+
+/** Daily advice string. */
+function _dailyAdvice(mode, yieldVal, qs) {
+  if (mode === 'MAINTAIN' && qs >= 0.5) return 'Keep the cascade going. Don\'t reset context — let it compound.'
+  if (mode === 'MAINTAIN') return 'You\'re in MAINTAIN but underperforming. Push the agent for more output per turn.'
+  if (mode === 'BUILD') return 'When you\'re done building, load prior context to transition to MAINTAIN. The cascade rewards reuse.'
+  if (mode === 'EDIT') return 'You\'re producing but using fresh input. Try to reuse prior context to boost leverage.'
+  if (mode === 'DEBUG') return 'When you\'re done debugging, load prior context to return to MAINTAIN. Don\'t let the debug phase drag on.'
+  if (mode === 'IDLE') return 'No activity detected. Start a session to build your cascade.'
+  return 'Keep working — the cascade will compound as you build context.'
+}
+
+/**
+ * Compute the cascade report block for a submission payload.
+ * Pure math — mode detection + badges + health score from the current pillars.
+ * The server stores this as-is (does NOT recompute modes).
+ * Weekly granularity is the privacy boundary — no daily modes in the report.
+ */
+function _computeReportBlock(pillars) {
+  const cas = cascade(pillars)
+  const modeInfo = detectMode(pillars)
+  const badges = computeBadges({
+    pillars,
+    cascade: cas,
+    history: [], // no history available at submit time — badges computed from current pillars only
+    isVerified: true, // submit_verified is the signed agent path
+    rank: null,
+  })
+  return {
+    current_mode: modeInfo.mode,
+    mode_confidence: modeInfo.confidence,
+    mode_distribution: { [modeInfo.mode]: 1.0 }, // single-window submission
+    mode_weighted_yield: cas.yield ?? 0,
+    peak_yield: cas.yield ?? 0,
+    health_score: _healthScore([{ mode: modeInfo.mode, yield: cas.yield ?? 0 }], cas.yield ?? 0),
+    badges,
+  }
+}