@animalabs/connectome-host 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.1
+
+### Added
+
+- **llm-calls logging for every provider**: `LoggingProviderAdapter`, a
+  provider-agnostic decorator over any `ProviderAdapter`, wraps the
+  openai-codex, openrouter, and openai-responses transports — which
+  previously had NO wire visibility (found post-deploy on Mica: zero
+  llm-calls files, requests undiagnosable). Full raw request + response
+  summary + usage + timing + error per call, size-guarded against
+  pathological payloads. Anthropic/Bedrock keep their purpose-built
+  logging classes.
+
+## 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.1",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -25,6 +25,7 @@ import {
   OpenRouterAdapter,
 } from '@animalabs/membrane';
 import { LoggingAnthropicAdapter } from './logging-adapter.js';
+import { LoggingProviderAdapter } from './logging-provider-wrapper.js';
 import { LoggingBedrockAdapter } from './logging-bedrock-adapter.js';
 import { CodexSubscriptionAdapter } from './codex-subscription-adapter.js';
 import { CallLedger } from './call-ledger.js';
@@ -835,11 +836,22 @@ async function main() {
     ? new LoggingBedrockAdapter({}, llmLogPath)
     : undefined;
   const adapter = provider === 'openai-responses'
-    ? new OpenAIResponsesAPIAdapter({
-        apiKey: config.openaiApiKey!,
-        baseURL: process.env.OPENAI_BASE_URL || undefined,
-      })
-    : bedrockAdapter ?? openrouterAdapter ?? codexAdapter ?? new LoggingAnthropicAdapter(
+    ? new LoggingProviderAdapter(
+        new OpenAIResponsesAPIAdapter({
+          apiKey: config.openaiApiKey!,
+          baseURL: process.env.OPENAI_BASE_URL || undefined,
+        }),
+        llmLogPath,
+      )
+    // Codex/openrouter/openai adapters get the provider-agnostic logging
+    // decorator (llm-calls.jsonl); anthropic and bedrock keep their
+    // purpose-built logging classes below. The bare `codexAdapter` /
+    // `openrouterAdapter` instances stay un-wrapped for auth commands and
+    // dispose() — only the membrane sees the wrapper.
+    : bedrockAdapter
+      ?? (openrouterAdapter ? new LoggingProviderAdapter(openrouterAdapter, llmLogPath) : undefined)
+      ?? (codexAdapter ? new LoggingProviderAdapter(codexAdapter, llmLogPath) : undefined)
+      ?? new LoggingAnthropicAdapter(
         {
           // Anthropic OAuth wins over API-key auth when both are present.
           // Subscription tokens additionally require this beta header.

package/src/logging-provider-wrapper.ts

@@ -0,0 +1,165 @@
+// Provider-agnostic ProviderAdapter decorator that appends each LLM call's
+// request, response, usage, timing, and any error to the same
+// `llm-calls.<iso>.jsonl` file the Anthropic and Bedrock paths use.
+//
+// Exists because llm-call logging grew adapter-by-adapter (Anthropic subclass,
+// Bedrock wrapper) and the remaining providers — openai-codex (Mica),
+// openrouter (K3) — had NO wire visibility at all: a post-deploy "did her
+// requests actually work?" check on Mica (2026-07-26) found zero llm-calls
+// files because the codex path never logged. This decorator wraps ANY
+// ProviderAdapter, so a new provider gets logging by construction rather than
+// by remembering to build a logging twin.
+//
+// Contents: full raw request and a summarized-but-complete response record
+// (stop reason, usage, per-block shape, full text) on every call, plus the
+// raw provider response. Retention/rotation/S3 shipping is the host box's
+// llm-logs sync job's problem — this file just writes lines.
+//
+// OOM note (learned on the Anthropic path, which once logged raw+normalized+
+// summary and contributed to production OOMs): we serialize the record ONCE,
+// and a size guard drops the raw bodies for pathological payloads (giant
+// image batches) rather than buffering multi-hundred-MB lines.
+//
+// Decorator safety: adapters whose complete() internally delegates to their
+// own stream() (codex does) self-call the INNER method, not the wrapper —
+// each membrane-level call logs exactly once.
+//
+// Each line: { type: 'call'|'error', provider, kind: 'complete'|'stream',
+//   timestamp, durationMs, requestSummary, response?, rawRequest?,
+//   rawResponse?, error?, truncated? }
+
+import type {
+  ProviderAdapter,
+  ProviderRequest,
+  ProviderResponse,
+  ProviderRequestOptions,
+  StreamCallbacks,
+} from '@animalabs/membrane';
+import { appendFileSync } from 'node:fs';
+
+/** Above this many serialized bytes, drop raw bodies and keep summaries. */
+const MAX_RECORD_BYTES = 16 * 1024 * 1024;
+
+function summarizeRequest(request: ProviderRequest): Record<string, unknown> {
+  const msgs = (request.messages ?? []) as Array<{ role?: string; content?: unknown }>;
+  const last = msgs[msgs.length - 1];
+  const lastPreview = typeof last?.content === 'string'
+    ? last.content.slice(0, 200)
+    : Array.isArray(last?.content)
+      ? (last.content as Array<{ type?: string; text?: string }>)
+          .map((b) => (b.type === 'text' ? (b.text ?? '').slice(0, 120) : `[${b.type}]`))
+          .join(' | ').slice(0, 300)
+      : undefined;
+  return {
+    model: request.model,
+    maxTokens: request.maxTokens,
+    messageCount: msgs.length,
+    systemChars: typeof request.system === 'string'
+      ? request.system.length
+      : Array.isArray(request.system)
+        ? JSON.stringify(request.system).length
+        : 0,
+    toolNames: (request.tools as Array<{ name?: string }> | undefined)?.map((t) => t.name) ?? null,
+    toolCount: (request.tools as unknown[] | undefined)?.length ?? 0,
+    lastMessageRole: last?.role,
+    lastMessagePreview: lastPreview,
+  };
+}
+
+function summarizeResponse(response: ProviderResponse): Record<string, unknown> {
+  const content = (response.content ?? []) as Array<{ type?: string; text?: string; name?: string }>;
+  return {
+    stopReason: response.stopReason
+      ?? (response.raw as { stop_reason?: string } | undefined)?.stop_reason
+      ?? null,
+    usage: response.usage ?? null,
+    blocks: content.map((b) => ({
+      type: b.type,
+      ...(b.type === 'text' ? { chars: (b.text ?? '').length, text: b.text } : {}),
+      ...(b.type === 'tool_use' ? { name: b.name } : {}),
+    })),
+  };
+}
+
+export class LoggingProviderAdapter implements ProviderAdapter {
+  readonly name: string;
+
+  constructor(
+    private readonly inner: ProviderAdapter,
+    private readonly logPath: string,
+  ) {
+    this.name = inner.name;
+  }
+
+  supportsModel(modelId: string): boolean {
+    return this.inner.supportsModel(modelId);
+  }
+
+  private log(record: Record<string, unknown>): void {
+    try {
+      let line = JSON.stringify(record);
+      if (line.length > MAX_RECORD_BYTES) {
+        const { rawRequest: _rq, rawResponse: _rr, ...rest } = record;
+        line = JSON.stringify({ ...rest, truncated: 'raw bodies dropped (record exceeded size guard)' });
+      }
+      appendFileSync(this.logPath, line + '\n');
+    } catch {
+      // Logging must never break inference.
+    }
+  }
+
+  private record(
+    kind: 'complete' | 'stream',
+    request: ProviderRequest,
+    started: number,
+    response?: ProviderResponse,
+    error?: unknown,
+  ): void {
+    this.log({
+      type: error === undefined ? 'call' : 'error',
+      provider: this.name,
+      kind,
+      timestamp: new Date(started).toISOString(),
+      durationMs: Date.now() - started,
+      requestSummary: summarizeRequest(request),
+      rawRequest: request,
+      ...(response !== undefined
+        ? { response: summarizeResponse(response), rawResponse: response.raw ?? null }
+        : {}),
+      ...(error !== undefined
+        ? { error: error instanceof Error ? `${error.name}: ${error.message}` : String(error) }
+        : {}),
+    });
+  }
+
+  async complete(
+    request: ProviderRequest,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    try {
+      const response = await this.inner.complete(request, options);
+      this.record('complete', request, started, response);
+      return response;
+    } catch (error) {
+      this.record('complete', request, started, undefined, error);
+      throw error;
+    }
+  }
+
+  async stream(
+    request: ProviderRequest,
+    callbacks: StreamCallbacks,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const started = Date.now();
+    try {
+      const response = await this.inner.stream(request, callbacks, options);
+      this.record('stream', request, started, response);
+      return response;
+    } catch (error) {
+      this.record('stream', request, started, undefined, error);
+      throw error;
+    }
+  }
+}

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();