@animalabs/connectome-host 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -1,7 +1,54 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 — 2026-07-26
+
+### Added
+
+- **Pins panel** — operator control over protected ranges, using the pin surface
+  that already existed in context-manager (`pinRange` / `markDocument` / `unpin`
+  / `listPins`). No cm or af change was needed.
+  - Three semantics kept visibly distinct rather than collapsed into one "pin",
+    because they do different things to the fold plan: **raw** (never folded),
+    **max L<sub>k</sub>** (fold no deeper than k; k=0 ≡ raw), and **at
+    L<sub>k</sub>** (pinned at exactly k — the frontier cut passes through that
+    node).
+  - `at L_k` is honored **only** by `foldingStrategy: 'kv-stable'`; elsewhere it
+    degrades to raw. The panel detects this and warns, rather than letting a
+    request silently mean something else.
+  - Ids are pickable from `/debug/context/curve` (~14ms, the cheapest debug
+    endpoint and the only one exposing per-entry store ids with a text preview),
+    so ranges are selected from the live context instead of pasted by hand.
+    Entries without a store id — merged summaries — are omitted, since a pin
+    needs a message id.
+  - New `request-pins` / `pin-add` / `pin-remove`, server frame `pins-list`,
+    broadcast on change like `settings-state`: pins alter what the next compile
+    folds, so operators must not hold divergent views. Full-auth only via
+    `observerMaySend`'s default-deny. `level` and `maxLevel` together is rejected
+    at the wire as ambiguous.
+  - Pins take effect on the next compile — no restart — and pair with dry run,
+    which is now ~1.6s rather than minutes.
+
+### Fixed
+
+- Dry-run cost text said "~8s"; measured ~1.6s after the context-manager solver
+  fixes. Corrected rather than left pessimistic.
+
 ## 0.5.4 — 2026-07-26
 
+### Corrected after release
+
+- The `0.5.4` note below claimed the entry projection fixed the 110s stall. **It
+  did not.** Re-measuring after the change showed 121,855ms — unchanged. The
+  projection cut payload (megabytes → 265KB) and removed the blob-inlining heap
+  exposure, both worth keeping, but the time was never serialization. The actual
+  cause was an O(members × groupSize) cliff in three kv-control solver loops,
+  triggered whenever a head/tail boundary falls inside a deep summary group —
+  fixed in context-manager (`1c4c436`, `7f2d5e1`; see
+  `docs/incremental-compile-problem.md` §9.3). Measured after that fix: dry run
+  **1.56s**, dry run + render **1.69s**, live compile 22.5s → 2.4s.
+
 ### Fixed
 
 - **`dry run + show context` was a 110-second agent stall.** Measured 110,348ms

package/package.json

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

package/src/index.ts

@@ -448,6 +448,8 @@ agents: [agentConfig],
     mcplServers: finalServers,
     gate: gateOptions,
     timeZone,
+    // Client-side programmatic tool calling (code_execution) — recipe opt-in.
+    ...(recipe.codeExecution ? { codeExecution: recipe.codeExecution } : {}),
   });
 
   // Wire post-creation hooks

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

@@ -59,6 +59,7 @@ import {
   type CallLedgerSnapshot,
   type McplListMessage,
   type SettingsStateMessage,
+  type PinsListMessage,
   type BranchesListMessage,
   type LessonsListMessage,
 } from '../web/protocol.js';
@@ -1977,6 +1978,64 @@ export class WebUiModule implements Module {
         return;
       }
 
