@animalabs/connectome-host 0.7.4 → 0.8.0

package/src/web/panel-data.ts

@@ -589,6 +589,25 @@ export function buildHealthSnapshot(app: PanelAppRef): Record<string, unknown> {
   } catch {
     // Health reads never throw.
   }
+  // Compression DEBT per agent — the single-authority reduction from cm
+  // (healthy / degraded / critical + the numbers behind it). Every wedge of
+  // the 2026-08-06 five-resident day was weeks of silently-failing
+  // compression surfacing as a sudden budget crisis; this block is what
+  // lets fleet-watch (and later the resident notice, af #99) catch the
+  // debt while it is still cheap.
+  try {
+    const debt: Record<string, unknown> = {};
+    for (const agent of app.framework.getAllAgents()) {
+      const strategy = (agent.getContextManager() as unknown as {
+        getStrategy?: () => { getCompressionDebt?: () => unknown };
+      }).getStrategy?.();
+      const d = strategy?.getCompressionDebt?.();
+      if (d) debt[(agent as unknown as { name: string }).name] = d;
+    }
+    (snapshot as Record<string, unknown>).compressionDebt = debt;
+  } catch {
+    // Health reads never throw.
+  }
   // Rendered context COMPOSITION per agent — head / raw middle / summaries
   // by level / tail, as actually emitted by the last compile. Sourced from
   // the strategy's own render stats (already computed in-process), so it is

package/src/workspace-mounts.ts

@@ -0,0 +1,73 @@
+/**
+ * Workspace mount construction — the single source of truth for which mounts
+ * a recipe's `modules.workspace` produces and with what flags.
+ *
+ * Used by BOTH the runtime (src/index.ts, to build the real WorkspaceModule
+ * config) and recipe validation (validateRecipe's instructions cross-check,
+ * which reasons about mount names, modes, and autoMaterialize). Keeping one
+ * builder prevents the validator from modeling a mount differently than the
+ * host constructs it — the exact split-brain the `_config` mount had when
+ * validation assumed it auto-materialized and the runtime built it without.
+ */
+
+import { join, resolve } from 'node:path';
+import type { MountConfig } from '@animalabs/agent-framework';
+import type { RecipeModules, RecipeWorkspaceMount } from './recipe.js';
+
+/**
+ * Build the mount list for a recipe's workspace declaration.
+ *
+ * Returns null when the workspace is disabled (`workspace: false`).
+ * `storePath` anchors the `_config` mount (session store config dir); pass
+ * any placeholder when only mount names/modes/flags are needed (validation).
+ */
+export function buildWorkspaceMounts(
+  workspace: RecipeModules['workspace'],
+  storePath: string,
+): MountConfig[] | null {
+  if (workspace === false) return null;
+
+  let mounts: MountConfig[];
+  if (typeof workspace === 'object' && workspace.mounts) {
+    // Only pass fields the recipe explicitly provides; let WorkspaceModule
+    // default the rest. watch is overridden to 'never' since the host does
+    // not need chokidar filesystem watchers by default.
+    mounts = workspace.mounts.map((m: RecipeWorkspaceMount) => {
+      const mount: MountConfig = {
+        name: m.name,
+        path: resolve(m.path),
+        mode: m.mode ?? 'read-write',
+        watch: m.watch ?? 'never',
+      };
+      if (m.ignore) mount.ignore = m.ignore;
+      if (m.maxFileSize !== undefined) mount.maxFileSize = m.maxFileSize;
+      if (m.wakeOnChange !== undefined) mount.wakeOnChange = m.wakeOnChange;
+      if (m.autoMaterialize !== undefined) mount.autoMaterialize = m.autoMaterialize;
+      return mount;
+    });
+  } else {
+    // Default: read-only input mount + read-write products mount.
+    mounts = [
+      { name: 'input', path: resolve('./input'), mode: 'read-only', watch: 'never' },
+      { name: 'products', path: resolve('./output'), mode: 'read-write', watch: 'never' },
+    ];
+  }
+
+  // Config mount: version-controls gate.json (and future config files) via
+  // Chronicle. Opt-in via recipe: workspace.configMount = true. NOTE: this
+  // mount is deliberately NOT autoMaterialize — the host re-materializes it
+  // explicitly after branch-changing commands, and ordinary agent edits stay
+  // Chronicle-side until then. Anything that assumes `_config` disk content
+  // tracks agent edits is wrong (see the instructions-path validation).
+  const wantConfigMount = typeof workspace === 'object' && workspace.configMount;
+  if (wantConfigMount) {
+    mounts.push({
+      name: '_config',
+      path: resolve(join(storePath, 'config')),
+      mode: 'read-write',
+      watch: 'always',
+    });
+  }
+
+  return mounts;
+}

package/test/audit-module-optins.test.ts

