@animalabs/connectome-host 0.7.3 → 0.8.0

package/test/instructions-module.test.ts

@@ -0,0 +1,258 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { mkdtempSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  DEFAULT_INSTRUCTIONS_HEADER,
+  DEFAULT_INSTRUCTIONS_PATH,
+  InstructionsModule,
+  type WorkspacePathResolver,
+} from '../src/modules/instructions-module.js';
+
+/**
+ * Minimal stand-in for WorkspaceModule.resolveAbsolutePath: one mount named
+ * `mountName` rooted at `root`, unknown mounts resolve to null (the real
+ * module's fail-open contract). Mirrors the real parsePath in resolving a
+ * bare mount name to the mount root — the module uses that for its realpath
+ * containment check.
+ */
+function makeResolver(mountName: string, root: string): WorkspacePathResolver {
+  return {
+    resolveAbsolutePath(mountPrefixedPath: string): string | null {
+      const slashIdx = mountPrefixedPath.indexOf('/');
+      const name = slashIdx >= 0 ? mountPrefixedPath.slice(0, slashIdx) : mountPrefixedPath;
+      if (name !== mountName) return null;
+      const rel = slashIdx >= 0 ? mountPrefixedPath.slice(slashIdx + 1) : '';
+      return resolve(root, rel);
+    },
+  };
+}
+
+describe('InstructionsModule', () => {
+  let dir: string;
+  let warnSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'instructions-module-'));
+    warnSpy = spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('injects file content under the default header at the default path', async () => {
+    writeFileSync(join(dir, 'AGENTS.md'), 'Always be excellent.\n');
+    const mod = new InstructionsModule();
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const injections = await mod.gatherContext('resident');
+    expect(injections).toHaveLength(1);
+    expect(injections[0].namespace).toBe('instructions');
+    expect(injections[0].position).toBe('system');
+    expect(injections[0].content).toEqual([{
+      type: 'text',
+      text: `${DEFAULT_INSTRUCTIONS_HEADER}\n\nAlways be excellent.\n`,
+    }]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test('exposes the shared-contract defaults', () => {
+    expect(DEFAULT_INSTRUCTIONS_PATH).toBe('instructions/AGENTS.md');
+    expect(new InstructionsModule().contextTimeoutMs).toBe(2000);
+  });
+
+  test('honors custom path, header, and position', async () => {
+    writeFileSync(join(dir, 'HOUSE-RULES.md'), 'No shouting.');
+    const mod = new InstructionsModule({
+      path: 'shared/HOUSE-RULES.md',
+      header: '## House rules',
+      position: 'afterUser',
+    });
+    mod.setWorkspace(makeResolver('shared', dir));
+
+    const injections = await mod.gatherContext('ephemeral-worker-1');
+    expect(injections).toHaveLength(1);
+    expect(injections[0].position).toBe('afterUser');
+    expect(injections[0].content).toEqual([{ type: 'text', text: '## House rules\n\nNo shouting.' }]);
+  });
+
+  test('supports position beforeUser', async () => {
+    writeFileSync(join(dir, 'AGENTS.md'), 'x');
+    const mod = new InstructionsModule({ position: 'beforeUser' });
+    mod.setWorkspace(makeResolver('instructions', dir));
+    expect((await mod.gatherContext('a'))[0].position).toBe('beforeUser');
+  });
+
+  test('returns the same injection for every agent name', async () => {
+    writeFileSync(join(dir, 'AGENTS.md'), 'shared doc');
+    const mod = new InstructionsModule();
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const forResident = await mod.gatherContext('resident');
+    const forEphemeral = await mod.gatherContext('resident_fork_3');
+    expect(forEphemeral).toEqual(forResident);
+  });
+
+  test('missing file fails open with a single warning across turns', async () => {
+    const mod = new InstructionsModule();
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    expect(await mod.gatherContext('a')).toEqual([]);
+    expect(await mod.gatherContext('a')).toEqual([]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('unknown mount fails open with a single warning', async () => {
+    const mod = new InstructionsModule({ path: 'nonexistent/AGENTS.md' });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    expect(await mod.gatherContext('a')).toEqual([]);
+    expect(await mod.gatherContext('a')).toEqual([]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('no workspace wired fails open', async () => {
+    const mod = new InstructionsModule();
+    expect(await mod.gatherContext('a')).toEqual([]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('recovers (and injects) once the file appears', async () => {
+    const mod = new InstructionsModule();
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    expect(await mod.gatherContext('a')).toEqual([]);
+    writeFileSync(join(dir, 'AGENTS.md'), 'now I exist');
+    const injections = await mod.gatherContext('a');
+    expect(injections).toHaveLength(1);
+    expect((injections[0].content[0] as { text: string }).text).toContain('now I exist');
+  });
+
+  test('caches by (mtime, size) and rereads when the file changes', async () => {
+    const file = join(dir, 'AGENTS.md');
+    writeFileSync(file, 'version one');
+    const mod = new InstructionsModule();
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const first = await mod.gatherContext('a');
+    const second = await mod.gatherContext('a');
+    // Unchanged stat → cache hit → identical array, no reread.
+    expect(second).toBe(first);
+
+    // Content change (different size) → cache miss → new content.
+    writeFileSync(file, 'version two, longer');
+    const third = await mod.gatherContext('a');
+    expect(third).not.toBe(first);
+    expect((third[0].content[0] as { text: string }).text).toContain('version two, longer');
+
+    // mtime bump alone (same size, same content) also invalidates.
+    utimesSync(file, new Date(), new Date(Date.now() + 5000));
+    const fourth = await mod.gatherContext('a');
+    expect(fourth).not.toBe(third);
+    expect(fourth).toEqual(third);
+  });
+
+  test('truncates at maxBytes with an explicit marker', async () => {
+    writeFileSync(join(dir, 'AGENTS.md'), 'a'.repeat(100));
+    const mod = new InstructionsModule({ maxBytes: 10 });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const injections = await mod.gatherContext('a');
+    const text = (injections[0].content[0] as { text: string }).text;
+    expect(text).toBe(`${DEFAULT_INSTRUCTIONS_HEADER}\n\n${'a'.repeat(10)}\n\n[truncated: first 10 of 100 bytes]`);
+  });
+
+  test('truncation never splits a multibyte character (no U+FFFD)', async () => {
+    // '€' is 3 bytes in UTF-8; maxBytes: 4 keeps one full '€' plus the lead
+    // byte of the second. The incomplete sequence must be dropped and the
+    // marker report the actual kept byte count.
+    writeFileSync(join(dir, 'AGENTS.md'), '€€€€');
+    const mod = new InstructionsModule({ maxBytes: 4 });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const text = ((await mod.gatherContext('a'))[0].content[0] as { text: string }).text;
+    expect(text).toBe(`${DEFAULT_INSTRUCTIONS_HEADER}\n\n€\n\n[truncated: first 3 of 12 bytes]`);
+    expect(text).not.toContain('�');
+  });
+
+  test('a multibyte character ending exactly at the cap survives', async () => {
+    // '€€' is 6 bytes; maxBytes: 3 keeps exactly one complete '€' — the
+    // boundary backup must not chop a sequence that finished at the cap.
+    writeFileSync(join(dir, 'AGENTS.md'), '€€');
+    const mod = new InstructionsModule({ maxBytes: 3 });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const text = ((await mod.gatherContext('a'))[0].content[0] as { text: string }).text;
+    expect(text).toBe(`${DEFAULT_INSTRUCTIONS_HEADER}\n\n€\n\n[truncated: first 3 of 6 bytes]`);
+    expect(text).not.toContain('�');
+  });
+
+  test('does not truncate a file exactly at maxBytes', async () => {
+    writeFileSync(join(dir, 'AGENTS.md'), 'a'.repeat(10));
+    const mod = new InstructionsModule({ maxBytes: 10 });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const text = ((await mod.gatherContext('a'))[0].content[0] as { text: string }).text;
+    expect(text).toBe(`${DEFAULT_INSTRUCTIONS_HEADER}\n\n${'a'.repeat(10)}`);
+  });
+
+  test('reads at most maxBytes from an oversized file', async () => {
+    // Regression for the unbounded-read finding: a large mounted file must
+    // never be loaded whole. The observable contract is that only the first
+    // maxBytes influence the injection regardless of file size.
+    const big = 'begin-' + 'x'.repeat(512 * 1024) + '-end';
+    writeFileSync(join(dir, 'AGENTS.md'), big);
+    const mod = new InstructionsModule({ maxBytes: 1000 });
+    mod.setWorkspace(makeResolver('instructions', dir));
+
+    const text = ((await mod.gatherContext('a'))[0].content[0] as { text: string }).text;
+    expect(text).toBe(
+      `${DEFAULT_INSTRUCTIONS_HEADER}\n\n${big.slice(0, 1000)}\n\n[truncated: first 1000 of ${big.length} bytes]`,
+    );
+    expect(text).not.toContain('-end');
+  });
+
+  test('rejects an in-mount symlink targeting a file outside the mount', async () => {
+    // Regression for the symlink-escape finding: resolveAbsolutePath's
+    // containment is lexical, so a symlink inside the mount must not import
+    // outside content into the trusted instructions block.
+    const outside = mkdtempSync(join(tmpdir(), 'instructions-outside-'));
+    try {
+      writeFileSync(join(outside, 'secret.txt'), 'OUTSIDE_SECRET');
+      symlinkSync(join(outside, 'secret.txt'), join(dir, 'AGENTS.md'));
+      const mod = new InstructionsModule();
+      mod.setWorkspace(makeResolver('instructions', dir));
+
+      expect(await mod.gatherContext('a')).toEqual([]);
+      expect(await mod.gatherContext('a')).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(String(warnSpy.mock.calls[0]?.[0])).toContain('outside its mount');
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  test('a symlink retargeted outside the mount stops injecting (no stale cache)', async () => {
+    const outside = mkdtempSync(join(tmpdir(), 'instructions-outside-'));
+    try {
+      writeFileSync(join(dir, 'real.md'), 'legit content');
+      symlinkSync(join(dir, 'real.md'), join(dir, 'AGENTS.md'));
+      const mod = new InstructionsModule();
+      mod.setWorkspace(makeResolver('instructions', dir));
+
+      // In-mount symlink is fine — realpath stays under the mount root.
+      const before = await mod.gatherContext('a');
+      expect((before[0].content[0] as { text: string }).text).toContain('legit content');
+
+      // Retarget outside: injection must stop, not serve the cached content.
+      writeFileSync(join(outside, 'secret.txt'), 'OUTSIDE_SECRET');
+      rmSync(join(dir, 'AGENTS.md'));
+      symlinkSync(join(outside, 'secret.txt'), join(dir, 'AGENTS.md'));
+      expect(await mod.gatherContext('a')).toEqual([]);
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+});

package/test/mcpl-admin-module.test.ts

@@ -15,8 +15,19 @@ import { readAgentOverlay, saveAgentOverlay } from '../src/mcpl-config.js';
 interface StubServer {
   id: string;
   connected: boolean;
+  retrying: boolean;
   toolPrefix: string;
   toolCount: number;
+  policyEstablished: boolean;
+  effectiveGrant: string[];
+  maskedCapabilities: string[];
+  deniedCapabilities: string[];
+  allowHostCommands: boolean;
+  manifestState?: {
+    lastValidatedRevision: string | null;
+    lastFetchedAt: number | null;
+    lastNegotiatedAt: number | null;
+  };
   command?: string;
   url?: string;
 }
@@ -32,8 +43,19 @@ function makeStubFramework() {
       servers.set(config.id, {
         id: config.id,
         connected: true,
+        retrying: false,
         toolPrefix: config.toolPrefix ?? `mcpl--${config.id}`,
         toolCount: 1,
+        policyEstablished: true,
+        effectiveGrant: ['channels.incoming'],
+        maskedCapabilities: ['channels.streaming'],
+        deniedCapabilities: ['contextHooks.beforeInference.inject.system'],
+        allowHostCommands: false,
+        manifestState: {
+          lastValidatedRevision: 'sha256:validated',
+          lastFetchedAt: Date.parse('2026-08-05T01:02:03.000Z'),
+          lastNegotiatedAt: Date.parse('2026-08-05T01:02:04.000Z'),
+        },
         command: config.command,
         url: config.url,
       });
@@ -49,8 +71,19 @@ function makeStubFramework() {
       servers.set(id, {
         id,
         connected: true,
+        retrying: false,
         toolPrefix: `mcpl--${id}`,
         toolCount: 1,
+        policyEstablished: true,
+        effectiveGrant: ['channels.incoming'],
+        maskedCapabilities: ['channels.streaming'],
+        deniedCapabilities: ['contextHooks.beforeInference.inject.system'],
+        allowHostCommands: false,
+        manifestState: {
+          lastValidatedRevision: 'sha256:validated',
+          lastFetchedAt: Date.parse('2026-08-05T01:02:03.000Z'),
+          lastNegotiatedAt: Date.parse('2026-08-05T01:02:04.000Z'),
+        },
         command: config?.command ?? prev?.command,
       });
     },
@@ -207,7 +240,38 @@ describe('mcpl_list', () => {
     const text = String(result.data);
     expect(text).toContain('discord: CONNECTED');
     expect(text).toContain('mytool: CONNECTED');
+    expect(text).toContain('policy=established');
+    expect(text).toContain('grant=[channels.incoming]');
+    expect(text).toContain('masked=[channels.streaming]');
+    expect(text).toContain('denied=[contextHooks.beforeInference.inject.system]');
+    expect(text).toContain('hostCommands=deny');
+    expect(text).toContain(
+      'manifest={revision="sha256:validated",' +
+      'fetchedAt=2026-08-05T01:02:03.000Z,' +
+      'negotiatedAt=2026-08-05T01:02:04.000Z}',
+    );
     expect(text).toContain('source=agent-overlay');
     expect(text).toContain('gone: UNLOADED');
   });
+
+  test('distinguishes older-framework unknown and bounds untrusted revisions', async () => {
+    const { stub, servers } = makeStubFramework();
+    await (stub as unknown as { connectMcplServer: (c: { id: string; command: string }) => Promise<void> })
+      .connectMcplServer({ id: 'discord', command: 'node' });
+    const mod = makeModule(stub);
+
+    const server = servers.get('discord')!;
+    delete server.manifestState;
+    expect(String((await call(mod, 'mcpl_list')).data)).toContain('manifest=unknown');
+
+    server.manifestState = {
+      lastValidatedRevision: `unsafe\n${'x'.repeat(100)}`,
+      lastFetchedAt: null,
+      lastNegotiatedAt: null,
+    };
+    const text = String((await call(mod, 'mcpl_list')).data);
+    expect(text).toContain('manifest={revision="unsafe\\n');
+    expect(text).not.toContain('unsafe\n');
+    expect(text).toContain('...",fetchedAt=none,negotiatedAt=none}');
+  });
 });

package/test/mcpl-agent-overlay.test.ts

@@ -13,6 +13,7 @@ import {
   saveAgentOverlay,
   applyAgentOverlay,
   resolveOverlayEntry,
+  AGENT_DEPLOY_DENIED_CAPABILITIES,
   type AgentOverlayEntry,
 } from '../src/mcpl-config.js';
 
@@ -109,18 +110,65 @@ describe('applyAgentOverlay', () => {
 });
 
 describe('resolveOverlayEntry', () => {
+  const BASELINE = [...AGENT_DEPLOY_DENIED_CAPABILITIES].sort();
+
   test('tombstones and empty entries resolve to null', () => {
     expect(resolveOverlayEntry('x', { disabled: true }, '/tmp/o.json')).toBeNull();
     expect(resolveOverlayEntry('x', {}, '/tmp/o.json')).toBeNull();
   });
 
-  test('url entries pass through with transport fields', () => {
+  test('url entries pass through with transport fields (plus the baseline capability mask)', () => {
     const r = resolveOverlayEntry('ws', { url: 'wss://host/mcpl', transport: 'websocket', token: 't' }, '/tmp/o.json');
-    expect(r).toEqual({ id: 'ws', url: 'wss://host/mcpl', transport: 'websocket', token: 't' });
+    expect(r).toEqual({ id: 'ws', url: 'wss://host/mcpl', transport: 'websocket', token: 't', reconnect: true, disabledCapabilities: BASELINE });
   });
 
   test('disabled flag is stripped from resolved config', () => {
     const r = resolveOverlayEntry('s', { command: 'node', disabled: false }, '/tmp/o.json');
-    expect(r).toEqual({ id: 's', command: 'node' });
+    expect(r).toEqual({ id: 's', command: 'node', disabledCapabilities: BASELINE });
+  });
+
+  // OpenAI-style strict function calling forces every schema property, so
+  // agent tool calls arrive with [] where the caller meant "unspecified" —
+  // and a PRESENT-empty allowlist is deny-all under the SPEC 0.5 pin (Mica's
+  // silently eventless eidoverse, 2026-08-04). [] must carry no intent.
+  test('empty allow/deny lists resolve as absent (strict-schema [] is "unspecified", never deny-all)', () => {
+    const r = resolveOverlayEntry('e', {
+      url: 'wss://host/mcpl',
+      enabledFeatureSets: [],
+      disabledFeatureSets: [],
+      enabledTools: [],
+      disabledTools: [],
+    }, '/tmp/o.json');
+    expect(r).toEqual({ id: 'e', url: 'wss://host/mcpl', reconnect: true, disabledCapabilities: BASELINE });
+  });
+
+  test('non-empty lists survive resolution', () => {
+    const r = resolveOverlayEntry('e', { url: 'wss://x/mcpl', enabledFeatureSets: ['eidoverse.*'], enabledTools: ['*'] }, '/tmp/o.json');
+    expect(r?.enabledFeatureSets).toEqual(['eidoverse.*']);
+    expect(r?.enabledTools).toEqual(['*']);
+  });
+
+  test('self-deployed servers never get consequential capabilities: baseline mask covers context hooks, server-initiated inference, lifecycle', () => {
+    expect(BASELINE).toEqual(['contextHooks', 'inferenceLifecycle', 'inferenceRequest']);
+  });
+
+  // A network server the agent deployed should come back when it bounces:
+  // reconnect-defaulted-false left Mythos permanently severed from eidoverse
+  // by a routine door deploy (2026-08-04) until his own next restart, days out.
+  test('websocket entries default reconnect: true; explicit false is respected; stdio keeps no default', () => {
+    expect(resolveOverlayEntry('a', { url: 'wss://x/mcpl' }, '/tmp/o.json')?.reconnect).toBe(true);
+    expect(resolveOverlayEntry('b', { url: 'wss://x/mcpl', reconnect: false }, '/tmp/o.json')?.reconnect).toBe(false);
+    expect(resolveOverlayEntry('c', { command: 'node' }, '/tmp/o.json')?.reconnect).toBeUndefined();
+  });
+
+  test('entry-supplied disabledCapabilities union with the baseline, never replace it', () => {
+    const r = resolveOverlayEntry('e', { url: 'wss://x/mcpl', disabledCapabilities: ['channels.streaming'] } as never, '/tmp/o.json');
+    expect(r?.disabledCapabilities).toEqual(['channels.streaming', ...BASELINE].sort());
+  });
+
+  test('enabledCapabilities is dropped — the agent overlay narrows, never widens (a hand-written entry could re-grant a §13.4 deny-by-default path)', () => {
+    const r = resolveOverlayEntry('e', { url: 'wss://x/mcpl', enabledCapabilities: ['contextHooks.beforeInference.inject.system'] } as never, '/tmp/o.json');
+    expect(r).not.toBeNull();
+    expect('enabledCapabilities' in (r as object)).toBe(false);
   });
 });

package/test/mcpl-child-env.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Host composition of stdio MCPL child env (composeMcplChildEnv): the
+ * framework's refusal-annotation baseline is injected for never-configured
+ * deployments, and an operator's explicit value always supersedes it — the
+ * host provides a default, never overrides a decision. The enforced
+ * precedence below this (file key incl. [] → legacy operator env → baseline)
+ * lives in the Discord adapter; what the host owns is that the injected
+ * value is EXACTLY the set the framework stamps (REFUSAL_REACTION_BASELINE,
+ * comma-joined) and that it rides in env — process plumbing below the model
+ * line, never agent-visible text.
+ */
+import { describe, test, expect } from 'bun:test';
+import { REFUSAL_REACTION_BASELINE } from '@animalabs/agent-framework';
+import { composeMcplChildEnv } from '../src/mcpl-config.js';
+
+const BASELINE = REFUSAL_REACTION_BASELINE.join(',');
+
+describe('composeMcplChildEnv', () => {
+  test('injects the framework baseline when the server entry does not set it', () => {
+    const env = composeMcplChildEnv({ SOME_VAR: 'x' }, 'UTC');
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe(BASELINE);
+    expect(env.SOME_VAR).toBe('x');
+  });
+
+  test('injected value round-trips to the exact framework annotation set', () => {
+    const env = composeMcplChildEnv(undefined, 'UTC');
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE!.split(',')).toEqual([
+      ...REFUSAL_REACTION_BASELINE,
+    ]);
+    expect(REFUSAL_REACTION_BASELINE.length).toBeGreaterThan(0);
+  });
+
+  test('operator-set baseline on the server entry supersedes the house value', () => {
+    const env = composeMcplChildEnv(
+      { DISCORD_SUPPRESSED_REACTIONS_BASELINE: '🈲' },
+      'UTC',
+    );
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe('🈲');
+  });
+
+  test('operator empty-string baseline is preserved, not re-defaulted', () => {
+    // An operator who explicitly set the var to empty chose "no baseline";
+    // the house value must not reappear underneath that decision.
+    const env = composeMcplChildEnv(
+      { DISCORD_SUPPRESSED_REACTIONS_BASELINE: '' },
+      'UTC',
+    );
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe('');
+  });
+
+  test('AGENT_TIMEZONE stays host-resolved (recipe wall clock, not a per-server knob)', () => {
+    const env = composeMcplChildEnv({ AGENT_TIMEZONE: 'Mars/Olympus' }, 'America/Los_Angeles');
+    expect(env.AGENT_TIMEZONE).toBe('America/Los_Angeles');
+  });
+
+  test('adds nothing beyond the two host-owned keys', () => {
+    const env = composeMcplChildEnv({ A: '1' }, 'UTC');
+    expect(Object.keys(env).sort()).toEqual([
+      'A',
+      'AGENT_TIMEZONE',
+      'DISCORD_SUPPRESSED_REACTIONS_BASELINE',
+    ]);
+  });
+});

package/test/mock-headless-child.ts

@@ -83,6 +83,20 @@ function simulateFinalInference(text: string, emitIdleAfter: boolean): void {
 function dispatch(msg: Record<string, unknown>): void {
   const t = typeof msg.type === 'string' ? msg.type : '';
   if (t === 'subscribe') return;  // accept silently
+  if (t === 'panel-request') {
+    // Panel-op verbs for FleetModule.requestPanel tests:
+    //   op 'hang' → never answers (timeout path)
+    //   op 'fail' → ok:false with a status (error passthrough path)
+    //   anything else → ok:true echoing the params back
+    const op = typeof msg.op === 'string' ? msg.op : '';
+    if (op === 'hang') return;
+    if (op === 'fail') {
+      emit({ type: 'panel-response', corrId: msg.corrId, op, ok: false, error: 'mock failure', status: 418 });
+      return;
+    }
+    emit({ type: 'panel-response', corrId: msg.corrId, op, ok: true, data: { op, echo: msg.params ?? null } });
+    return;
+  }
   if (t === 'shutdown') {
     emit({ type: 'lifecycle', phase: 'exiting', reason: 'shutdown' });
     setTimeout(() => process.exit(0), 50);

package/test/nudge-command.test.ts

@@ -0,0 +1,47 @@
+/**
+ * /nudge — admin-level: run inference on the agent's CURRENT context without
+ * adding any message or event. Thin shim over framework.nudgeAgent(); these
+ * tests pin the argument pass-through and the operator-facing wording.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { AgentFramework } from '@animalabs/agent-framework';
+import { handleCommand } from '../src/commands.js';
+
+function app(nudgeAgent: AgentFramework['nudgeAgent']): Parameters<typeof handleCommand>[1] {
+  return {
+    framework: { nudgeAgent } as AgentFramework,
+    sessionManager: {} as never,
+    recipe: { name: 'test' } as never,
+    branchState: {} as never,
+    switchSession: async () => {},
+  };
+}
+
+describe('/nudge', () => {
+  test('nudges the default agent and reports immediate run when idle', () => {
+    const calls: Array<[string | undefined, string | undefined]> = [];
+    const result = handleCommand('/nudge', app((name, by) => {
+      calls.push([name, by]);
+      return { ok: true, agentName: 'main', agentStatus: 'idle' };
+    }));
+    expect(calls).toEqual([[undefined, 'host-console']]);
+    expect(result.lines[0]?.text).toMatch(/Nudged main/);
+    expect(result.lines[0]?.text).toMatch(/no new events/);
+    expect(result.lines[0]?.text).toMatch(/running now/);
+  });
+
+  test('passes an explicit agent name and reports queueing when busy', () => {
+    const result = handleCommand('/nudge sidekick', app((name) => {
+      expect(name).toBe('sidekick');
+      return { ok: true, agentName: 'sidekick', agentStatus: 'streaming' };
+    }));
+    expect(result.lines[0]?.text).toMatch(/queued — runs when current turn settles \(agent is streaming\)/);
+  });
+
+  test('surfaces framework errors', () => {
+    const result = handleCommand('/nudge ghost', app(() => (
+      { ok: false, error: 'Unknown agent: ghost' }
+    )));
+    expect(result.lines[0]?.text).toBe('Nudge failed: Unknown agent: ghost');
+  });
+});

package/test/recipe-cache-keepalive.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Tests for recipe.agent.cacheKeepalive validation.
+ *
+ * The load-bearing case is `refreshAfterMinutes >= the cache TTL`: such a
+ * keepalive always fires AFTER the entry has expired, so every poke pays a full
+ * 2x cache write instead of a 0.1x read — while still looking like a healthy
+ * successful call. That must fail at recipe-load time, not on a bill.
+ */
+import { describe, test, expect } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipeWith(cacheKeepalive?: unknown, cacheTtl?: unknown) {
+  return {
+    name: 'keepalive-test',
+    agent: {
+      systemPrompt: 'sys',
+      ...(cacheTtl !== undefined && { cacheTtl }),
+      ...(cacheKeepalive !== undefined && { cacheKeepalive }),
+    },
+  };
+}
+
+describe('recipe agent.cacheKeepalive validation', () => {
+  test('omitting it is valid — keepalive is on by default', () => {
+    expect(validateRecipe(recipeWith()).agent.cacheKeepalive).toBeUndefined();
+  });
+
+  test('accepts an explicit opt-out', () => {
+    const r = validateRecipe(recipeWith({ enabled: false }));
+    expect(r.agent.cacheKeepalive?.enabled).toBe(false);
+  });
+
+  test('accepts sane tuning', () => {
+    const r = validateRecipe(recipeWith({ maxIdleHours: 12, refreshAfterMinutes: 50 }));
+    expect(r.agent.cacheKeepalive?.maxIdleHours).toBe(12);
+    expect(r.agent.cacheKeepalive?.refreshAfterMinutes).toBe(50);
+  });
+
+  test('rejects a refresh interval at or past the 1h TTL (every poke would be a cache WRITE)', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 60 }, '1h'))).toThrow(/less than the 1h cache TTL/);
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 90 }, '1h'))).toThrow(/less than the 1h cache TTL/);
+  });
+
+  test('rejects a refresh interval at or past the 5m TTL', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 45 }, '5m'))).toThrow(/less than the 5m cache TTL/);
+    expect(validateRecipe(recipeWith({ refreshAfterMinutes: 4 }, '5m')).agent.cacheKeepalive?.refreshAfterMinutes).toBe(4);
+  });
+
+  test('rejects non-positive and non-numeric values', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 0 }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: '45' }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ maxIdleHours: -1 }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ maxIdleHours: 'lots' }))).toThrow(/positive number/);
+  });
+
+  test('rejects a non-object', () => {
+    expect(() => validateRecipe(recipeWith('yes'))).toThrow(/must be an object/);
+  });
+});

