@animalabs/connectome-host 0.7.2 → 0.7.4

package/src/web/protocol.ts

@@ -323,6 +323,10 @@ export interface PeekMessage {
  *  surface a "module not loaded" hint rather than appearing broken. */
 export interface LessonsListMessage {
   type: 'lessons-list';
+  /** Which process this snapshot describes: 'local' or a fleet-child name.
+   *  Lets the SPA drop stale replies after a scope switch instead of
+   *  rendering child A's data under child B's header. */
+  scope?: string;
   loaded: boolean;
   lessons: Array<{
     id: string;
@@ -339,6 +343,8 @@ export interface LessonsListMessage {
 /** Workspace mount summary — response to request-workspace-mounts. */
 export interface WorkspaceMountsMessage {
   type: 'workspace-mounts';
+  /** Process this snapshot describes ('local' or fleet-child name). */
+  scope?: string;
   /** True iff WorkspaceModule is loaded in the recipe. */
   loaded: boolean;
   mounts: Array<{
@@ -353,6 +359,8 @@ export interface WorkspaceMountsMessage {
 /** Recursive file listing for one mount — response to request-workspace-tree. */
 export interface WorkspaceTreeMessage {
   type: 'workspace-tree';
+  /** Process this listing came from ('local' or fleet-child name). */
+  scope?: string;
   mount: string;
   entries: Array<{ path: string; size: number }>;
 }
@@ -361,6 +369,8 @@ export interface WorkspaceTreeMessage {
  *  line-numbered (cat -n style) as returned by the workspace `read` tool. */
 export interface WorkspaceFileMessage {
   type: 'workspace-file';
+  /** Process this file came from ('local' or fleet-child name). */
+  scope?: string;
   path: string;
   totalLines: number;
   fromLine: number;
@@ -376,6 +386,10 @@ export interface WorkspaceFileMessage {
  *  changes are file-only and require restart anyway. */
 export interface McplListMessage {
   type: 'mcpl-list';
+  /** Process whose MCPL view this is ('local' or fleet-child name). The
+   *  registry FILE is shared cwd-wide, but which entries a process actually
+   *  loads is per-recipe — see `live`. */
+  scope?: string;
   /** Path to the config file (informational — operator may want to grep
    *  for it locally). */
   configPath: string;
@@ -389,6 +403,18 @@ export interface McplListMessage {
     enabledFeatureSets?: string[];
     disabledFeatureSets?: string[];
   }>;
+  /** Servers the scoped process actually LOADED (recipe opt-in + agent
+   *  overlay), with live connection status from its framework. Absent on
+   *  older hosts. This is the per-scope truth the file registry can't give:
+   *  a conductor with zero MCPLs and a clerk with five share one file. */
+  live?: Array<{
+    id: string;
+    connected: boolean;
+    toolCount: number;
+    toolPrefix?: string;
+    /** command or url — whatever the transport targets. */
+    target?: string;
+  }>;
 }
 
 /**
@@ -399,6 +425,8 @@ export interface McplListMessage {
  */
 export interface PinsListMessage {
   type: 'pins-list';
+  /** Process these pins live in ('local' or fleet-child name). */
+  scope?: string;
   agent: string;
   pins: Array<{
     id: string;
@@ -418,6 +446,11 @@ export interface PinsListMessage {
   levelHonored: boolean;
   /** Deepest fold level currently present, so the UI can bound level inputs. */
   deepestLevel?: number;
+  /** Recent pinnable messages (REAL store ids) from the scoped process.
+   *  Shipped for fleet-child scopes, where the SPA has no message window of
+   *  its own to build a picker from; local scope keeps using the client-side
+   *  candidate list. */
+  candidates?: Array<{ id: string; index: number; participant: string; text: string }>;
 }
 
 /**
@@ -429,6 +462,8 @@ export interface PinsListMessage {
  */
 export interface SettingsStateMessage {
   type: 'settings-state';
+  /** Process these settings belong to ('local' or fleet-child name). */
+  scope?: string;
   agent: string;
   /** Live values. `transition` is 'converging' while a paced descent runs. */
   settings: {
@@ -661,11 +696,14 @@ export interface RequestLessonsMessage {
   scope?: string;
 }
 
-/** Pull the configured MCPL servers from mcpl-servers.json. Response is an
- *  `mcpl-list` envelope. Recipe-defined servers are excluded — those live in
+/** Pull the MCPL server view: the shared file registry plus the scoped
+ *  process's LIVE loaded servers. Response is an `mcpl-list` envelope.
+ *  Recipe-defined servers appear only in `live` — their definitions live in
  *  the recipe file and aren't editable from here. */
 export interface RequestMcplMessage {
   type: 'request-mcpl';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
 }
 
 /** Pull the Chronicle branch listing. Response is a `branches-list` envelope
@@ -699,9 +737,13 @@ export interface McplSetEnvMessage {
   env: Record<string, string>;
 }
 
-/** Pull the agent's protected ranges. Response is a `pins-list` envelope. */
+/** Pull the agent's protected ranges. Response is a `pins-list` envelope.
+ *  With a fleet-child `scope` the child also ships picker `candidates`
+ *  (recent real store ids) since the SPA has no window into its store. */
 export interface RequestPinsMessage {
   type: 'request-pins';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
 }
 
@@ -723,6 +765,8 @@ export interface RequestPinsMessage {
  */
 export interface PinAddMessage {
   type: 'pin-add';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
   kind?: 'pin' | 'document';
   firstMessageId: string;
@@ -735,6 +779,8 @@ export interface PinAddMessage {
 
 export interface PinRemoveMessage {
   type: 'pin-remove';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
   pinId: string;
 }
@@ -743,7 +789,9 @@ export interface PinRemoveMessage {
  *  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. */
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
+  /** Agent name; defaults to the scoped process's primary agent. */
   agent?: string;
 }
 
@@ -767,6 +815,8 @@ export interface RequestSettingsMessage {
  */
 export interface SettingsUpdateMessage {
   type: 'settings-update';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
   contextBudgetTokens?: number;
   tailTokens?: number;
@@ -782,6 +832,8 @@ export interface SettingsUpdateMessage {
 /** Revert named settings to their recipe values (all four when omitted). */
 export interface SettingsResetMessage {
   type: 'settings-reset';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
   keys?: string[];
   persist?: boolean;
@@ -791,6 +843,8 @@ export interface SettingsResetMessage {
 /** Abandon an in-flight paced descent, holding the current frontier. */
 export interface SettingsCancelTransitionMessage {
   type: 'settings-cancel-transition';
+  /** Fleet child name, or 'local'/undefined for the parent process. */
+  scope?: string;
   agent?: string;
   persist?: boolean;
 }
@@ -898,9 +952,10 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
   switch (v.type) {
     case 'ping':
     case 'interrupt':
-    case 'request-mcpl':
     case 'request-branches':
       return true;
+    case 'request-mcpl':
+      return isOptionalScope(v.scope);
     case 'user-message':
       return typeof v.content === 'string';
     case 'observer-hello': {
@@ -938,8 +993,9 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
     case 'mcpl-set-env':
       return isValidMcplId(v.id) && isStringMap(v.env);
     case 'request-pins':
-      return isOptionalNonEmptyString(v.agent);
+      return isOptionalScope(v.scope) && isOptionalNonEmptyString(v.agent);
     case 'pin-add': {
+      if (!isOptionalScope(v.scope)) return false;
       if (!isOptionalNonEmptyString(v.agent)) return false;
       if (!isNonEmptyString(v.firstMessageId)) return false;
       if (v.lastMessageId !== undefined && !isNonEmptyString(v.lastMessageId)) return false;
@@ -957,10 +1013,11 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
       return true;
     }
     case 'pin-remove':
-      return isOptionalNonEmptyString(v.agent) && isNonEmptyString(v.pinId);
+      return isOptionalScope(v.scope) && isOptionalNonEmptyString(v.agent) && isNonEmptyString(v.pinId);
     case 'request-settings':
-      return isOptionalNonEmptyString(v.agent);
+      return isOptionalScope(v.scope) && isOptionalNonEmptyString(v.agent);
     case 'settings-update': {
+      if (!isOptionalScope(v.scope)) return false;
       if (!isOptionalNonEmptyString(v.agent)) 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
@@ -976,12 +1033,13 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
         || v.transitionPaceTokens !== undefined;
     }
     case 'settings-reset':
-      return isOptionalNonEmptyString(v.agent)
+      return isOptionalScope(v.scope)
+        && isOptionalNonEmptyString(v.agent)
         && isOptionalBool(v.persist)
         && isOptionalBool(v.notify)
         && isOptionalStringArray(v.keys);
     case 'settings-cancel-transition':
-      return isOptionalNonEmptyString(v.agent) && isOptionalBool(v.persist);
+      return isOptionalScope(v.scope) && isOptionalNonEmptyString(v.agent) && isOptionalBool(v.persist);
     case 'request-workspace-mounts':
       return v.scope === undefined || typeof v.scope === 'string';
     case 'request-workspace-tree':
@@ -1041,6 +1099,13 @@ function isOptionalNonEmptyString(v: unknown): v is string | undefined {
   return v === undefined || isNonEmptyString(v);
 }
 
+/** Scope fields: 'local' or a fleet-child name. Same lax shape the existing
+ *  lessons/workspace requests use — the server resolves unknown children to
+ *  a clean error rather than the validator guessing the fleet roster. */
+function isOptionalScope(v: unknown): v is string | undefined {
+  return v === undefined || typeof v === 'string';
+}
+
 function isOptionalBool(v: unknown): v is boolean | undefined {
   return v === undefined || typeof v === 'boolean';
 }

package/test/audit-module-optins.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Tests for the report-only module opt-in audit (Sol's #32 closure gate,
+ * step 3). The contract under test: explicit enables are surfaced for an
+ * operator decision, omissions are explained as the defaults flip working,
+ * resolved .recipe.json snapshots are pointers rather than findings, and
+ * nothing is ever modified.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  classifyModule,
+  looksLikeRecipe,
+  auditRecipe,
+  auditPaths,
+  renderReport,
+  AUDITED_MODULES,
+} from '../scripts/audit-module-optins.js';
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), 'optin-audit-'));
+}
+
+const AGENT = { name: 'test-agent', systemPrompt: 'hi' };
+
+describe('classifyModule', () => {
+  test('true and config objects are explicit enables', () => {
+    expect(classifyModule(true)).toBe('explicit-enable');
+    expect(classifyModule({ model: 'x' })).toBe('explicit-enable');
+  });
+  test('false is an explicit disable; absent is omitted', () => {
+    expect(classifyModule(false)).toBe('explicit-disable');
+    expect(classifyModule(undefined)).toBe('omitted');
+  });
+});
+
+describe('looksLikeRecipe', () => {
+  test('recipe-shaped objects pass; package.json-shaped ones do not', () => {
+    expect(looksLikeRecipe({ name: 'r', agent: AGENT })).toBe(true);
+    expect(looksLikeRecipe({ name: 'pkg', version: '1.0.0' })).toBe(false);
+    expect(looksLikeRecipe(['name'])).toBe(false);
+    expect(looksLikeRecipe(null)).toBe(false);
+  });
+});
+
+describe('auditRecipe', () => {
+  test('classifies each audited module independently', () => {
+    const a = auditRecipe(
+      { name: 'r', agent: AGENT, modules: { lessons: true, retrieval: false, wake: true } },
+      'r.json',
+    );
+    expect(a.states).toEqual({ subagents: 'omitted', lessons: 'explicit-enable', retrieval: 'explicit-disable' });
+    expect(a.isSnapshot).toBe(false);
+    expect(a.matchesOldDefaultBoilerplate).toBe(false);
+  });
+
+  test('flags retrieval-without-lessons as inert after upgrade', () => {
+    const a = auditRecipe({ name: 'r', agent: AGENT, modules: { retrieval: true } }, 'r.json');
+    expect(a.inertRetrieval).toBe(true);
+    // With lessons enabled the combination is coherent, not inert.
+    const ok = auditRecipe({ name: 'r', agent: AGENT, modules: { retrieval: true, lessons: true } }, 'r.json');
+    expect(ok.inertRetrieval).toBe(false);
+  });
+
+  test('a .recipe.json with all three true is old-default boilerplate; a source recipe never is', () => {
+    const modules = { subagents: true, lessons: true, retrieval: true };
+    const snap = auditRecipe({ name: 'r', agent: AGENT, modules }, 'data/.recipe.json');
+    expect(snap.isSnapshot).toBe(true);
+    expect(snap.matchesOldDefaultBoilerplate).toBe(true);
+    const src = auditRecipe({ name: 'r', agent: AGENT, modules }, 'data/recipe.json');
+    expect(src.matchesOldDefaultBoilerplate).toBe(false);
+  });
+
+  test('collects local fleet children, resolves relative paths, skips URLs', () => {
+    const a = auditRecipe(
+      {
+        name: 'parent',
+        agent: AGENT,
+        modules: { fleet: { children: [{ recipe: 'child.json' }, { recipe: 'https://x.example/c.json' }] } },
+      },
+      '/deploy/recipes/parent.json',
+    );
+    expect(a.childRecipePaths).toEqual(['/deploy/recipes/child.json']);
+  });
+});
+
+describe('auditPaths', () => {
+  test('scans directories, follows fleet children, skips non-recipes, modifies nothing', () => {
+    const dir = tmp();
+    const recipesDir = join(dir, 'recipes');
+    mkdirSync(recipesDir);
+    writeFileSync(
+      join(recipesDir, 'parent.json'),
+      JSON.stringify({
+        name: 'parent',
+        agent: AGENT,
+        modules: { lessons: true, fleet: { children: [{ recipe: '../elsewhere/child.json' }] } },
+      }),
+    );
+    // Child lives OUTSIDE the scanned dir — reachable only by following the reference.
+    mkdirSync(join(dir, 'elsewhere'));
+    const childPath = join(dir, 'elsewhere', 'child.json');
+    writeFileSync(childPath, JSON.stringify({ name: 'child', agent: AGENT, modules: { retrieval: true } }));
+    writeFileSync(join(recipesDir, 'package.json'), JSON.stringify({ name: 'pkg', version: '1.0.0' }));
+    writeFileSync(join(recipesDir, 'broken.json'), '{nope');
+
+    const before = statSync(join(recipesDir, 'parent.json')).mtimeMs;
+    const { audits, unreadable } = auditPaths([recipesDir]);
+    expect(unreadable).toEqual([]);
+    expect(audits.map((a) => a.recipeName).sort()).toEqual(['child', 'parent']);
+    // Report-only, literally: nothing was rewritten.
+    expect(statSync(join(recipesDir, 'parent.json')).mtimeMs).toBe(before);
+    expect(readFileSync(childPath, 'utf-8')).toContain('"retrieval":true');
+  });
+
+  test('finds dot-prefixed .recipe.json snapshots in scanned directories', () => {
+    const dir = tmp();
+    writeFileSync(
+      join(dir, '.recipe.json'),
+      JSON.stringify({ name: 'snap', agent: AGENT, modules: { subagents: true, lessons: true, retrieval: true } }),
+    );
+    const { audits } = auditPaths([dir]);
+    expect(audits.length).toBe(1);
+    expect(audits[0].isSnapshot).toBe(true);
+    expect(audits[0].matchesOldDefaultBoilerplate).toBe(true);
+  });
+
+  test('reports unreadable path arguments', () => {
+    const { audits, unreadable } = auditPaths([join(tmp(), 'nope.json')]);
+    expect(audits).toEqual([]);
+    expect(unreadable.length).toBe(1);
+  });
+});
+
+describe('renderReport', () => {
+  test('explicit enables and inert retrieval need decisions; omissions and disables do not', () => {
+    const clean = auditRecipe({ name: 'clean', agent: AGENT, modules: { lessons: false } }, 'clean.json');
+    expect(renderReport([clean]).needsDecision).toBe(0);
+
+    const enabled = auditRecipe({ name: 'e', agent: AGENT, modules: { lessons: true, retrieval: true } }, 'e.json');
+    // two explicit enables, no inert-retrieval (lessons present)
+    expect(renderReport([enabled]).needsDecision).toBe(2);
+
+    const inert = auditRecipe({ name: 'i', agent: AGENT, modules: { retrieval: true } }, 'i.json');
+    // one explicit enable + one inert-retrieval warning
+    expect(renderReport([inert]).needsDecision).toBe(2);
+  });
+
+  test('snapshot enables are informational, never decision items', () => {
+    const snap = auditRecipe(
+      { name: 's', agent: AGENT, modules: { subagents: true, lessons: true, retrieval: true } },
+      'data/.recipe.json',
+    );
+    const { text, needsDecision } = renderReport([snap]);
+    expect(needsDecision).toBe(0);
+    expect(text).toContain('not authoritative');
+    expect(text).toContain('old DEFAULT_RECIPE shape');
+  });
+
+  test('every audited module appears in a source-recipe report', () => {
+    const a = auditRecipe({ name: 'r', agent: AGENT }, 'r.json');
+    const { text } = renderReport([a]);
+    for (const m of AUDITED_MODULES) expect(text).toContain(`${m}:`);
+  });
+});

package/test/bedrock-prompt-caching.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Bedrock prompt caching is model-gated, not suppressed transport-wide
+ * (issue #35). The deny-list is the pre-GA FAMILIES (Claude v2/instant,
+ * Claude 3, 3.5 Sonnet — Bedrock's caching GA never covered them), matched
+ * at the family boundary so dated ids, bare aliases, -latest, and
+ * inference-profile forms all resolve the same. Everything currently
+ * invokable on Bedrock caches (verified by live probe 2026-07-31; the
+ * 3.5 era is EOL there). The old blanket promptCaching:false made every
+ * modern Bedrock agent re-pay its full context on every call.
+ *
+ * The recipe override must land at BOTH layers — per-agent config for
+ * agent inference AND Membrane defaultPromptCaching for internal callers
+ * (compression/merge) — on every provider, per Sol's #69 review.
+ */
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+import {
+  buildFrameworkAgentConfig,
+  bedrockModelSupportsPromptCaching,
+  membraneCachingOverride,
+} from '../src/framework-agent-config.js';
+
+function recipe(agent: Record<string, unknown> = {}) {
+  return { name: 'bedrock-caching-test', agent: { systemPrompt: 'sys', ...agent } };
+}
+
+describe('bedrockModelSupportsPromptCaching', () => {
+  test('ids without GA caching support are gated off', () => {
+    for (const id of [
+      'anthropic.claude-3-opus-20240229-v1:0',
+      'anthropic.claude-3-sonnet-20240229-v1:0',
+      'anthropic.claude-3-haiku-20240307-v1:0',
+      'us.anthropic.claude-3-5-sonnet-20240620-v1:0',
+      // "3.6" — its caching was preview-only on Bedrock, dropped at GA
+      // (and the model itself is EOL there as of 7/2026).
+      'us.anthropic.claude-3-5-sonnet-20241022-v2:0',
+      'claude-3-5-sonnet-20241022',
+      'claude-3-opus-20240229',
+      'anthropic.claude-v2:1',
+      'anthropic.claude-instant-v1',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+
+  test('the deny-list matches families, not single dated spellings', () => {
+    // Sol's #69 review: bare aliases, -latest, and profile forms of the
+    // pre-GA families must not fall through to caching-on.
+    for (const id of [
+      'claude-3-opus',
+      'claude-3-opus-latest',
+      'claude-3-sonnet',
+      'claude-3-haiku-latest',
+      'claude-3-5-sonnet',
+      'claude-3-5-sonnet-latest',
+      'us.anthropic.claude-3-opus-latest-v1:0',
+      'apac.anthropic.claude-3-5-sonnet-v2:0',
+      'CLAUDE-3-OPUS',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+
+  test('models with GA Bedrock caching support stay on', () => {
+    for (const id of [
+      'anthropic.claude-3-5-haiku-20241022-v1:0',
+      'claude-3-5-haiku-latest',
+      'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+      'claude-3-7-sonnet',
+      'us.anthropic.claude-sonnet-4-20250514-v1:0',
+      'claude-sonnet-4-20250514',
+      'claude-opus-4-6',
+      'bedrock:us.anthropic.claude-opus-4-20250514-v1:0',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(true);
+    }
+  });
+
+  test('non-Claude Bedrock ids are conservatively off, not accidentally on', () => {
+    for (const id of ['amazon.nova-pro-v1:0', 'meta.llama3-70b-instruct-v1:0', 'mistral.mistral-large-2402-v1:0']) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+});
+
+describe('bedrock agent config', () => {
+  test('GA-supported bedrock model gets caching on, without cacheTtl', () => {
+    const parsed = validateRecipe(recipe({ provider: 'bedrock' }));
+    const config = buildFrameworkAgentConfig(
+      parsed, 'agent', 'us.anthropic.claude-3-7-sonnet-20250219-v1:0', undefined,
+    );
+    expect(config.promptCaching).toBe(true);
+    // Bedrock rejects cache_control.ttl; the recipe default ('1h') must not
+    // ride along even though membrane also strips it.
+    expect(Object.prototype.hasOwnProperty.call(config, 'cacheTtl')).toBe(false);
+  });
+
+  test('legacy bedrock model keeps caching suppressed', () => {
+    const parsed = validateRecipe(recipe({ provider: 'bedrock' }));
+    const config = buildFrameworkAgentConfig(
+      parsed, 'agent', 'us.anthropic.claude-3-5-sonnet-20240620-v1:0', undefined,
+    );
+    expect(config.promptCaching).toBe(false);
+  });
+
+  test('recipe promptCaching overrides the model gate in both directions', () => {
+    const forcedOff = buildFrameworkAgentConfig(
+      validateRecipe(recipe({ provider: 'bedrock', promptCaching: false })),
+      'agent', 'us.anthropic.claude-3-7-sonnet-20250219-v1:0', undefined,
+    );
+    expect(forcedOff.promptCaching).toBe(false);
+
+    // Explicit opt-in for an account/region whose entitlements differ
+    // from the GA table (the gate is a default, not a hard ceiling).
+    const forcedOn = buildFrameworkAgentConfig(
+      validateRecipe(recipe({ provider: 'bedrock', promptCaching: true })),
+      'agent', 'us.anthropic.claude-3-5-sonnet-20241022-v2:0', undefined,
+    );
+    expect(forcedOn.promptCaching).toBe(true);
+  });
+
+  test('explicit override lands at BOTH layers on any provider (composition)', () => {
+    // Anthropic recipe, explicit false: agent config off AND membrane
+    // default off — internal callers (compression/merge) read the latter.
+    const anthOff = validateRecipe(recipe({ promptCaching: false }));
+    expect(buildFrameworkAgentConfig(anthOff, 'agent', 'claude-opus-4-6', undefined).promptCaching).toBe(false);
+    expect(membraneCachingOverride(anthOff, 'claude-opus-4-6')).toEqual({ defaultPromptCaching: false });
+
+    // Bedrock explicit true and false: both layers agree with the override.
+    const bedOn = validateRecipe(recipe({ provider: 'bedrock', promptCaching: true }));
+    expect(buildFrameworkAgentConfig(bedOn, 'agent', 'us.anthropic.claude-3-5-sonnet-20241022-v2:0', undefined).promptCaching).toBe(true);
+    expect(membraneCachingOverride(bedOn, 'us.anthropic.claude-3-5-sonnet-20241022-v2:0')).toEqual({ defaultPromptCaching: true });
+
+    const bedOff = validateRecipe(recipe({ provider: 'bedrock', promptCaching: false }));
+    expect(buildFrameworkAgentConfig(bedOff, 'agent', 'us.anthropic.claude-opus-4-1-20250805-v1:0', undefined).promptCaching).toBe(false);
+    expect(membraneCachingOverride(bedOff, 'us.anthropic.claude-opus-4-1-20250805-v1:0')).toEqual({ defaultPromptCaching: false });
+
+    // Bedrock with no explicit override: the model gate supplies the
+    // answer at both layers too.
+    const bedGate = validateRecipe(recipe({ provider: 'bedrock' }));
+    expect(membraneCachingOverride(bedGate, 'us.anthropic.claude-3-7-sonnet-20250219-v1:0')).toEqual({ defaultPromptCaching: true });
+    expect(membraneCachingOverride(bedGate, 'anthropic.claude-3-opus-20240229-v1:0')).toEqual({ defaultPromptCaching: false });
+
+    // Anthropic with no override: BOTH layers stay silent — membrane's
+    // own default (on) governs, and we don't bake it in here.
+    const anthDefault = validateRecipe(recipe());
+    expect(Object.prototype.hasOwnProperty.call(
+      buildFrameworkAgentConfig(anthDefault, 'agent', 'claude-opus-4-6', undefined), 'promptCaching',
+    )).toBe(false);
+    expect(membraneCachingOverride(anthDefault, 'claude-opus-4-6')).toEqual({});
+  });
+
+  test('non-bedrock providers keep prior behavior: caching omitted, cacheTtl forwarded', () => {
+    const parsed = validateRecipe(recipe());
+    const config = buildFrameworkAgentConfig(parsed, 'agent', 'claude-opus-4-6', undefined);
+    expect(Object.prototype.hasOwnProperty.call(config, 'promptCaching')).toBe(false);
+    expect(config.cacheTtl).toBe('1h');
+  });
+
+  test('recipe promptCaching applies on non-bedrock providers too', () => {
+    const parsed = validateRecipe(recipe({ promptCaching: false }));
+    const config = buildFrameworkAgentConfig(parsed, 'agent', 'claude-opus-4-6', undefined);
+    expect(config.promptCaching).toBe(false);
+  });
+
+  test('non-boolean promptCaching is rejected at validation', () => {
+    expect(() => validateRecipe(recipe({ promptCaching: 'yes' }))).toThrow(/promptCaching/);
+    expect(() => validateRecipe(recipe({ promptCaching: 1 }))).toThrow(/promptCaching/);
+  });
+});

package/test/fleet-panel-request.test.ts

@@ -0,0 +1,90 @@
+/**
+ * FleetModule.requestPanel — the promise-based panel-op verb the WebUI's
+ * fleet-scope routing rides on (WS panels and the HTTP ?scope= proxy).
+ *
+ * Uses the mock headless child, which answers panel-request with:
+ *   op 'hang' → nothing (timeout path)
+ *   op 'fail' → {ok:false, error, status:418} (error passthrough)
+ *   others    → {ok:true, data:{op, echo:params}}
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FleetModule, type FleetModuleConfig } from '../src/modules/fleet-module.js';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const MOCK_CHILD_PATH = join(TEST_DIR, 'mock-headless-child.ts');
+
+function makeFleet(overrides: Partial<FleetModuleConfig> = {}): FleetModule {
+  return new FleetModule({
+    childIndexPath: MOCK_CHILD_PATH,
+    socketWaitTimeoutMs: 10_000,
+    readyTimeoutMs: 5_000,
+    gracefulShutdownMs: 3_000,
+    sigtermEscalationMs: 1_000,
+    ...overrides,
+  });
+}
+
+describe('FleetModule.requestPanel', () => {
+  let tmpDir: string;
+  let fleet: FleetModule;
+
+  beforeAll(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-panel-'));
+    fleet = makeFleet();
+    const res = await fleet.handleToolCall({
+      id: 'launch-panelkid',
+      name: 'launch',
+      input: { name: 'panelkid', recipe: 'mock-recipe', dataDir: join(tmpDir, 'panelkid') },
+    });
+    if (!res.success) throw new Error(`launch failed: ${res.error}`);
+  });
+
+  afterAll(async () => {
+    try { await fleet.stop(); } catch { /* noop */ }
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('round-trips op + params and resolves the child data', async () => {
+    const result = await fleet.requestPanel('panelkid', 'settings', { agent: 'clerk' });
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({ op: 'settings', echo: { agent: 'clerk' } });
+  });
+
+  test('concurrent requests correlate independently', async () => {
+    const [a, b] = await Promise.all([
+      fleet.requestPanel('panelkid', 'health', { n: 1 }),
+      fleet.requestPanel('panelkid', 'pins', { n: 2 }),
+    ]);
+    expect(a.ok).toBe(true);
+    expect((a.data as { op: string }).op).toBe('health');
+    expect(b.ok).toBe(true);
+    expect((b.data as { op: string }).op).toBe('pins');
+  });
+
+  test('child-reported failure passes error and status through', async () => {
+    const result = await fleet.requestPanel('panelkid', 'fail');
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('mock failure');
+    expect(result.status).toBe(418);
+  });
+
+  test('unanswered request resolves ok:false with 504 after timeoutMs', async () => {
+    const started = Date.now();
+    const result = await fleet.requestPanel('panelkid', 'hang', undefined, 400);
+    expect(Date.now() - started).toBeGreaterThanOrEqual(380);
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(504);
+    expect(result.error).toContain('timed out');
+  });
+
+  test('unknown child resolves ok:false with 404 without touching the wire', async () => {
+    const result = await fleet.requestPanel('nobody', 'settings');
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(404);
+    expect(result.error).toContain('nobody');
+  });
+});