@animalabs/connectome-host 0.3.1

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

@@ -0,0 +1,126 @@
+/**
+ * Agent overlay (mcpl-servers.agent.json) — persistence and merge semantics
+ * for agent-deployed MCPL servers.
+ */
+
+import { test, expect, describe } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import {
+  readAgentOverlay,
+  saveAgentOverlay,
+  applyAgentOverlay,
+  resolveOverlayEntry,
+  type AgentOverlayEntry,
+} from '../src/mcpl-config.js';
+
+function withTmp<T>(fn: (dir: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), 'agent-overlay-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe('readAgentOverlay / saveAgentOverlay', () => {
+  test('missing file reads as empty object', () => {
+    withTmp((dir) => {
+      expect(readAgentOverlay(join(dir, 'nope.json'))).toEqual({});
+    });
+  });
+
+  test('round-trips entries', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'mcpl-servers.agent.json');
+      const entries: Record<string, AgentOverlayEntry> = {
+        mytool: { command: 'node', args: ['server.js'] },
+        discord: { disabled: true },
+      };
+      saveAgentOverlay(path, entries);
+      expect(readAgentOverlay(path)).toEqual(entries);
+    });
+  });
+});
+
+describe('applyAgentOverlay', () => {
+  const base = [
+    { id: 'discord', command: 'node', args: ['/abs/discord.js'] },
+    { id: 'heartbeat', command: 'node', args: ['/abs/heartbeat.js'] },
+  ];
+
+  test('no overlay file → servers unchanged', () => {
+    withTmp((dir) => {
+      const result = applyAgentOverlay(base, join(dir, 'nope.json'));
+      expect(result).toEqual(base);
+    });
+  });
+
+  test('tombstone removes a recipe server', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'overlay.json');
+      saveAgentOverlay(path, { discord: { disabled: true } });
+      const result = applyAgentOverlay(base, path);
+      expect(result.map(s => s.id)).toEqual(['heartbeat']);
+    });
+  });
+
+  test('overlay entry replaces an existing server in place', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'overlay.json');
+      saveAgentOverlay(path, { heartbeat: { command: 'bun', args: ['new.ts'] } });
+      const result = applyAgentOverlay(base, path);
+      expect(result.map(s => s.id)).toEqual(['discord', 'heartbeat']);
+      const hb = result.find(s => s.id === 'heartbeat') as Record<string, unknown>;
+      expect(hb.command).toBe('bun');
+    });
+  });
+
+  test('new overlay entry is appended', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'overlay.json');
+      saveAgentOverlay(path, { mytool: { command: 'node', args: ['tool.js'] } });
+      const result = applyAgentOverlay(base, path);
+      expect(result.map(s => s.id)).toEqual(['discord', 'heartbeat', 'mytool']);
+    });
+  });
+
+  test('relative args resolve against the overlay directory', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'overlay.json');
+      saveAgentOverlay(path, { mytool: { command: 'node', args: ['./servers/tool.js', '--flag'] } });
+      const result = applyAgentOverlay(base, path);
+      const tool = result.find(s => s.id === 'mytool') as { args: string[] };
+      expect(tool.args[0]).toBe(resolve(dir, './servers/tool.js'));
+      expect(tool.args[1]).toBe('--flag');
+    });
+  });
+
+  test('entries with neither command nor url are skipped (corrupt tombstone-ish)', () => {
+    withTmp((dir) => {
+      const path = join(dir, 'overlay.json');
+      writeFileSync(path, JSON.stringify({ mcplServers: { broken: { env: { A: '1' } } } }));
+      const result = applyAgentOverlay(base, path);
+      expect(result.map(s => s.id)).toEqual(['discord', 'heartbeat']);
+    });
+  });
+});
+
+describe('resolveOverlayEntry', () => {
+  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', () => {
+    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' });
+  });
+
+  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' });
+  });
+});

package/test/mock-headless-child.ts