package/test/recipe-compression-fallback.test.ts

@@ -13,9 +13,19 @@ describe('compression recall-curve recipe settings', () => {
     const parsed = validateRecipe(recipe({
       compressionRefusalCurveFallbacks: 3,
       compressionContextBudgetTokens: 200_000,
+      compressionRecallBudgetTokens: 40_000,
+      compressionSourceOnly: false,
+      compressionSourceOnlyFallback: true,
+      compressionMergeSourceOnly: false,
+      compressionMergeSourceOnlyFallback: true,
     }));
     expect(parsed.agent.strategy?.compressionRefusalCurveFallbacks).toBe(3);
     expect(parsed.agent.strategy?.compressionContextBudgetTokens).toBe(200_000);
+    expect(parsed.agent.strategy?.compressionRecallBudgetTokens).toBe(40_000);
+    expect(parsed.agent.strategy?.compressionSourceOnly).toBe(false);
+    expect(parsed.agent.strategy?.compressionSourceOnlyFallback).toBe(true);
+    expect(parsed.agent.strategy?.compressionMergeSourceOnly).toBe(false);
+    expect(parsed.agent.strategy?.compressionMergeSourceOnlyFallback).toBe(true);
   });
 
   test('accepts zero as an explicit fallback disable', () => {
@@ -32,5 +42,14 @@ describe('compression recall-curve recipe settings', () => {
       .toThrow(/compressionContextBudgetTokens/);
     expect(() => validateRecipe(recipe({ compressionContextBudgetTokens: '200000' })))
       .toThrow(/compressionContextBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: 0 })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: 1.5 })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: '40000' })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    for (const key of ['compressionSourceOnly', 'compressionSourceOnlyFallback', 'compressionMergeSourceOnly', 'compressionMergeSourceOnlyFallback']) {
+      expect(() => validateRecipe(recipe({ [key]: 'yes' }))).toThrow(new RegExp(key));
+    }
   });
 });