pi-fovea 0.7.0 → 0.8.0

package/README.md

@@ -153,7 +153,7 @@ Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override
 | `sync.enabled` | `true` | pre-agent and post-turn continuous sync |
 | `sync.budget` | `1024` | token cap for proactive steering context |
 | `sync.ackClean` | `false` | toast after clean structural turns |
-| `sync.warmFileThreshold` | `2` | newly relevant files that justify proactive model steering |
+| `sync.steerThreshold` | `0.15` | total surprise (channel-weighted heat above the session sync memory) that justifies proactive model steering |
 | `sync.pushFocus` | `true` | embed a budgeted focus preview of the top drift target in red syncs |
 | `tools.defaultBudget` | `2000` | fallback maxTokens for the fovea_* tools |
 | `tools.replaceGrep` | `true` | install hybrid native-text / bare-query graph grep |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/src/core/config.ts

@@ -15,8 +15,10 @@ interface FoveaSyncConfig {
   budget: number;
   /** Also send a tiny model-visible ack on clean turns (default false: silent green). */
   ackClean: boolean;
-  /** Number of newly relevant files that justifies proactive steering on its own. */
-  warmFileThreshold: number;
+  /** Total surprise — channel-adjusted cascade mass above the session heat
+   * memory — that justifies proactive model steering on warmth alone.
+   * Route and deletion signals always steer regardless. */
+  steerThreshold: number;
   /** Push (default): red syncs embed a budgeted focus preview of the top drift
    * target. Pull: the update ends in a Next: advisory the model may follow. */
   pushFocus: boolean;
@@ -39,7 +41,12 @@ export const DEFAULT_FOVEA_CONFIG: FoveaConfig = {
     enabled: true,
     budget: 1024,
     ackClean: false,
-    warmFileThreshold: 2,
+    // Masses are heat units leaked outside the changed files (1 unit seeded
+    // per changed file), discounted by channel. Measured: a central fixture
+    // semantic edit (tests/fixtures/mini server/users.go) totals ≈0.077
+    // adjusted; a pair of weak shared-literal/co-change warm-ups ≈0.01–0.03;
+    // one strong call/import neighbor on a 350-node repo ≈0.19.
+    steerThreshold: 0.15,
     pushFocus: true,
   },
   tools: {
@@ -68,7 +75,7 @@ export const projectFoveaConfigPath = (cwd: string): string => path.join(cwd, CO
 const BOUNDS: Record<string, [number, number]> = {
   "sync.budget": [128, 8192],
   "tools.defaultBudget": [256, 16000],
-  "sync.warmFileThreshold": [1, 16],
+  "sync.steerThreshold": [0.02, 8],
 };
 
 const clamp = (id: string, value: number): number => {
@@ -82,6 +89,12 @@ const boolValue = (value: unknown, fallback: boolean): boolean =>
 const intValue = (id: string, value: unknown, fallback: number): number =>
   clamp(id, typeof value === "number" && Number.isFinite(value) ? value : fallback);
 
+const floatValue = (id: string, value: unknown, fallback: number): number => {
+  const n = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  const [lo, hi] = BOUNDS[id] ?? [Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY];
+  return Math.min(hi, Math.max(lo, n));
+};
+
 const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
   if (typeof partial !== "object" || partial === null || Array.isArray(partial)) return base;
   const src = partial as Record<string, unknown>;
@@ -92,7 +105,7 @@ const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
       enabled: boolValue(sync.enabled, base.sync.enabled),
       budget: intValue("sync.budget", sync.budget, base.sync.budget),
       ackClean: boolValue(sync.ackClean, base.sync.ackClean),
-      warmFileThreshold: intValue("sync.warmFileThreshold", sync.warmFileThreshold, base.sync.warmFileThreshold),
+      steerThreshold: floatValue("sync.steerThreshold", sync.steerThreshold, base.sync.steerThreshold),
       pushFocus: boolValue(sync.pushFocus, base.sync.pushFocus),
     },
     tools: {

package/src/core/ops.ts

@@ -840,8 +840,8 @@ export interface ImpactArgs {
   budget?: number;
 }
 
-export const impact = async (root: string, args: ImpactArgs): Promise<OpResult> => {
-  const state = await ensureState(root);
+export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState): Promise<OpResult> => {
+  const state = ensured ?? (await ensureState(root));
   const g = state.graph;
   const B = clampBudget(args.budget, 2000);
   const files = new Set<string>(args.files ?? []);
@@ -869,14 +869,21 @@ export const impact = async (root: string, args: ImpactArgs): Promise<OpResult>
   const exclude = new Set(seeds.map((i) => g.nodes[i]!.id));
   const seedFiles = new Set(seeds.map((i) => g.nodes[i]!.file));
 
-  // Aggregate warmed mass per file (excluding the seeds themselves).
+  // Aggregate warmed mass per file (excluding the seeds themselves). Heat
+  // retained by the seed files (seedMass) is the scale-free normalizer turn
+  // sync uses, since raw mass shrinks with graph size.
   const fileAgg = new Map<string, number>();
   const fileTop = new Map<string, Array<[number, number]>>();
   const anchorHits: GroupLine[] = [];
+  let seedMass = 0;
   g.nodes.forEach((n, i) => {
-    if (exclude.has(n.id) || seedFiles.has(n.file)) return;
+    if (exclude.has(n.id)) return;
     const v = field[i]!;
     if (v <= 1e-6) return;
+    if (seedFiles.has(n.file)) {
+      seedMass += v;
+      return;
+    }
     if (n.kind === "anchor") {
       anchorHits.push({ label: `⚑ ${n.name}`, mass: v, detail: `${n.file}:${n.line}` });
       return;
@@ -971,6 +978,15 @@ export const impact = async (root: string, args: ImpactArgs): Promise<OpResult>
       // and the strongest direct evidence channel without text re-parsing.
       warmedAnchors: anchorHits.map((h) => h.label.replace(/^⚑\s*/, "")),
       warmedFiles: fileEntries.map(([file]) => file),
+      // Heat retained by the seed files themselves — a graph-size-invariant
+      // normalizer for warmedMass (per-file warmth as a fraction of the heat
+      // the change site keeps).
+      seedMass: Number(seedMass.toFixed(6)),
+      // Per-file cascade mass (Σ node heat, seeds excluded). Turn-sync gates
+      // on these masses; the file list alone cannot rank a drizzle against a
+      // real cascade. Rounded so the warm-cache path and the inline path
+      // carry bit-identical payloads.
+      warmedMass: Object.fromEntries(fileEntries.map(([file, mass]) => [file, Number(mass.toFixed(6))])),
       warmedReasons: Object.fromEntries(fileEntries.map(([file]) => [
         file,
         [...(reasonByFile.get(file) ?? new Set(["graph path"]))],

package/src/core/render.ts

@@ -190,7 +190,7 @@ export const revealFoveated = (
     if (h >= HOT_TIER || seedSet.has(i)) {
       lines.push(
         node.kind === "file"
-          ? `▒ ${node.file}${context}`
+          ? `▪ ${node.file}${context}`
           : node.kind === "anchor"
             ? `⚑ ${node.sig}${context}`
             : `▲ ${formatNodeLocation(node)}  ${node.sig}${context}`,

package/src/core/sync.ts

@@ -23,8 +23,10 @@ interface SyncBaseline {
   shas: Map<string, string>;
   /** file -> extracted semantic facts, excluding the content hash. */
   semantics: Map<string, string>;
-  /** Previously reported undisclosed warmth, for delta delivery. */
-  warmed?: Set<string>;
+  /** file -> absorbed cascade mass (μ): the decayed union of all reported warmth. */
+  heat?: Map<string, number>;
+  /** Hysteresis latch: any red sync disarms warmth firing until total surprise drops back into the re-arm fraction. */
+  warmthArmed?: boolean;
   /** Drift targets already push-embedded in this baseline chain (embed-once). */
   pushed?: Set<string>;
 }
@@ -44,14 +46,114 @@ const setBaseline = (root: string, baseline: SyncBaseline): void => {
   while (baselines.size > ROOT_CACHE_LIMIT) baselines.delete(baselines.keys().next().value!);
 };
 
-export const resetSyncBaselines = (): void => baselines.clear();
+export const resetSyncBaselines = (): void => {
+  baselines.clear();
+  warmCache.clear();
+};
+
+// Channel priors for the surprise gate. A cascade whose only evidence is a
+// weak-prior channel (shared literal, co-change) must move proportionally
+// more raw heat to steer. Reason labels mirror reasonFor() in ops.ts.
+const CHANNEL_WEIGHT: Record<string, number> = {
+  "call dependency": 1,
+  "import dependency": 1,
+  "test dependency": 1,
+  "inheritance": 1,
+  "shared route": 1,
+  "co-change history": 0.5,
+  "shared literal": 0.35,
+  "graph path": 0.5,
+};
+// Unlabeled multi-hop warmth.
+const CHANNEL_UNKNOWN = 0.5;
+// Heat memory decay per structural sync (μ ← 0.7μ): repeat warmth re-fires
+// only once it exceeds what the session was already told.
+const HEAT_DECAY = 0.7;
+// Hysteresis re-arm band, as a fraction of the steer threshold.
+const REARM_FRACTION = 0.5;
+const round4 = (x: number): number => Math.round(x * 1e4) / 1e4;
+
+// Background warm. The blocking `sync` call on the user-perceived send path
+// (before_agent_start / turn_end) recomputes extraction, graph assembly, the
+// baseline fingerprint, and the impact cascade whenever the repo drifted.
+// `warmSync` runs those heavyweight ingredients eagerly as soon as edits land
+// (tool_execution_end), keyed by state version + changed-file set, so the same
+// drift's sync call reuses them and stays verdict-only. Never advances the
+// baseline, never reports, never throws; a drift without a warm (external
+// edits between turns) falls back to the inline compute in `sync`.
+
+interface WarmCompute {
+  /** State version this computation fingerprints. */
+  version: string;
+  /** Canonical key of the changed-file set this warm covers. */
+  filesKey: string;
+  /** Full next-baseline snapshot, identical to snapshot(state). */
+  snapshot: SyncBaseline;
+  /** impact() outputs for the changed set. */
+  warmedFiles: string[];
+  warmedMass: Record<string, number>;
+  warmReasons: Record<string, string[]>;
+}
+
+const warmCache = new Map<string, WarmCompute>();
+
+const filesKey = (files: readonly string[]): string => [...new Set(files)].sort().join("\n");
+
+/** Files whose extracted facts moved since a baseline, in canonical order. */
+const semanticDrift = (state: RepoState, prev: SyncBaseline): string[] => {
+  const changed = Object.keys(state.facts).filter(
+    (file) => prev.shas.get(file) !== state.facts[file]!.sha1,
+  );
+  return changed.filter(
+    (file) => prev.semantics.get(file) !== semanticFacts(state, file) && state.graph.byFile.has(file),
+  );
+};
+
+export interface WarmParams {
+  /** Optional drift hints, same role as sync hints; the probe stays the oracle. */
+  files?: string[];
+  /** Token budget for the impact cascade (mirrors sync.budget). */
+  budget: number;
+}
+
+export const warmSync = async (root: string, params: WarmParams, state?: RepoState): Promise<void> => {
+  try {
+    const cur = state ?? (await ensureState(root, { hints: params.files ?? [], force: false }));
+    const prev = getBaseline(root);
+    if (!prev || prev.version === cur.version) return;
+    const files = semanticDrift(cur, prev);
+    if (!files.length) return;
+    const key = filesKey(files);
+    const cached = warmCache.get(root);
+    if (cached && cached.version === cur.version && cached.filesKey === key) return;
+    const next = await snapshot(cur);
+    // The impact cascade runs against the same immutable state snapshot the
+    // fingerprint used, so the cached pair is consistent for cur.version.
+    const result = await impact(root, { files, includeUncommitted: false, budget: params.budget }, cur);
+    warmCache.set(root, {
+      version: cur.version,
+      filesKey: key,
+      snapshot: next,
+      warmedFiles: (result.details.warmedFiles as string[] | undefined) ?? [],
+      warmedMass: (result.details.warmedMass as Record<string, number> | undefined) ?? {},
+      warmReasons: (result.details.warmedReasons as Record<string, string[]> | undefined) ?? {},
+    });
+    while (warmCache.size > ROOT_CACHE_LIMIT) warmCache.delete(warmCache.keys().next().value!);
+  } catch {
+    // Best-effort: a failed warm just means the next blocking sync computes
+    // inline (with its own error reporting), exactly as before.
+  }
+};
 
 export interface SyncParams {
   /** Optional drift hints (e.g. files touched by pi's edit/write tools this
    * turn). Unioned into the warmth seeds; never the source of truth. */
   files?: string[];
   budget: number;
-  warmFileThreshold: number;
+  /** Total surprise (channel-adjusted cascade mass above the session heat
+   * memory) that justifies proactive steering on warmth alone. Route and
+   * deletion signals bypass it. */
+  steerThreshold: number;
   /** Push vs pull (default push): embed the top file target's focus context. */
   pushFocus?: boolean;
 }
@@ -152,44 +254,106 @@ export const sync = async (
   const changed = Object.keys(state.facts).filter(
     (file) => prev.shas.get(file) !== state.facts[file]!.sha1,
   );
-  const semanticChanged = changed.filter(
-    (file) => prev.semantics.get(file) !== semanticFacts(state, file) && state.graph.byFile.has(file),
-  );
+  const semanticChanged = semanticDrift(state, prev);
   const hinted = (params.files ?? []).filter((file) => semanticChanged.includes(file));
   const deleted = [...prev.shas.keys()].filter((file) => !(file in state.facts));
   const files = [...new Set([...semanticChanged, ...hinted])];
 
   let warmNow: Set<string> = new Set();
-  let warmNew: string[] = [];
+  let warmMass: Record<string, number> = {};
   let warmReasons: Record<string, string[]> = {};
+  let preparedBaseline: SyncBaseline | undefined;
   if (files.length) {
-    const result = await impact(root, { files, includeUncommitted: false, budget: params.budget });
-    const warmedFiles = (result.details.warmedFiles as string[] | undefined) ?? [];
-    warmReasons = (result.details.warmedReasons as Record<string, string[]> | undefined) ?? {};
-    warmNow = new Set(warmedFiles.filter((file) => !disclosedFiles.has(file) && !files.includes(file)));
-    warmNew = prev.warmed === undefined
-      ? [...warmNow]
-      : [...warmNow].filter((file) => !prev.warmed!.has(file));
+    // Edit-time `warmSync` may have precomputed the heavyweight ingredients —
+    // the next baseline fingerprint and the impact cascade — so this blocking
+    // hook only renders the verdict. Keyed by state version + changed set, a
+    // stale warm (more drift landed since) falls through to the inline compute.
+    const prepared = warmCache.get(root);
+    const preparedHit =
+      prepared !== undefined &&
+      prepared.version === state.version &&
+      prepared.filesKey === filesKey(files);
+    if (preparedHit) {
+      warmCache.delete(root);
+      preparedBaseline = prepared.snapshot;
+      warmMass = prepared.warmedMass;
+      warmReasons = prepared.warmReasons;
+      warmNow = new Set(prepared.warmedFiles.filter(
+        (file) => !disclosedFiles.has(file) && !files.includes(file),
+      ));
+    } else {
+      const result = await impact(root, { files, includeUncommitted: false, budget: params.budget });
+      const warmedFiles = (result.details.warmedFiles as string[] | undefined) ?? [];
+      warmMass = (result.details.warmedMass as Record<string, number> | undefined) ?? {};
+      warmReasons = (result.details.warmedReasons as Record<string, string[]> | undefined) ?? {};
+      warmNow = new Set(warmedFiles.filter((file) => !disclosedFiles.has(file) && !files.includes(file)));
+    }
   }
 
-  const pushed = new Set(prev.pushed ?? []);
-  setBaseline(root, { ...(await snapshot(state)), warmed: warmNow, pushed });
+  // Surprise gate. Warmth earns a steer only to the extent its channel-adjusted
+  // mass exceeds μ, the session's heat memory: the decayed union of every
+  // cascade already disclosed. Repeat warmth around ongoing work contributes
+  // nothing; genuinely hotter re-warming fires again. Novelty is continuous,
+  // not a one-sync set difference.
+  const channelMass = (file: string): number => {
+    let prior = 0;
+    for (const reason of warmReasons[file] ?? []) prior = Math.max(prior, CHANNEL_WEIGHT[reason] ?? CHANNEL_UNKNOWN);
+    return (warmMass[file] ?? 0) * (prior || CHANNEL_UNKNOWN);
+  };
+  const memory = new Map<string, number>();
+  for (const [file, mass] of prev.heat ?? []) {
+    const decayed = mass * HEAT_DECAY;
+    if (decayed > 1e-6) memory.set(file, decayed);
+  }
+  const surprise = new Map<string, number>();
+  let surpriseTotal = 0;
+  for (const file of warmNow) {
+    const delta = channelMass(file) - (memory.get(file) ?? 0);
+    if (delta > 1e-9) {
+      surprise.set(file, delta);
+      surpriseTotal += delta;
+    }
+  }
 
+  const pushed = new Set(prev.pushed ?? []);
   // Extraction failures leave fact gaps that look like anchor *removals* —
   // never escalate red on removals while degraded; the degraded note is
   // already loud in details.
   const degraded = state.extraction.failed.length > 0;
-  const red = (added.length - newlyImplicit.length) > 0 ||
+  const structuralRed = (added.length - newlyImplicit.length) > 0 ||
     (removed.length > 0 && !degraded) ||
-    deleted.some((file) => !isTestScope(file)) ||
-    warmNew.length >= Math.max(1, params.warmFileThreshold);
+    deleted.some((file) => !isTestScope(file));
+  const prevArmed = prev.warmthArmed !== false;
+  const warmthFire = prevArmed && surpriseTotal >= params.steerThreshold;
+  const red = structuralRed || warmthFire;
+  // Hysteresis: a red sync discloses its whole cascade, so the latch disarms
+  // until total surprise drops into the re-arm fraction of the threshold.
+  const warmthArmed = red ? false : prevArmed || surpriseTotal <= params.steerThreshold * REARM_FRACTION;
+  // Absorb on disclosure: every warmed file the message covers charges the
+  // memory at its current adjusted mass, displayed or not.
+  if (red) {
+    for (const file of warmNow) {
+      const adjusted = channelMass(file);
+      if (adjusted > (memory.get(file) ?? 0)) memory.set(file, adjusted);
+    }
+  }
+  const orderedWarm = [...surprise.entries()]
+    .sort((a, b) => b[1] - a[1] || Number(isTestScope(a[0])) - Number(isTestScope(b[0])) || a[0].localeCompare(b[0]))
+    .map(([file]) => file);
+  setBaseline(root, {
+    ...(preparedBaseline ?? (await snapshot(state))),
+    heat: memory.size ? memory : undefined,
+    warmthArmed,
+    pushed,
+  });
   if (!red) {
     return {
       structural: true, red: false, tokens: 0,
       details: {
         version: state.version,
         anchorsDelta: added.length - removed.length,
-        warmNew: warmNew.length,
+        warmNew: orderedWarm.length,
+        surprise: round4(surpriseTotal),
         changedFiles: changed,
         semanticChangedFiles: files,
         deletedFiles: deleted,
@@ -203,8 +367,6 @@ export const sync = async (
     : deleted.length
       ? `deleted ${deleted.slice(0, 4).join(", ")}${deleted.length > 4 ? ` (+${deleted.length - 4} more)` : ""}`
       : "route structure";
-  const orderedWarm = [...warmNew].sort((a, b) =>
-    Number(isTestScope(a)) - Number(isTestScope(b)) || a.localeCompare(b));
   const lines: string[] = [
     "Repository structure changed.",
     `Changed: ${changedSummary}`,
@@ -267,6 +429,7 @@ export const sync = async (
       changedFiles: changed,
       semanticChangedFiles: files,
       warmNew: orderedWarm,
+      surprise: round4(surpriseTotal),
       warmReasons,
       deletedFiles: deleted,
       ...(embedded ? { pushedFocus: focusTarget } : {}),

package/src/index.ts

@@ -11,7 +11,7 @@ import { hasAstGrep } from "./core/astgrep.js";
 import { ROOT_CACHE_LIMIT } from "./core/asyncutil.js";
 import { dwell, ensureStateBackground, focus, impact, sketch } from "./core/ops.js";
 import { resetSessions } from "./core/session.js";
-import { resetSyncBaselines, sync } from "./core/sync.js";
+import { resetSyncBaselines, sync, warmSync } from "./core/sync.js";
 import { openFoveaSettings } from "./ui/settings.js";
 import type { NodeKind } from "./core/types.js";
 
@@ -195,7 +195,28 @@ export default function fovea(pi: ExtensionAPI) {
   // conversation turns exit at zero cost through the version fast path.
   let turnFiles: string[] = [];
   let lastSyncError: string | undefined;
+  // Background warm pipeline: every edit schedules a debounced preparation of
+  // the next sync verdict, so the blocking sync on the send path (before_agent
+  // start / turn_end) reuses a precomputed fingerprint + impact cascade instead
+  // of re-extracting and re-diffusing while the UI waits.
+  const WARM_DEBOUNCE_MS = 250;
+  const warmTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const warmAfterEdit = (root: string, cfg: FoveaConfig): void => {
+    const rels = turnFiles
+      .map((p) => (p.startsWith(root + "/") ? p.slice(root.length + 1) : p))
+      .filter((p) => !p.startsWith("/"));
+    if (!rels.length || !cfg.sync.enabled) return;
+    const files = [...rels];
+    const existing = warmTimers.get(root);
+    if (existing) clearTimeout(existing);
+    warmTimers.set(root, setTimeout(() => {
+      warmTimers.delete(root);
+      void warmSync(root, { files, budget: cfg.sync.budget }).catch(() => {});
+    }, WARM_DEBOUNCE_MS));
+  };
   pi.on("session_shutdown", () => {
+    for (const timer of warmTimers.values()) clearTimeout(timer);
+    warmTimers.clear();
     lifecycleEpoch++;
     turnFiles = [];
     lastSyncError = undefined;
@@ -210,13 +231,19 @@ export default function fovea(pi: ExtensionAPI) {
     const args = event.args as { path?: unknown };
     if (typeof args.path === "string") turnFiles.push(args.path);
   });
+  // Warm once the file is actually on disk (tool_execution_start fires during
+  // preflight, before the write lands); the debounce also coalesces bursts.
+  pi.on("tool_execution_end", (event, ctx) => {
+    if (event.toolName !== "edit" && event.toolName !== "write") return;
+    warmAfterEdit(ctx.cwd, configFor(ctx.cwd, ctx.isProjectTrusted()));
+  });
   pi.on("before_agent_start", async (_event, ctx) => {
     try {
       const cfg = configFor(ctx.cwd, ctx.isProjectTrusted());
       if (!cfg.sync.enabled) return;
       const outcome = await sync(
         ctx.cwd,
-        { files: [], budget: cfg.sync.budget, warmFileThreshold: cfg.sync.warmFileThreshold, pushFocus: cfg.sync.pushFocus },
+        { files: [], budget: cfg.sync.budget, steerThreshold: cfg.sync.steerThreshold, pushFocus: cfg.sync.pushFocus },
         undefined,
         { probe: "cheap" },
       );
@@ -251,7 +278,7 @@ export default function fovea(pi: ExtensionAPI) {
       if (!cfg.sync.enabled) return;
       const outcome = await sync(
         ctx.cwd,
-        { files: rels, budget: cfg.sync.budget, warmFileThreshold: cfg.sync.warmFileThreshold, pushFocus: cfg.sync.pushFocus },
+        { files: rels, budget: cfg.sync.budget, steerThreshold: cfg.sync.steerThreshold, pushFocus: cfg.sync.pushFocus },
         undefined,
         { probe: "cheap" },
       );

package/src/ui/settings.ts

@@ -36,7 +36,7 @@ import {
 
 const BOOLEANS = ["true", "false"] as const;
 const BUDGETS = [256, 512, 1024, 2048, 4096, 8192] as const;
-const THRESHOLDS = [1, 2, 3, 5, 8, 13] as const;
+const THRESHOLDS = [0.05, 0.1, 0.15, 0.25, 0.5, 1] as const;
 
 const SELECT_LAYOUT: SelectListLayoutOptions = {
   minPrimaryColumnWidth: 12,
@@ -249,10 +249,10 @@ const buildItems = (
       "Show a brief notification after changed-but-actionless turns. Default off; clean turns spend no model tokens.",
     values: BOOLEANS,
   }),
-  setting("sync.warmFileThreshold", "Steer threshold", String(config.sync.warmFileThreshold), {
+  setting("sync.steerThreshold", "Steer threshold", String(config.sync.steerThreshold), {
     description:
-      "How many newly relevant files justify steering the model. Higher means fewer continuations; route changes always steer.",
-    submenu: numericSubmenu(theme, THRESHOLDS, "Relevance threshold", "Newly relevant file count that steers the model."),
+      "Total surprise (channel-weighted heat above the session's sync memory) that justifies steering the model. Higher means fewer continuations; route changes always steer.",
+    submenu: numericSubmenu(theme, THRESHOLDS, "Steer threshold", "Surprise mass that steers the model."),
   }),
   setting("sync.pushFocus", "Push focus detail", config.sync.pushFocus ? "true" : "false", {
     description: