@animalabs/connectome-host 0.7.3 → 0.8.0

package/test/conversations-recipe.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Recipe surface for per-channel conversation routing:
+ * schema validation of the `conversations` block, and the host-side mapping
+ * to the framework's ConversationRouterConfig (templateAgent auto-filled
+ * from the recipe agent, strategyFactory building fresh per-fork strategy
+ * instances from the recipe's own strategy config).
+ */
+import { describe, test, expect } from 'bun:test';
+import { validateRecipe, type Recipe } from '../src/recipe.js';
+import { buildConversationsConfig } from '../src/framework-strategy.js';
+
+function baseRecipe(extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    name: 'Test',
+    agent: { name: 'sherlock', systemPrompt: 'test' },
+    ...extra,
+  };
+}
+
+describe('validateRecipe — conversations schema', () => {
+  test('absent block is accepted', () => {
+    expect(() => validateRecipe(baseRecipe())).not.toThrow();
+  });
+
+  test('full valid block is accepted', () => {
+    expect(() => validateRecipe(baseRecipe({
+      conversations: {
+        bind: { dm: 'always', groupDm: 'always', channel: 'mention' },
+        trigger: { dm: 'always', groupDm: 'mention', channel: 'mention' },
+        idleTtlMs: 12 * 60 * 60 * 1000,
+        closurePrompt: 'Finalize the case report and post the answer.',
+        agentPrefix: 'case',
+      },
+    }))).not.toThrow();
+  });
+
+  test('empty object is accepted (all defaults come from the framework)', () => {
+    expect(() => validateRecipe(baseRecipe({ conversations: {} }))).not.toThrow();
+  });
+
+  test('non-object block is rejected', () => {
+    expect(() => validateRecipe(baseRecipe({ conversations: true }))).toThrow(/must be an object/);
+    expect(() => validateRecipe(baseRecipe({ conversations: [] }))).toThrow(/must be an object/);
+  });
+
+  test('unknown top-level conversation field is rejected rather than silently ignored', () => {
+    expect(() => validateRecipe(baseRecipe({
+      conversations: { idleTTLms: 1000 },
+    }))).toThrow(/unknown field \"idleTTLms\"/);
+  });
+
+  test('unknown channel kind is rejected', () => {
+    expect(() => validateRecipe(baseRecipe({
+      conversations: { bind: { thread: 'always' } },
+    }))).toThrow(/unknown channel kind "thread"/);
+  });
+
+  test('invalid bind rule is rejected', () => {
+    expect(() => validateRecipe(baseRecipe({
+      conversations: { bind: { channel: 'sometimes' } },
+    }))).toThrow(/conversations\.bind\.channel/);
+  });
+
+  test("trigger rule 'never' is rejected (bind-only rule)", () => {
+    expect(() => validateRecipe(baseRecipe({
+      conversations: { trigger: { channel: 'never' } },
+    }))).toThrow(/conversations\.trigger\.channel/);
+  });
+
+  test('non-positive idleTtlMs is rejected', () => {
+    expect(() => validateRecipe(baseRecipe({ conversations: { idleTtlMs: 0 } })))
+      .toThrow(/idleTtlMs/);
+    expect(() => validateRecipe(baseRecipe({ conversations: { idleTtlMs: -5 } })))
+      .toThrow(/idleTtlMs/);
+    for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, 1.5]) {
+      expect(() => validateRecipe(baseRecipe({ conversations: { idleTtlMs: bad } })))
+        .toThrow(/idleTtlMs/);
+    }
+  });
+
+  test('blank closurePrompt is rejected', () => {
+    expect(() => validateRecipe(baseRecipe({ conversations: { closurePrompt: '  ' } })))
+      .toThrow(/closurePrompt/);
+  });
+
+  test('agentPrefix with unsafe characters is rejected', () => {
+    for (const bad of ['with space', 'slash/py', 'dot.seg', '']) {
+      expect(() => validateRecipe(baseRecipe({ conversations: { agentPrefix: bad } })))
+        .toThrow(/agentPrefix/);
+    }
+    expect(() => validateRecipe(baseRecipe({ conversations: { agentPrefix: 'case-fork_2' } })))
+      .not.toThrow();
+  });
+});
+
+describe('buildConversationsConfig — recipe → FrameworkConfig mapping', () => {
+  const recipe = validateRecipe(baseRecipe({
+    conversations: {
+      bind: { channel: 'mention' },
+      idleTtlMs: 3600_000,
+      agentPrefix: 'case',
+    },
+  })) as Recipe;
+
+  test('returns undefined when the recipe has no conversations block', () => {
+    const bare = validateRecipe(baseRecipe()) as Recipe;
+    expect(buildConversationsConfig(bare, 'sherlock', 'model-x', 'UTC')).toBeUndefined();
+  });
+
+  test('templateAgent is auto-filled with the host agent name', () => {
+    const cfg = buildConversationsConfig(recipe, 'sherlock', 'model-x', 'UTC');
+    expect(cfg?.templateAgent).toBe('sherlock');
+  });
+
+  test('recipe fields pass through; omitted fields stay absent for framework defaults', () => {
+    const cfg = buildConversationsConfig(recipe, 'sherlock', 'model-x', 'UTC')!;
+    expect(cfg.bind).toEqual({ channel: 'mention' });
+    expect(cfg.idleTtlMs).toBe(3600_000);
+    expect(cfg.agentPrefix).toBe('case');
+    expect('trigger' in cfg).toBe(false);
+    expect('closurePrompt' in cfg).toBe(false);
+  });
+
+  test('strategyFactory builds a FRESH strategy instance per call', () => {
+    const cfg = buildConversationsConfig(recipe, 'sherlock', 'model-x', 'UTC')!;
+    expect(cfg.strategyFactory).toBeDefined();
+    const a = cfg.strategyFactory!();
+    const b = cfg.strategyFactory!();
+    expect(a).toBeDefined();
+    expect(b).toBeDefined();
+    expect(a).not.toBe(b);
+  });
+
+  test('strategyFactory honors the recipe strategy type', () => {
+    const passthrough = validateRecipe(baseRecipe({
+      agent: { name: 'p', systemPrompt: 't', strategy: { type: 'passthrough' } },
+      conversations: {},
+    })) as Recipe;
+    const cfg = buildConversationsConfig(passthrough, 'p', 'model-x', 'UTC')!;
+    expect(cfg.strategyFactory!().constructor.name).toBe('PassthroughStrategy');
+  });
+});

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

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

package/test/framework-fkm-composition.test.ts

@@ -86,7 +86,7 @@ describe('framework FKM composition', () => {
     });
   });
 
-  test('composes validation, serialization, and AF/CM wiring for the merged FKM settings without cross-agent bleed', () => {
+  test('composes validation, serialization, and AF/CM wiring for the merged FKM settings without cross-agent bleed', async () => {
     const parsed = validateRecipe(recipe({
       provider: 'openai-responses',
       maxTokens: 4_096,
@@ -103,13 +103,20 @@ describe('framework FKM composition', () => {
         type: 'autobiographical',
         compressionRefusalCurveFallbacks: 2,
         compressionContextBudgetTokens: 19_000,
+        compressionRecallBudgetTokens: 17_000,
+        compressionSourceOnly: false,
+        compressionSourceOnlyFallback: true,
+        compressionMergeSourceOnly: false,
+        compressionMergeSourceOnlyFallback: true,
       },
     }));
 
     const dir = mkdtempSync(join(tmpdir(), 'connectome-fkm-'));
     tempDirs.push(dir);
-    saveRecipe(dir, parsed);
-    const reloaded = loadSavedRecipe(dir);
+    // Saving an already-resolved recipe through the new unresolved-snapshot
+    // path is legal: substitution over resolved content is a no-op.
+    saveRecipe(dir, parsed as unknown as Record<string, unknown>);
+    const reloaded = await loadSavedRecipe(dir);
     expect(reloaded).not.toBeNull();
 
     expect(reloaded!.agent.sameRoundThinkTextPolicy).toBe('private');
@@ -118,11 +125,21 @@ describe('framework FKM composition', () => {
     });
     expect(reloaded!.agent.strategy?.compressionRefusalCurveFallbacks).toBe(2);
     expect(reloaded!.agent.strategy?.compressionContextBudgetTokens).toBe(19_000);
+    expect(reloaded!.agent.strategy?.compressionRecallBudgetTokens).toBe(17_000);
+    expect(reloaded!.agent.strategy?.compressionSourceOnly).toBe(false);
+    expect(reloaded!.agent.strategy?.compressionSourceOnlyFallback).toBe(true);
+    expect(reloaded!.agent.strategy?.compressionMergeSourceOnly).toBe(false);
+    expect(reloaded!.agent.strategy?.compressionMergeSourceOnlyFallback).toBe(true);
 
     const runtimeStrategy = buildFrameworkStrategy(reloaded!, 'model', 'America/Los_Angeles');
     const runtimeConfig = strategyConfigView(runtimeStrategy);
     expect(runtimeConfig.compressionRefusalCurveFallbacks).toBe(2);
     expect(runtimeConfig.compressionContextBudgetTokens).toBe(19_000);
+    expect(runtimeConfig.compressionRecallBudgetTokens).toBe(17_000);
+    expect(runtimeConfig.compressionSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionSourceOnlyFallback).toBe(true);
+    expect(runtimeConfig.compressionMergeSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionMergeSourceOnlyFallback).toBe(true);
 
     const agentConfig = buildFrameworkAgentConfig(reloaded!, 'agent', 'model', runtimeStrategy);
     expect(agentConfig.sameRoundThinkTextPolicy).toBe('private');
@@ -138,14 +155,29 @@ describe('framework FKM composition', () => {
         type: 'autobiographical',
         compressionRefusalCurveFallbacks: 0,
         compressionContextBudgetTokens: 50_000,
+        compressionRecallBudgetTokens: 41_000,
+        compressionSourceOnly: true,
+        compressionSourceOnlyFallback: false,
+        compressionMergeSourceOnly: true,
+        compressionMergeSourceOnlyFallback: false,
       },
     }));
     const otherStrategy = buildFrameworkStrategy(otherRecipe, 'other-model', 'America/Los_Angeles');
     const otherConfig = strategyConfigView(otherStrategy);
     expect(otherConfig.compressionRefusalCurveFallbacks).toBe(0);
     expect(otherConfig.compressionContextBudgetTokens).toBe(50_000);
+    expect(otherConfig.compressionRecallBudgetTokens).toBe(41_000);
+    expect(otherConfig.compressionSourceOnly).toBe(true);
+    expect(otherConfig.compressionSourceOnlyFallback).toBe(false);
+    expect(otherConfig.compressionMergeSourceOnly).toBe(true);
+    expect(otherConfig.compressionMergeSourceOnlyFallback).toBe(false);
     expect(otherConfig).not.toBe(runtimeConfig);
     expect(runtimeConfig.compressionRefusalCurveFallbacks).toBe(2);
     expect(runtimeConfig.compressionContextBudgetTokens).toBe(19_000);
+    expect(runtimeConfig.compressionRecallBudgetTokens).toBe(17_000);
+    expect(runtimeConfig.compressionSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionSourceOnlyFallback).toBe(true);
+    expect(runtimeConfig.compressionMergeSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionMergeSourceOnlyFallback).toBe(true);
   });
 });

package/test/framework-strategy-defaults.test.ts

@@ -39,6 +39,47 @@ describe('standard-recipe memory defaults', () => {
     expect(config.summaryParticipant).toBe('Mira');
   });
 
+  test('frontdesk gets adaptive + kv-stable too (2026-08-03 clerk outage: hierarchical saturates)', () => {
+    const strategy = buildFrameworkStrategy(
+      recipe({ name: 'Desk', strategy: { type: 'frontdesk' } }),
+      'some-model',
+      'Europe/Kyiv',
+    );
+    const config = configView(strategy);
+    expect(config.adaptiveResolution).toBe(true);
+    expect(config.foldingStrategy).toBe('kv-stable');
+  });
+
+  test('frontdesk adaptiveResolution: false is the hierarchical rollback lever', () => {
+    const strategy = buildFrameworkStrategy(
+      recipe({ name: 'Desk', strategy: { type: 'frontdesk', adaptiveResolution: false } }),
+      'some-model',
+      'Europe/Kyiv',
+    );
+    const config = configView(strategy);
+    expect(config.adaptiveResolution).toBe(false);
+    expect(config.foldingStrategy).toBeUndefined();
+  });
+
+  test('productionBudgetTokens is passed through exactly and omission stays omitted', () => {
+    const configured = buildFrameworkStrategy(
+      recipe({
+        name: 'Mira',
+        strategy: { type: 'autobiographical', productionBudgetTokens: 123_456 },
+      }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(configured).productionBudgetTokens).toBe(123_456);
+
+    const omitted = buildFrameworkStrategy(
+      recipe({ name: 'Mira', strategy: { type: 'autobiographical' } }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(omitted).productionBudgetTokens).toBeUndefined();
+  });
+
   test('explicit recipe values override the defaults', () => {
     const strategy = buildFrameworkStrategy(
       recipe({

package/test/frontdesk-strategy.test.ts

@@ -2,7 +2,6 @@ import { describe, test, expect } from 'bun:test';
 import type {
   MessageStoreView,
   StoredMessage,
-  SummaryEntry,
   ContextEntry,
 } from '@animalabs/context-manager';
 import { FrontdeskStrategy } from '../src/strategies/frontdesk-strategy.js';
@@ -54,12 +53,12 @@ class TestFrontdesk extends FrontdeskStrategy {
   public pub_updateSalience(store: MessageStoreView) {
     this.updateSalience(store);
   }
-  public pub_selectL1(l1: SummaryEntry[], budget: number, maxTokens: number) {
-    return this.selectL1Summaries(l1, budget, maxTokens);
-  }
   public pub_isTopicBoundary(a: StoredMessage, b: StoredMessage) {
     return this.isTopicBoundary(a, b);
   }
+  public pub_chunkBoundaryHint(a: StoredMessage, b: StoredMessage) {
+    return this.chunkBoundaryHint(a, b);
+  }
   public pub_compressionInstruction(chunkMessages: StoredMessage[], target: number) {
     // Build a minimal Chunk shape sufficient for getCompressionInstruction
     const chunk = {
@@ -293,44 +292,33 @@ describe('compression instruction', () => {
   });
 });
 
-describe('salience-biased L1 selection', () => {
-  function summary(id: string, tokens: number, sourceIds: string[]): SummaryEntry {
-    return {
-      id,
-      level: 1,
-      content: '',
-      tokens,
-      sourceLevel: 0,
-      sourceIds,
-      sourceRange: { first: sourceIds[0] ?? '', last: sourceIds[sourceIds.length - 1] ?? '' },
-      created: Date.now(),
-    };
-  }
+describe('chunk boundary hint (topic-aware chunking via the base seam)', () => {
+  // The chunking mechanics — record persistence, minimum-size, tool-pairing
+  // guard — are context-manager's contract, gated by its
+  // chunk-boundary-hook tests. What is conhost's to pin is the hint policy:
+  // frontdesk hints exactly at topic boundaries.
 
-  test('prefers L1 summaries whose sources contain salient messages', () => {
+  test('hints a close when adjacent messages change topic on one channel', () => {
     const s = makeStrategy();
-    const q = msg('User', 'what is x?', {}); // salient: unanswered
-    s.pub_updateSalience(makeStore([q]));
-
-    // Two L1 summaries, each 100 tokens; budget fits only one
-    const routineFirst = summary('L1-0', 100, ['unrelated-1']);
-    const salientSecond = summary('L1-1', 100, [q.id]);
-
-    const { selected } = s.pub_selectL1([routineFirst, salientSecond], 100, 100);
-    expect(selected).toHaveLength(1);
-    expect(selected[0].id).toBe('L1-1');
+    const a = msg('User', 'x', { serverId: 'zulip', channelId: 'zulip:eng', topic: 'retries' });
+    const b = msg('User', 'y', { serverId: 'zulip', channelId: 'zulip:eng', topic: 'deploys' });
+    expect(s.pub_chunkBoundaryHint(a, b)).toBe(true);
   });
 
-  test('falls back to routine summaries once salient are exhausted', () => {
+  test('does not hint within a topic or when topic metadata is absent', () => {
     const s = makeStrategy();
-    const q = msg('User', 'what is x?', {});
-    s.pub_updateSalience(makeStore([q]));
+    const a = msg('User', 'x', { serverId: 'zulip', channelId: 'zulip:eng', topic: 'retries' });
+    const b = msg('User', 'y', { serverId: 'zulip', channelId: 'zulip:eng', topic: 'retries' });
+    const bare = msg('User', 'z', {});
+    expect(s.pub_chunkBoundaryHint(a, b)).toBe(false);
+    expect(s.pub_chunkBoundaryHint(a, bare)).toBe(false);
+    expect(s.pub_chunkBoundaryHint(bare, a)).toBe(false);
+  });
 
-    const salient = summary('L1-1', 50, [q.id]);
-    const routine = summary('L1-2', 50, ['unrelated-1']);
-    const { selected } = s.pub_selectL1([routine, salient], 200, 200);
-    expect(selected).toHaveLength(2);
-    expect(selected[0].id).toBe('L1-1'); // salient first
-    expect(selected[1].id).toBe('L1-2');
+  test('hint agrees with isTopicBoundary across channels (same topic name, different channel)', () => {
+    const s = makeStrategy();
+    const a = msg('User', 'x', { serverId: 'zulip', channelId: 'zulip:eng', topic: 'retries' });
+    const b = msg('User', 'y', { serverId: 'zulip', channelId: 'zulip:ops', topic: 'retries' });
+    expect(s.pub_chunkBoundaryHint(a, b)).toBe(s.pub_isTopicBoundary(a, b));
   });
 });

package/test/gate-telemetry-adapter.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Adapter-level proof (review finding on #113): with the PUBLISHED membrane,
+ * a stream call consults the active-turn trigger and carries the origin trio,
+ * while a complete call (compression / side-calls / keepalive) carries the
+ * debt stamp only. Runs the real AnthropicAdapter with a mocked SDK client.
+ */
+import { describe, expect, it } from 'bun:test';
+import { AnthropicAdapter } from '@animalabs/membrane';
+import { gateTelemetryHeaders } from '../src/gate-telemetry.js';
+
+const env = { GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' };
+const wake = { reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:1:2', counterparty: 'discord:user:42' };
+
+const REQUEST = {
+  model: 'claude-test',
+  messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
+} as any;
+
+const RESPONSE = {
+  id: 'msg_test', model: 'claude-test', role: 'assistant',
+  content: [{ type: 'text', text: 'ok' }], stop_reason: 'end_turn',
+  usage: { input_tokens: 1, output_tokens: 1 },
+};
+
+/** Minimal SDK stream: an async iterable of the events the adapter reads. */
+function mockStream() {
+  const events = [
+    { type: 'message_start', message: { id: 'msg_s', model: 'claude-test', role: 'assistant', content: [], usage: { input_tokens: 1, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'ok' } },
+    { type: 'content_block_stop', index: 0 },
+    { type: 'message_delta', delta: { stop_reason: 'end_turn', stop_sequence: null }, usage: { output_tokens: 1 } },
+    { type: 'message_stop' },
+  ];
+  return {
+    async *[Symbol.asyncIterator]() { for (const e of events) yield e; },
+  };
+}
+
+function adapterWithTrigger(trigger: () => typeof wake | null) {
+  let asked = 0;
+  const dyn = gateTelemetryHeaders(env, () => 3, () => { asked++; return trigger(); })!;
+  const adapter = new AnthropicAdapter({ apiKey: 'sk-test', cacheKeepalive: { enabled: false }, dynamicHeaders: dyn } as any);
+  const calls: Array<{ kind: string; headers: Record<string, string> | undefined }> = [];
+  (adapter as any).client = {
+    messages: {
+      create: async (_req: unknown, opts: { headers?: Record<string, string> }) => { calls.push({ kind: 'complete', headers: opts?.headers }); return RESPONSE; },
+      stream: async (_req: unknown, opts: { headers?: Record<string, string> }) => { calls.push({ kind: 'stream', headers: opts?.headers }); return mockStream(); },
+    },
+  };
+  return { adapter, calls, asked: () => asked };
+}
+
+describe('gate telemetry through the published AnthropicAdapter', () => {
+  it('complete lane: debt only — the active trigger is not consulted', async () => {
+    const { adapter, calls, asked } = adapterWithTrigger(() => wake);
+    await adapter.complete(REQUEST);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.kind).toBe('complete');
+    expect(calls[0]!.headers).toEqual({ 'x-gate-debt-chunks': '3' });
+    expect(asked()).toBe(0);
+  });
+
+  it('stream lane: the trigger is consulted and the origin trio rides the request', async () => {
+    const { adapter, calls, asked } = adapterWithTrigger(() => wake);
+    const chunks: string[] = [];
+    await adapter.stream(REQUEST, { onChunk: (c: string) => { chunks.push(c); } } as any);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.kind).toBe('stream');
+    expect(calls[0]!.headers).toEqual({
+      'x-gate-debt-chunks': '3',
+      'x-gate-origin': 'event',
+      'x-gate-channel': 'discord:1:2',
+      'x-gate-counterparty': 'discord:user:42',
+    });
+    expect(asked()).toBe(1);
+  });
+
+  it('stream lane with no turn in progress: debt only, nothing guessed', async () => {
+    const { adapter, calls } = adapterWithTrigger(() => null);
+    await adapter.stream(REQUEST, { onChunk: () => {} } as any);
+    expect(calls[0]!.headers).toEqual({ 'x-gate-debt-chunks': '3' });
+  });
+});

package/test/gate-telemetry.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The x-gate-* stamp must be impossible to send to a vendor: attachment is
+ * double-gated on the operator's explicit GATE_TELEMETRY declaration AND a
+ * configured base URL. Review finding on the first wiring: the stamp was
+ * attached unconditionally, so with ANTHROPIC_BASE_URL unset the household
+ * value went to the vendor's default endpoint.
+ */
+import { describe, expect, it } from 'bun:test';
+import { gateTelemetryHeaders, originClass } from '../src/gate-telemetry.js';
+
+const debt = () => 7;
+
+describe('gateTelemetryHeaders', () => {
+  it('default vendor endpoint (no base URL): never attaches, even when flagged', () => {
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: '1' }, debt)).toBeUndefined();
+  });
+
+  it('base URL without the operator declaration: never attaches', () => {
+    expect(gateTelemetryHeaders({ ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: '0', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: 'false', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+  });
+
+  it('declared gateway: attaches a live stamp', () => {
+    const fn = gateTelemetryHeaders({ GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt);
+    expect(fn).toBeDefined();
+    expect(fn!()).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('unreadable debt stays null (membrane drops null values — unstamped, never guessed)', () => {
+    const fn = gateTelemetryHeaders({ GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, () => null);
+    expect(fn!()).toEqual({ 'x-gate-debt-chunks': null });
+  });
+
+  const env = { GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' };
+  const wake = { reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:1:2', counterparty: 'discord:user:42' };
+
+  it('origin trio rides the stream lane: why, where, by whom — ids only', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => wake);
+    expect(fn!({ lane: 'stream' })).toEqual({
+      'x-gate-debt-chunks': 7,
+      'x-gate-origin': 'event',
+      'x-gate-channel': 'discord:1:2',
+      'x-gate-counterparty': 'discord:user:42',
+    });
+  });
+
+  it('complete lane (compression, side-calls, keepalive) carries debt only — a background call is not the turn', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => wake);
+    expect(fn!({ lane: 'complete' })).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('no lane told (older membrane) or no trigger known: honest — debt only, or trio without guessing', () => {
+    expect(gateTelemetryHeaders(env, debt, () => null)!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7 });
+    expect(gateTelemetryHeaders(env, debt, () => wake)!()).toMatchObject({ 'x-gate-origin': 'event' });
+    expect(gateTelemetryHeaders(env, debt)!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('heartbeat wakes carry no channel or counterparty (null → dropped by membrane)', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'heartbeat:tick', source: 'heartbeat' }));
+    expect(fn!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7, 'x-gate-origin': 'heartbeat', 'x-gate-channel': null, 'x-gate-counterparty': null });
+  });
+
+  it('originClass: heartbeat / mail / event / operator, raw reason otherwise (sanitized, clipped)', () => {
+    expect(originClass({ reason: 'heartbeat', source: 'heartbeat' })).toBe('heartbeat');
+    expect(originClass({ reason: 'mail:incoming', source: 'fenmail' })).toBe('mail');
+    expect(originClass({ reason: 'mcpl:push-event', source: 'discord' })).toBe('event');
+    expect(originClass({ reason: 'admin-nudge (someone)', source: 'framework' })).toBe('operator');
+    expect(originClass({ reason: 'external-message', source: 'headless' })).toBe('operator');
+    expect(originClass({ reason: 'external-message', source: 'tui' })).toBe('operator');
+    expect(originClass({ reason: 'provider-acceleration-retry', source: 'framework' })).toBe('provider-acceleration-retry');
+    expect(originClass({ reason: 'weird reason!!'.repeat(6), source: 'x' })).toHaveLength(40);
+  });
+
+  it('attributes are header-safe: a value with any non-ASCII or control character is withheld whole, never rewritten', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:\u{1F600}', counterparty: 'discord:user:4\r\n2' }));
+    const h = fn!({ lane: 'stream' });
+    expect(h['x-gate-channel']).toBeNull();
+    expect(h['x-gate-counterparty']).toBeNull();
+    // and what IS sent can always be put in real Headers (Fetch ByteString rule)
+    const ok = gateTelemetryHeaders(env, debt, () => wake)!({ lane: 'stream' });
+    const sendable = Object.fromEntries(Object.entries(ok).filter(([, v]) => v !== null).map(([k, v]) => [k, String(v)]));
+    expect(() => new Headers(sendable)).not.toThrow();
+    expect(new Headers(sendable).get('x-gate-counterparty')).toBe('discord:user:42');
+  });
+
+  it('attributes are clipped to 120 visible-ASCII characters', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'mcpl:channel-incoming', source: 'discord', counterparty: 'x'.repeat(200) }));
+    expect((fn!({ lane: 'stream' })['x-gate-counterparty'] as string).length).toBe(120);
+  });
+});