@@ -8,7 +8,7 @@
 
 import { describe, test, expect } from 'bun:test';
 import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import {
   classifyModule,
@@ -74,15 +74,22 @@ describe('auditRecipe', () => {
   });
 
   test('collects local fleet children, resolves relative paths, skips URLs', () => {
+    const parentPath = resolve('/deploy/recipes/parent.json');
     const a = auditRecipe(
       {
         name: 'parent',
         agent: AGENT,
         modules: { fleet: { children: [{ recipe: 'child.json' }, { recipe: 'https://x.example/c.json' }] } },
       },
-      '/deploy/recipes/parent.json',
+      parentPath,
     );
-    expect(a.childRecipePaths).toEqual(['/deploy/recipes/child.json']);
+
+    // The https child is skipped; the relative one resolves beside the parent.
+    expect(a.childRecipePaths).toHaveLength(1);
+    const [childPath] = a.childRecipePaths;
+    expect(isAbsolute(childPath)).toBe(true);
+    expect(dirname(childPath)).toBe(dirname(parentPath));
+    expect(basename(childPath)).toBe('child.json');
   });
 });
 

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

@@ -0,0 +1,83 @@
+/**
+ * Keepalive events must ALL reach stderr.
+ *
+ * The host unit routes StandardError to service-stderr.log and leaves stdout on
+ * the journal, so an event written with console.log lands where no operator
+ * greps. That actually happened on fable-cm 2026-08-23: the keepalive refreshed
+ * a 523k prefix three times, correctly, while a monitor tailing
+ * service-stderr.log reported zero activity for three hours.
+ *
+ * These tests fail if anyone re-introduces severity routing.
+ */
+import { describe, test, expect } from 'bun:test';
+import {
+  logKeepaliveEvent,
+  formatKeepaliveEvent,
+  KEEPALIVE_LOG_PREFIX,
+} from '../src/cache-keepalive-log.js';
+import type { KeepaliveEvent } from '@animalabs/membrane';
+
+const EVENTS: KeepaliveEvent[] = [
+  { type: 'refreshed', key: 'k1', lane: 'stream', readTokens: 523102, idleMs: 2987020 },
+  { type: 'expired', key: 'k1', idleMs: 21600000 },
+  { type: 'ineffective', key: 'k1', reason: 'wrote-instead-of-read', readTokens: 0, writeTokens: 523102 },
+  { type: 'skipped', key: 'k1', reason: 'no-1h-breakpoint' },
+  { type: 'error', key: 'k1', error: '400 invalid_request_error', consecutive: 1 },
+  { type: 'disabled', reason: '3 consecutive keepalive failures' },
+];
+
+describe('keepalive event logging', () => {
+  test('every event type is written, none silently dropped', () => {
+    for (const event of EVENTS) {
+      const lines: string[] = [];
+      logKeepaliveEvent(event, (l) => lines.push(l));
+      expect(lines.length).toBe(1);
+    }
+  });
+
+  test('routine refreshes are logged, not filtered as noise', () => {
+    // The regression this guards: treating `refreshed` as too chatty to log
+    // leaves no positive evidence the feature ran at all.
+    const lines: string[] = [];
+    logKeepaliveEvent(EVENTS[0]!, (l) => lines.push(l));
+    expect(lines[0]).toContain('refreshed');
+    expect(lines[0]).toContain('523102');
+  });
+
+  test('lines carry the greppable prefix', () => {
+    for (const event of EVENTS) {
+      expect(formatKeepaliveEvent(event).startsWith(KEEPALIVE_LOG_PREFIX)).toBe(true);
+    }
+  });
+
+  test('the payload is machine-readable JSON after the prefix', () => {
+    const line = formatKeepaliveEvent(EVENTS[2]!);
+    const json = line.slice(KEEPALIVE_LOG_PREFIX.length).trim();
+    const parsed = JSON.parse(json) as { type: string; reason: string; writeTokens: number };
+    expect(parsed.type).toBe('ineffective');
+    expect(parsed.reason).toBe('wrote-instead-of-read');
+    expect(parsed.writeTokens).toBe(523102);
+  });
+
+  test('DEFAULT SINK IS STDERR for every event type — not stdout', () => {
+    // The actual bug. console.error -> stderr -> service-stderr.log;
+    // console.log -> stdout -> journal, where nobody looks.
+    const origLog = console.log;
+    const origErr = console.error;
+    const origWarn = console.warn;
+    const toStdout: string[] = [];
+    const toStderr: string[] = [];
+    try {
+      console.log = (...a: unknown[]) => { toStdout.push(String(a[0])); };
+      console.error = (...a: unknown[]) => { toStderr.push(String(a[0])); };
+      console.warn = (...a: unknown[]) => { toStderr.push(String(a[0])); };
+      for (const event of EVENTS) logKeepaliveEvent(event);
+    } finally {
+      console.log = origLog;
+      console.error = origErr;
+      console.warn = origWarn;
+    }
+    expect(toStderr.length).toBe(EVENTS.length);
+    expect(toStdout.length).toBe(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/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

@@ -61,6 +61,25 @@ describe('standard-recipe memory defaults', () => {
     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/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);
+  });
+});