@animalabs/connectome-host 0.3.1

package/test/fleet-no-subfleets.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Phase 6 — no-subfleets invariant.
+ *
+ * A fleet child recipe may not itself declare a `modules.fleet` entry.
+ * Validation happens before subprocess spawn so the failure surfaces as a
+ * clean synchronous tool error.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FleetModule } from '../src/modules/fleet-module.js';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, '..');
+const INDEX_PATH = join(REPO_ROOT, 'src', 'index.ts');
+
+interface ToolResultLike {
+  success?: boolean;
+  isError?: boolean;
+  error?: string;
+}
+
+describe('FleetModule — no-subfleets invariant', () => {
+  let tmpDir: string;
+  // Tests 3 and 4 pass validation and actually spawn a (detached) bun child;
+  // without explicit cleanup the children orphan to PID 1.  Track every
+  // FleetModule we construct so afterAll can reap them.
+  const activeFleets: FleetModule[] = [];
+
+  beforeAll(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-no-subfleets-'));
+  });
+
+  afterAll(async () => {
+    // Reap in parallel — production shutdown timeouts (graceful 10s + SIGTERM 5s
+    // + SIGKILL 2s ≈ 17s per fleet) would blow Bun's 5s hook budget if awaited
+    // serially. The constructor below also overrides those to snappy values.
+    await Promise.all(activeFleets.map((f) => f.stop().catch(() => { /* noop */ })));
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  }, 30_000);
+
+  async function runLaunch(recipeBody: object): Promise<ToolResultLike> {
+    const recipePath = join(tmpDir, `recipe-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+    writeFileSync(recipePath, JSON.stringify(recipeBody), 'utf-8');
+
+    const fleet = new FleetModule({
+      childRuntimePath: 'bun',
+      childIndexPath: INDEX_PATH,
+      // Snappy shutdown so afterAll reaping stays within the hook budget
+      // even if a spawned child is uncooperative (no API key, etc.).
+      gracefulShutdownMs: 1_000,
+      sigtermEscalationMs: 500,
+    });
+    activeFleets.push(fleet);
+    // FleetModule.start() reads/writes Chronicle state; for a pure validation
+    // test we drive handleToolCall directly without start(). The launch path
+    // we exercise here checks the recipe before any subprocess spawn.
+    const result = await fleet.handleToolCall({
+      id: 'test-call',
+      name: 'launch',
+      input: {
+        name: 'subfleet-child',
+        recipe: recipePath,
+        dataDir: join(tmpDir, 'subfleet-child'),
+      },
+    }) as ToolResultLike;
+
+    return result;
+  }
+
+  test('recipe with modules.fleet=true is rejected', async () => {
+    const result = await runLaunch({
+      name: 'NestedFleetTrue',
+      agent: { name: 'inner', systemPrompt: 'x' },
+      modules: {
+        fleet: true,
+        subagents: false,
+        lessons: false,
+        retrieval: false,
+        wake: false,
+        workspace: false,
+      },
+    });
+    expect(result.success).toBe(false);
+    expect(result.isError).toBe(true);
+    expect(result.error).toContain('nested fleets are not supported');
+  });
+
+  test('recipe with modules.fleet object is rejected', async () => {
+    const result = await runLaunch({
+      name: 'NestedFleetObject',
+      agent: { name: 'inner', systemPrompt: 'x' },
+      modules: {
+        fleet: { children: [] },
+        subagents: false,
+        lessons: false,
+        retrieval: false,
+        wake: false,
+        workspace: false,
+      },
+    });
+    expect(result.success).toBe(false);
+    expect(result.isError).toBe(true);
+    expect(result.error).toContain('nested fleets are not supported');
+  });
+
+  test('recipe without fleet module is accepted (passes validation, may fail later in spawn path)', async () => {
+    const result = await runLaunch({
+      name: 'PlainChild',
+      agent: { name: 'inner', systemPrompt: 'x' },
+      modules: {
+        subagents: false,
+        lessons: false,
+        retrieval: false,
+        wake: false,
+        workspace: false,
+      },
+    });
+    // We don't care if the spawn itself succeeds in this test environment —
+    // we care that the *invariant validation* doesn't reject it. Any rejection
+    // here would be from a different code path (spawn-time errors), not the
+    // no-subfleets check we just added.
+    if (result.success === false && result.error) {
+      expect(result.error).not.toContain('nested fleets');
+    }
+  });
+
+  test('recipe with modules.fleet=false is accepted (explicit opt-out is fine)', async () => {
+    const result = await runLaunch({
+      name: 'ExplicitlyDisabledFleet',
+      agent: { name: 'inner', systemPrompt: 'x' },
+      modules: {
+        fleet: false,
+        subagents: false,
+        lessons: false,
+        retrieval: false,
+        wake: false,
+        workspace: false,
+      },
+    });
+    if (result.success === false && result.error) {
+      expect(result.error).not.toContain('nested fleets');
+    }
+  });
+});

package/test/fleet-orchestration.test.ts

@@ -0,0 +1,353 @@
+/**
+ * Tests for the orchestration primitives added alongside the Phase-5 caveat fixes:
+ *   - child-side synthetic events (lifecycle:idle, inference:speech)
+ *   - fleet--relay (sibling messaging)
+ *   - fleet--await (fan-out wait)
+ *
+ * Uses a minimal mock child (test/mock-headless-child.ts) so the tests don't
+ * need an ANTHROPIC_API_KEY or a working framework/Membrane/Chronicle stack.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, 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,
+  });
+}
+
+async function launchChild(fleet: FleetModule, name: string, dataDir: string): Promise<void> {
+  const res = await fleet.handleToolCall({
+    id: `launch-${name}`,
+    name: 'launch',
+    input: { name, recipe: 'mock-recipe', dataDir },
+  });
+  if (!res.success) {
+    throw new Error(`launch ${name} failed: ${res.error}`);
+  }
+}
+
+async function send(fleet: FleetModule, name: string, content: string): Promise<void> {
+  const res = await fleet.handleToolCall({
+    id: `send-${name}-${Date.now()}`,
+    name: 'send',
+    input: { name, content },
+  });
+  if (!res.success) throw new Error(`send to ${name} failed: ${res.error}`);
+}
+
+async function command(fleet: FleetModule, name: string, cmd: string): Promise<void> {
+  const res = await fleet.handleToolCall({
+    id: `cmd-${name}-${Date.now()}`,
+    name: 'command',
+    input: { name, command: cmd },
+  });
+  if (!res.success) throw new Error(`command ${cmd} to ${name} failed: ${res.error}`);
+}
+
+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, 30));
+  }
+  throw new Error(`waitFor timed out: ${label}`);
+}
+
+describe('lifecycle:idle + inference:speech from mock child', () => {
+  let tmpDir: string;
+  let fleet: FleetModule;
+
+  beforeAll(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-orch-synth-'));
+    fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'a', join(tmpDir, 'a'));
+  });
+
+  afterAll(async () => {
+    try { await fleet.stop(); } catch { /* noop */ }
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('text command triggers inference:speech and lifecycle:idle', async () => {
+    await send(fleet, 'a', 'hello there');
+
+    await waitFor(
+      () => fleet.getChildren().get('a')!.lastCompletedSpeech.length > 0,
+      2_000,
+      'lastCompletedSpeech populated from inference:speech',
+    );
+    expect(fleet.getChildren().get('a')!.lastCompletedSpeech).toBe('echo: hello there');
+
+    await waitFor(
+      () => fleet.getChildren().get('a')!.events.some(
+        (e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'idle',
+      ),
+      2_000,
+      'lifecycle:idle event recorded',
+    );
+  });
+
+  test('tool-ending round does NOT update lastCompletedSpeech; final round does', async () => {
+    // Before: we have "echo: hello there" from the previous test.
+    const before = fleet.getChildren().get('a')!.lastCompletedSpeech;
+    expect(before).toContain('echo: hello there');
+
+    await command(fleet, 'a', '/tool-use-then-speak FINAL-ANSWER');
+
+    await waitFor(
+      () => fleet.getChildren().get('a')!.lastCompletedSpeech === 'FINAL-ANSWER',
+      3_000,
+      'lastCompletedSpeech updated to FINAL-ANSWER (tool-use round ignored)',
+    );
+  });
+});
+
+describe('fleet--relay', () => {
+  let tmpDir: string;
+  let fleet: FleetModule;
+
+  beforeAll(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-orch-relay-'));
+    fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'src', join(tmpDir, 'src'));
+    await launchChild(fleet, 'dst', join(tmpDir, 'dst'));
+  });
+
+  afterAll(async () => {
+    try { await fleet.stop(); } catch { /* noop */ }
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('errors when source has no completed speech yet', async () => {
+    const res = await fleet.handleToolCall({
+      id: 'relay-empty',
+      name: 'relay',
+      input: { from: 'src', to: 'dst' },
+    });
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/No completed speech/i);
+  });
+
+  test('relays source speech to target (with prefix)', async () => {
+    await send(fleet, 'src', 'findings summary');
+    await waitFor(
+      () => fleet.getChildren().get('src')!.lastCompletedSpeech === 'echo: findings summary',
+      2_000,
+      'src lastCompletedSpeech set',
+    );
+
+    const res = await fleet.handleToolCall({
+      id: 'relay-ok',
+      name: 'relay',
+      input: { from: 'src', to: 'dst', prefix: 'Miner says:' },
+    });
+    expect(res.success).toBe(true);
+    expect(res.data).toMatchObject({ from: 'src', to: 'dst' });
+
+    // The mock echoes whatever text it receives, so the destination's
+    // lastCompletedSpeech should reflect our prefixed payload.
+    await waitFor(
+      () => fleet.getChildren().get('dst')!.lastCompletedSpeech.startsWith('echo: Miner says:'),
+      3_000,
+      'dst received relayed message and echoed',
+    );
+    expect(fleet.getChildren().get('dst')!.lastCompletedSpeech).toContain('findings summary');
+  });
+
+  test('rejects same-child relay', async () => {
+    const res = await fleet.handleToolCall({
+      id: 'relay-self',
+      name: 'relay',
+      input: { from: 'src', to: 'src' },
+    });
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/different children/);
+  });
+
+  test('rejects unknown children', async () => {
+    const res1 = await fleet.handleToolCall({
+      id: 'relay-nosrc', name: 'relay', input: { from: 'ghost', to: 'dst' },
+    });
+    expect(res1.success).toBe(false);
+    expect(res1.error).toMatch(/Unknown source child/);
+
+    const res2 = await fleet.handleToolCall({
+      id: 'relay-nodst', name: 'relay', input: { from: 'src', to: 'ghost' },
+    });
+    expect(res2.success).toBe(false);
+    expect(res2.error).toMatch(/Unknown child/);
+  });
+});
+
+describe('fleet--await', () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'fkm-orch-await-'));
+  });
+
+  afterAll(() => {
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  test('returns immediately when all named children are already idle', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'x', join(tmpDir, 'x1'));
+
+    // Trigger one round so child emits lifecycle:idle.
+    await send(fleet, 'x', 'hi');
+    await waitFor(
+      () => fleet.getChildren().get('x')!.events.some(
+        (e) => e.type === 'lifecycle' && (e as { phase?: string }).phase === 'idle',
+      ),
+      2_000,
+      'x became idle',
+    );
+
+    const t0 = Date.now();
+    const res = await fleet.handleToolCall({
+      id: 'await-idle-fast',
+      name: 'await',
+      input: { names: ['x'], timeoutMs: 1_000 },
+    });
+    const elapsed = Date.now() - t0;
+    expect(res.success).toBe(true);
+    expect((res.data as { completed?: boolean }).completed).toBe(true);
+    expect(elapsed).toBeLessThan(500);
+
+    await fleet.stop();
+  });
+
+  test('blocks until all named children emit idle', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'p', join(tmpDir, 'p'));
+    await launchChild(fleet, 'q', join(tmpDir, 'q'));
+
+    // Kick both, then await — the await should resolve after both idle up.
+    const awaitPromise = (async () => {
+      // tiny delay to make sure the sends land before the wait checks "already idle"
+      await new Promise((r) => setTimeout(r, 50));
+      return fleet.handleToolCall({
+        id: 'await-both',
+        name: 'await',
+        input: { names: ['p', 'q'], timeoutMs: 5_000 },
+      });
+    })();
+
+    await send(fleet, 'p', 'work');
+    await send(fleet, 'q', 'work');
+
+    const res = await awaitPromise;
+    expect(res.success).toBe(true);
+    const data = res.data as { names: string[]; completed: boolean };
+    expect(data.completed).toBe(true);
+    expect(data.names.sort()).toEqual(['p', 'q']);
+
+    await fleet.stop();
+  }, 15_000);
+
+  test('returns on any idle when requireAll is false', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'fast', join(tmpDir, 'fast'));
+    await launchChild(fleet, 'slow', join(tmpDir, 'slow'));
+
+    const awaitPromise = (async () => {
+      await new Promise((r) => setTimeout(r, 50));
+      return fleet.handleToolCall({
+        id: 'await-any',
+        name: 'await',
+        input: { names: ['fast', 'slow'], timeoutMs: 5_000, requireAll: false },
+      });
+    })();
+
+    await send(fleet, 'fast', 'quick');
+    // 'slow' left unbothered — requireAll:false means we return as soon as fast idles.
+
+    const res = await awaitPromise;
+    expect(res.success).toBe(true);
+    const data = res.data as { names: string[]; completed: boolean };
+    expect(data.completed).toBe(true);
+    expect(data.names).toContain('fast');
+
+    await fleet.stop();
+  }, 15_000);
+
+  test('times out returning partial set', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'stuck', join(tmpDir, 'stuck'));
+
+    await command(fleet, 'stuck', '/hang');
+
+    const res = await fleet.handleToolCall({
+      id: 'await-timeout',
+      name: 'await',
+      input: { names: ['stuck'], timeoutMs: 300 },
+    });
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/timed out/i);
+
+    await fleet.stop();
+  }, 15_000);
+
+  test('fails fast when waited-for child crashes', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+    await launchChild(fleet, 'doomed', join(tmpDir, 'doomed'));
+
+    const awaitPromise = (async () => {
+      await new Promise((r) => setTimeout(r, 50));
+      return fleet.handleToolCall({
+        id: 'await-crash',
+        name: 'await',
+        input: { names: ['doomed'], timeoutMs: 5_000 },
+      });
+    })();
+
+    // Send the crash command.
+    await command(fleet, 'doomed', '/crash');
+
+    const res = await awaitPromise;
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/crashed|exited/);
+
+    await fleet.stop();
+  }, 15_000);
+
+  test('rejects empty or unknown names', async () => {
+    const fleet = makeFleet();
+    await fleet.start({} as unknown as Parameters<typeof fleet.start>[0]);
+
+    const empty = await fleet.handleToolCall({
+      id: 'await-empty', name: 'await', input: { names: [] },
+    });
+    expect(empty.success).toBe(false);
+    expect(empty.error).toMatch(/non-empty/);
+
+    const unknown = await fleet.handleToolCall({
+      id: 'await-unk', name: 'await', input: { names: ['ghost'] },
+    });
+    expect(unknown.success).toBe(false);
+    expect(unknown.error).toMatch(/Unknown child/);
+
+    await fleet.stop();
+  });
+});

package/test/fleet-recipe.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Schema-validation tests for modules.fleet and the triumvirate.json recipe.
+ * Pure JSON-in / validator-out tests — no subprocess needed.
+ */
+import { describe, test, expect } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateRecipe } from '../src/recipe.js';
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, '..');
+
+function baseRecipe(extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    name: 'Test',
+    agent: { systemPrompt: 'test' },
+    ...extra,
+  };
+}
+
+describe('validateRecipe — fleet schema', () => {
+  test('boolean form is accepted', () => {
+    expect(() => validateRecipe(baseRecipe({ modules: { fleet: true } }))).not.toThrow();
+    expect(() => validateRecipe(baseRecipe({ modules: { fleet: false } }))).not.toThrow();
+  });
+
+  test('valid object form is accepted', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: {
+        fleet: {
+          children: [
+            { name: 'miner', recipe: 'recipes/miner.json', autoStart: true },
+            { name: 'clerk', recipe: 'recipes/clerk.json' },
+          ],
+          allowedRecipes: ['recipes/*', 'https://trusted.example/agents/*'],
+          defaultSubscription: ['lifecycle'],
+        },
+      },
+    }))).not.toThrow();
+  });
+
+  test('rejects mid-string * in allowedRecipes', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { allowedRecipes: ['recipes/*.json'] } },
+    }))).toThrow(/mid-string "\*"/);
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { allowedRecipes: ['rec*/miner.json'] } },
+    }))).toThrow(/mid-string "\*"/);
+  });
+
+  test('children must be an array', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { children: 'not-an-array' } },
+    }))).toThrow(/children must be an array/);
+  });
+
+  test('each child must have a non-empty name', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { children: [{ recipe: 'r.json' }] } },
+    }))).toThrow(/name must be a non-empty string/);
+  });
+
+  test('each child must have a non-empty recipe', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { children: [{ name: 'x' }] } },
+    }))).toThrow(/recipe must be a non-empty string/);
+  });
+
+  test('duplicate child names are rejected', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: {
+        fleet: {
+          children: [
+            { name: 'miner', recipe: 'a.json' },
+            { name: 'miner', recipe: 'b.json' },
+          ],
+        },
+      },
+    }))).toThrow(/duplicated/);
+  });
+
+  test('allowedRecipes must be an array of strings', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { allowedRecipes: 'recipes/*.json' } },
+    }))).toThrow(/allowedRecipes must be an array/);
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { allowedRecipes: [1, 2, 3] } },
+    }))).toThrow(/allowedRecipes must be an array of strings/);
+  });
+
+  test('subscription must be an array when present', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { children: [{ name: 'x', recipe: 'r.json', subscription: 'not-array' }] } },
+    }))).toThrow(/subscription must be an array/);
+  });
+
+  test('autoStart must be boolean when present', () => {
+    expect(() => validateRecipe(baseRecipe({
+      modules: { fleet: { children: [{ name: 'x', recipe: 'r.json', autoStart: 'yes' }] } },
+    }))).toThrow(/autoStart must be a boolean/);
+  });
+});
+
+describe('recipes/triumvirate.json', () => {
+  test('parses and validates cleanly', () => {
+    const triumviratePath = join(REPO_ROOT, 'recipes', 'triumvirate.json');
+    const raw = JSON.parse(readFileSync(triumviratePath, 'utf-8'));
+    const recipe = validateRecipe(raw);
+
+    expect(recipe.name).toBe('Knowledge Mining Triumvirate');
+    expect(recipe.agent.name).toBe('conductor');
+    expect(recipe.modules?.fleet).toBeDefined();
+    const fleet = recipe.modules?.fleet;
+    if (typeof fleet === 'object' && fleet !== null) {
+      expect(fleet.children).toHaveLength(3);
+      const names = fleet.children!.map((c) => c.name).sort();
+      expect(names).toEqual(['clerk', 'miner', 'reviewer']);
+      expect(fleet.children!.every((c) => c.autoStart === true)).toBe(true);
+    } else {
+      throw new Error('fleet should be an object');
+    }
+  });
+});

package/test/fleet-route.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Unit tests for the @childname direct-routing parser used by the TUI.
+ */
+import { describe, test, expect } from 'bun:test';
+import { parseFleetRoute } from '../src/modules/fleet-types.js';
+
+describe('parseFleetRoute', () => {
+  test('routes plain @name content', () => {
+    expect(parseFleetRoute('@miner hello there')).toEqual({ childName: 'miner', content: 'hello there' });
+  });
+
+  test('strips colon after name', () => {
+    expect(parseFleetRoute('@miner: hello')).toEqual({ childName: 'miner', content: 'hello' });
+  });
+
+  test('accepts hyphens and dots in names', () => {
+    expect(parseFleetRoute('@my-bot list channels')).toEqual({ childName: 'my-bot', content: 'list channels' });
+    expect(parseFleetRoute('@bot.v2 ping')).toEqual({ childName: 'bot.v2', content: 'ping' });
+  });
+
+  test('preserves multi-line payloads', () => {
+    const r = parseFleetRoute('@miner first line\nsecond line');
+    expect(r?.childName).toBe('miner');
+    expect(r?.content).toBe('first line\nsecond line');
+  });
+
+  test('returns null for non-@ inputs', () => {
+    expect(parseFleetRoute('plain text')).toBeNull();
+    expect(parseFleetRoute('  leading whitespace then text')).toBeNull();
+  });
+
+  test('returns null for @ with no payload', () => {
+    expect(parseFleetRoute('@miner')).toBeNull();
+    expect(parseFleetRoute('@miner ')).toBeNull();
+  });
+
+  test('returns null for @@ literal escape', () => {
+    expect(parseFleetRoute('@@example.com email-like')).toBeNull();
+  });
+
+  test('tolerates leading whitespace before @', () => {
+    expect(parseFleetRoute('  @miner go')).toEqual({ childName: 'miner', content: 'go' });
+  });
+});