@animalabs/connectome-host 0.3.1

package/test/headless-describe.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Integration test for the 'describe' IPC verb.
+ *
+ * Spawns a headless daemon, sends {type:'describe'}, and asserts the
+ * child responds with a single 'snapshot' event whose tree shape matches
+ * AgentTreeReducer's output. Also verifies snapshot bypasses subscription
+ * filtering — the parent should always be able to recover state regardless
+ * of how it has narrowed the event stream.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { connect as netConnect, type Socket } from 'node:net';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, '..');
+const INDEX_PATH = join(REPO_ROOT, 'src', 'index.ts');
+
+const MINIMAL_RECIPE = {
+  name: 'Describe Test',
+  agent: {
+    name: 'commander',
+    systemPrompt: 'never asked to infer in this test',
+  },
+  modules: {
+    subagents: false,
+    lessons: false,
+    retrieval: false,
+    wake: false,
+    workspace: false,
+  },
+};
+
+function lineReader(socket: Socket): { events: Array<Record<string, unknown>>; stop: () => void } {
+  const events: Array<Record<string, unknown>> = [];
+  let buf = '';
+  const handler = (chunk: Buffer): void => {
+    buf += chunk.toString('utf-8');
+    let i: number;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!line) continue;
+      try { events.push(JSON.parse(line) as Record<string, unknown>); } catch { /* ignore malformed */ }
+    }
+  };
+  socket.on('data', handler);
+  return { events, stop: (): void => { socket.off('data', handler); } };
+}
+
+async function waitFor(check: () => boolean, timeoutMs: number, label: string): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (check()) return;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`waitFor timed out after ${timeoutMs}ms: ${label}`);
+}
+
+async function connectSocket(path: string, timeoutMs = 3_000): Promise<Socket> {
+  return new Promise((resolveConn, rejectConn) => {
+    const s = netConnect(path);
+    const timer = setTimeout(() => {
+      s.destroy();
+      rejectConn(new Error(`socket connect timeout: ${path}`));
+    }, timeoutMs);
+    s.once('connect', () => { clearTimeout(timer); resolveConn(s); });
+    s.once('error', (err) => { clearTimeout(timer); rejectConn(err); });
+  });
+}
+
+describe('headless daemon — describe / snapshot', () => {
+  let tmpDir: string;
+  let recipePath: string;
+  let socketPath: string;
+  let child: ChildProcess;
+
+  beforeAll(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-describe-'));
+    recipePath = join(tmpDir, 'recipe.json');
+    socketPath = join(tmpDir, 'ipc.sock');
+    writeFileSync(recipePath, JSON.stringify(MINIMAL_RECIPE), 'utf-8');
+
+    child = spawn(
+      'bun',
+      [INDEX_PATH, recipePath, '--headless'],
+      {
+        cwd: tmpDir,
+        env: {
+          ...process.env,
+          ANTHROPIC_API_KEY: 'sk-test-describe',
+          DATA_DIR: tmpDir,
+        },
+        stdio: ['ignore', 'ignore', 'ignore'],
+      },
+    );
+
+    await waitFor(() => existsSync(socketPath), 15_000, 'socket file appears');
+  });
+
+  afterAll(() => {
+    try { if (child.exitCode === null) child.kill('SIGKILL'); } catch { /* noop */ }
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('describe returns a snapshot with the seeded framework agent', async () => {
+    const sock = await connectSocket(socketPath);
+    const r = lineReader(sock);
+
+    await waitFor(
+      () => r.events.some((e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'ready'),
+      5_000,
+      'lifecycle:ready',
+    );
+
+    sock.write(JSON.stringify({ type: 'describe', corrId: 'test-1' }) + '\n');
+
+    await waitFor(
+      () => r.events.some((e) => e.type === 'snapshot'),
+      3_000,
+      'snapshot response',
+    );
+
+    const snap = r.events.find((e) => e.type === 'snapshot') as Record<string, unknown>;
+    expect(snap.corrId).toBe('test-1');
+    expect(typeof snap.asOfTs).toBe('number');
+
+    const childMeta = snap.child as Record<string, unknown>;
+    expect(childMeta.name).toBe('Describe Test');
+    expect(typeof childMeta.pid).toBe('number');
+    expect(typeof childMeta.startedAt).toBe('number');
+
+    const tree = snap.tree as { nodes: Array<Record<string, unknown>>; callIdIndex: Record<string, string> };
+    expect(Array.isArray(tree.nodes)).toBe(true);
+    expect(tree.nodes.length).toBeGreaterThanOrEqual(1);
+    const commander = tree.nodes.find(n => n.name === 'commander');
+    expect(commander).toBeDefined();
+    expect(commander!.kind).toBe('framework');
+    expect(commander!.phase).toBe('idle');
+
+    r.stop();
+    sock.destroy();
+  });
+
+  test('snapshot bypasses subscription filter', async () => {
+    const sock = await connectSocket(socketPath);
+    const r = lineReader(sock);
+
+    await waitFor(
+      () => r.events.some((e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'ready'),
+      5_000,
+      'lifecycle:ready (filter test)',
+    );
+
+    // Narrow the subscription to something snapshot is not part of.
+    sock.write(JSON.stringify({ type: 'subscribe', events: ['command-output'] }) + '\n');
+    await new Promise((r) => setTimeout(r, 100));
+
+    const eventsBefore = r.events.length;
+    sock.write(JSON.stringify({ type: 'describe', corrId: 'filter-test' }) + '\n');
+
+    await waitFor(
+      () => r.events.slice(eventsBefore).some((e) => e.type === 'snapshot'),
+      3_000,
+      'snapshot delivered despite narrow subscription',
+    );
+
+    r.stop();
+    sock.destroy();
+  });
+
+  test('cleanup', async () => {
+    // Final shutdown so afterAll doesn't have to SIGKILL.
+    const sock = await connectSocket(socketPath);
+    sock.write(JSON.stringify({ type: 'shutdown' }) + '\n');
+    await new Promise((r) => setTimeout(r, 500));
+    sock.destroy();
+  });
+});

package/test/headless-smoke.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Phase 1 smoke test for headless daemon mode.
+ *
+ * Spawns `bun src/index.ts <recipe> --headless` as a subprocess in a
+ * temp dir, then exercises the JSONL-over-Unix-socket protocol:
+ *   - lifecycle:ready emitted on connect
+ *   - subscribe filter applied
+ *   - /help command produces command-output events (offline-safe path)
+ *   - client disconnect does NOT kill the child
+ *   - reconnecting yields a fresh lifecycle:ready
+ *   - shutdown command exits cleanly with socket + pid file removed
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { connect as netConnect, type Socket } from 'node:net';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, '..');
+const INDEX_PATH = join(REPO_ROOT, 'src', 'index.ts');
+
+// Recipe with all optional modules disabled — no MCP servers, no workspace
+// mounts, no lessons/retrieval, no wake gate.  TimeModule + TuiModule are
+// always-on in createFramework() but neither needs external resources.
+const MINIMAL_RECIPE = {
+  name: 'Smoke Test',
+  agent: {
+    name: 'smoke',
+    systemPrompt: 'never asked to infer in this test',
+  },
+  modules: {
+    subagents: false,
+    lessons: false,
+    retrieval: false,
+    wake: false,
+    workspace: false,
+  },
+};
+
+// --- helpers -------------------------------------------------------------
+
+function lineReader(socket: Socket): { events: Array<Record<string, unknown>>; stop: () => void } {
+  const events: Array<Record<string, unknown>> = [];
+  let buf = '';
+  const handler = (chunk: Buffer): void => {
+    buf += chunk.toString('utf-8');
+    let i: number;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!line) continue;
+      try { events.push(JSON.parse(line) as Record<string, unknown>); } catch { /* ignore malformed */ }
+    }
+  };
+  socket.on('data', handler);
+  return { events, stop: (): void => { socket.off('data', handler); } };
+}
+
+async function waitFor(check: () => boolean, timeoutMs: number, label: string): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (check()) return;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`waitFor timed out after ${timeoutMs}ms: ${label}`);
+}
+
+async function connectSocket(path: string, timeoutMs = 3_000): Promise<Socket> {
+  return new Promise((resolveConn, rejectConn) => {
+    const s = netConnect(path);
+    const timer = setTimeout(() => {
+      s.destroy();
+      rejectConn(new Error(`socket connect timeout: ${path}`));
+    }, timeoutMs);
+    s.once('connect', () => { clearTimeout(timer); resolveConn(s); });
+    s.once('error', (err) => { clearTimeout(timer); rejectConn(err); });
+  });
+}
+
+// --- test ----------------------------------------------------------------
+
+describe('headless daemon — Phase 1', () => {
+  let tmpDir: string;
+  let recipePath: string;
+  let socketPath: string;
+  let pidPath: string;
+  let logPath: string;
+  let child: ChildProcess;
+
+  beforeAll(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-headless-'));
+    recipePath = join(tmpDir, 'recipe.json');
+    socketPath = join(tmpDir, 'ipc.sock');
+    pidPath = join(tmpDir, 'headless.pid');
+    logPath = join(tmpDir, 'headless.log');
+    writeFileSync(recipePath, JSON.stringify(MINIMAL_RECIPE), 'utf-8');
+
+    child = spawn(
+      'bun',
+      [INDEX_PATH, recipePath, '--headless'],
+      {
+        // cwd=tmpDir so DEFAULT_CONFIG_PATH (cwd/mcpl-servers.json) doesn't
+        // accidentally pick up the dev's real MCPL config.
+        cwd: tmpDir,
+        env: {
+          ...process.env,
+          ANTHROPIC_API_KEY: 'sk-test-headless-smoke',
+          DATA_DIR: tmpDir,
+        },
+        stdio: ['ignore', 'ignore', 'ignore'],
+      },
+    );
+
+    await waitFor(() => existsSync(socketPath), 15_000, 'socket file appears');
+  });
+
+  afterAll(() => {
+    try { if (child.exitCode === null) child.kill('SIGKILL'); } catch { /* noop */ }
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('protocol: ready → subscribe → command → reconnect → shutdown', async () => {
+    // -- Connect 1: receive ready, run /help --
+    const sock1 = await connectSocket(socketPath);
+    const r1 = lineReader(sock1);
+
+    await waitFor(
+      () => r1.events.some((e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'ready'),
+      5_000,
+      'first lifecycle:ready',
+    );
+
+    // Narrow subscription so we can assert the filter is applied.
+    sock1.write(JSON.stringify({ type: 'subscribe', events: ['lifecycle', 'command-output'] }) + '\n');
+    await new Promise((r) => setTimeout(r, 100));
+
+    // /help is offline-safe — no LLM call.
+    sock1.write(JSON.stringify({ type: 'command', command: '/help' }) + '\n');
+    await waitFor(
+      () => r1.events.filter((e) => e.type === 'command-output').length >= 5,
+      5_000,
+      'command-output lines from /help',
+    );
+
+    // -- Disconnect; verify child stays up --
+    r1.stop();
+    sock1.destroy();
+    await new Promise((r) => setTimeout(r, 200));
+    expect(child.exitCode).toBeNull();
+
+    // -- Connect 2: fresh ready event --
+    const sock2 = await connectSocket(socketPath);
+    const r2 = lineReader(sock2);
+
+    await waitFor(
+      () => r2.events.some((e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'ready'),
+      5_000,
+      'second lifecycle:ready (after reconnect)',
+    );
+
+    // -- Shutdown; verify exit + cleanup --
+    sock2.write(JSON.stringify({ type: 'shutdown' }) + '\n');
+
+    await waitFor(
+      () => r2.events.some((e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'exiting'),
+      3_000,
+      'lifecycle:exiting',
+    );
+
+    const exitCode = await new Promise<number | null>((resolveExit) => {
+      if (child.exitCode !== null) { resolveExit(child.exitCode); return; }
+      child.once('exit', (code) => resolveExit(code));
+    });
+
+    r2.stop();
+    sock2.destroy();
+
+    expect(exitCode).toBe(0);
+
+    // Give OS a beat for unlink to propagate
+    await new Promise((r) => setTimeout(r, 100));
+    expect(existsSync(socketPath)).toBe(false);
+    expect(existsSync(pidPath)).toBe(false);
+    expect(existsSync(logPath)).toBe(true);
+    expect(readFileSync(logPath, 'utf-8').length).toBeGreaterThan(0);
+  }, 60_000);
+});

package/test/logging-adapter.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from 'bun:test';
+import { LoggingAnthropicAdapter } from '../src/logging-adapter.js';
+import type { ProviderRequest, ProviderResponse } from '@animalabs/membrane';
+
+// Regression guard for the reasoning passthrough. `withReasoning` injects
+// adaptive `thinking` into `request.extra`, which the Anthropic adapter
+// forwards to the API params verbatim. This is invisible to the type system
+// (membrane's ProviderRequest doesn't type `thinking`), so it's exactly the
+// kind of contract that silently rots on a dependency bump — pin it here so
+// the next break is a red test with a name, not a tsc error blamed on the
+// wrong package (see the git history of this file).
+
+const baseRequest: ProviderRequest = {
+  messages: [],
+  model: 'claude-opus-4-6',
+  maxTokens: 1024,
+};
+
+const enabled = () => ({ enabled: true, budgetTokens: 0 });
+const disabled = () => ({ enabled: false, budgetTokens: 0 });
+
+describe('LoggingAnthropicAdapter.withReasoning', () => {
+  test('injects adaptive thinking into request.extra when reasoning enabled', () => {
+    const adapter = new LoggingAnthropicAdapter({ apiKey: 'test' }, '/dev/null', enabled);
+    const out = (adapter as unknown as { withReasoning(r: ProviderRequest): ProviderRequest })
+      .withReasoning(baseRequest);
+    expect((out.extra as Record<string, { type?: string }> | undefined)?.thinking?.type).toBe('adaptive');
+    // shallow clone — original request untouched
+    expect((baseRequest as { extra?: unknown }).extra).toBeUndefined();
+  });
+
+  test('preserves pre-existing extra keys', () => {
+    const adapter = new LoggingAnthropicAdapter({ apiKey: 'test' }, '/dev/null', enabled);
+    const req = { ...baseRequest, extra: { normalizedMessages: 'keep-me' } } as ProviderRequest;
+    const out = (adapter as unknown as { withReasoning(r: ProviderRequest): ProviderRequest })
+      .withReasoning(req);
+    const extra = out.extra as Record<string, unknown>;
+    expect(extra.normalizedMessages).toBe('keep-me');
+    expect((extra.thinking as { type?: string }).type).toBe('adaptive');
+  });
+
+  test('no-op (same reference) when reasoning disabled', () => {
+    const adapter = new LoggingAnthropicAdapter({ apiKey: 'test' }, '/dev/null', disabled);
+    const out = (adapter as unknown as { withReasoning(r: ProviderRequest): ProviderRequest })
+      .withReasoning(baseRequest);
+    expect(out).toBe(baseRequest);
+  });
+
+  test('no-op when no reasoning getter is wired', () => {
+    const adapter = new LoggingAnthropicAdapter({ apiKey: 'test' }, '/dev/null');
+    const out = (adapter as unknown as { withReasoning(r: ProviderRequest): ProviderRequest })
+      .withReasoning(baseRequest);
+    expect(out).toBe(baseRequest);
+  });
+});
+
+describe('LoggingAnthropicAdapter request logging', () => {
+  const adapter = new LoggingAnthropicAdapter({ apiKey: 'test' }, '/dev/null');
+  const internals = adapter as unknown as {
+    requestSummary(r: ProviderRequest): Record<string, unknown>;
+    refusalRawRequest(r: ProviderResponse, raw: unknown): unknown;
+  };
+
+  test('summarizes requests without retaining message content', () => {
+    const request = {
+      ...baseRequest,
+      messages: [{ role: 'user', content: [{ type: 'text', text: 'large context' }] }],
+      tools: [{ name: 'shell', description: 'run a command', inputSchema: {} }],
+    } as ProviderRequest;
+
+    expect(internals.requestSummary(request)).toEqual({
+      model: 'claude-opus-4-6',
+      maxTokens: 1024,
+      messages: 1,
+      tools: 1,
+    });
+  });
+
+  test('retains the raw request only for refusals', () => {
+    const rawRequest = { messages: ['forensic context'] };
+    const success = { raw: { stop_reason: 'end_turn' } } as unknown as ProviderResponse;
+    const refusal = { raw: { stop_reason: 'refusal' } } as unknown as ProviderResponse;
+
+    expect(internals.refusalRawRequest(success, rawRequest)).toBeUndefined();
+    expect(internals.refusalRawRequest(refusal, rawRequest)).toBe(rawRequest);
+  });
+});

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

@@ -0,0 +1,213 @@
+/**
+ * McplAdminModule — agent-facing deploy/restart/unload tools, exercised
+ * against a stub framework. Overlay persistence is verified on disk.
+ */
+
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { AgentFramework } from '@animalabs/agent-framework';
+
+import { McplAdminModule } from '../src/modules/mcpl-admin-module.js';
+import { readAgentOverlay, saveAgentOverlay } from '../src/mcpl-config.js';
+
+interface StubServer {
+  id: string;
+  connected: boolean;
+  toolPrefix: string;
+  toolCount: number;
+  command?: string;
+  url?: string;
+}
+
+function makeStubFramework() {
+  const servers = new Map<string, StubServer>();
+  const calls: string[] = [];
+  const stub = {
+    listMcplServers: () => [...servers.values()],
+    connectMcplServer: async (config: { id: string; command?: string; url?: string; toolPrefix?: string }) => {
+      calls.push(`connect:${config.id}`);
+      if (servers.has(config.id)) throw new Error(`MCPL server "${config.id}" is already registered`);
+      servers.set(config.id, {
+        id: config.id,
+        connected: true,
+        toolPrefix: config.toolPrefix ?? `mcpl--${config.id}`,
+        toolCount: 1,
+        command: config.command,
+        url: config.url,
+      });
+    },
+    disconnectMcplServer: async (id: string) => {
+      calls.push(`disconnect:${id}`);
+      servers.delete(id);
+    },
+    restartMcplServer: async (id: string, config?: { id: string; command?: string }) => {
+      calls.push(`restart:${id}`);
+      if (!servers.has(id) && !config) throw new Error(`MCPL server "${id}" is not configured`);
+      const prev = servers.get(id);
+      servers.set(id, {
+        id,
+        connected: true,
+        toolPrefix: `mcpl--${id}`,
+        toolCount: 1,
+        command: config?.command ?? prev?.command,
+      });
+    },
+  };
+  return { stub: stub as unknown as AgentFramework, servers, calls };
+}
+
+let dir: string;
+let overlayPath: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'mcpl-admin-'));
+  overlayPath = join(dir, 'mcpl-servers.agent.json');
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function makeModule(framework: AgentFramework) {
+  const mod = new McplAdminModule({
+    overlayPath,
+    configPath: join(dir, 'mcpl-servers.json'),
+  });
+  mod.setFramework(framework);
+  return mod;
+}
+
+function call(mod: McplAdminModule, name: string, input: Record<string, unknown> = {}) {
+  return mod.handleToolCall({ id: 'c1', name, input } as never);
+}
+
+describe('mcpl_deploy', () => {
+  test('deploys a new server: connects it and persists to the overlay', async () => {
+    const { stub, servers, calls } = makeStubFramework();
+    const mod = makeModule(stub);
+
+    const result = await call(mod, 'mcpl_deploy', { id: 'mytool', command: 'node', args: ['tool.js'] });
+
+    expect(result.success).toBe(true);
+    expect(calls).toEqual(['connect:mytool']);
+    expect(servers.has('mytool')).toBe(true);
+    expect(readAgentOverlay(overlayPath).mytool).toEqual({ command: 'node', args: ['tool.js'] });
+  });
+
+  test('redeploying a loaded server restarts it with the new config', async () => {
+    const { stub, calls } = makeStubFramework();
+    const mod = makeModule(stub);
+
+    await call(mod, 'mcpl_deploy', { id: 'mytool', command: 'node' });
+    const result = await call(mod, 'mcpl_deploy', { id: 'mytool', command: 'bun' });
+
+    expect(result.success).toBe(true);
+    expect(calls).toEqual(['connect:mytool', 'restart:mytool']);
+    expect(readAgentOverlay(overlayPath).mytool).toEqual({ command: 'bun' });
+  });
+
+  test('rejects missing command/url, both at once, and bad ids', async () => {
+    const { stub } = makeStubFramework();
+    const mod = makeModule(stub);
+
+    expect((await call(mod, 'mcpl_deploy', { id: 'x' })).success).toBe(false);
+    expect((await call(mod, 'mcpl_deploy', { id: 'x', command: 'a', url: 'ws://b' })).success).toBe(false);
+    expect((await call(mod, 'mcpl_deploy', { id: 'bad id!', command: 'a' })).success).toBe(false);
+  });
+
+  test('connect failure keeps the overlay entry and reports the error', async () => {
+    const { stub } = makeStubFramework();
+    (stub as unknown as { connectMcplServer: () => Promise<void> }).connectMcplServer =
+      async () => { throw new Error('spawn ENOENT'); };
+    const mod = makeModule(stub);
+
+    const result = await call(mod, 'mcpl_deploy', { id: 'broken', command: 'nonexistent' });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('spawn ENOENT');
+    expect(readAgentOverlay(overlayPath).broken).toEqual({ command: 'nonexistent' });
+  });
+});
+
+describe('mcpl_unload', () => {
+  test('agent-deployed server: disconnects and deletes the overlay entry', async () => {
+    const { stub, servers } = makeStubFramework();
+    const mod = makeModule(stub);
+    await call(mod, 'mcpl_deploy', { id: 'mytool', command: 'node' });
+
+    const result = await call(mod, 'mcpl_unload', { id: 'mytool' });
+
+    expect(result.success).toBe(true);
+    expect(servers.has('mytool')).toBe(false);
+    expect(readAgentOverlay(overlayPath).mytool).toBeUndefined();
+  });
+
+  test('recipe server: disconnects and writes a tombstone', async () => {
+    const { stub, servers } = makeStubFramework();
+    // Simulate a recipe-loaded server the module didn't deploy.
+    await (stub as unknown as { connectMcplServer: (c: { id: string; command: string }) => Promise<void> })
+      .connectMcplServer({ id: 'discord', command: 'node' });
+    const mod = makeModule(stub);
+
+    const result = await call(mod, 'mcpl_unload', { id: 'discord' });
+
+    expect(result.success).toBe(true);
+    expect(servers.has('discord')).toBe(false);
+    expect(readAgentOverlay(overlayPath).discord).toEqual({ disabled: true });
+  });
+
+  test('persist:false leaves the overlay untouched', 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 result = await call(mod, 'mcpl_unload', { id: 'discord', persist: false });
+
+    expect(result.success).toBe(true);
+    expect(servers.has('discord')).toBe(false);
+    expect(readAgentOverlay(overlayPath)).toEqual({});
+  });
+
+  test('unknown server errors', async () => {
+    const { stub } = makeStubFramework();
+    const mod = makeModule(stub);
+    expect((await call(mod, 'mcpl_unload', { id: 'nope' })).success).toBe(false);
+  });
+});
+
+describe('mcpl_restart', () => {
+  test('restarts a loaded server', async () => {
+    const { stub, calls } = makeStubFramework();
+    await (stub as unknown as { connectMcplServer: (c: { id: string; command: string }) => Promise<void> })
+      .connectMcplServer({ id: 'discord', command: 'node' });
+    const mod = makeModule(stub);
+
+    const result = await call(mod, 'mcpl_restart', { id: 'discord' });
+
+    expect(result.success).toBe(true);
+    expect(calls).toEqual(['connect:discord', 'restart:discord']);
+  });
+});
+
+describe('mcpl_list', () => {
+  test('shows live servers, sources, and tombstones', async () => {
+    const { stub } = makeStubFramework();
+    await (stub as unknown as { connectMcplServer: (c: { id: string; command: string }) => Promise<void> })
+      .connectMcplServer({ id: 'discord', command: 'node' });
+    const mod = makeModule(stub);
+    await call(mod, 'mcpl_deploy', { id: 'mytool', command: 'bun' });
+    saveAgentOverlay(overlayPath, { ...readAgentOverlay(overlayPath), gone: { disabled: true } });
+
+    const result = await call(mod, 'mcpl_list');
+
+    expect(result.success).toBe(true);
+    const text = String(result.data);
+    expect(text).toContain('discord: CONNECTED');
+    expect(text).toContain('mytool: CONNECTED');
+    expect(text).toContain('source=agent-overlay');
+    expect(text).toContain('gone: UNLOADED');
+  });
+});