+      case 'request-pins': {
+        const msg = this.buildPinsList(this.resolveSettingsAgent(parsed.agent));
+        if (!msg) {
+          this.send(client, { type: 'error', message: 'pins unavailable on this build' });
+          return;
+        }
+        this.send(client, msg);
+        return;
+      }
+
+      // Pins change what the NEXT compile folds, so like settings these
+      // broadcast rather than replying to the requester only.
+      case 'pin-add': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const cm = this.pinnableCm(agentName);
+          const opts: Record<string, unknown> = {};
+          if (parsed.name !== undefined) opts.name = parsed.name;
+          if (parsed.level !== undefined) opts.level = parsed.level;
+          if (parsed.maxLevel !== undefined) opts.maxLevel = parsed.maxLevel;
+          if (parsed.kind === 'document') {
+            cm.markDocument!(parsed.firstMessageId, opts);
+          } else {
+            // A single-message pin is a range of one; the strategy takes both ends.
+            cm.pinRange!(parsed.firstMessageId, parsed.lastMessageId ?? parsed.firstMessageId, opts);
+          }
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `pin-add failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        this.broadcastPinsList(agentName);
+        return;
+      }
+
+      case 'pin-remove': {
+        const agentName = this.resolveSettingsAgent(parsed.agent);
+        try {
+          const cm = this.pinnableCm(agentName);
+          const ok = cm.unpin!(parsed.pinId);
+          if (!ok) {
+            // Not an exception: a stale panel can ask twice. Say so plainly and
+            // still re-broadcast, so the client converges on reality.
+            this.send(client, { type: 'error', message: `no such pin: ${parsed.pinId}` });
+          }
+        } catch (err) {
+          this.send(client, {
+            type: 'error',
+            message: `pin-remove failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          return;
+        }
+        this.broadcastPinsList(agentName);
+        return;
+      }
+
       case 'request-settings': {
         this.sendSettingsState(client, parsed.agent);
         return;
@@ -1988,10 +2047,11 @@ export class WebUiModule implements Module {
       case 'settings-update': {
         const agentName = this.resolveSettingsAgent(parsed.agent);
         try {
-          const patch: Record<string, number> = {};
+          const patch: Record<string, number | boolean> = {};
           if (parsed.contextBudgetTokens !== undefined) patch.contextBudgetTokens = parsed.contextBudgetTokens;
           if (parsed.tailTokens !== undefined) patch.tailTokens = parsed.tailTokens;
           if (parsed.transitionPaceTokens !== undefined) patch.transitionPaceTokens = parsed.transitionPaceTokens;
+          if (parsed.immediate !== undefined) patch.immediate = parsed.immediate;
           const fw = sharedServer!.app.framework as unknown as {
             updateAgentRuntimeSettings: (n: string, p: unknown, o?: { persist?: boolean }) => unknown;
           };
@@ -2712,6 +2772,98 @@ export class WebUiModule implements Module {
     }
   }
 
+  /** Duck-typed pin surface. Throws with a clear reason rather than returning a
+   *  half-usable object, so handlers can report it to the operator verbatim. */
+  private pinnableCm(agentName: string): {
+    pinRange?: (a: string, b: string, o?: unknown) => string;
+    markDocument?: (a: string, o?: unknown) => string;
+    unpin?: (id: string) => boolean;
+    listPins?: () => ReadonlyArray<Record<string, unknown>>;
+  } {
+    const app = sharedServer?.app;
+    if (!app) throw new Error('app not bound yet');
+    const agent = app.framework.getAgent(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    const cm = agent.getContextManager() as unknown as {
+      pinRange?: (a: string, b: string, o?: unknown) => string;
+      markDocument?: (a: string, o?: unknown) => string;
+      unpin?: (id: string) => boolean;
+      listPins?: () => ReadonlyArray<Record<string, unknown>>;
+    };
+    if (typeof cm.listPins !== 'function' || typeof cm.pinRange !== 'function') {
+      throw new Error('the active context strategy does not support pins');
+    }
+    return cm;
+  }
+
+  /**
+   * Pin snapshot. Never throws — an unsupported strategy is a legitimate
+   * read-only state for the panel, not an error to surface.
+   *
+   * `levelHonored` matters: pin-AT-level is implemented only by the kv-stable
+   * controller. Elsewhere it degrades to raw, which is a safe superset but not
+   * what the operator asked for, so the UI needs to be able to say so.
+   */
+  private buildPinsList(agentName: string): PinsListMessage | null {
+    const app = sharedServer?.app;
+    if (!app) return null;
+    let pins: PinsListMessage['pins'] = [];
+    let supported = false;
+    try {
+      const cm = this.pinnableCm(agentName);
+      pins = (cm.listPins!() ?? []).map((p) => ({
+        id: String(p.id),
+        firstMessageId: String(p.firstMessageId),
+        lastMessageId: String(p.lastMessageId),
+        kind: p.kind === 'document' ? 'document' : 'pin',
+        ...(typeof p.name === 'string' ? { name: p.name } : {}),
+        created: typeof p.created === 'number' ? p.created : 0,
+        ...(typeof p.level === 'number' ? { level: p.level } : {}),
+        ...(typeof p.maxLevel === 'number' ? { maxLevel: p.maxLevel } : {}),
+      }));
+      supported = true;
+    } catch {
+      supported = false;
+    }
+
+    let levelHonored = false;
+    let deepestLevel: number | undefined;
+    try {
+      const strategyCfg = (app.recipe.agent as unknown as {
+        strategy?: { foldingStrategy?: string };
+      }).strategy;
+      levelHonored = strategyCfg?.foldingStrategy === 'kv-stable';
+      const agent = app.framework.getAgent(agentName);
+      const cm = agent?.getContextManager() as unknown as {
+        getSummaries?: () => Array<{ level?: number }>;
+      } | undefined;
+      const sums = cm?.getSummaries?.() ?? [];
+      for (const s of sums) {
+        if (typeof s.level === 'number' && (deepestLevel === undefined || s.level > deepestLevel)) {
+          deepestLevel = s.level;
+        }
+      }
+    } catch { /* informational only */ }
+
+    return {
+      type: 'pins-list',
+      agent: agentName,
+      pins,
+      pinsSupported: supported,
+      levelHonored,
+      ...(deepestLevel !== undefined ? { deepestLevel } : {}),
+    };
+  }
+
+  private broadcastPinsList(agentName: string): void {
+    if (!sharedServer?.app) return;
+    const msg = this.buildPinsList(agentName);
+    if (!msg) return;
+    for (const c of sharedServer.clients.values()) {
+      if (c.welcomed) this.send(c, msg);
+    }
+  }
+
   /** Default to the recipe's primary agent when the client omits a name. */
   private resolveSettingsAgent(name?: string): string {
     if (name) return name;

package/src/recipe.ts

@@ -602,6 +602,27 @@ export interface RecipeExtension {
   sourceMeta?: Record<string, unknown>;
 }
 
+/**
+ * Client-side programmatic tool calling (af `code_execution` tool, af ≥0.7.2).
+ *
+ * SECURITY: like mcpl_deploy, enabling this means trusting the agent with
+ * code execution — model-authored python runs as the host user with the
+ * agent's full tool surface injected. It is a robustness boundary (deadline,
+ * kill, respawn), not a sandbox. The agents we host already have shells;
+ * enable deliberately all the same.
+ */
+export interface RecipeCodeExecution {
+  enabled: boolean;
+  /** Python interpreter (default: python3 from PATH; needs ≥3.8). */
+  pythonPath?: string;
+  /** Per-inner-tool-call timeout, ms (default 270_000). */
+  toolCallTimeoutMs?: number;
+  /** Whole-script deadline, ms (default 600_000). */
+  scriptTimeoutMs?: number;
+  /** Idle interpreter reclaim, ms (default 300_000; 0 disables). */
+  idleReclaimMs?: number;
+}
+
 export interface Recipe {
   name: string;
   description?: string;
@@ -612,6 +633,8 @@ export interface Recipe {
   /** Deployment-specific code extensions, keyed by a human-readable name. */
   extensions?: Record<string, RecipeExtension>;
   sessionNaming?: { examples?: string[] };
+  /** Client-side programmatic tool calling (code_execution tool). */
+  codeExecution?: RecipeCodeExecution;
 }
 
 // ---------------------------------------------------------------------------
@@ -1234,6 +1257,24 @@ export function validateRecipe(raw: unknown): Recipe {
     }
   }
 
+  if (obj.codeExecution !== undefined) {
+    if (!obj.codeExecution || typeof obj.codeExecution !== 'object' || Array.isArray(obj.codeExecution)) {
+      throw new Error('Recipe codeExecution must be an object.');
+    }
+    const ce = obj.codeExecution as Record<string, unknown>;
+    if (typeof ce.enabled !== 'boolean') {
+      throw new Error('Recipe codeExecution.enabled must be a boolean.');
+    }
+    if (ce.pythonPath !== undefined && (typeof ce.pythonPath !== 'string' || !ce.pythonPath.trim())) {
+      throw new Error('Recipe codeExecution.pythonPath must be a non-empty string.');
+    }
+    for (const k of ['toolCallTimeoutMs', 'scriptTimeoutMs', 'idleReclaimMs'] as const) {
+      if (ce[k] !== undefined && (typeof ce[k] !== 'number' || (ce[k] as number) < 0)) {
+        throw new Error(`Recipe codeExecution.${k} must be a non-negative number.`);
+      }
+    }
+  }
+
   return obj as unknown as Recipe;
 }
 

package/src/web/protocol.ts

@@ -391,6 +391,35 @@ export interface McplListMessage {
   }>;
 }
 
+/**
+ * Protected ranges (pins / documents) for one agent.
+ *
+ * BROADCAST on change: pins alter what the next compile folds, so two operators
+ * must not hold divergent views of them.
+ */
+export interface PinsListMessage {
+  type: 'pins-list';
+  agent: string;
+  pins: Array<{
+    id: string;
+    firstMessageId: string;
+    lastMessageId: string;
+    kind: 'pin' | 'document';
+    name?: string;
+    created: number;
+    /** Pinned AT exactly this fold level (0 = raw). */
+    level?: number;
+    /** Hard cap on fold depth. */
+    maxLevel?: number;
+  }>;
+  /** False when the active strategy has no pin support — panel goes read-only. */
+  pinsSupported: boolean;
+  /** False when `level` would silently degrade to raw (non-kv-stable folding). */
+  levelHonored: boolean;
+  /** Deepest fold level currently present, so the UI can bound level inputs. */
+  deepestLevel?: number;
+}
+
 /**
  * Runtime context-settings snapshot.
  *
@@ -510,6 +539,7 @@ export type WebUiServerMessage =
   | LessonsListMessage
   | McplListMessage
   | SettingsStateMessage
+  | PinsListMessage
   | WorkspaceMountsMessage
   | WorkspaceTreeMessage
   | WorkspaceFileMessage
@@ -669,6 +699,46 @@ export interface McplSetEnvMessage {
   env: Record<string, string>;
 }
 
+/** Pull the agent's protected ranges. Response is a `pins-list` envelope. */
+export interface RequestPinsMessage {
+  type: 'request-pins';
+  agent?: string;
+}
+
+/**
+ * Create a protected range.
+ *
+ * Three distinct semantics, deliberately not collapsed into one "pin":
+ *  - neither `level` nor `maxLevel` → classic pin: forced RAW, never folded
+ *  - `maxLevel: k` → fold no deeper than L_k (`0` is equivalent to a classic pin)
+ *  - `level: k`    → pin AT exactly L_k; the frontier cut passes through that
+ *                    node, neither deeper nor shallower
+ *
+ * `kind: 'document'` marks a single message as a document instead of pinning a
+ * range, and ignores `lastMessageId`.
+ *
+ * NOTE: `level` is honored only by `foldingStrategy: 'kv-stable'`. Other
+ * strategies degrade it to raw — a safe superset, but not what was asked for.
+ * `pins-list.levelHonored` reports which case the live agent is in.
+ */
+export interface PinAddMessage {
+  type: 'pin-add';
+  agent?: string;
+  kind?: 'pin' | 'document';
+  firstMessageId: string;
+  /** Ignored for `kind: 'document'`; defaults to `firstMessageId` for a pin. */
+  lastMessageId?: string;
+  level?: number;
+  maxLevel?: number;
+  name?: string;
+}
+
+export interface PinRemoveMessage {
+  type: 'pin-remove';
+  agent?: string;
+  pinId: 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 {
@@ -701,6 +771,10 @@ export interface SettingsUpdateMessage {
   contextBudgetTokens?: number;
   tailTokens?: number;
   transitionPaceTokens?: number;
+  /** Apply a budget DECREASE immediately (one-shot fold-down, KV
+   *  invalidation paid this turn) instead of starting a paced descent.
+   *  The emergency lever for refusal streaks / over-wall wedges. */
+  immediate?: boolean;
   persist?: boolean;
   notify?: boolean;
 }
@@ -794,6 +868,9 @@ export type WebUiClientMessage =
   | McplAddMessage
   | McplRemoveMessage
   | McplSetEnvMessage
+  | RequestPinsMessage
+  | PinAddMessage
+  | PinRemoveMessage
   | RequestSettingsMessage
   | SettingsUpdateMessage
   | SettingsResetMessage
@@ -860,11 +937,32 @@ 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-pins':
+      return isOptionalNonEmptyString(v.agent);
+    case 'pin-add': {
+      if (!isOptionalNonEmptyString(v.agent)) return false;
+      if (!isNonEmptyString(v.firstMessageId)) return false;
+      if (v.lastMessageId !== undefined && !isNonEmptyString(v.lastMessageId)) return false;
+      if (v.kind !== undefined && v.kind !== 'pin' && v.kind !== 'document') return false;
+      if (v.name !== undefined && !isNonEmptyString(v.name)) return false;
+      // Fold levels are small non-negative integers (0 = raw). Reject strings
+      // and fractions before they reach the strategy's pin normalizer.
+      for (const k of ['level', 'maxLevel']) {
+        const x = v[k];
+        if (x === undefined) continue;
+        if (typeof x !== 'number' || !Number.isSafeInteger(x) || x < 0 || x > 32) return false;
+      }
+      // level and maxLevel are different semantics; asking for both is ambiguous.
+      if (v.level !== undefined && v.maxLevel !== undefined) return false;
+      return true;
+    }
+    case 'pin-remove':
+      return isOptionalNonEmptyString(v.agent) && isNonEmptyString(v.pinId);
     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;
+      if (!isOptionalBool(v.persist) || !isOptionalBool(v.notify) || !isOptionalBool(v.immediate)) 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

package/test/settings-protocol.test.ts

@@ -62,3 +62,40 @@ describe('settings messages — wire validation', () => {
     expect(isClientMessage({ type: 'request-settings', agent: 7 })).toBe(false);
   });
 });
+
+describe('pin messages — wire validation', () => {
+  it('accepts a single-message raw pin', () => {
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1' })).toBe(true);
+  });
+
+  it('accepts a range, a document, a label, and level modes', () => {
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', lastMessageId: 'm-9' })).toBe(true);
+    expect(isClientMessage({ type: 'pin-add', kind: 'document', firstMessageId: 'm-1' })).toBe(true);
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', name: 'seed' })).toBe(true);
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', level: 0 })).toBe(true);
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', maxLevel: 2 })).toBe(true);
+  });
+
+  it('rejects level AND maxLevel together — different semantics, ambiguous intent', () => {
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', level: 1, maxLevel: 2 })).toBe(false);
+  });
+
+  it('rejects bad levels and bad ids', () => {
+    for (const bad of ['1', 1.5, -1, 33, NaN, null, {}]) {
+      expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', level: bad })).toBe(false);
+    }
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: '' })).toBe(false);
+    expect(isClientMessage({ type: 'pin-add' })).toBe(false);
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', kind: 'bogus' })).toBe(false);
+    expect(isClientMessage({ type: 'pin-add', firstMessageId: 'm-1', lastMessageId: '' })).toBe(false);
+  });
+
+  it('validates pin-remove and request-pins', () => {
+    expect(isClientMessage({ type: 'pin-remove', pinId: 'pin-3' })).toBe(true);
+    expect(isClientMessage({ type: 'pin-remove' })).toBe(false);
+    expect(isClientMessage({ type: 'pin-remove', pinId: '' })).toBe(false);
+    expect(isClientMessage({ type: 'request-pins' })).toBe(true);
+    expect(isClientMessage({ type: 'request-pins', agent: 'mythos' })).toBe(true);
+    expect(isClientMessage({ type: 'request-pins', agent: 5 })).toBe(false);
+  });
+});

package/web/src/App.tsx

@@ -11,6 +11,7 @@ import { LessonsPanel, type LessonRow } from './Lessons';
 import { McplPanel, type McplServerRow } from './Mcpl';
 import { SettingsPanel, type SettingsState } from './Settings';
 import { DryContext, type DryContextData } from './DryContext';
+import { PinsPanel, type PinsState } from './Pins';
 import { FilesPanel, FileViewerModal, type Mount, type FlatEntry, type FileViewer } from './Files';
 import { ContextPanel } from './Context';
 import { ContextDocument } from './ContextDocument';
@@ -274,7 +275,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' | 'settings' | 'health';
+  type SidebarTab = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'pins' | 'health';
   const [sidebarTab, setSidebarTab] = createSignal<SidebarTab>('tree');
   const [mainView, setMainView] = createSignal<'chat' | 'context' | 'dry'>('chat');
   /** Rendered dry-run context awaiting display. Never applied — see DryContext. */
@@ -325,6 +326,15 @@ export function App() {
     wire.send({ type: 'request-settings' });
   };
 
+  /** Pins panel state — broadcast on change, like settings: pins alter the next
+   *  compile's fold plan, so operators must not hold divergent views. */
+  const [pinsState, setPinsState] = createSignal<PinsState | null>(null);
+  const [pinsLoaded, setPinsLoaded] = createSignal(false);
+  const refreshPins = (): void => {
+    setPinsLoaded(false);
+    wire.send({ type: 'request-pins' });
+  };
+
   /** Workspace files panel state — mounts list + per-mount tree cache. */
   const [mounts, setMounts] = createSignal<Mount[]>([]);
   const [mountsLoaded, setMountsLoaded] = createSignal(false);