@@ -0,0 +1,133 @@
+/**
+ * Minimal wire-protocol-only mock of a headless child, used as
+ * FleetModuleConfig.childIndexPath in orchestration tests.
+ *
+ * Implements just enough of the parent↔child protocol to exercise
+ * fleet--relay / fleet--await / lifecycle:idle / inference:speech
+ * without spinning up the full framework + Membrane + Chronicle stack.
+ *
+ * Commands it understands (on top of shutdown/subscribe from the real one):
+ *   { "type": "text", "content": "..." }
+ *       → emit inference:started, inference:speech, inference:completed,
+ *         then lifecycle:idle after ~30ms (simulates final-inference round).
+ *
+ *   { "type": "command", "command": "/hang" }
+ *       → same as text but SKIP the lifecycle:idle emit (for await timeout).
+ *
+ *   { "type": "command", "command": "/crash" }
+ *       → process.exit(1) (for await crash-detection test).
+ *
+ *   { "type": "command", "command": "/tool-use-then-speak <text>" }
+ *       → simulate a tool-using turn (tool_calls_yielded clears speech)
+ *         followed by a final turn with the supplied text.
+ */
+import { createServer, type Socket } from 'node:net';
+import { join, resolve } from 'node:path';
+import { existsSync, unlinkSync, mkdirSync, writeFileSync } from 'node:fs';
+
+const dataDir = resolve(process.env.DATA_DIR || './data');
+mkdirSync(dataDir, { recursive: true });
+const socketPath = join(dataDir, 'ipc.sock');
+const pidPath = join(dataDir, 'headless.pid');
+
+if (existsSync(socketPath)) {
+  try { unlinkSync(socketPath); } catch { /* noop */ }
+}
+writeFileSync(pidPath, String(process.pid));
+
+let currentClient: Socket | null = null;
+
+function emit(obj: Record<string, unknown>): void {
+  if (!currentClient) return;
+  try {
+    currentClient.write(JSON.stringify({ ...obj, ts: Date.now() }) + '\n');
+  } catch { /* noop */ }
+}
+
+const server = createServer((sock) => {
+  if (currentClient) {
+    try { currentClient.end(); } catch { /* noop */ }
+  }
+  currentClient = sock;
+
+  let buf = '';
+  sock.on('data', (chunk) => {
+    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;
+      let msg: Record<string, unknown>;
+      try { msg = JSON.parse(line) as Record<string, unknown>; } catch { continue; }
+      dispatch(msg);
+    }
+  });
+
+  sock.on('end', () => { if (currentClient === sock) currentClient = null; });
+  sock.on('error', () => { /* swallow */ });
+
+  // Ready with our own pid.
+  emit({ type: 'lifecycle', phase: 'ready', pid: process.pid, dataDir });
+});
+
+function simulateFinalInference(text: string, emitIdleAfter: boolean): void {
+  emit({ type: 'inference:started', agentName: 'mock' });
+  emit({ type: 'inference:speech', agentName: 'mock', content: text });
+  emit({ type: 'inference:completed', agentName: 'mock' });
+  if (emitIdleAfter) {
+    setTimeout(() => emit({ type: 'lifecycle', phase: 'idle' }), 30);
+  }
+}
+
+function dispatch(msg: Record<string, unknown>): void {
+  const t = typeof msg.type === 'string' ? msg.type : '';
+  if (t === 'subscribe') return;  // accept silently
+  if (t === 'shutdown') {
+    emit({ type: 'lifecycle', phase: 'exiting', reason: 'shutdown' });
+    setTimeout(() => process.exit(0), 50);
+    return;
+  }
+  if (t === 'text' && typeof msg.content === 'string') {
+    simulateFinalInference(`echo: ${msg.content}`, true);
+    return;
+  }
+  if (t === 'command' && typeof msg.command === 'string') {
+    const cmd = msg.command;
+    if (cmd === '/hang') {
+      // Simulate text intake without going idle — for await-timeout testing.
+      emit({ type: 'inference:started', agentName: 'mock' });
+      emit({ type: 'inference:speech', agentName: 'mock', content: 'still thinking' });
+      emit({ type: 'inference:completed', agentName: 'mock' });
+      // No lifecycle:idle.
+      return;
+    }
+    if (cmd === '/crash') {
+      process.exit(1);
+    }
+    if (cmd.startsWith('/tool-use-then-speak ')) {
+      const finalText = cmd.slice('/tool-use-then-speak '.length);
+      // Round 1: thought preamble that ends in tool calls — speech tracker resets.
+      emit({ type: 'inference:started', agentName: 'mock' });
+      emit({ type: 'inference:tokens', agentName: 'mock', content: 'let me think' });
+      emit({ type: 'inference:tool_calls_yielded', agentName: 'mock', calls: [{ id: 't1', name: 'dummy', input: {} }] });
+      emit({ type: 'inference:completed', agentName: 'mock' });
+      // Round 2: final speech — should be the one that lands in lastCompletedSpeech.
+      setTimeout(() => simulateFinalInference(finalText, true), 20);
+      return;
+    }
+    if (cmd === '/help') {
+      emit({ type: 'command-output', text: '--- mock help ---', style: 'system' });
+      emit({ type: 'command-output', text: '  no real commands here', style: 'system' });
+      return;
+    }
+  }
+}
+
+server.listen(socketPath);
+server.on('error', () => { /* swallow */ });
+
+process.on('SIGTERM', () => {
+  emit({ type: 'lifecycle', phase: 'exiting', reason: 'sigterm' });
+  setTimeout(() => process.exit(0), 50);
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Tests for recipe.agent.cacheTtl: accepted values pass validation and an
+ * invalid TTL fails at recipe-load time (not as a provider 400 at first
+ * inference).
+ */
+import { describe, test, expect } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipeWithCacheTtl(cacheTtl?: unknown) {
+  return {
+    name: 'ttl-test',
+    agent: {
+      systemPrompt: 'sys',
+      ...(cacheTtl !== undefined && { cacheTtl }),
+    },
+  };
+}
+
+describe('recipe agent.cacheTtl validation', () => {
+  test('accepts "5m"', () => {
+    expect(validateRecipe(recipeWithCacheTtl('5m')).agent.cacheTtl).toBe('5m');
+  });
+
+  test('accepts "1h"', () => {
+    expect(validateRecipe(recipeWithCacheTtl('1h')).agent.cacheTtl).toBe('1h');
+  });
+
+  test('accepts unset (provider default applies)', () => {
+    expect(validateRecipe(recipeWithCacheTtl()).agent.cacheTtl).toBeUndefined();
+  });
+
+  test('rejects a typo\'d TTL at load time', () => {
+    expect(() => validateRecipe(recipeWithCacheTtl('1hr'))).toThrow(/cacheTtl must be '5m' or '1h'/);
+    expect(() => validateRecipe(recipeWithCacheTtl('60m'))).toThrow(/cacheTtl/);
+    expect(() => validateRecipe(recipeWithCacheTtl(3600))).toThrow(/cacheTtl/);
+  });
+});

package/test/recipe-env.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Tests for the ${VAR} env substitution added to loadRecipe.
+ * Exercises substituteEnvVars() directly (pure function) plus an end-to-end
+ * loadRecipe flow via a temp recipe file.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadRecipe, substituteEnvVars } from '../src/recipe.js';
+
+describe('substituteEnvVars', () => {
+  const originalEnv = process.env;
+  beforeEach(() => { process.env = { ...originalEnv }; });
+  afterEach(() => { process.env = originalEnv; });
+
+  test('substitutes ${VAR} in a string', () => {
+    process.env.FOO = 'hello';
+    expect(substituteEnvVars('prefix ${FOO} suffix', 'test')).toBe('prefix hello suffix');
+  });
+
+  test('substitutes multiple vars in one string', () => {
+    process.env.A = 'x'; process.env.B = 'y';
+    expect(substituteEnvVars('${A}-${B}', 'test')).toBe('x-y');
+  });
+
+  test('leaves strings without patterns untouched', () => {
+    expect(substituteEnvVars('no pattern here', 'test')).toBe('no pattern here');
+  });
+
+  test('walks nested objects', () => {
+    process.env.TOKEN = 'abc123';
+    const input = {
+      mcpServers: {
+        gitlab: {
+          env: { TOKEN: '${TOKEN}' },
+          args: ['--flag', 'value'],
+        },
+      },
+    };
+    const out = substituteEnvVars(input, 'test') as typeof input;
+    expect(out.mcpServers.gitlab.env.TOKEN).toBe('abc123');
+    expect(out.mcpServers.gitlab.args).toEqual(['--flag', 'value']);
+  });
+
+  test('walks arrays', () => {
+    process.env.X = 'X-val';
+    const out = substituteEnvVars(['a', '${X}', 'c'], 'test');
+    expect(out).toEqual(['a', 'X-val', 'c']);
+  });
+
+  test('passes through non-string leaves', () => {
+    const out = substituteEnvVars({ a: 1, b: true, c: null, d: 'literal' }, 'test');
+    expect(out).toEqual({ a: 1, b: true, c: null, d: 'literal' });
+  });
+
+  test('throws on missing env var with actionable message', () => {
+    delete process.env.MISSING_VAR;
+    expect(() => substituteEnvVars('${MISSING_VAR}', 'recipes/foo.json'))
+      .toThrow(/MISSING_VAR/);
+    expect(() => substituteEnvVars('${MISSING_VAR}', 'recipes/foo.json'))
+      .toThrow(/recipes\/foo\.json/);
+    expect(() => substituteEnvVars('${MISSING_VAR}', 'recipes/foo.json'))
+      .toThrow(/\.env|delete the section/);
+  });
+
+  test('does not touch literal $-without-braces', () => {
+    expect(substituteEnvVars('price: $5 and $100', 'test')).toBe('price: $5 and $100');
+  });
+
+  test('pattern requires valid identifier (starts with letter or underscore)', () => {
+    // ${1FOO} is not a valid var name and should be left alone.
+    expect(substituteEnvVars('${1FOO}', 'test')).toBe('${1FOO}');
+  });
+
+  test('supports underscore-prefixed names', () => {
+    process.env._PRIVATE = 'secret';
+    expect(substituteEnvVars('${_PRIVATE}', 'test')).toBe('secret');
+  });
+});
+
+describe('loadRecipe — end-to-end with env substitution', () => {
+  const originalEnv = process.env;
+  let tmpDir: string;
+  let recipePath: string;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-recipe-env-'));
+    recipePath = join(tmpDir, 'recipe.json');
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('substitution flows through loadRecipe to the validated recipe', async () => {
+    process.env.FAKE_TOKEN = 'tok-abc';
+    const recipe = {
+      name: 'Env Test',
+      agent: { systemPrompt: 'Your token is ${FAKE_TOKEN}.' },
+    };
+    writeFileSync(recipePath, JSON.stringify(recipe), 'utf-8');
+
+    const loaded = await loadRecipe(recipePath);
+    expect(loaded.agent.systemPrompt).toBe('Your token is tok-abc.');
+  });
+
+  test('missing env var surfaces a clear error from loadRecipe', async () => {
+    delete process.env.NEVER_SET;
+    const recipe = {
+      name: 'Env Test',
+      agent: { systemPrompt: 'placeholder' },
+      mcpServers: {
+        foo: { command: 'node', env: { SOME_KEY: '${NEVER_SET}' } },
+      },
+    };
+    writeFileSync(recipePath, JSON.stringify(recipe), 'utf-8');
+
+    await expect(loadRecipe(recipePath)).rejects.toThrow(/NEVER_SET/);
+  });
+
+  describe('${VAR:-default} syntax', () => {
+    test('uses default when var unset', () => {
+      delete process.env.LATER_SET;
+      expect(substituteEnvVars('${LATER_SET:-fallback}', 't')).toBe('fallback');
+    });
+
+    test('uses default when var is empty string', () => {
+      process.env.EMPTY_VAR = '';
+      expect(substituteEnvVars('${EMPTY_VAR:-fallback}', 't')).toBe('fallback');
+    });
+
+    test('uses var value when set and non-empty', () => {
+      process.env.SET_VAR = 'real-value';
+      expect(substituteEnvVars('${SET_VAR:-fallback}', 't')).toBe('real-value');
+    });
+
+    test('empty default is allowed', () => {
+      delete process.env.OPTIONAL_VAR;
+      expect(substituteEnvVars('${OPTIONAL_VAR:-}', 't')).toBe('');
+    });
+
+    test('does NOT throw on unset var with default', () => {
+      delete process.env.NEVER_SET;
+      expect(() => substituteEnvVars('${NEVER_SET:-default}', 't')).not.toThrow();
+    });
+
+    test('mixed default + required in same string', () => {
+      delete process.env.HOST;
+      delete process.env.PORT;
+      process.env.HOST = 'example.com';
+      expect(substituteEnvVars('${HOST}:${PORT:-21}', 't')).toBe('example.com:21');
+    });
+  });
+});

package/test/recipe-path-resolution.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests for parent-recipe-dir-relative resolution of
+ * `modules.fleet.children[].recipe`.
+ *
+ * Runtime paths (workspace mounts, dataDir) stay CWD-relative — those are
+ * intentionally NOT touched by this resolver and are covered elsewhere.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRecipe, resolveRecipeRelative, type Recipe } from '../src/recipe.js';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, '..');
+
+function writeParent(dir: string, children: Array<Record<string, unknown>>): string {
+  const path = join(dir, 'parent.json');
+  const recipe = {
+    name: 'Parent',
+    agent: { systemPrompt: 'x' },
+    modules: { fleet: { children } },
+  };
+  writeFileSync(path, JSON.stringify(recipe), 'utf-8');
+  return path;
+}
+
+function fleetChildren(recipe: Recipe) {
+  const fleet = recipe.modules?.fleet;
+  if (!fleet || typeof fleet !== 'object' || !fleet.children) {
+    throw new Error('recipe has no fleet.children');
+  }
+  return fleet.children;
+}
+
+describe('resolveRecipeRelative', () => {
+  test('absolute path passes through unchanged', () => {
+    expect(resolveRecipeRelative('/abs/miner.json', { kind: 'file', dir: '/anywhere' }))
+      .toBe('/abs/miner.json');
+  });
+
+  test('http URL passes through unchanged', () => {
+    expect(resolveRecipeRelative('https://ex.com/a.json', { kind: 'file', dir: '/anywhere' }))
+      .toBe('https://ex.com/a.json');
+    expect(resolveRecipeRelative('http://ex.com/a.json', { kind: 'url', base: 'https://other.com/' }))
+      .toBe('http://ex.com/a.json');
+  });
+
+  test('bare filename resolves against parent dir', () => {
+    expect(resolveRecipeRelative('child.json', { kind: 'file', dir: '/opt/recipes' }))
+      .toBe('/opt/recipes/child.json');
+  });
+
+  test('dotted prefix resolves against parent dir', () => {
+    expect(resolveRecipeRelative('./child.json', { kind: 'file', dir: '/opt/recipes' }))
+      .toBe('/opt/recipes/child.json');
+    expect(resolveRecipeRelative('../other/child.json', { kind: 'file', dir: '/opt/recipes' }))
+      .toBe('/opt/other/child.json');
+  });
+
+  test('URL base resolves relative child to sibling URL', () => {
+    expect(resolveRecipeRelative('child.json', { kind: 'url', base: 'https://ex.com/dir/parent.json' }))
+      .toBe('https://ex.com/dir/child.json');
+  });
+});
+
+describe('loadRecipe — children[].recipe resolution', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'conhost-recipe-resolve-'));
+  });
+
+  afterEach(() => {
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('external bundle: bare filename resolves to sibling of parent', async () => {
+    const parentPath = writeParent(tmpDir, [
+      { name: 'kid', recipe: 'child.json', autoStart: true },
+    ]);
+    writeFileSync(join(tmpDir, 'child.json'), JSON.stringify({
+      name: 'Child', agent: { systemPrompt: 'y' },
+    }), 'utf-8');
+
+    const recipe = await loadRecipe(parentPath);
+    const [child] = fleetChildren(recipe);
+    expect(child.recipe).toBe(resolve(tmpDir, 'child.json'));
+  });
+
+  test('CWD-independence: same parent, different CWDs, same resolution', async () => {
+    const parentPath = writeParent(tmpDir, [
+      { name: 'kid', recipe: './child.json', autoStart: true },
+    ]);
+    const expected = resolve(tmpDir, 'child.json');
+
+    const originalCwd = process.cwd();
+    try {
+      process.chdir('/tmp');
+      const a = await loadRecipe(parentPath);
+      process.chdir(tmpDir);
+      const b = await loadRecipe(parentPath);
+      process.chdir(REPO_ROOT);
+      const c = await loadRecipe(parentPath);
+
+      expect(fleetChildren(a)[0].recipe).toBe(expected);
+      expect(fleetChildren(b)[0].recipe).toBe(expected);
+      expect(fleetChildren(c)[0].recipe).toBe(expected);
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+
+  test('absolute child path passes through', async () => {
+    const absChild = join(tmpDir, 'elsewhere.json');
+    const parentPath = writeParent(tmpDir, [
+      { name: 'kid', recipe: absChild, autoStart: true },
+    ]);
+
+    const recipe = await loadRecipe(parentPath);
+    expect(fleetChildren(recipe)[0].recipe).toBe(absChild);
+  });
+
+  test('URL child path passes through', async () => {
+    const parentPath = writeParent(tmpDir, [
+      { name: 'kid', recipe: 'https://example.com/child.json', autoStart: true },
+    ]);
+
+    const recipe = await loadRecipe(parentPath);
+    expect(fleetChildren(recipe)[0].recipe).toBe('https://example.com/child.json');
+  });
+
+  test('nested parent dir: child resolves relative to the parent file, not CWD', async () => {
+    const nested = join(tmpDir, 'bundle');
+    mkdirSync(nested, { recursive: true });
+    const parentPath = writeParent(nested, [
+      { name: 'kid', recipe: 'child.json', autoStart: true },
+    ]);
+
+    const originalCwd = process.cwd();
+    try {
+      process.chdir(tmpDir); // NOT the bundle dir
+      const recipe = await loadRecipe(parentPath);
+      expect(fleetChildren(recipe)[0].recipe).toBe(resolve(nested, 'child.json'));
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+
+  test('in-tree triumvirate: children resolve to siblings in recipes/', async () => {
+    // The shipped triumvirate.json references ${ZULIP_CHANNEL} in its
+    // conductor prompt; substituteEnvVars throws on missing vars, so set
+    // a placeholder for the load.  We're only testing path resolution.
+    const prevZulipChannel = process.env.ZULIP_CHANNEL;
+    process.env.ZULIP_CHANNEL = 'test-channel';
+    try {
+      const triumviratePath = join(REPO_ROOT, 'recipes', 'triumvirate.json');
+      const recipe = await loadRecipe(triumviratePath);
+      const children = fleetChildren(recipe);
+      const byName = Object.fromEntries(children.map((c) => [c.name, c.recipe]));
+      expect(byName.miner).toBe(join(REPO_ROOT, 'recipes', 'knowledge-miner.json'));
+      expect(byName.reviewer).toBe(join(REPO_ROOT, 'recipes', 'knowledge-reviewer.json'));
+      expect(byName.clerk).toBe(join(REPO_ROOT, 'recipes', 'clerk.json'));
+    } finally {
+      if (prevZulipChannel === undefined) delete process.env.ZULIP_CHANNEL;
+      else process.env.ZULIP_CHANNEL = prevZulipChannel;
+    }
+  });
+});