@animalabs/connectome-host 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 — 2026-07-26
+
+### Added
+
+- **Context settings panel** (webui `Settings` tab) — live control of the
+  agent's compile window, replacing the stop → edit the `framework/state`
+  Chronicle slot → start dance. Edits `contextBudgetTokens`, `tailTokens` and
+  `transitionPaceTokens`; Apply / reset-to-recipe / revert-edits, plus cancel
+  for an in-flight descent.
+  - New client messages `request-settings`, `settings-update`,
+    `settings-reset`, `settings-cancel-transition`; new server frame
+    `settings-state`. No protocol version bump (additive).
+  - `settings-state` is **broadcast** to every welcomed client, unlike
+    `mcpl-list` — these are live process values, so two operators must not see
+    divergent budgets.
+  - Mutations are full-auth only for free: `observerMaySend` denies by default,
+    so new message types are never reachable by scoped observers.
+  - `persist: false` applies ephemerally (live now, reverts on restart) for
+    operator experiments. `notify: true` optionally pushes a notice to the
+    agent; **off by default**, because the notice is new text in the very
+    context being tuned — it invalidates the KV prefix and is itself
+    classifier-visible. The agent can always pull current settings via its own
+    `agent_settings` tool instead.
+  - The panel is explicit about three things that would otherwise mislead:
+    raising the budget applies at once but **lowering starts a paced
+    convergence** (shown as `converging` / `blocked`, with the blocked reason
+    spelled out); only a few keys are hot, so `targetChunkTokens`,
+    `headWindowTokens`, `mergeThreshold`, `foldingStrategy` and friends are
+    listed under "restart only" rather than offered as controls; and preview
+    requires a context-manager with dry-run support, so an older build reports
+    "preview unavailable" instead of rendering an empty result.
+- **`GET /debug/context/preview?budget=&tail=[&agent=]`** — non-committing
+  preview of the fold plan at a hypothetical window. Persists no fold
+  resolutions, enqueues no compression, advances no transition bookkeeping
+  (the guarantee lives in context-manager's dry-run select). An infeasible
+  budget is reported as `fits: false` with per-component diagnostics rather
+  than an error — learning a budget cannot work is the reason to preview
+  instead of applying and taking the outage. Returns 501 when the resolved
+  context-manager predates dry-run support. Requires the `debug` scope.
+
+### Fixed
+
+- `/debug/context/curve` compiled against `app.recipe.agent.contextBudgetTokens`
+  — the **stale recipe** value. Runtime overrides live in the `framework/state`
+  Chronicle slot and win over the recipe, so the curve was plotted at the wrong
+  budget for any agent whose budget had ever been changed at runtime. Now reads
+  the live `getAgentRuntimeSettings`, falling back to the recipe.
+
 ## 0.4.0
 
 ### Changed

package/bun.lock

@@ -5,10 +5,10 @@
     "": {
       "name": "connectome-host",
       "dependencies": {
-        "@animalabs/agent-framework": "^0.6.8",
+        "@animalabs/agent-framework": "^0.7.0",
         "@animalabs/chronicle": "^0.2.0",
-        "@animalabs/context-manager": "^0.5.13",
-        "@animalabs/membrane": "^0.5.73",
+        "@animalabs/context-manager": "^0.6.0",
+        "@animalabs/membrane": "^0.5.75",
         "@opentui/core": "^0.1.82",
       },
       "devDependencies": {
@@ -19,13 +19,13 @@
     },
   },
   "packages": {
-    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.6.8", "", { "dependencies": { "@animalabs/chronicle": "^0.2.2", "@animalabs/context-manager": "^0.5.13", "@animalabs/membrane": "^0.5.73", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js", "agent-framework-recover": "dist/src/recovery/recover-cli.js" } }, "sha512-hLu+DI0Xj40zSRm+KmjEZO/uzizd2Gbaiih4IGNXJJZf0mcIxYDbOynEMpaLHtXGYMS8eYFmQK02ytdL9thtoA=="],
+    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.7.0", "", { "dependencies": { "@animalabs/chronicle": "^0.2.2", "@animalabs/context-manager": "^0.6.0", "@animalabs/membrane": "^0.5.75", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js", "agent-framework-recover": "dist/src/recovery/recover-cli.js" } }, "sha512-9FRQsCPaCZuZe0pyj+xq2NvdbSWQxRvdgO8nojVezpysaJL+w/Ba9tahGaOK7ZP12ZqnX3Q88wlttsXY+A47Gw=="],
 
     "@animalabs/chronicle": ["@animalabs/chronicle@0.2.1", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.1", "@animalabs/chronicle-darwin-x64": "0.2.1", "@animalabs/chronicle-linux-arm64-gnu": "0.2.1", "@animalabs/chronicle-linux-x64-gnu": "0.2.1", "@animalabs/chronicle-win32-x64-msvc": "0.2.1" } }, "sha512-rDFc069yfi7BQUusgsXBwBdqljUWLByXSYaTF40AP+tonBh0No3eF9VzKTSy1I8DYg/jAUHIKtVdKDGsVMVubw=="],
 
-    "@animalabs/context-manager": ["@animalabs/context-manager@0.5.13", "", { "dependencies": { "@animalabs/chronicle": "^0.2.6", "@animalabs/membrane": "^0.5.69" } }, "sha512-1NOsyCeiJoAa4MrBSGw1zbbs2XfvhRbkMfkFNCNFH9gSFTq/4tMwMu6lmZ082oNeB9FvptGrjCuZdVP8B9/UdA=="],
+    "@animalabs/context-manager": ["@animalabs/context-manager@0.6.0", "", { "dependencies": { "@animalabs/chronicle": "^0.2.6", "@animalabs/membrane": "^0.5.69" } }, "sha512-X8PKvHouS0dXt6faHeMyI2FehgyFKPT3vBaqM7QN6o/O/3I5pU8UX+WR1nsixfgw+la83lDC+OHn+lPe1A7DVg=="],
 
-    "@animalabs/membrane": ["@animalabs/membrane@0.5.73", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-w1rt/JVOD6dWwEO54tfR0yrLzwwD45cpYJ9hWJhHxs8k9FvW1PgIIV1KmNFNbpY8MR9HC5g7Lqgvhzs3pDst+g=="],
+    "@animalabs/membrane": ["@animalabs/membrane@0.5.75", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-eWtkrbQQga8UWDMH4VzPfZzcwYQLwngUcQ2tMeuERMBJ6WkXQzSJkcQVjM3ZvexvytnLsFTMOATvT58Igl9JuA=="],
 
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.52.0", "", { "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-d4c+fg+xy9e46c8+YnrrgIQR45CZlAi7PwdzIfDXDM6ACxEZli1/fxhURsq30ZpMZy6LvSkr41jGq5aF5TD7rQ=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {

package/src/modules/web-ui-module.ts

@@ -58,6 +58,7 @@ import {
   type TokenUsage,
   type CallLedgerSnapshot,
   type McplListMessage,
+  type SettingsStateMessage,
   type BranchesListMessage,
   type LessonsListMessage,
 } from '../web/protocol.js';
@@ -1076,6 +1077,9 @@ export class WebUiModule implements Module {
     if (url.pathname === '/debug/context/maintenance') {
       return this.handleContextMaintenance();
     }
+    if (url.pathname === '/debug/context/preview') {
+      return this.handleContextPreview(url);
+    }
     if (url.pathname === '/curve') {
       return new Response(CURVE_PAGE_HTML, {
         headers: { 'content-type': 'text/html; charset=utf-8' },
@@ -1181,6 +1185,79 @@ export class WebUiModule implements Module {
     return Response.json(buildContextCoverageSnapshot(agentName, cm));
   }
 
+  /**
+   * Preview the fold plan at a HYPOTHETICAL budget / tail, without applying it.
+   *
+   *   GET /debug/context/preview?budget=<tokens>[&tail=<tokens>][&agent=<name>]
+   *
+   * Commits nothing — no fold resolutions persisted, no compression enqueued,
+   * no transition bookkeeping advanced. That guarantee lives in
+   * context-manager's `previewContext` (dry-run select); this endpoint only
+   * forwards. An infeasible budget is reported as `fits: false` with the
+   * per-component diagnostics, NOT as an error: learning that a budget can't
+   * work is the reason to preview instead of applying and taking the outage.
+   *
+   * Returns 501 when the resolved context-manager predates dry-run support, so
+   * the panel can say so instead of rendering an empty result.
+   */
+  private handleContextPreview(url: URL): Response {
+    const app = sharedServer?.app;
+    if (!app) return Response.json({ error: 'app not bound yet' }, { status: 503 });
+    const agentName = url.searchParams.get('agent') || app.recipe.agent.name || 'agent';
+    const agent = app.framework.getAgent(agentName);
+    if (!agent) {
+      return Response.json({ error: `Agent not found: ${agentName}` }, { status: 404 });
+    }
+
+    const budgetRaw = url.searchParams.get('budget');
+    const budget = budgetRaw === null ? NaN : Number(budgetRaw);
+    if (!Number.isSafeInteger(budget) || budget <= 0) {
+      return Response.json({ error: 'budget must be a positive integer' }, { status: 400 });
+    }
+    const tailRaw = url.searchParams.get('tail');
+    const overrides: Record<string, unknown> = {};
+    if (tailRaw !== null) {
+      const tail = Number(tailRaw);
+      if (!Number.isSafeInteger(tail) || tail < 0) {
+        return Response.json({ error: 'tail must be a non-negative integer' }, { status: 400 });
+      }
+      // The strategy knob behind "tail" is recentWindowTokens.
+      overrides.recentWindowTokens = tail;
+    }
+
+    const fw = app.framework as unknown as {
+      previewContextSettings?: (n: string, b: number, o?: Record<string, unknown>) => unknown;
+    };
+    if (typeof fw.previewContextSettings !== 'function') {
+      return Response.json(
+        { error: 'preview unsupported: this agent-framework build has no previewContextSettings' },
+        { status: 501 },
+      );
+    }
+    try {
+      const result = fw.previewContextSettings(
+        agentName,
+        budget,
+        Object.keys(overrides).length > 0 ? overrides : undefined,
+      );
+      if (result === null || result === undefined) {
+        return Response.json(
+          {
+            error: 'preview unavailable: the resolved context-manager has no dry-run support, '
+              + 'or the active strategy has no fold plan (non-adaptive)',
+          },
+          { status: 501 },
+        );
+      }
+      return Response.json({ agent: agentName, budget, ...(overrides as object), preview: result });
+    } catch (err) {
+      return Response.json(
+        { error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+  }
+
   /**
    * Debug endpoint: return the membrane-normalized request the framework would
    * hand to the model if the agent were activated right now. Delegates to
@@ -1254,7 +1331,18 @@ export class WebUiModule implements Module {
     }
     try {
       const cm = (agent as unknown as { getContextManager: () => any }).getContextManager();
-      const maxTokens = app.recipe.agent.contextBudgetTokens ?? 200_000;
+      // Use the LIVE budget, not the recipe's. Runtime overrides persist in the
+      // `framework/state` Chronicle slot and win over the recipe, so reading
+      // app.recipe here plotted the wrong curve on any agent whose budget had
+      // ever been changed at runtime — which is every agent the settings panel
+      // touches. Fall back to the recipe only if the live read is unavailable.
+      let maxTokens = app.recipe.agent.contextBudgetTokens ?? 200_000;
+      try {
+        const live = (app.framework as unknown as {
+          getAgentRuntimeSettings?: (n: string) => { contextBudgetTokens?: number };
+        }).getAgentRuntimeSettings?.(agentName)?.contextBudgetTokens;
+        if (typeof live === 'number' && live > 0) maxTokens = live;
+      } catch { /* keep the recipe fallback */ }
       const reserveForResponse = app.recipe.agent.maxTokens ?? 16_384;
       const compiled = await cm.compile({ maxTokens, reserveForResponse });
 
@@ -1763,6 +1851,78 @@ export class WebUiModule implements Module {
         return;
       }
 
+      case 'request-settings': {
+        this.sendSettingsState(client, parsed.agent);
+        return;
+      }
+
+      // Settings mutations are live process state, so every case BROADCASTS
+      // rather than replying to the requester only (contrast sendMcplList,
+      // which is file-only). Two operators must not see divergent budgets.
+      case 'settings-update': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const patch: Record<string, number> = {};
+          if (parsed.contextBudgetTokens !== undefined) patch.contextBudgetTokens = parsed.contextBudgetTokens;
+          if (parsed.tailTokens !== undefined) patch.tailTokens = parsed.tailTokens;
+          if (parsed.transitionPaceTokens !== undefined) patch.transitionPaceTokens = parsed.transitionPaceTokens;
+          const fw = sharedServer!.app.framework as unknown as {
+            updateAgentRuntimeSettings: (n: string, p: unknown, o?: { persist?: boolean }) => unknown;
+          };
+          fw.updateAgentRuntimeSettings(agentName, patch, { persist: parsed.persist !== false });
+        } catch (err) {
+          // Expected failures land here and must reach the operator verbatim:
+          // budget ≤ max response tokens, or a strategy that cannot prepare a
+          // smaller window live. Silently swallowing them would look like the
+          // apply worked.
+          this.send(client, {
+            type: 'error',
+            message: `settings-update failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        if (parsed.notify === true) this.notifyAgentOfSettingsChange(agentName, 'update');
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
+      case 'settings-reset': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const fw = sharedServer!.app.framework as unknown as {
+            resetAgentRuntimeSettings: (n: string, k?: string[], o?: { persist?: boolean }) => unknown;
+          };
+          fw.resetAgentRuntimeSettings(agentName, parsed.keys, { persist: parsed.persist !== false });
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `settings-reset failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        if (parsed.notify === true) this.notifyAgentOfSettingsChange(agentName, 'reset');
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
+      case 'settings-cancel-transition': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const fw = sharedServer!.app.framework as unknown as {
+            cancelAgentRuntimeSettingsTransition: (n: string) => unknown;
+          };
+          fw.cancelAgentRuntimeSettingsTransition(agentName);
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `settings-cancel-transition failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        this.broadcastSettingsState(agentName);
+        return;
+      }
+
       case 'request-workspace-mounts': {
         if (parsed.scope && parsed.scope !== 'local') {
           this.routeFleetRequest(client, parsed.scope, 'workspace-mounts',
@@ -2426,6 +2586,125 @@ export class WebUiModule implements Module {
     }
   }
 
+  /** Default to the recipe's primary agent when the client omits a name. */
+  private resolveSettingsAgent(name?: string): string {
+    if (name) return name;
+    const app = sharedServer?.app;
+    return app?.recipe.agent.name ?? app?.framework.getAllAgents()[0]?.name ?? 'agent';
+  }
+
+  /**
+   * Build the settings snapshot. Never throws: this feeds a panel, and a
+   * strategy that isn't hot-configurable is a legitimate state to render
+   * read-only rather than an error to surface.
+   */
+  private buildSettingsState(agentName: string): SettingsStateMessage | null {
+    const app = sharedServer?.app;
+    if (!app) return null;
+    const fw = app.framework as unknown as {
+      getAgentRuntimeSettings?: (n: string) => Record<string, unknown>;
+      getAgent?: (n: string) => unknown;
+    };
+    if (typeof fw.getAgentRuntimeSettings !== 'function') return null;
+
+    let settings: Record<string, unknown>;
+    try {
+      settings = fw.getAgentRuntimeSettings(agentName);
+    } catch {
+      return null;
+    }
+
+    // Which knobs this build can apply live, probed rather than assumed: the
+    // hot set is a property of the ACTIVE strategy, not of the host version.
+    let hotConfigurable = false;
+    let previewAvailable = false;
+    try {
+      const agent = app.framework.getAgent(agentName);
+      const cm = agent?.getContextManager() as unknown as {
+        getHotContextSettings?: () => unknown;
+        previewContext?: unknown;
+      } | undefined;
+      hotConfigurable = !!cm && typeof cm.getHotContextSettings === 'function'
+        && cm.getHotContextSettings() !== null;
+      // Older context-manager builds resolve without previewContext. Report it
+      // so the panel says "preview unavailable on this build" instead of
+      // rendering an empty chart and looking broken.
+      previewAvailable = !!cm && typeof cm.previewContext === 'function';
+    } catch { /* leave both false — read-only panel */ }
+
+    const overrides: string[] = [];
+    try {
+      const agent = app.framework.getAgent(agentName) as unknown as {
+        getRuntimeSettingsOverrides?: () => Record<string, unknown>;
+      } | undefined;
+      const ov = agent?.getRuntimeSettingsOverrides?.() ?? {};
+      for (const [k, val] of Object.entries(ov)) if (val !== undefined) overrides.push(k);
+    } catch { /* informational only */ }
+
+    return {
+      type: 'settings-state',
+      agent: agentName,
+      settings: settings as SettingsStateMessage['settings'],
+      overrides,
+      // contextBudgetTokens is applied by the Agent itself; the other three are
+      // forwarded into the strategy's hot-settings channel, so they need a
+      // hot-configurable strategy to mean anything.
+      hotKeys: hotConfigurable
+        ? ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens', 'sameRoundThinkTextPolicy']
+        : ['contextBudgetTokens'],
+      hotConfigurable,
+      previewAvailable,
+    };
+  }
+
+  private sendSettingsState(client: ClientState, agentName?: string): void {
+    const msg = this.buildSettingsState(this.resolveSettingsAgent(agentName));
+    if (!msg) {
+      this.send(client, { type: 'error', message: 'runtime settings unavailable on this build' });
+      return;
+    }
+    this.send(client, msg);
+  }
+
+  /** Fan out to every welcomed client — settings are live process state. */
+  private broadcastSettingsState(agentName: string): void {
+    if (!sharedServer?.app) return;
+    const msg = this.buildSettingsState(agentName);
+    if (!msg) return;
+    for (const c of sharedServer.clients.values()) {
+      if (c.welcomed) this.send(c, msg);
+    }
+  }
+
+  /**
+   * Opt-in push notice to the agent that an operator changed its context
+   * settings. OFF by default at the protocol level, because this injects text
+   * into the very context being tuned: it invalidates the KV prefix and is
+   * itself classifier-visible. The zero-cost alternative the agent always has
+   * is to PULL via its `agent_settings` tool.
+   */
+  private notifyAgentOfSettingsChange(agentName: string, kind: 'update' | 'reset'): void {
+    try {
+      const app = sharedServer?.app;
+      if (!app) return;
+      const s = this.buildSettingsState(agentName);
+      const budget = s?.settings.contextBudgetTokens;
+      const tail = s?.settings.tailTokens;
+      const transition = s?.settings.transition;
+      const text = kind === 'reset'
+        ? `[operator] context settings reset to recipe defaults`
+        : `[operator] context settings changed`
+          + (budget !== undefined ? ` — budget ${budget}` : '')
+          + (tail !== undefined ? `, tail ${tail}` : '')
+          + (transition === 'converging' ? ' (converging gradually)' : '');
+      const cm = app.framework.getAgent(agentName)?.getContextManager();
+      cm?.addMessage('Context Manager', [{ type: 'text', text }], { system: true });
+    } catch (err) {
+      // A failed notice must never fail the apply that already succeeded.
+      console.warn('[settings] notify failed (change still applied):', err);
+    }
+  }
+
   private broadcastBranchChanged(): void {
     if (!sharedServer?.app) return;
     const cm = sharedServer?.app.framework.getAllAgents()[0]?.getContextManager();

package/src/web/protocol.ts

@@ -391,6 +391,41 @@ export interface McplListMessage {
   }>;
 }
 
+/**
+ * Runtime context-settings snapshot.
+ *
+ * BROADCAST to every welcomed client on change — unlike `mcpl-list`, these are
+ * live process state, not a config file, so two operators must not see
+ * divergent values.
+ */
+export interface SettingsStateMessage {
+  type: 'settings-state';
+  agent: string;
+  /** Live values. `transition` is 'converging' while a paced descent runs. */
+  settings: {
+    contextBudgetTokens: number;
+    tailTokens?: number;
+    transitionPaceTokens?: number;
+    sameRoundThinkTextPolicy?: string;
+    sameRoundThinkTextPolicySource?: string;
+    transition: 'stable' | 'converging' | 'blocked';
+    /** Why a descent is stuck: pace below floor, or protected context too big. */
+    transitionReason?: string;
+  };
+  /** Keys currently overridden away from the recipe (i.e. persisted). */
+  overrides: string[];
+  /** Which keys this build can apply live. Everything else needs a restart —
+   *  the UI must show that split rather than implying all knobs are hot. */
+  hotKeys: string[];
+  /** False when the strategy is not hot-configurable at all (e.g. passthrough):
+   *  the panel should go read-only rather than offer controls that will throw. */
+  hotConfigurable: boolean;
+  /** True when this build's context-manager exposes dry-run preview. Older
+   *  context-manager versions resolve without it, and the panel must say
+   *  "preview unavailable" rather than silently showing nothing. */
+  previewAvailable: boolean;
+}
+
 /** A page of older history — response to `request-history`, routed only to
  *  the requesting client and correlated by `corrId`. */
 export interface HistoryPageMessage {
@@ -474,6 +509,7 @@ export type WebUiServerMessage =
   | QuitConfirmRequiredMessage
   | LessonsListMessage
   | McplListMessage
+  | SettingsStateMessage
   | WorkspaceMountsMessage
   | WorkspaceTreeMessage
   | WorkspaceFileMessage
@@ -633,6 +669,58 @@ export interface McplSetEnvMessage {
   env: Record<string, string>;
 }
 
+/** Pull the current runtime context settings for an agent, plus which knobs are
+ *  live-appliable vs restart-only. Response is a `settings-state` envelope. */
+export interface RequestSettingsMessage {
+  type: 'request-settings';
+  /** Agent name; defaults to the recipe's primary agent. */
+  agent?: string;
+}
+
+/**
+ * Apply runtime context settings live.
+ *
+ * Semantics that the UI must not misrepresent:
+ *  - RAISING contextBudgetTokens applies immediately.
+ *  - LOWERING it starts a PACED convergence (`transition: 'converging'`)
+ *    rather than folding everything at once; it can be cancelled.
+ *  - Only these keys are hot. Chunk size, head window, merge threshold and
+ *    friends are recipe-and-restart only.
+ *
+ * `persist: false` makes the change ephemeral — live now, gone on restart —
+ * which is the mode for operator experiments. Default persists.
+ *
+ * `notify: true` pushes a notice into the agent's context. OFF by default and
+ * deliberately so: the notice is new text in the very context being tuned, so
+ * it invalidates the KV prefix and can itself trip a refusal classifier. The
+ * agent can always PULL current settings via its own `agent_settings` tool.
+ */
+export interface SettingsUpdateMessage {
+  type: 'settings-update';
+  agent?: string;
+  contextBudgetTokens?: number;
+  tailTokens?: number;
+  transitionPaceTokens?: number;
+  persist?: boolean;
+  notify?: boolean;
+}
+
+/** Revert named settings to their recipe values (all four when omitted). */
+export interface SettingsResetMessage {
+  type: 'settings-reset';
+  agent?: string;
+  keys?: string[];
+  persist?: boolean;
+  notify?: boolean;
+}
+
+/** Abandon an in-flight paced descent, holding the current frontier. */
+export interface SettingsCancelTransitionMessage {
+  type: 'settings-cancel-transition';
+  agent?: string;
+  persist?: boolean;
+}
+
 /** Pull the list of workspace mounts. Response is `workspace-mounts`.
  *  Optional `scope` selects a fleet child instead of the parent. */
 export interface RequestWorkspaceMountsMessage {
@@ -706,6 +794,10 @@ export type WebUiClientMessage =
   | McplAddMessage
   | McplRemoveMessage
   | McplSetEnvMessage
+  | RequestSettingsMessage
+  | SettingsUpdateMessage
+  | SettingsResetMessage
+  | SettingsCancelTransitionMessage
   | RequestWorkspaceMountsMessage
   | RequestWorkspaceTreeMessage
   | RequestWorkspaceFileMessage
@@ -768,6 +860,30 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
       return isValidMcplId(v.id);
     case 'mcpl-set-env':
       return isValidMcplId(v.id) && isStringMap(v.env);
+    case 'request-settings':
+      return isOptionalNonEmptyString(v.agent);
+    case 'settings-update': {
+      if (!isOptionalNonEmptyString(v.agent)) return false;
+      if (!isOptionalBool(v.persist) || !isOptionalBool(v.notify)) return false;
+      // Positive-integer-or-absent for each knob. The semantic gate (budget must
+      // exceed max response tokens; tail/pace need a hot-configurable strategy)
+      // lives in Agent.validateRuntimeSettingsPatch — this only guarantees the
+      // shape so that gate gets numbers instead of strings.
+      for (const k of ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens']) {
+        if (!isOptionalPositiveInt(v[k])) return false;
+      }
+      // Require at least one actual knob: an empty patch would throw downstream.
+      return v.contextBudgetTokens !== undefined
+        || v.tailTokens !== undefined
+        || v.transitionPaceTokens !== undefined;
+    }
+    case 'settings-reset':
+      return isOptionalNonEmptyString(v.agent)
+        && isOptionalBool(v.persist)
+        && isOptionalBool(v.notify)
+        && isOptionalStringArray(v.keys);
+    case 'settings-cancel-transition':
+      return isOptionalNonEmptyString(v.agent) && isOptionalBool(v.persist);
     case 'request-workspace-mounts':
       return v.scope === undefined || typeof v.scope === 'string';
     case 'request-workspace-tree':
@@ -822,3 +938,17 @@ function isOptionalStringArray(v: unknown): v is string[] | undefined {
   if (!Array.isArray(v)) return false;
   return v.every((x) => typeof x === 'string');
 }
+
+function isOptionalNonEmptyString(v: unknown): v is string | undefined {
+  return v === undefined || isNonEmptyString(v);
+}
+
+function isOptionalBool(v: unknown): v is boolean | undefined {
+  return v === undefined || typeof v === 'boolean';
+}
+
+/** Token counts: safe positive integers only. Rejects strings, NaN, Infinity,
+ *  fractions and negatives before they reach the settings validator. */
+function isOptionalPositiveInt(v: unknown): v is number | undefined {
+  return v === undefined || (typeof v === 'number' && Number.isSafeInteger(v) && v > 0);
+}

package/test/settings-protocol.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Wire validation for the context-settings messages.
+ *
+ * These messages mutate a LIVE agent's context budget, so malformed payloads
+ * must be rejected at the protocol edge rather than reaching
+ * Agent.validateRuntimeSettingsPatch as strings/NaN/fractions.
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { isClientMessage } from '../src/web/protocol.js';
+
+describe('settings messages — wire validation', () => {
+  it('accepts a minimal budget update', () => {
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 120_000 })).toBe(true);
+  });
+
+  it('accepts tail-only and pace-only updates', () => {
+    expect(isClientMessage({ type: 'settings-update', tailTokens: 30_000 })).toBe(true);
+    expect(isClientMessage({ type: 'settings-update', transitionPaceTokens: 8_000 })).toBe(true);
+  });
+
+  it('accepts persist/notify flags and an agent name', () => {
+    expect(isClientMessage({
+      type: 'settings-update',
+      contextBudgetTokens: 100_000,
+      persist: false,
+      notify: true,
+      agent: 'mythos',
+    })).toBe(true);
+  });
+
+  it('rejects an empty patch — it would throw downstream', () => {
+    expect(isClientMessage({ type: 'settings-update' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', persist: true })).toBe(false);
+  });
+
+  it('rejects non-integer / non-positive / stringly token counts', () => {
+    for (const bad of ['100000', 100.5, -1, 0, NaN, Infinity, null, {}]) {
+      expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: bad }))
+        .toBe(false);
+    }
+  });
+
+  it('rejects non-boolean flags and empty agent names', () => {
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, persist: 'yes' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, notify: 1 })).toBe(false);
+    expect(isClientMessage({ type: 'settings-update', contextBudgetTokens: 1, agent: '' })).toBe(false);
+  });
+
+  it('validates reset and cancel shapes', () => {
+    expect(isClientMessage({ type: 'settings-reset' })).toBe(true);
+    expect(isClientMessage({ type: 'settings-reset', keys: ['contextBudgetTokens'] })).toBe(true);
+    expect(isClientMessage({ type: 'settings-reset', keys: 'contextBudgetTokens' })).toBe(false);
+    expect(isClientMessage({ type: 'settings-cancel-transition' })).toBe(true);
+    expect(isClientMessage({ type: 'settings-cancel-transition', persist: false })).toBe(true);
+    expect(isClientMessage({ type: 'settings-cancel-transition', agent: 42 })).toBe(false);
+  });
+
+  it('validates request-settings', () => {
+    expect(isClientMessage({ type: 'request-settings' })).toBe(true);
+    expect(isClientMessage({ type: 'request-settings', agent: 'mythos' })).toBe(true);
+    expect(isClientMessage({ type: 'request-settings', agent: 7 })).toBe(false);
+  });
+});

package/web/src/App.tsx

@@ -9,6 +9,7 @@ import { StreamPanel, formatStreamEvent, type StreamLine } from './Stream';
 import { UsagePanel } from './Usage';
 import { LessonsPanel, type LessonRow } from './Lessons';
 import { McplPanel, type McplServerRow } from './Mcpl';
+import { SettingsPanel, type SettingsState } from './Settings';
 import { FilesPanel, FileViewerModal, type Mount, type FlatEntry, type FileViewer } from './Files';
 import { ContextPanel } from './Context';
 import { ContextDocument } from './ContextDocument';
@@ -272,7 +273,7 @@ export function App() {
 
   /** Right-sidebar tab selection. The Tree is the most-used surface so it's
    *  the default; lessons / mcp / files are operator-driven panels. */
-  type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'health';
+  type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
   const [sidebarTab, setSidebarTab] = createSignal<SidebarTab>('tree');
   const [mainView, setMainView] = createSignal<'chat' | 'context'>('chat');
 
@@ -311,6 +312,16 @@ export function App() {
     wire.send({ type: 'request-mcpl' });
   };
 
+  /** Context-settings panel state. The server BROADCASTS `settings-state` after
+   *  every mutation (unlike mcpl-list, which is requester-only), because these
+   *  are live process values — two operators must not see divergent budgets. */
+  const [settingsState, setSettingsState] = createSignal<SettingsState | null>(null);
+  const [settingsLoaded, setSettingsLoaded] = createSignal(false);
+  const refreshSettings = (): void => {
+    setSettingsLoaded(false);
+    wire.send({ type: 'request-settings' });
+  };
+
   /** Workspace files panel state — mounts list + per-mount tree cache. */
   const [mounts, setMounts] = createSignal<Mount[]>([]);
   const [mountsLoaded, setMountsLoaded] = createSignal(false);
@@ -876,6 +887,10 @@ export function App() {
           setMcplConfigPath(configPath);
           setMcplServers(servers);
         },
+        setSettings: (state) => {
+          setSettingsLoaded(true);
+          setSettingsState(state);
+        },
         setMounts: (loaded, moduleLoaded, list) => {
           setMountsLoaded(loaded);
           setWorkspaceModuleLoaded(moduleLoaded);
@@ -1174,6 +1189,7 @@ export function App() {
               if (tab === 'lessons' && !lessonsLoaded()) refreshLessons();
               if (tab === 'mcp' && !mcplLoaded()) refreshMcpl();
               if (tab === 'files' && !mountsLoaded()) refreshMounts();
+              if (tab === 'settings' && !settingsLoaded()) refreshSettings();
             }}
           />
           <div class="flex-1 min-h-0">
@@ -1212,6 +1228,17 @@ export function App() {
                 onSetEnv={(id, env) => wire.send({ type: 'mcpl-set-env', id, env })}
               />
             </Show>
+            <Show when={sidebarTab() === 'settings'}>
+              <SettingsPanel
+                loaded={settingsLoaded()}
+                state={settingsState()}
+                onRefresh={refreshSettings}
+                onApply={(patch) => wire.send({ type: 'settings-update', ...patch })}
+                onReset={(keys, persist) =>
+                  wire.send({ type: 'settings-reset', ...(keys ? { keys } : {}), persist })}
+                onCancelTransition={() => wire.send({ type: 'settings-cancel-transition' })}
+              />
+            </Show>
             <Show when={sidebarTab() === 'files'}>
               <FilesPanel
                 loaded={mountsLoaded()}
@@ -1282,6 +1309,8 @@ interface HandlerHooks {
   setLessons: (loaded: boolean, moduleLoaded: boolean, lessons: LessonRow[]) => void;
   /** Apply an mcpl-list response from the server. */
   setMcpl: (configPath: string, servers: McplServerRow[]) => void;
+  /** Apply a settings-state broadcast. */
+  setSettings: (state: SettingsState) => void;
   /** Apply a workspace-mounts response. */
   setMounts: (loaded: boolean, moduleLoaded: boolean, mounts: Mount[]) => void;
   /** Apply a workspace-tree response for one mount. */
@@ -1412,6 +1441,9 @@ function handleServerMessage(
     case 'mcpl-list':
       hooks.setMcpl(msg.configPath, msg.servers);
       return;
+    case 'settings-state':
+      hooks.setSettings(msg as unknown as SettingsState);
+      return;
     case 'workspace-mounts':
       hooks.setMounts(true, msg.loaded, msg.mounts);
       return;
@@ -1942,7 +1974,7 @@ function CommandSuggestions(props: { draft: string; onPick: (cmd: string) => voi
   );
 }
 
-type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'health';
+type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
 
 function SidebarTabs(props: {
   current: SidebarTabId;
@@ -1954,6 +1986,7 @@ function SidebarTabs(props: {
     { id: 'mcp', label: 'MCP', title: 'MCPL servers' },
     { id: 'files', label: 'Files', title: 'Workspace mounts + files' },
     { id: 'context', label: 'Context', title: 'Compiled context makeup' },
+    { id: 'settings', label: 'Settings', title: 'Live context budget / tail, with preview' },
     { id: 'health', label: 'Health', title: 'Runtime settings, failures, quarantine' },
   ];
   return (

package/web/src/Settings.tsx

@@ -0,0 +1,434 @@
+/**
+ * Context settings panel — live control of the agent's compile window.
+ *
+ * Replaces the stop → edit the `framework/state` Chronicle slot → start dance.
+ * Three things this panel is deliberately honest about, because getting any of
+ * them wrong would mislead an operator into an outage:
+ *
+ *  1. RAISING the budget applies at once; LOWERING starts a PACED convergence
+ *     that can sit in `converging` for many turns, and can be cancelled. Apply
+ *     is not "done" the moment it returns.
+ *  2. Only a few keys are hot. Chunk size, head window, merge threshold and
+ *     friends are recipe-and-restart-only — shown, but not offered as controls.
+ *  3. Preview requires a context-manager build with dry-run support. When the
+ *     resolved build lacks it we say so, rather than rendering an empty result
+ *     that looks like "nothing would change".
+ */
+
+import { createSignal, Show, For, onCleanup } from 'solid-js';
+
+export interface SettingsSnapshot {
+  contextBudgetTokens: number;
+  tailTokens?: number;
+  transitionPaceTokens?: number;
+  sameRoundThinkTextPolicy?: string;
+  sameRoundThinkTextPolicySource?: string;
+  transition: 'stable' | 'converging' | 'blocked';
+  transitionReason?: string;
+}
+
+export interface SettingsState {
+  agent: string;
+  settings: SettingsSnapshot;
+  overrides: string[];
+  hotKeys: string[];
+  hotConfigurable: boolean;
+  previewAvailable: boolean;
+}
+
+interface PreviewResult {
+  finalTokens: number;
+  budgetTokens: number;
+  fits: boolean;
+  exhausted: boolean;
+  headTokens: number;
+  tailTokens: number;
+  middleTokens: number;
+  middleChunkCount: number;
+  deepestLevel: number;
+  resolutions: Record<string, number>;
+  appliedCount: number;
+  producedCount: number;
+}
+
+/** Settings the strategy reads only at construction — surfaced so an operator
+ *  can see them without being invited to "change" them from here. */
+const RESTART_ONLY = [
+  'targetChunkTokens',
+  'headWindowTokens',
+  'mergeThreshold',
+  'foldingStrategy',
+  'maxSpeculativeL1s',
+  'adaptiveResolution',
+  'compressionSlackRatio',
+];
+
+const TRANSITION_HELP: Record<string, string> = {
+  transition_pace_too_small:
+    'the per-turn pace is below the floor — raise transitionPaceTokens or the descent cannot progress',
+  protected_context_exceeds_target:
+    'head + tail alone exceed the target — the verbatim window must shrink before this budget is reachable',
+};
+
+export function SettingsPanel(props: {
+  loaded: boolean;
+  state: SettingsState | null;
+  onRefresh(): void;
+  onApply(patch: {
+    contextBudgetTokens?: number;
+    tailTokens?: number;
+    transitionPaceTokens?: number;
+    persist: boolean;
+    notify: boolean;
+  }): void;
+  onReset(keys: string[] | undefined, persist: boolean): void;
+  onCancelTransition(): void;
+}) {
+  const [budget, setBudget] = createSignal<string>('');
+  const [tail, setTail] = createSignal<string>('');
+  const [pace, setPace] = createSignal<string>('');
+  const [persist, setPersist] = createSignal(true);
+  const [notify, setNotify] = createSignal(false);
+
+  const [preview, setPreview] = createSignal<PreviewResult | null>(null);
+  const [previewErr, setPreviewErr] = createSignal<string | null>(null);
+  const [previewing, setPreviewing] = createSignal(false);
+
+  let debounce: number | undefined;
+  onCleanup(() => { if (debounce) window.clearTimeout(debounce); });
+
+  const s = () => props.state?.settings;
+  const isHot = (k: string) => props.state?.hotKeys.includes(k) ?? false;
+
+  /** Prefill the inputs from live values so the operator edits from reality. */
+  const syncFromLive = () => {
+    const cur = s();
+    if (!cur) return;
+    setBudget(String(cur.contextBudgetTokens));
+    setTail(cur.tailTokens !== undefined ? String(cur.tailTokens) : '');
+    setPace(cur.transitionPaceTokens !== undefined ? String(cur.transitionPaceTokens) : '');
+  };
+
+  const num = (v: string): number | undefined => {
+    if (v.trim() === '') return undefined;
+    const n = Number(v);
+    return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+  };
+
+  /** Debounced: an operator dragging a value should not fire a compile per keystroke.
+   *  The request itself is non-committing, but it is still real CPU on a live agent. */
+  const runPreview = () => {
+    if (!props.state?.previewAvailable) return;
+    const b = num(budget());
+    if (b === undefined) { setPreview(null); setPreviewErr(null); return; }
+    if (debounce) window.clearTimeout(debounce);
+    debounce = window.setTimeout(async () => {
+      setPreviewing(true);
+      setPreviewErr(null);
+      try {
+        const qs = new URLSearchParams({ budget: String(b), agent: props.state!.agent });
+        const t = num(tail());
+        if (t !== undefined) qs.set('tail', String(t));
+        const res = await fetch(`/debug/context/preview?${qs}`, { credentials: 'same-origin' });
+        const body = await res.json();
+        if (!res.ok) {
+          setPreview(null);
+          setPreviewErr(body?.error ?? `HTTP ${res.status}`);
+          return;
+        }
+        setPreview(body.preview as PreviewResult);
+      } catch (e) {
+        setPreview(null);
+        setPreviewErr(e instanceof Error ? e.message : String(e));
+      } finally {
+        setPreviewing(false);
+      }
+    }, 350) as unknown as number;
+  };
+
+  const apply = () => {
+    const patch: Record<string, number> = {};
+    const b = num(budget());
+    const t = num(tail());
+    const p = num(pace());
+    const cur = s();
+    if (b !== undefined && b !== cur?.contextBudgetTokens) patch.contextBudgetTokens = b;
+    if (t !== undefined && t !== cur?.tailTokens) patch.tailTokens = t;
+    if (p !== undefined && p !== cur?.transitionPaceTokens) patch.transitionPaceTokens = p;
+    if (Object.keys(patch).length === 0) return;
+    props.onApply({ ...patch, persist: persist(), notify: notify() });
+  };
+
+  const lowering = () => {
+    const b = num(budget());
+    const cur = s();
+    return b !== undefined && cur !== undefined && b < cur.contextBudgetTokens;
+  };
+
+  const dirty = () => {
+    const cur = s();
+    if (!cur) return false;
+    const b = num(budget()), t = num(tail()), p = num(pace());
+    return (b !== undefined && b !== cur.contextBudgetTokens)
+      || (t !== undefined && t !== cur.tailTokens)
+      || (p !== undefined && p !== cur.transitionPaceTokens);
+  };
+
+  return (
+    <div class="h-full overflow-y-auto px-3 py-2 text-xs">
+      <div class="flex items-center gap-2 mb-2">
+        <span class="text-neutral-500 uppercase tracking-wider text-[10px] font-semibold">
+          context settings
+        </span>
+        <Show when={props.state}>
+          <span class="text-neutral-600 text-[10px] font-mono">{props.state!.agent}</span>
+        </Show>
+        <button
+          type="button"
+          class="ml-auto px-2 py-0.5 text-[10px] bg-neutral-800 hover:bg-neutral-700 text-neutral-300 rounded font-mono"
+          onClick={() => { props.onRefresh(); setTimeout(syncFromLive, 150); }}
+        >
+          refresh
+        </button>
+      </div>
+
+      <Show when={!props.loaded}>
+        <div class="text-neutral-600 italic">Loading…</div>
+      </Show>
+
+      <Show when={props.loaded && !props.state}>
+        <div class="text-amber-400/80">Runtime settings unavailable on this build.</div>
+      </Show>
+
+      <Show when={props.state}>
+        {/* ---- transition status: the thing an operator most needs to see ---- */}
+        <Show when={s()!.transition !== 'stable'}>
+          <div
+            class={`mb-2 px-2 py-1.5 rounded border text-[11px] ${
+              s()!.transition === 'blocked'
+                ? 'bg-red-950/40 border-red-800 text-red-300'
+                : 'bg-amber-950/40 border-amber-800 text-amber-200'
+            }`}
+          >
+            <div class="font-semibold">
+              {s()!.transition === 'blocked' ? 'descent BLOCKED' : 'descent converging'}
+            </div>
+            <Show when={s()!.transitionReason}>
+              <div class="mt-0.5 text-[10px] opacity-90">
+                {TRANSITION_HELP[s()!.transitionReason!] ?? s()!.transitionReason}
+              </div>
+            </Show>
+            <button
+              type="button"
+              class="mt-1 px-2 py-0.5 text-[10px] bg-neutral-800 hover:bg-neutral-700 text-neutral-200 rounded font-mono"
+              onClick={() => props.onCancelTransition()}
+            >
+              cancel transition (hold current frontier)
+            </button>
+          </div>
+        </Show>
+
+        <Show when={!props.state!.hotConfigurable}>
+          <div class="mb-2 px-2 py-1 rounded bg-neutral-900 border border-neutral-800 text-[10px] text-neutral-400">
+            This strategy is not hot-configurable — only the budget can be changed live.
+          </div>
+        </Show>
+
+        {/* ---- live values ---- */}
+        <table class="w-full mb-3 font-mono text-[11px]">
+          <tbody>
+            <For each={[
+              ['contextBudgetTokens', s()!.contextBudgetTokens],
+              ['tailTokens', s()!.tailTokens],
+              ['transitionPaceTokens', s()!.transitionPaceTokens],
+              ['sameRoundThinkTextPolicy', s()!.sameRoundThinkTextPolicy],
+            ] as Array<[string, unknown]>}>
+              {([k, v]) => (
+                <tr>
+                  <td class="text-neutral-500 pr-2">{k}</td>
+                  <td class="text-neutral-200 text-right tabular-nums">
+                    {v === undefined ? '–' : String(v)}
+                  </td>
+                  <td class="pl-2 w-16">
+                    <Show when={props.state!.overrides.includes(k)}>
+                      <span class="text-[9px] px-1 rounded bg-cyan-900/50 text-cyan-300">override</span>
+                    </Show>
+                  </td>
+                </tr>
+              )}
+            </For>
+          </tbody>
+        </table>
+
+        {/* ---- editors ---- */}
+        <div class="space-y-1.5 mb-2">
+          <For each={[
+            ['budget', 'contextBudgetTokens', budget, setBudget] as const,
+            ['tail', 'tailTokens', tail, setTail] as const,
+            ['pace', 'transitionPaceTokens', pace, setPace] as const,
+          ]}>
+            {([label, key, get, set]) => (
+              <label class="flex items-center gap-2">
+                <span class="text-neutral-500 w-12">{label}</span>
+                <input
+                  type="number"
+                  disabled={!isHot(key)}
+                  value={get()}
+                  placeholder={isHot(key) ? 'tokens' : 'restart only'}
+                  onInput={(e) => { set(e.currentTarget.value); runPreview(); }}
+                  class="flex-1 bg-neutral-900 border border-neutral-700 rounded px-1.5 py-0.5
+                         font-mono text-[11px] text-neutral-100 disabled:opacity-40"
+                />
+              </label>
+            )}
+          </For>
+        </div>
+
+        <div class="flex items-center gap-3 mb-2 text-[10px] text-neutral-400">
+          <label class="flex items-center gap-1">
+            <input type="checkbox" checked={persist()} onChange={(e) => setPersist(e.currentTarget.checked)} />
+            persist
+          </label>
+          <label class="flex items-center gap-1" title="Injects a notice into the agent's context. This perturbs the very context being tuned — it invalidates the KV prefix and is classifier-visible. The agent can always read settings itself via agent_settings.">
+            <input type="checkbox" checked={notify()} onChange={(e) => setNotify(e.currentTarget.checked)} />
+            notify agent
+          </label>
+        </div>
+        <div class="text-[10px] text-neutral-600 mb-2 leading-relaxed">
+          <Show when={!persist()}>
+            <div>ephemeral — live now, reverts on restart.</div>
+          </Show>
+          <Show when={lowering()}>
+            <div class="text-amber-500/90">
+              lowering the budget converges gradually, not instantly — it will report
+              <span class="font-mono"> converging</span> until it settles.
+            </div>
+          </Show>
+        </div>
+
+        <div class="flex items-center gap-2 mb-3">
+          <button
+            type="button"
+            disabled={!dirty()}
+            class="px-2 py-0.5 text-[10px] rounded font-mono bg-cyan-900/50 hover:bg-cyan-900/70
+                   text-cyan-200 disabled:opacity-30 disabled:hover:bg-cyan-900/50"
+            onClick={apply}
+          >
+            apply
+          </button>
+          <button
+            type="button"
+            class="px-2 py-0.5 text-[10px] bg-neutral-800 hover:bg-neutral-700 text-neutral-300 rounded font-mono"
+            onClick={() => { props.onReset(undefined, persist()); setTimeout(syncFromLive, 200); }}
+          >
+            reset to recipe
+          </button>
+          <button
+            type="button"
+            class="px-2 py-0.5 text-[10px] bg-neutral-800 hover:bg-neutral-700 text-neutral-300 rounded font-mono"
+            onClick={syncFromLive}
+          >
+            revert edits
+          </button>
+        </div>
+
+        {/* ---- preview ---- */}
+        <div class="border-t border-neutral-800 pt-2">
+          <div class="flex items-center gap-2 mb-1">
+            <span class="text-neutral-500 uppercase tracking-wider text-[10px] font-semibold">
+              preview
+            </span>
+            <Show when={previewing()}>
+              <span class="text-neutral-600 text-[10px]">computing…</span>
+            </Show>
+          </div>
+
+          <Show when={!props.state!.previewAvailable}>
+            <div class="text-[10px] text-neutral-500 leading-relaxed">
+              Preview unavailable on this build — the resolved context-manager has no
+              dry-run support. Apply still works; you just won't see the plan first.
+            </div>
+          </Show>
+
+          <Show when={props.state!.previewAvailable && previewErr()}>
+            <div class="text-[10px] text-amber-400/90">{previewErr()}</div>
+          </Show>
+
+          <Show when={preview()}>
+            {(p) => (
+              <div>
+                <div
+                  class={`px-2 py-1 rounded mb-1.5 text-[11px] border ${
+                    p().fits
+                      ? 'bg-emerald-950/40 border-emerald-800 text-emerald-300'
+                      : 'bg-red-950/40 border-red-800 text-red-300'
+                  }`}
+                >
+                  {p().fits
+                    ? `fits — ${p().finalTokens.toLocaleString()} of ${p().budgetTokens.toLocaleString()} tok`
+                    : `DOES NOT FIT — ${p().finalTokens.toLocaleString()} tok vs ${p().budgetTokens.toLocaleString()} budget`}
+                  <Show when={!p().fits && p().exhausted}>
+                    <div class="text-[10px] opacity-90 mt-0.5">
+                      picker exhausted: nothing further can be folded. Applying this would
+                      hard-fail the compile.
+                    </div>
+                  </Show>
+                </div>
+
+                <table class="w-full font-mono text-[10px]">
+                  <tbody>
+                    <For each={[
+                      ['head (verbatim)', p().headTokens],
+                      ['tail (verbatim)', p().tailTokens],
+                      ['middle (foldable)', p().middleTokens],
+                      ['middle chunks', p().middleChunkCount],
+                      ['deepest fold level', `L${p().deepestLevel}`],
+                      ['folds applied', p().appliedCount],
+                    ] as Array<[string, unknown]>}>
+                      {([k, v]) => (
+                        <tr>
+                          <td class="text-neutral-500 pr-2">{k}</td>
+                          <td class="text-neutral-300 text-right tabular-nums">
+                            {typeof v === 'number' ? v.toLocaleString() : String(v)}
+                          </td>
+                        </tr>
+                      )}
+                    </For>
+                    <tr>
+                      <td class="text-neutral-500 pr-2">summaries to produce</td>
+                      <td
+                        class={`text-right tabular-nums ${
+                          p().producedCount > 0 ? 'text-amber-400' : 'text-neutral-300'
+                        }`}
+                      >
+                        {p().producedCount}
+                      </td>
+                    </tr>
+                  </tbody>
+                </table>
+                <Show when={p().producedCount > 0}>
+                  <div class="text-[10px] text-amber-500/80 mt-1 leading-relaxed">
+                    {p().producedCount} summar{p().producedCount === 1 ? 'y' : 'ies'} do not exist
+                    yet — reaching this layout costs that many compression calls first.
+                  </div>
+                </Show>
+              </div>
+            )}
+          </Show>
+        </div>
+
+        {/* ---- restart-only knobs, shown but not offered ---- */}
+        <div class="border-t border-neutral-800 mt-3 pt-2">
+          <div class="text-neutral-500 uppercase tracking-wider text-[10px] font-semibold mb-1">
+            restart only
+          </div>
+          <div class="text-[10px] text-neutral-600 leading-relaxed">
+            These come from the recipe and are read at construction — changing them needs a
+            restart, not this panel:
+            <span class="font-mono text-neutral-500"> {RESTART_ONLY.join(', ')}</span>
+          </div>
+        </div>
+      </Show>
+    </div>
+  );
+}