@@ -894,6 +904,10 @@ export function App() {
           setSettingsLoaded(true);
           setSettingsState(state);
         },
+        setPins: (state) => {
+          setPinsLoaded(true);
+          setPinsState(state);
+        },
         setMounts: (loaded, moduleLoaded, list) => {
           setMountsLoaded(loaded);
           setWorkspaceModuleLoaded(moduleLoaded);
@@ -1201,6 +1215,7 @@ export function App() {
               if (tab === 'mcp' && !mcplLoaded()) refreshMcpl();
               if (tab === 'files' && !mountsLoaded()) refreshMounts();
               if (tab === 'settings' && !settingsLoaded()) refreshSettings();
+              if (tab === 'pins' && !pinsLoaded()) refreshPins();
             }}
           />
           <div class="flex-1 min-h-0">
@@ -1251,6 +1266,16 @@ export function App() {
                 onDryContext={(ctx) => { setDryContext(ctx as DryContextData); setMainView('dry'); }}
               />
             </Show>
+            <Show when={sidebarTab() === 'pins'}>
+              <PinsPanel
+                loaded={pinsLoaded()}
+                state={pinsState()}
+                agent={pinsState()?.agent}
+                onRefresh={refreshPins}
+                onAdd={(input) => wire.send({ type: 'pin-add', ...input })}
+                onRemove={(pinId) => wire.send({ type: 'pin-remove', pinId })}
+              />
+            </Show>
             <Show when={sidebarTab() === 'files'}>
               <FilesPanel
                 loaded={mountsLoaded()}
@@ -1323,6 +1348,8 @@ interface HandlerHooks {
   setMcpl: (configPath: string, servers: McplServerRow[]) => void;
   /** Apply a settings-state broadcast. */
   setSettings: (state: SettingsState) => void;
+  /** Apply a pins-list broadcast. */
+  setPins: (state: PinsState) => void;
   /** Apply a workspace-mounts response. */
   setMounts: (loaded: boolean, moduleLoaded: boolean, mounts: Mount[]) => void;
   /** Apply a workspace-tree response for one mount. */
@@ -1456,6 +1483,9 @@ function handleServerMessage(
     case 'settings-state':
       hooks.setSettings(msg as unknown as SettingsState);
       return;
+    case 'pins-list':
+      hooks.setPins(msg as unknown as PinsState);
+      return;
     case 'workspace-mounts':
       hooks.setMounts(true, msg.loaded, msg.mounts);
       return;
@@ -1986,7 +2016,7 @@ function CommandSuggestions(props: { draft: string; onPick: (cmd: string) => voi
   );
 }
 
-type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'health';
+type SidebarTabId = 'tree' | 'lessons' | 'mcp' | 'files' | 'context' | 'settings' | 'pins' | 'health';
 
 function SidebarTabs(props: {
   current: SidebarTabId;
@@ -1999,6 +2029,7 @@ function SidebarTabs(props: {
     { 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: 'pins', label: 'Pins', title: 'Protected ranges — constrain what the fold plan may fold' },
     { id: 'health', label: 'Health', title: 'Runtime settings, failures, quarantine' },
   ];
   return (

package/web/src/Pins.tsx

@@ -0,0 +1,318 @@
+/**
+ * Pins panel — operator control over protected ranges.
+ *
+ * Three semantics, kept visibly distinct because collapsing them into one
+ * "pin" button would hide what actually happens to the fold plan:
+ *
+ *   raw        — never folded (classic pin)
+ *   max L_k    — fold no deeper than k (k=0 is equivalent to raw)
+ *   at L_k     — pinned AT exactly k; the frontier cut passes through that node
+ *
+ * `at L_k` is honored only by the kv-stable folding strategy. Elsewhere it
+ * degrades to raw — a safe superset, but not what was asked for — so the panel
+ * warns rather than letting it pass silently.
+ *
+ * Message ids come from /debug/context/curve (cheap: ~14ms) so the operator
+ * picks from the live context instead of pasting ids.
+ */
+
+import { createSignal, For, Show } from 'solid-js';
+
+export interface PinRow {
+  id: string;
+  firstMessageId: string;
+  lastMessageId: string;
+  kind: 'pin' | 'document';
+  name?: string;
+  created: number;
+  level?: number;
+  maxLevel?: number;
+}
+
+export interface PinsState {
+  agent: string;
+  pins: PinRow[];
+  pinsSupported: boolean;
+  levelHonored: boolean;
+  deepestLevel?: number;
+}
+
+interface CurveEntry {
+  i: number;
+  kind: string;
+  id: string | null;
+  participant?: string;
+  rendered?: number;
+  msgCount?: number;
+  text?: string;
+}
+
+const ago = (ms: number) => {
+  if (!ms) return '—';
+  const s = Math.max(0, Math.round((Date.now() - ms) / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.round(s / 60)}m`;
+  if (s < 86400) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+};
+
+/** What the fold plan will actually do with this range. */
+function describe(p: PinRow): string {
+  if (p.level !== undefined) return p.level === 0 ? 'at raw' : `at L${p.level}`;
+  if (p.maxLevel !== undefined) return p.maxLevel === 0 ? 'raw (max L0)' : `max L${p.maxLevel}`;
+  return 'raw';
+}
+
+export function PinsPanel(props: {
+  loaded: boolean;
+  state: PinsState | null;
+  agent?: string;
+  onRefresh(): void;
+  onAdd(input: {
+    kind: 'pin' | 'document';
+    firstMessageId: string;
+    lastMessageId?: string;
+    level?: number;
+    maxLevel?: number;
+    name?: string;
+  }): void;
+  onRemove(pinId: string): void;
+}) {
+  const [first, setFirst] = createSignal('');
+  const [last, setLast] = createSignal('');
+  const [name, setName] = createSignal('');
+  const [mode, setMode] = createSignal<'raw' | 'max' | 'at'>('raw');
+  const [lvl, setLvl] = createSignal('1');
+  const [asDoc, setAsDoc] = createSignal(false);
+
+  const [curve, setCurve] = createSignal<CurveEntry[] | null>(null);
+  const [curveErr, setCurveErr] = createSignal<string | null>(null);
+  const [picking, setPicking] = createSignal(false);
+
+  /** /debug/context/curve is the cheap endpoint (~14ms) and the only one that
+   *  exposes per-entry store ids alongside a text preview. */
+  const loadCurve = async () => {
+    setPicking(true);
+    setCurveErr(null);
+    try {
+      const qs = props.agent ? `?agent=${encodeURIComponent(props.agent)}` : '';
+      const res = await fetch(`/debug/context/curve${qs}`, { credentials: 'same-origin' });
+      const body = await res.json();
+      if (!res.ok) { setCurveErr(body?.error ?? `HTTP ${res.status}`); return; }
+      setCurve((body.entries ?? []) as CurveEntry[]);
+    } catch (e) {
+      setCurveErr(e instanceof Error ? e.message : String(e));
+    } finally {
+      setPicking(false);
+    }
+  };
+
+  const submit = () => {
+    const f = first().trim();
+    if (!f) return;
+    const n = Number(lvl());
+    const levelOk = Number.isSafeInteger(n) && n >= 0 && n <= 32;
+    props.onAdd({
+      kind: asDoc() ? 'document' : 'pin',
+      firstMessageId: f,
+      ...(asDoc() || !last().trim() ? {} : { lastMessageId: last().trim() }),
+      ...(mode() === 'at' && levelOk ? { level: n } : {}),
+      ...(mode() === 'max' && levelOk ? { maxLevel: n } : {}),
+      ...(name().trim() ? { name: name().trim() } : {}),
+    });
+    setFirst(''); setLast(''); setName('');
+  };
+
+  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">pins</span>
+        <Show when={props.state}>
+          <span class="text-neutral-600 text-[10px]">{props.state!.pins.length}</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()}
+        >
+          refresh
+        </button>
+      </div>
+
+      <Show when={!props.loaded}><div class="text-neutral-600 italic">Loading…</div></Show>
+
+      <Show when={props.state && !props.state.pinsSupported}>
+        <div class="text-amber-400/80 text-[11px]">
+          The active context strategy does not support pins.
+        </div>
+      </Show>
+
+      <Show when={props.state?.pinsSupported}>
+        <div class="text-[10px] text-neutral-600 mb-2 leading-relaxed">
+          Pins constrain the fold plan and take effect on the <b>next compile</b> — no restart.
+          They persist and are branch-scoped. Pair with a dry run to see the effect before it
+          reaches a real turn.
+        </div>
+
+        <Show when={!props.state!.levelHonored}>
+          <div class="mb-2 px-2 py-1 rounded bg-amber-950/40 border border-amber-800
+                      text-[10px] text-amber-200 leading-relaxed">
+            This agent is not on <span class="font-mono">kv-stable</span> folding, so
+            <b> "at L<sub>k</sub>" degrades to raw</b> — a safe superset, but not what you asked
+            for. Prefer <span class="font-mono">raw</span> or <span class="font-mono">max L</span>
+            here.
+          </div>
+        </Show>
+
+        {/* ---- existing pins ---- */}
+        <Show when={props.state!.pins.length === 0}>
+          <div class="text-neutral-600 italic mb-3">No pins.</div>
+        </Show>
+        <Show when={props.state!.pins.length > 0}>
+          <table class="w-full mb-3 font-mono text-[10px]">
+            <tbody>
+              <For each={props.state!.pins}>
+                {(p) => (
+                  <tr class="border-b border-neutral-900">
+                    <td class="pr-1 align-top">
+                      <span class={p.kind === 'document' ? 'text-indigo-300' : 'text-cyan-300'}>
+                        {p.kind === 'document' ? 'doc' : 'pin'}
+                      </span>
+                    </td>
+                    <td class="pr-1 align-top text-neutral-200">{describe(p)}</td>
+                    <td class="pr-1 align-top text-neutral-400 break-all">
+                      {p.firstMessageId}
+                      <Show when={p.lastMessageId !== p.firstMessageId}>
+                        <span class="text-neutral-600"> → {p.lastMessageId}</span>
+                      </Show>
+                      <Show when={p.name}>
+                        <div class="text-neutral-500">“{p.name}”</div>
+                      </Show>
+                    </td>
+                    <td class="pr-1 align-top text-neutral-600">{ago(p.created)}</td>
+                    <td class="align-top text-right">
+                      <button
+                        type="button"
+                        class="px-1.5 py-0.5 rounded bg-neutral-800 hover:bg-red-900/60
+                               text-neutral-400 hover:text-red-200"
+                        title={`unpin ${p.id}`}
+                        onClick={() => props.onRemove(p.id)}
+                      >
+                        unpin
+                      </button>
+                    </td>
+                  </tr>
+                )}
+              </For>
+            </tbody>
+          </table>
+        </Show>
+
+        {/* ---- add ---- */}
+        <div class="border-t border-neutral-800 pt-2">
+          <div class="text-neutral-500 uppercase tracking-wider text-[10px] font-semibold mb-1.5">
+            add
+          </div>
+
+          <div class="space-y-1.5 mb-2">
+            <label class="flex items-center gap-2">
+              <span class="text-neutral-500 w-10">from</span>
+              <input value={first()} onInput={(e) => setFirst(e.currentTarget.value)}
+                placeholder="message id"
+                class="flex-1 bg-neutral-900 border border-neutral-700 rounded px-1.5 py-0.5
+                       font-mono text-[11px] text-neutral-100" />
+            </label>
+            <label class="flex items-center gap-2" title={asDoc() ? 'documents cover a single message' : ''}>
+              <span class="text-neutral-500 w-10">to</span>
+              <input value={last()} disabled={asDoc()}
+                onInput={(e) => setLast(e.currentTarget.value)}
+                placeholder={asDoc() ? 'n/a for documents' : 'optional — defaults to “from”'}
+                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>
+            <label class="flex items-center gap-2">
+              <span class="text-neutral-500 w-10">label</span>
+              <input value={name()} onInput={(e) => setName(e.currentTarget.value)}
+                placeholder="optional"
+                class="flex-1 bg-neutral-900 border border-neutral-700 rounded px-1.5 py-0.5
+                       font-mono text-[11px] text-neutral-100" />
+            </label>
+          </div>
+
+          <div class="flex items-center gap-3 mb-2 text-[10px] text-neutral-400 flex-wrap">
+            <For each={[['raw', 'raw'], ['max', 'max L'], ['at', 'at L']] as Array<[string, string]>}>
+              {([v, label]) => (
+                <label class="flex items-center gap-1">
+                  <input type="radio" name="pinmode" checked={mode() === v}
+                    onChange={() => setMode(v as 'raw' | 'max' | 'at')} />
+                  {label}
+                </label>
+              )}
+            </For>
+            <Show when={mode() !== 'raw'}>
+              <input type="number" min="0" max={props.state!.deepestLevel ?? 8}
+                value={lvl()} onInput={(e) => setLvl(e.currentTarget.value)}
+                class="w-14 bg-neutral-900 border border-neutral-700 rounded px-1 py-0.5
+                       font-mono text-[11px] text-neutral-100" />
+              <Show when={props.state!.deepestLevel !== undefined}>
+                <span class="text-neutral-600">deepest present: L{props.state!.deepestLevel}</span>
+              </Show>
+            </Show>
+            <label class="flex items-center gap-1">
+              <input type="checkbox" checked={asDoc()} onChange={(e) => setAsDoc(e.currentTarget.checked)} />
+              as document
+            </label>
+          </div>
+
+          <div class="flex items-center gap-2 mb-3">
+            <button type="button" disabled={!first().trim()}
+              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"
+              onClick={submit}>
+              add pin
+            </button>
+            <button type="button"
+              class="px-2 py-0.5 text-[10px] rounded font-mono bg-neutral-800 hover:bg-neutral-700 text-neutral-300"
+              onClick={() => void loadCurve()}>
+              {picking() ? 'loading…' : curve() ? 'reload ids' : 'pick from context'}
+            </button>
+          </div>
+
+          <Show when={curveErr()}>
+            <div class="text-[10px] text-amber-400/90 mb-2">{curveErr()}</div>
+          </Show>
+
+          {/* ---- id picker ---- */}
+          <Show when={curve()}>
+            <div class="max-h-64 overflow-y-auto border border-neutral-800 rounded">
+              <For each={curve()!.filter((e) => e.id)}>
+                {(e) => (
+                  <div class="flex items-start gap-1.5 px-1.5 py-1 border-b border-neutral-900
+                              hover:bg-neutral-900/60">
+                    <span class="text-[9px] font-mono text-neutral-600 w-8 shrink-0">#{e.i}</span>
+                    <span class={`text-[9px] font-mono w-8 shrink-0 ${
+                      e.kind === 'raw' ? 'text-emerald-400/80' : 'text-orange-400/80'
+                    }`}>{e.kind}</span>
+                    <span class="text-[10px] text-neutral-400 flex-1 truncate"
+                      title={e.text ?? ''}>{(e.text ?? '').slice(0, 90)}</span>
+                    <button type="button"
+                      class="text-[9px] font-mono px-1 rounded bg-neutral-800 hover:bg-neutral-700
+                             text-neutral-400 shrink-0"
+                      onClick={() => setFirst(e.id!)}>from</button>
+                    <button type="button" disabled={asDoc()}
+                      class="text-[9px] font-mono px-1 rounded bg-neutral-800 hover:bg-neutral-700
+                             text-neutral-400 shrink-0 disabled:opacity-30"
+                      onClick={() => setLast(e.id!)}>to</button>
+                  </div>
+                )}
+              </For>
+            </div>
+            <div class="text-[10px] text-neutral-600 mt-1">
+              Entries without a store id (merged summaries) are omitted — a pin needs a message id.
+            </div>
+          </Show>
+        </div>
+      </Show>
+    </div>
+  );
+}

package/web/src/Settings.tsx

@@ -96,6 +96,7 @@ export function SettingsPanel(props: {
     contextBudgetTokens?: number;
     tailTokens?: number;
     transitionPaceTokens?: number;
+    immediate?: boolean;
     persist: boolean;
     notify: boolean;
   }): void;
@@ -109,6 +110,7 @@ export function SettingsPanel(props: {
   const [pace, setPace] = createSignal<string>('');
   const [persist, setPersist] = createSignal(true);
   const [notify, setNotify] = createSignal(false);
+  const [immediate, setImmediate] = createSignal(false);
 
   const [preview, setPreview] = createSignal<PreviewResult | null>(null);
   const [acct, setAcct] = createSignal<PreviewAccounting | null>(null);
@@ -196,7 +198,12 @@ export function SettingsPanel(props: {
     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() });
+    props.onApply({
+      ...patch,
+      ...(lowering() && immediate() ? { immediate: true } : {}),
+      persist: persist(),
+      notify: notify(),
+    });
   };
 
   const lowering = () => {
@@ -339,10 +346,26 @@ export function SettingsPanel(props: {
             <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>
+            <label
+              class="flex items-center gap-1 text-neutral-400 mb-1"
+              title="Skip the paced descent: the next compile plans straight at the new budget. The whole fold-down and its KV-prefix invalidation land on that one turn — the emergency lever for refusal streaks or over-budget wedges. Cancels any in-flight descent."
+            >
+              <input type="checkbox" checked={immediate()} onChange={(e) => setImmediate(e.currentTarget.checked)} />
+              drop immediately
+            </label>
+            <Show when={!immediate()}>
+              <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.
+                Check <span class="font-mono">drop immediately</span> to skip the descent.
+              </div>
+            </Show>
+            <Show when={immediate()}>
+              <div class="text-red-400/90">
+                immediate drop: the full fold-down (and its KV re-read) lands on the next
+                turn, and any in-flight descent is cancelled.
+              </div>
+            </Show>
           </Show>
         </div>
 
@@ -384,7 +407,7 @@ export function SettingsPanel(props: {
               class="px-2 py-0.5 text-[10px] rounded font-mono bg-neutral-800 hover:bg-neutral-700
                      text-neutral-200 disabled:opacity-30"
               onClick={() => void runDryRun(false)}
-              title="Compile at these settings without applying them. Does not commit anything. Measured ~8s on a large store."
+              title="Compile at these settings without applying them. Does not commit anything. ~1.6s on a large store after the 2026-07-26 solver fixes."
             >
               dry run
             </button>
@@ -408,7 +431,7 @@ export function SettingsPanel(props: {
           <div class="text-[10px] text-neutral-600 mb-1.5 leading-relaxed">
             A dry run is a <b class="text-neutral-500">full compile</b> and it runs on the agent's
             thread — while it runs the agent does nothing else (no heartbeat, no Discord, no MCPL).
-            Measured ~8s on a large store; it commits nothing (no fold resolutions, no compression
+            Measured ~1.6s on a large store; it commits nothing (no fold resolutions, no compression
             queued). Runs are serialized with a short cooldown, so a second click is refused rather
             than queueing another pause.
           </div>