melchizedek-agents 0.9.6 → 0.16.0

package/dist/scripts/a2a_server.js

@@ -1,1058 +1,395 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
-import express from 'express';
-import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from "../lib/grounding.js";
-import rateLimit from 'express-rate-limit';
-import { AGENT_CARD_PATH } from '@a2a-js/sdk';
-import { timingSafeEqual, createHash } from 'node:crypto';
-import { loadEnv } from "../lib/loadEnv.js";
-import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
-import { AsyncLocalStorage } from 'async_hooks';
-import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@a2a-js/sdk/server/express';
-import { Runner, InMemorySessionService, getFunctionCalls, getFunctionResponses, setLogLevel, LogLevel } from '@google/adk';
-import { loadSyndicate } from "../lib/loadSyndicate.js";
-import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from "../lib/dispatch.js";
-import { traceAgentRun } from "../lib/observability/tracer.js";
-import { configDigest } from "../lib/observability/lineage.js";
-import { resolveModel } from "../lib/models/registry.js";
-import { compileGraph as compileGraphShared, compileSubagent as compileSubagentShared } from "../lib/compile.js";
-import { hasSupabaseCredentials, createSupabaseServices } from "../lib/persistence/supabaseProvider.js";
-import { ProjectedSessionService, renderTranscriptDigest } from "../lib/session/transcript.js";
-const requestContextStorage = new AsyncLocalStorage();
-const A2A_APP_NAME = 'melchizedek-a2a';
-/** X-User-Id must be short and filesystem/key-safe; anything else is rejected. */
-const SITE_USER_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
-/** X-Surface-* values obey the same charset rule, for the same reason. */
-const SURFACE_VALUE_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
-const SURFACE_HEADERS = [
-    ['x-surface', 'name'],
-    ['x-surface-guild', 'guild'],
-    ['x-surface-channel', 'channel'],
-    ['x-surface-user', 'user'],
-];
-/**
- * Root-span attributes for the caller's surface. Absent headers produce no
- * attributes at all, so a caller that names nothing writes NULLs rather than
- * a row full of 'unknown' — an unnamed surface and a surface named 'unknown'
- * are different facts and the ledger should not conflate them.
- */
-function surfaceAttributes(ctx) {
-    const s = ctx?.surface;
-    if (!s)
-        return {};
-    const attrs = { 'surface.name': s.name };
-    if (s.guild)
-        attrs['surface.guild'] = s.guild;
-    if (s.channel)
-        attrs['surface.channel'] = s.channel;
-    if (s.user)
-        attrs['surface.user'] = s.user;
-    return attrs;
-}
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 /**
- * Memory/session silo derivation.
- * Base silo: a hash of the caller's API key (one bucket per credential).
- * With X-User-Id, the end-user is siloed BENEATH the key hash — so a site
- * proxying many humans through one backend key gets one bucket per human,
- * and no site can ever reach into another credential's buckets, because
- * the key hash always prefixes.
+ * scripts/a2a_server.ts — the `melchizedek-serve` bin and `npm run start:a2a`.
+ *
+ * Reads the environment, refuses unsafe configurations, builds the server
+ * with `createA2AApp` (lib/a2a/app.ts — mountable in your own Express app),
+ * listens, and drains in-flight tasks on SIGTERM. Every turn runs through
+ * lib/runtime/syndicateTurn.ts, the same runtime the REPL and evals use.
+ *
+ * Environment (all optional; see .env.example):
+ *   PORT                      listen port (4000)
+ *   HOST                      bind address. Default: all interfaces when a
+ *                             secret is set, 127.0.0.1 when none is.
+ *   PUBLIC_URL                external base URL for agent cards; also marks a
+ *                             deployment as public (secret + hardening required)
+ *   A2A_SERVER_SECRET         bearer secret every request must present (A2A_AUTH=secret);
+ *                             with A2A_AUTH=callers it stays valid beside the caller
+ *                             tokens, with its old scoping, until you remove it
+ *   A2A_AUTH                  who a caller is (ADR 0025): secret (default) | callers |
+ *                             jwt | header
+ *   A2A_CALLERS               callers: `name:sha256[:scope]; …` — one token per calling
+ *                             backend. Mint: melchizedek-serve --new-caller <name>
+ *   A2A_JWT_JWKS_URL          jwt: your identity provider's JWKS (or A2A_JWT_SECRET, HS256)
+ *   A2A_JWT_ISSUER            jwt: required iss
+ *   A2A_JWT_AUDIENCE          jwt: required aud
+ *   A2A_JWT_SCOPE_CLAIM       jwt: the user claim (sub)
+ *   A2A_JWT_TENANT_CLAIM      jwt: optional tenant claim; scope becomes <tenant>/<user>
+ *   A2A_TRUSTED_USER_HEADER   header: the header your authenticating gateway sets
+ *                             (requires A2A_SERVER_SECRET, which only the gateway holds)
+ *   ALLOW_UNAUTHENTICATED     "true" to bind a non-loopback HOST with no secret
+ *   ALLOW_UNHARDENED_DB       "true" to accept an unhardened Supabase schema
+ *   A2A_TASK_TIMEOUT_MS       per-task wall-clock budget (900000; 0 = none)
+ *   A2A_MAX_CONCURRENT_TASKS  concurrent tasks across all agents (0 = unlimited)
+ *   A2A_RATE_LIMIT_MAX        task submissions per window per IP (60)
+ *   A2A_RATE_LIMIT_WINDOW_MS  rate-limit window (900000)
+ *   A2A_AUTH_FAILURE_MAX      failed authentications per window per IP (30)
+ *   A2A_TRUST_PROXY           Express trust-proxy: hop count, true/false, or subnets (1)
+ *   A2A_BODY_LIMIT            JSON body limit ("1mb")
+ *   A2A_KEY_MODE              server (default): models run on the server's keys;
+ *                             byok: the caller's X-API-Key pays. Under A2A_AUTH=secret
+ *                             the mode also scopes data: X-User-Id in server mode,
+ *                             the key's hash in byok (the pre-0.16 behaviour)
+ *   A2A_SERVED_AGENTS         comma list: the only agent ids /:agentId/ serves;
+ *                             only these may fall back to examples/ and templates/
+ *   A2A_REGISTRY_AGENTS       comma list: bare ids that load from adk_agent_registry
+ *                             (others are files; registry:<id> always is the registry)
+ *   A2A_SHUTDOWN_GRACE_MS     how long SIGTERM waits for running tasks (25000)
+ *   A2A_BUDGETS               daily budgets per UTC day (ADR 0026), JSON:
+ *                             {"perCaller":{"tasks":500,"llmCalls":5000,"tokens":5000000},
+ *                              "callers":{"reports":{"tasks":100}},"perScope":{"tasks":50}}.
+ *                             Counted in Postgres or Supabase when configured
+ *                             (db/migrations/0004), else in process memory
+ *   A2A_METRICS_TOKEN         bearer for GET /metrics (Prometheus); unset = no route
+ *   A2A_LOG_FORMAT            text (default) | json: one JSON object per line,
+ *                             including a `task` record per finished task
+ *   DATABASE_URL              Postgres for every durable store (sessions, memory,
+ *                             A2A tasks, erase) — multi-instance safe (ADR 0021).
+ *                             Without it: Supabase when its credentials are set,
+ *                             else process memory.
+ *   DATABASE_POOL_MAX         connections in the storage pool (default 10)
+ *   A2A_TURN_LOCK_POOL_MAX    connections for per-conversation turn locks, one per
+ *                             running turn (default 20). Behind a session-mode
+ *                             pooler (Supabase :5432) keep the two sums under its
+ *                             client limit, per instance.
  */
-function deriveUserId(ctx) {
-    const keyHash = createHash('sha256').update(ctx.apiKey).digest('hex').slice(0, 16);
-    return ctx.siteUserId ? `a2a-${keyHash}/${ctx.siteUserId}` : `a2a-${keyHash}`;
-}
-// ── Dynamic Agent Card Compiler ──────────────────────────────────────────
-// Synthesizes the public card configuration from current registry variables
-function compileAgentCard(config) {
-    const orchestratorConfig = config.orchestrator;
-    const subagents = config.subagents || [];
-    const url = process.env.PUBLIC_URL || 'http://localhost:4000';
-    return {
-        name: orchestratorConfig.name,
-        description: orchestratorConfig.description || 'Syndicate Orchestrator Agent',
-        protocolVersion: '0.3.0',
-        version: '2.0.0',
-        url: `${url}/a2a/jsonrpc`,
-        preferredTransport: 'JSONRPC',
-        capabilities: {
-            streaming: true,
-            pushNotifications: false,
-            stateTransitionHistory: true
-        },
-        defaultInputModes: ['text/plain'],
-        defaultOutputModes: ['text/plain'],
-        skills: subagents.map(sub => ({
-            id: sub.name,
-            name: sub.name,
-            description: sub.description || 'Subagent collaborator',
-            tags: sub.tools || []
-        })),
-        additionalInterfaces: [
-            { url: `${url}/a2a/jsonrpc`, transport: 'JSONRPC' },
-            { url: `${url}/a2a/rest`, transport: 'HTTP+JSON' }
-        ]
-    };
-}
-// ── Log Formatting Helpers ────────────────────────────────────────────────
-// Summarises tool call args into a single readable string, truncating long values.
-function formatToolArgs(args) {
-    if (!args || Object.keys(args).length === 0)
-        return '';
-    return Object.entries(args)
-        .map(([k, v]) => {
-        const raw = typeof v === 'string' ? v : JSON.stringify(v);
-        return `${k}=${raw.length > 60 ? `${raw.slice(0, 60)}...` : raw}`;
-    })
-        .join(', ');
+import { randomBytes } from 'node:crypto';
+import { realpathSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { setLogLevel, LogLevel } from '@google/adk';
+import { createA2AApp } from '../lib/a2a/app.js';
+import { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, sharedSecret, trustedHeader, } from '../lib/a2a/identity.js';
+import { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from '../lib/a2a/policy.js';
+import { hasSupabaseCredentials } from '../lib/persistence/supabaseProvider.js';
+import { setTaskBackend } from '../lib/tools/taskTools.js';
+import { redisRateLimitStore } from '../lib/a2a/redisLimits.js';
+import { dbSchema } from '../lib/storage/schema.js';
+import { postgresStorage } from '../lib/storage/postgres/index.js';
+import { isPlaceholderValue, loadEnv } from '../lib/loadEnv.js';
+import { flushTracing } from '../lib/observability/tracer.js';
+// Re-exported for existing importers (tests/failNarration.test.ts).
+export { describeTurnError } from '../lib/a2a/executor.js';
+/** Minimum bearer-secret length below which the server warns. */
+const MIN_SECRET_LENGTH = 32;
+const isLoopback = (host) => host === '127.0.0.1' || host === '::1' || host === 'localhost';
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${name} must be a non-negative number (got '${raw}')`);
+    return Math.floor(n);
 }
-// ── Progress telemetry ────────────────────────────────────────────────────
-// `[STATUS]` is a consumer contract, not decoration: A2A clients scan task
-// history for messages carrying this prefix and surface them as live progress
-// (the Discord bot edits its "Considering your query..." placeholder with the
-// newest one). Keep these lines short and human-readable — they are read by a
-// person waiting for an answer, not by a parser.
-function publishWorking(eventBus, taskId, contextId, text) {
-    eventBus.publish({
-        kind: 'status-update',
-        taskId,
-        contextId,
-        status: {
-            state: 'working',
-            message: {
-                kind: 'message',
-                messageId: crypto.randomUUID(),
-                role: 'agent',
-                parts: [{ kind: 'text', text: `[STATUS] ${text}` }],
-                contextId,
-                taskId
-            },
-            timestamp: new Date().toISOString()
-        },
-        final: false
-    });
+function envTrustProxy() {
+    const raw = process.env.A2A_TRUST_PROXY?.trim();
+    if (!raw)
+        return 1;
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return raw;
 }
-/** One human-readable line naming WHY a turn failed, for the failed task's
- *  status message — the text the Discord surface renders verbatim. Provider
- *  errors sometimes arrive as a raw JSON blob (Gemini ApiError:
- *  `{"error":{"code":503,"message":"...","status":"UNAVAILABLE"}}`), so the
- *  inner message is dug out before falling back to the string itself. An
- *  empty message keeps the old pointer at the server logs. */
-export function describeTurnError(error) {
-    let msg = (error.message ?? '').trim();
-    if (msg.startsWith('{')) {
-        try {
-            const parsed = JSON.parse(msg);
-            const inner = parsed?.error?.message ?? parsed?.message;
-            if (typeof inner === 'string' && inner.trim())
-                msg = inner.trim();
-        }
-        catch { /* not JSON — use as-is */ }
+/** A2A_LOG_FORMAT=json: every server line is one JSON object (ts, level, msg, …). */
+const jsonLogs = () => (process.env.A2A_LOG_FORMAT ?? '').trim().toLowerCase() === 'json';
+function emit(level, message, fields) {
+    if (jsonLogs()) {
+        const line = JSON.stringify({ ts: new Date().toISOString(), level, msg: message.replace(/^\[A2A\]\s*(⚠|✗|✓)?\s*/, ''), ...fields });
+        (level === 'info' ? console.log : console.error)(line);
+        return;
     }
-    if (!msg)
-        return 'see server logs for details.';
-    return msg.length > 300 ? `${msg.slice(0, 297)}...` : msg;
+    (level === 'info' ? console.log : level === 'warn' ? console.warn : console.error)(message);
 }
-// ── Native ADK AgentExecutor Bridge ───────────────────────────────────────
-class SyndicateExecutor {
-    config;
-    sessionService;
-    memoryService;
-    /** Provenance stamp for every turn this executor serves (lineage.ts). */
-    configHash;
-    constructor(config, sessionService, memoryService) {
-        this.config = config;
-        this.sessionService = sessionService;
-        this.memoryService = memoryService;
-    }
-    configHashFor() {
-        if (!this.configHash) {
-            try {
-                this.configHash = configDigest(this.config, (ref) => loadSyndicate(ref));
-            }
-            catch {
-                this.configHash = 'unhashable';
-            }
-        }
-        return this.configHash;
-    }
-    /**
-     * Run ONE agent for ONE turn against a named session, draining its event
-     * stream. DELEGATE mode calls this once (the orchestrator); PLAN-DISPATCH
-     * calls it twice — the classifier, then the route it chose.
-     *
-     * Errors are RETURNED rather than published, because the two callers want
-     * different things from them: a failed specialist is a failed task, but a
-     * failed classifier must fall back to the default route and still answer.
-     */
-    async runTurn(params) {
-        const { agent, sessionId, userId, userParts, taskId, contextId, eventBus } = params;
-        const runner = new Runner({
-            agent,
-            appName: A2A_APP_NAME,
-            sessionService: params.sessionService ?? this.sessionService,
-            ...(this.memoryService ? { memoryService: this.memoryService } : {})
-        });
-        let stream = runner.runAsync({
-            userId,
-            sessionId,
-            newMessage: { role: 'user', parts: userParts },
-            ...(this.config.max_steps !== undefined ? { maxSteps: this.config.max_steps } : {})
-        });
-        let combinedText = '';
-        let lastToolResultText = '';
-        const invokedToolNames = new Set();
-        // The DELEGATE relay-fallback predicate, evaluated by the tracer in its
-        // finally (after the last event) so the turn row records whether the
-        // orchestrator's relay failed. Same rule as the substitution below.
-        const normalizeName = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
-        const relayFallbackFired = () => {
-            const text = combinedText.trim();
-            const echoed = text.length > 0 && [...invokedToolNames].some((n) => normalizeName(n) === normalizeName(text));
-            return (!text || echoed) && !!lastToolResultText;
-        };
-        if (params.trace) {
-            stream = traceAgentRun(stream, {
-                syndicateName: this.config.syndicate_name || 'melchizedek-syndicate',
-                bindings: this.config.variables || {},
-                input: userParts,
-                route: params.route,
-                // Identity: the CONVERSATION id (contextId), not the classifier's
-                // throwaway lane — every stage of one turn shares session/task ids.
-                sessionId: contextId,
-                userId,
-                taskId,
-                stage: params.stage,
-                configHash: this.configHashFor(),
-                attributes: surfaceAttributes(requestContextStorage.getStore()),
-                onEnd: () => ({
-                    'syndicate.relay_fallback': params.stage === 'delegate' && relayFallbackFired(),
-                }),
-            });
-        }
-        let lastTokenTotal = 0;
-        let lastThinkingTokens = 0;
-        let error;
-        const grounding = newGroundingState();
-        let groundingAnnounced = false;
-        for await (const event of stream) {
-            const evAny = event;
-            // Native search grounding rides on the model event, not on a tool call.
-            if (collectGrounding(evAny, grounding)) {
-                const firstSight = grounding.queries.size + grounding.sources.size > 0 && !groundingAnnounced;
-                console.log(`[A2A] ⌕ Grounding: ${describeGrounding(grounding)}`);
-                if (params.publishToolStatus && firstSight) {
-                    // Same shape as a function-tool line so consumers that parse
-                    // "Invoking tool:" (nihilistic-penguin RouteTrace) list it.
-                    publishWorking(eventBus, taskId, contextId, `Invoking tool: web_search`);
-                }
-                groundingAnnounced = true;
-            }
-            if ((evAny.errorCode || evAny.errorMessage) && evAny.errorCode !== 'STOP') {
-                error = {
-                    code: evAny.errorCode ?? 'ERROR',
-                    message: evAny.errorMessage ?? ''
-                };
-                console.error(`[A2A] Error [${error.code}]: ${error.message}`);
-                break;
-            }
-            // Tool calls — log formatted name + args, publish working status to eventBus
-            const calls = getFunctionCalls(event);
-            if (calls && calls.length > 0) {
-                for (const call of calls) {
-                    if (call.name === 'transfer_to_agent') {
-                        const target = call.args?.agentName ?? 'unknown';
-                        console.log(`[A2A] → Delegating to: ${target}`);
-                        if (params.publishToolStatus) {
-                            publishWorking(eventBus, taskId, contextId, `Delegating to subagent: ${target}`);
-                        }
-                    }
-                    else {
-                        const argStr = formatToolArgs(call.args);
-                        if (call.name)
-                            invokedToolNames.add(call.name);
-                        console.log(`[A2A] → Tool: ${call.name}(${argStr})`);
-                        if (params.publishToolStatus) {
-                            publishWorking(eventBus, taskId, contextId, `Invoking tool: ${call.name}`);
-                        }
-                    }
-                }
-            }
-            // Tool responses — log name and result size (avoids dumping raw JSON/base64 to logs)
-            const responses = getFunctionResponses(event);
-            if (responses && responses.length > 0) {
-                for (const resp of responses) {
-                    const respAny = resp;
-                    const respName = respAny.name ?? respAny.functionResponse?.name ?? 'unknown';
-                    const respContent = respAny.response ?? respAny.functionResponse?.response ?? {};
-                    const resultStr = typeof respContent === 'string' ? respContent : JSON.stringify(respContent);
-                    if (respName && respName !== 'unknown')
-                        invokedToolNames.add(respName);
-                    console.log(`[A2A] ← Result: ${respName} — ${resultStr.length.toLocaleString()} chars`);
-                    // Kept as the DELEGATE-mode relay fallback below. Only plain text
-                    // results qualify — a structured/base64 payload (e.g. image tools)
-                    // is not a relayable answer.
-                    const resultText = typeof respContent === 'string'
-                        ? respContent
-                        : typeof respContent.result === 'string' ? respContent.result : '';
-                    if (resultText.trim()) {
-                        lastToolResultText = resultText.trim();
-                    }
-                }
-            }
-            // The answer is the LAST turn's text, not every turn's — the same rule
-            // AgentTool applied by returning only its final event. It mattered the
-            // moment specialists started running directly: a tool-using agent
-            // narrates between calls ("Pulling FinTwit-specific NVDA signal…"), and
-            // accumulating glued that commentary to the front of its report. A
-            // prompt rule against narrating was not enough on grok-4.5, so the rule
-            // lives here instead. Thinking traces are suppressed throughout (too
-            // verbose for the server log, and never part of the answer).
-            //
-            // Within ONE event, parts are joined — a single answer legitimately
-            // arrives in several parts. `partial` events are streaming chunks of the
-            // turn in progress, so they append rather than replace; this deployment
-            // does not enable streaming, but getting it wrong would truncate an
-            // answer, which is the failure this whole area exists to prevent.
-            let eventText = '';
-            if (event.content?.parts) {
-                for (const part of event.content.parts) {
-                    const textContent = part.text ?? '';
-                    const isThought = part.thought === true;
-                    if (!isThought && textContent) {
-                        eventText += textContent;
-                    }
-                }
-            }
-            if (eventText) {
-                combinedText = evAny.partial === true ? combinedText + eventText : eventText;
-            }
-        }
-        const sourcesLine = webSourcesLine(grounding);
-        if (params.publishToolStatus && sourcesLine) {
-            // Published AFTER the loop so it lands once, with the full set. A
-            // consumer contract (penguin RouteTrace `_SOURCES_RE`): "Web sources: a, b".
-            publishWorking(eventBus, taskId, contextId, sourcesLine);
-        }
-        return {
-            text: combinedText.trim(),
-            lastToolResultText,
-            invokedToolNames,
-            grounding: (grounding.queries.size || grounding.sources.size)
-                ? { queries: [...grounding.queries], sources: [...grounding.sources] }
-                : undefined,
-            tokenInfo: lastTokenTotal > 0
-                ? ` | ${lastTokenTotal.toLocaleString()} tokens${lastThinkingTokens > 0 ? ` (${lastThinkingTokens.toLocaleString()} thinking)` : ''}`
-                : '',
-            error
-        };
-    }
-    async execute(requestContext, eventBus) {
-        const message = requestContext.userMessage;
-        const rawParts = message.content || message.parts || [];
-        const userParts = rawParts.map((p) => {
-            if (typeof p === 'string')
-                return { text: p };
-            return { text: p.text || '' };
-        });
-        const contextId = requestContext.contextId;
-        const taskId = requestContext.taskId;
-        const queryPreview = userParts.map((p) => p.text ?? '').join(' ').replace(/\n/g, ' ').slice(0, 120);
-        console.log(`[A2A] ─── Task ${taskId.slice(0, 8)} | ${this.config.syndicate_name}`);
-        console.log(`[A2A] Query: "${queryPreview}${queryPreview.length >= 120 ? '...' : ''}"`);
-        try {
-            // Initialize task on the event bus to allow non-blocking clients to start polling immediately
-            eventBus.publish({
-                id: taskId,
-                kind: 'task',
-                contextId,
-                status: {
-                    state: 'submitted',
-                    timestamp: new Date().toISOString()
-                },
-                history: []
-            });
-            const authContext = requestContextStorage.getStore();
-            if (!authContext) {
-                throw new Error('No authentication context available.');
-            }
-            // Session & memory isolation: per-credential by API-key hash, and
-            // per end-user beneath it when the caller supplies X-User-Id.
-            // See deriveUserId() for the silo contract.
-            const userId = deriveUserId(authContext);
-            if (userParts.length === 0)
-                throw new Error('Message parts are required.');
-            // Model resolution: the YAML model id always wins — its prefix names
-            // the provider (claude-*, gpt-*, grok-*, ollama/*, else Gemini). The
-            // X-Provider header is DEPRECATED and only picks a default model when
-            // the YAML omits `model` entirely. lib/models/registry.ts is the
-            // single implementation, shared with the CLI path.
-            const resolveModelForRequest = (modelName) => resolveModel(modelName, {
-                apiKey: authContext.apiKey,
-                defaultProvider: authContext.provider,
-            });
-            // Compile ADK nodes through the shared compiler (lib/compile.ts) — the
-            // observatory runs the same function, so the graph an eval measures is
-            // the graph this server serves. compileSubagent builds ONE runnable
-            // agent from a subagent entry; in DELEGATE mode compileGraph wraps it in
-            // an AgentTool, in PLAN-DISPATCH the same agent is run directly as the
-            // chosen route, so both methods dispatch to identical agents.
-            const compileOpts = {
-                resolveModel: resolveModelForRequest,
-                onUnknownTool: (name) => console.warn(`[A2A] WARNING: Unknown tool '${name}' — skipping.`),
-                log: (message) => console.log(`[A2A] ${message}`),
-            };
-            const compileSubagent = (subCfg) => compileSubagentShared(subCfg, compileOpts);
-            const compileGraph = (configObj) => compileGraphShared(configObj, compileOpts);
-            const ensureSession = async (sessionId) => {
-                const existing = await this.sessionService.getSession({
-                    sessionId,
-                    appName: A2A_APP_NAME,
-                    userId
-                });
-                if (existing)
-                    return true;
-                await this.sessionService.createSession({
-                    sessionId,
-                    appName: A2A_APP_NAME,
-                    userId
-                });
-                return false;
-            };
-            const failTask = (text) => {
-                eventBus.publish({
-                    kind: 'status-update',
-                    taskId,
-                    contextId,
-                    status: {
-                        state: 'failed',
-                        message: {
-                            kind: 'message',
-                            messageId: crypto.randomUUID(),
-                            role: 'agent',
-                            parts: [{ kind: 'text', text }],
-                            contextId,
-                            taskId
-                        },
-                        timestamp: new Date().toISOString()
-                    },
-                    final: true
-                });
-            };
-            const resumed = await ensureSession(contextId);
-            console.log(`[A2A] Session: ${resumed ? 'resumed' : 'new'} — context ${contextId.slice(0, 8)}`);
-            let finalText = '';
-            let tokenInfo = '';
-            let routerTokenInfo = '';
-            if (isDispatchSyndicate(this.config)) {
-                // ══ PLAN ═══════════════════════════════════════════════════════════
-                // Deterministic overrides come FIRST: when the message itself decides
-                // the route (an x.com link only XScout can open, an explicit demand
-                // for a named tool), there is nothing to classify. The classifier LLM
-                // call is skipped entirely — cheaper, and immune to a weak classifier
-                // out-voting a stated rule (2026-08-15).
-                const overrideWarnings = [];
-                const messageText = userParts.map((p) => p.text ?? '').join('\n');
-                let resolution = matchRouteOverride(messageText, this.config, overrideWarnings);
-                for (const warning of overrideWarnings)
-                    console.warn(`[A2A] ⚠ ${warning}`);
-                if (resolution) {
-                    console.log(`[A2A] ⇄ Route pinned by override: ${resolution.route}`);
-                }
-                else {
-                    // ── The classifier reads the SHARED transcript ──────────────────
-                    // Its JSON verdicts must never enter the user-facing transcript —
-                    // the next specialist would read them as conversation — so it does
-                    // not write to the shared session. It used to get its own durable
-                    // `<contextId>::route` lane instead, and that lane was the bug: it
-                    // accumulated the user's messages and the router's own verdicts and
-                    // NOTHING ELSE, so the router had never seen a single answer it had
-                    // routed. On 2026-08-15 a user's counter-argument to the desk's
-                    // MU/SNDK/NVDA/AMD verdict read to it as a remark with no request
-                    // behind it and went to small talk; its own rule 2 (redo/method
-                    // complaint) and rule 5 (follow-ups on prior analysis) were dead
-                    // letters, since neither can be recognised without the answer being
-                    // followed up. The lane also had HOLES: a message pinned by
-                    // `route_overrides` skips this branch entirely and was therefore
-                    // never recorded, so the X recon that opened that same thread was
-                    // missing from the router's history altogether.
-                    //
-                    // Now history arrives as INPUT — a compact digest of the real
-                    // exchange, both sides of it — and the lane is a throwaway
-                    // in-memory session that is discarded with the request. Nothing to
-                    // keep in sync, nothing to leave holes in, nothing persisted.
-                    const routerAgent = await compileGraph(this.config);
-                    const routerSessionId = `${contextId}::route`;
-                    const routerSessions = new InMemorySessionService();
-                    await routerSessions.createSession({
-                        sessionId: routerSessionId,
-                        appName: A2A_APP_NAME,
-                        userId
-                    });
-                    const sharedSession = await this.sessionService.getSession({
-                        sessionId: contextId,
-                        appName: A2A_APP_NAME,
-                        userId
-                    });
-                    const digest = renderTranscriptDigest(sharedSession?.events ?? []);
-                    const routerParts = digest
-                        ? [{
-                                text: `RECENT CONVERSATION, oldest first — context for your classification only. `
-                                    + `Never answer it, and never route on it alone; it is here so you can tell a `
-                                    + `follow-up, a redo request, or a challenge to a previous answer apart from small talk.\n`
-                                    + `${digest}\n\n--- MESSAGE TO CLASSIFY ---\n${messageText}`
-                            }]
-                        : userParts;
-                    const plan = await this.runTurn({
-                        agent: routerAgent,
-                        sessionId: routerSessionId,
-                        userId,
-                        userParts: routerParts,
-                        taskId,
-                        contextId,
-                        eventBus,
-                        trace: true, // one row per classification: misroutes are diagnosable from stored data
-                        stage: 'classify',
-                        publishToolStatus: false, // a dispatch classifier holds no tools
-                        sessionService: routerSessions
-                    });
-                    // Fail-static: a dead classifier costs the user a good route, never
-                    // their answer. An empty payload resolves to default_route by design.
-                    resolution = resolveRoute(plan.error ? '' : plan.text, this.config);
-                    if (plan.error) {
-                        console.warn(`[A2A] ⚠ Router failed [${plan.error.code}] — defaulting to '${resolution.route}'.`);
-                    }
-                    else if (resolution.fellBack) {
-                        console.warn(`[A2A] ⚠ Routing fell back to '${resolution.route}': ${resolution.fallbackReason}`);
-                    }
-                    routerTokenInfo = plan.tokenInfo;
-                }
-                const routeCfg = (this.config.subagents || []).find(sub => sub.name === resolution.route);
-                if (!routeCfg) {
-                    throw new Error(`Dispatch failed: no subagent named '${resolution.route}' is declared.`);
-                }
-                const routeNote = resolution.reason ? ` — ${resolution.reason}` : '';
-                console.log(`[A2A] ⇄ Route: ${resolution.route}${routeNote}${routerTokenInfo}`);
-                publishWorking(eventBus, taskId, contextId, `Routed to ${resolution.route}${routeNote}`);
-                // ══ DISPATCH ═══════════════════════════════════════════════════════
-                // The chosen route answers the user directly — its output IS the task
-                // result, with no relay turn to lose or mangle it. It runs in the
-                // SHARED session, so every route writes into one transcript: a
-                // follow-up handled by a different specialist still sees what the last
-                // one said, and long-term memory ingests real answers rather than a
-                // relay copy of them.
-                //
-                // It READS that transcript through a projection (lib/session/
-                // transcript.ts), because sharing the session is not the same as
-                // sharing the conversation. ADK renders any event authored by a
-                // different agent as `role: "user"` prefixed "For context:" — so a
-                // route reading a shared session gets the whole thread as one
-                // undifferentiated user monologue, with the previous route's private
-                // reasoning and raw tool payloads mixed into it. The projection hands
-                // it real `role: "model"` turns instead, labelled by the desk that
-                // spoke, with thoughts and tool traffic stripped.
-                const routeAgent = await compileSubagent(routeCfg);
-                const turn = await this.runTurn({
-                    agent: routeAgent,
-                    sessionId: contextId,
-                    userId,
-                    userParts,
-                    taskId,
-                    contextId,
-                    eventBus,
-                    trace: true,
-                    stage: 'dispatch',
-                    publishToolStatus: true,
-                    route: resolution,
-                    sessionService: new ProjectedSessionService(this.sessionService, routeCfg.name)
-                });
-                if (turn.error) {
-                    failTask(`Error: [${turn.error.code}] ${resolution.route} failed to answer — ${describeTurnError(turn.error)}`);
-                    return;
-                }
-                tokenInfo = turn.tokenInfo;
-                finalText = turn.text;
-                if (!finalText) {
-                    // Naming the route turns a blank reply into a lead. This is the
-                    // shape the XScout outage took: the specialist ran and returned
-                    // nothing because its provider rejected the call upstream.
-                    console.warn(`[A2A] ⚠ Route '${resolution.route}' produced no output.`);
-                    finalText = `${resolution.route} returned no output — the server logs carry the upstream error.`;
-                }
-            }
-            else {
-                // ══ DELEGATE (classic) ═════════════════════════════════════════════
-                // Subagents are AgentTools; the orchestrator relays the answer it got.
-                const orchestrator = await compileGraph(this.config);
-                const turn = await this.runTurn({
-                    agent: orchestrator,
-                    sessionId: contextId,
-                    userId,
-                    userParts,
-                    taskId,
-                    contextId,
-                    eventBus,
-                    trace: true,
-                    stage: 'delegate',
-                    publishToolStatus: true
-                });
-                if (turn.error) {
-                    failTask(`Error: [${turn.error.code}] The agent run failed — ${describeTurnError(turn.error)}`);
-                    return;
-                }
-                tokenInfo = turn.tokenInfo;
-                // Failed-relay fallback: an orchestrator (flash-lite especially) can
-                // botch the hop that relays a specialist answer, in two observed ways —
-                // finishing STOP with zero output tokens, or emitting the bare tool NAME
-                // as its text ("FinancialAnalyst", 3 tokens) instead of the answer. Both
-                // discard a fully-formed result, so the last tool result is returned
-                // deterministically rather than retrying the relay LLM (a retry costs a
-                // full round-trip and can fail the same way again).
-                //
-                // PLAN-DISPATCH does not need any of this — it has no relay turn to
-                // fail. This branch is why the two methods exist side by side.
-                //
-                // Degenerate-text detection is deliberately narrow — an exact match to an
-                // invoked tool name after stripping non-alphanumerics — because short
-                // real answers are legitimate ("Yes, as of Q2 2026."), so no length or
-                // ratio heuristic may be used here.
-                const normalize = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
-                finalText = turn.text;
-                const echoedToolName = finalText.length > 0 && [...turn.invokedToolNames]
-                    .some(name => normalize(name) === normalize(finalText));
-                if ((!finalText || echoedToolName) && turn.lastToolResultText) {
-                    const reason = echoedToolName
-                        ? `echoed the tool name ("${finalText}")`
-                        : 'emitted no text';
-                    console.warn(`[A2A] ⚠ Orchestrator ${reason} — relaying last tool result verbatim (${turn.lastToolResultText.length.toLocaleString()} chars).`);
-                    finalText = turn.lastToolResultText;
-                }
-            }
-            if (finalText) {
-                console.log(`[A2A] ✓ Task ${taskId.slice(0, 8)} complete — ${finalText.length.toLocaleString()} chars${tokenInfo}`);
-                eventBus.publish({
-                    kind: 'status-update',
-                    taskId,
-                    contextId,
-                    status: {
-                        state: 'completed',
-                        message: {
-                            kind: 'message',
-                            messageId: crypto.randomUUID(),
-                            role: 'agent',
-                            parts: [{ kind: 'text', text: finalText }],
-                            contextId,
-                            taskId
-                        },
-                        timestamp: new Date().toISOString()
-                    },
-                    final: true
-                });
-            }
-            else {
-                console.log(`[A2A] ✓ Task ${taskId.slice(0, 8)} complete — empty output`);
-                eventBus.publish({
-                    kind: 'status-update',
-                    taskId,
-                    contextId,
-                    status: {
-                        state: 'completed',
-                        timestamp: new Date().toISOString()
-                    },
-                    final: true
-                });
-            }
-            // Long-term memory ingestion: the A2A server is stateless, so there is
-            // no "session end" moment like the CLI's exit — ingest after every
-            // completed task instead. The memory service dedupes facts per user
-            // key, so re-serializing the same conversation next turn is harmless.
-            // Runs AFTER the final status publish so it never delays the reply.
-            if (this.memoryService) {
-                try {
-                    const endedSession = await this.sessionService.getSession({
-                        sessionId: contextId,
-                        appName: A2A_APP_NAME,
-                        userId
-                    });
-                    if (endedSession && endedSession.events.length > 0) {
-                        // The Supabase service accepts per-consumer extraction rules; the
-                        // base interface does not declare them, and only that service is
-                        // ever wired here (startServer constructs it directly).
-                        await this.memoryService
-                            .addSessionToMemory(endedSession, this.config.memory_extraction_rules);
-                    }
-                }
-                catch (memErr) {
-                    const msg = memErr instanceof Error ? memErr.message : String(memErr);
-                    console.error(`[A2A] ⚠ Memory ingestion failed (reply already delivered): ${msg}`);
-                }
-            }
-        }
-        catch (error) {
-            console.error(`[A2A] Exception on task ${taskId.slice(0, 8)}: ${error.message}`);
-            eventBus.publish({
-                kind: 'status-update',
-                taskId,
-                contextId,
-                status: {
-                    state: 'failed',
-                    message: {
-                        kind: 'message',
-                        messageId: crypto.randomUUID(),
-                        role: 'agent',
-                        parts: [{ kind: 'text', text: 'Internal Error: the request could not be completed. See server logs for details.' }],
-                        contextId,
-                        taskId
-                    },
-                    timestamp: new Date().toISOString()
-                },
-                final: true
-            });
-        }
-        finally {
-            eventBus.finished();
-        }
-    }
-    async cancelTask() { }
+function fatal(message) {
+    emit('error', `[A2A] ✗ FATAL: ${message}`);
+    process.exit(1);
 }
-// ── Bootstrap Routine ──────────────────────────────────────────────────────
-export async function startServer(syndicateName = 'syndicate.yaml') {
+export async function startServer(syndicateName = 'syndicate.yaml', extensions = {}) {
     loadEnv(import.meta.url);
-    // Suppress ADK internal INFO/DEBUG logs (raw event JSON, embeddings, binary blobs)
+    // Conversation content stays out of stdout unless the operator opts in:
+    // the root span carries the full user message and answer.
+    if (process.env.OTEL_CONSOLE_SPANS === undefined)
+        process.env.OTEL_CONSOLE_SPANS = 'false';
+    // ADK's INFO/DEBUG logs carry raw event JSON; keep them quiet.
     setLogLevel(LogLevel.WARN);
-    const serverBindings = {
-        current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
-    };
-    let config;
-    if (syndicateName.startsWith('registry:')) {
-        const registryId = syndicateName.replace('registry:', '');
-        // Lazy import to prevent circular dependency issues during regular boot
-        const { loadSyndicateFromRegistry } = await import("../lib/loadSyndicate.js");
-        config = await loadSyndicateFromRegistry(registryId, { bindings: serverBindings });
+    const publicUrl = process.env.PUBLIC_URL?.trim() || undefined;
+    const port = envInt('PORT', 4000);
+    // ── Authentication posture ─────────────────────────────────────────────────
+    let secret = process.env.A2A_SERVER_SECRET?.trim() || undefined;
+    if (secret && isPlaceholderValue(secret)) {
+        fatal('A2A_SERVER_SECRET is still the .env.example placeholder. Generate one: openssl rand -hex 32');
     }
-    else {
-        config = loadSyndicate(syndicateName, { bindings: serverBindings });
+    if (secret && secret.length < MIN_SECRET_LENGTH) {
+        emit('warn', `[A2A] ⚠ A2A_SERVER_SECRET is shorter than ${MIN_SECRET_LENGTH} characters; use a long random value.`);
     }
-    const agentCard = compileAgentCard(config);
-    // Persistence: sessions whenever Supabase credentials exist. The memory
-    // service is constructed alongside (it's just a client handle) but is only
-    // handed to executors whose syndicate opts in via memory_system:
-    // "long-term" — static agent here, dynamic agents per-config below.
-    // Embeddings and fact extraction use the SERVER's Gemini key (memory is
-    // operator infrastructure, like tools); the caller's BYOK key only funds
-    // inference.
-    const wantsLongTermMemory = config.memory_system === 'long-term';
-    let sessionService = new InMemorySessionService();
-    let memoryService;
-    if (hasSupabaseCredentials()) {
-        const services = await createSupabaseServices({
-            apiKey: process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY || '',
-            withMemory: true
-        });
-        sessionService = services.sessionService;
-        memoryService = services.memoryService;
-        if (wantsLongTermMemory) {
-            console.log(`[A2A] Long-term memory enabled for "${config.syndicate_name}" (per-user silos via X-User-Id).`);
+    const list = (name) => process.env[name] ? process.env[name].split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const keyModeRaw = (process.env.A2A_KEY_MODE ?? 'server').trim().toLowerCase();
+    if (keyModeRaw !== 'server' && keyModeRaw !== 'byok')
+        fatal(`A2A_KEY_MODE must be 'server' or 'byok' (got '${keyModeRaw}')`);
+    const keyMode = keyModeRaw;
+    // ── Identity: who a caller is, and whose data a request touches (ADR 0025) ─
+    const authKind = (process.env.A2A_AUTH ?? 'secret').trim().toLowerCase();
+    let authenticator;
+    let identityLabel = '';
+    try {
+        if (authKind === 'callers') {
+            const spec = process.env.A2A_CALLERS?.trim();
+            if (!spec)
+                fatal('A2A_AUTH=callers needs A2A_CALLERS (name:sha256[:scope]; …). Mint a caller: melchizedek-serve --new-caller <name>');
+            const callers = parseCallers(spec);
+            authenticator = secret ? firstOf(callerTokens(callers), sharedSecret({ secret, keyMode })) : callerTokens(callers);
+            identityLabel = `caller tokens (${callers.map((c) => c.name).join(', ')})${secret ? ' + the legacy A2A_SERVER_SECRET' : ''}`;
+        }
+        else if (authKind === 'jwt') {
+            const issuer = list('A2A_JWT_ISSUER');
+            const audience = list('A2A_JWT_AUDIENCE');
+            if (!issuer || !audience)
+                fatal('A2A_AUTH=jwt needs A2A_JWT_ISSUER and A2A_JWT_AUDIENCE.');
+            authenticator = jwtIdentity({
+                jwksUrl: process.env.A2A_JWT_JWKS_URL?.trim() || undefined,
+                secret: process.env.A2A_JWT_SECRET?.trim() || undefined,
+                issuer: issuer.length === 1 ? issuer[0] : issuer,
+                audience: audience.length === 1 ? audience[0] : audience,
+                scopeClaim: process.env.A2A_JWT_SCOPE_CLAIM?.trim() || undefined,
+                tenantClaim: process.env.A2A_JWT_TENANT_CLAIM?.trim() || undefined,
+            });
+            identityLabel = `JWT (iss ${issuer.join(', ')})`;
         }
-        // Defense-in-depth check: warn operators when db/hardening.sql has not
-        // been applied. Without it, the anon/authenticated Supabase API paths
-        // can read adk_sessions and adk_memory_facts directly — the application
-        // silo (user_key) does nothing against that route. Escalation mirrors
-        // the A2A_SERVER_SECRET pattern: fatal for public deployments unless
-        // explicitly overridden.
-        const rls = await services.checkRlsHardening();
-        if (rls.applied) {
-            console.log(`[A2A] ✓ DB hardening verified — ${rls.detail}.`);
+        else if (authKind === 'header') {
+            const header = process.env.A2A_TRUSTED_USER_HEADER?.trim();
+            if (!header)
+                fatal('A2A_AUTH=header needs A2A_TRUSTED_USER_HEADER.');
+            if (!secret)
+                fatal('A2A_AUTH=header needs A2A_SERVER_SECRET: only the gateway holding it may set the user header.');
+            authenticator = trustedHeader({ header });
+            identityLabel = `gateway header ${header} behind the bearer secret`;
         }
-        else {
-            const allowUnhardened = process.env.ALLOW_UNHARDENED_DB === 'true';
-            if (process.env.PUBLIC_URL && !allowUnhardened) {
-                console.error('[A2A] ✗ FATAL: PUBLIC_URL is set but Supabase hardening is missing');
-                console.error(`[A2A]   (${rls.detail}).`);
-                console.error('[A2A]   User transcripts and memory facts are exposed to the anon API key.');
-                console.error('[A2A]   Run db/hardening.sql in the Supabase SQL Editor, or set');
-                console.error('[A2A]   ALLOW_UNHARDENED_DB=true to accept the risk explicitly.');
-                process.exit(1);
-            }
-            console.log(`[A2A] ⚠ WARNING: Supabase hardening not applied — ${rls.detail}.`);
-            console.log('[A2A]   Run db/hardening.sql before serving real user data. Details:');
-            console.log('[A2A]   lib/memory/README.md → "Hardening".');
+        else if (authKind !== 'secret') {
+            fatal(`A2A_AUTH must be secret, callers, jwt or header (got '${authKind}')`);
         }
     }
-    else if (wantsLongTermMemory) {
-        console.log('[A2A] ⚠ WARNING: syndicate requests long-term memory but Supabase credentials are missing — memory disabled.');
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
     }
-    const app = express();
-    app.set('trust proxy', 1); // Trust Heroku proxy for accurate IP rate limiting
-    // Security: Server-Level Authentication (Before body parsing)
-    const serverSecret = process.env.A2A_SERVER_SECRET;
-    if (!serverSecret) {
-        // Running without a shared secret leaves every endpoint open (the BYOK
-        // X-API-Key check only verifies presence, not validity). Tolerate this for
-        // local dev, but refuse to boot a publicly-addressable deployment.
-        if (process.env.PUBLIC_URL) {
-            console.error('[A2A] ✗ FATAL: PUBLIC_URL is set but A2A_SERVER_SECRET is missing. Refusing to start an unauthenticated public server.');
+    // Caller tokens and JWTs are bearer credentials checked by the
+    // authenticator; the shared secret is then not a gate of its own.
+    const bearerGate = authKind === 'secret' || authKind === 'header';
+    const authenticated = !!secret || !!authenticator;
+    let host = process.env.HOST?.trim() || undefined;
+    if (!authenticated) {
+        if (publicUrl)
+            fatal('PUBLIC_URL is set but A2A_SERVER_SECRET is missing. Refusing to start an unauthenticated public server.');
+        if (host && !isLoopback(host) && process.env.ALLOW_UNAUTHENTICATED !== 'true') {
+            fatal(`HOST=${host} would expose an unauthenticated server. Set A2A_SERVER_SECRET, or ALLOW_UNAUTHENTICATED=true to accept the risk.`);
+        }
+        // Without a secret the server answers only on this machine.
+        host = host ?? '127.0.0.1';
+        emit('warn', `[A2A] ⚠ A2A_SERVER_SECRET is not set: authentication is off and the server binds ${host} only.`);
+    }
+    /** A positive integer from the environment, or undefined; anything else stops the server. */
+    const positiveInt = (name) => {
+        const raw = process.env[name]?.trim();
+        if (!raw)
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < 1) {
+            console.error(`[A2A] ✗ ${name} must be a positive integer (got "${raw}").`);
             process.exit(1);
         }
-        console.log('[A2A] ⚠ WARNING: A2A_SERVER_SECRET is not configured. Server-level authentication is disabled (local dev only).');
-    }
-    else {
-        const expected = Buffer.from(serverSecret);
-        app.use((req, res, next) => {
-            const authHeader = req.headers.authorization;
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-                res.status(401).json({ error: 'Unauthorized: Missing or invalid Authorization Bearer token' });
-                return;
-            }
-            const token = Buffer.from(authHeader.substring(7));
-            // Constant-time comparison to avoid leaking the secret via response timing.
-            if (token.length !== expected.length || !timingSafeEqual(token, expected)) {
-                res.status(401).json({ error: 'Unauthorized: Invalid Authorization Bearer token' });
-                return;
-            }
-            next();
-        });
+        return n;
+    };
+    const servedAgents = list('A2A_SERVED_AGENTS');
+    const registryAgents = list('A2A_REGISTRY_AGENTS');
+    // Storage: Postgres when DATABASE_URL is set (every durable store, safe
+    // across instances); otherwise createA2AApp's default (Supabase, else memory).
+    const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;
+    const pgStorage = databaseUrl
+        ? postgresStorage({
+            connectionString: databaseUrl,
+            schema: dbSchema(),
+            ...(positiveInt('DATABASE_POOL_MAX') ? { poolConfig: { max: positiveInt('DATABASE_POOL_MAX') } } : {}),
+            ...(positiveInt('A2A_TURN_LOCK_POOL_MAX') ? { lockPoolMax: positiveInt('A2A_TURN_LOCK_POOL_MAX') } : {}),
+            memory: { apiKey: process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY || '' },
+        })
+        : undefined;
+    if (!pgStorage && dbSchema() !== 'public') {
+        console.error(`[A2A] ✗ MELCHIZEDEK_DB_SCHEMA=${dbSchema()} needs DATABASE_URL: a private schema is not reachable over the Supabase REST API.`);
+        process.exit(1);
     }
-    app.use(express.json());
-    // Security: BYOK Middleware
-    // NOTE ON SCOPE: the X-API-Key only funds LLM *inference* (Gemini/Claude).
-    // Tool calls (e.g. generate_image, google_search) use the server's own
-    // keys from the environment, so they bill the operator, not the caller. This
-    // check verifies the header is present, not that the key is valid — validity
-    // is enforced upstream by the provider. The bearer token above is the real
-    // gate; keep it set in any shared/public deployment.
-    app.use((req, res, next) => {
-        const apiKey = req.headers['x-api-key'];
-        const provider = req.headers['x-provider'] || 'google';
-        const rawUserId = req.headers['x-user-id'];
-        if (!apiKey) {
-            res.status(401).json({ error: 'Unauthorized: Missing X-API-Key header' });
-            return;
-        }
-        // X-User-Id (optional): the caller's own identifier for the END USER
-        // behind this request (e.g. a site's authenticated account id). It
-        // silos sessions AND long-term memory per user beneath the caller's
-        // API-key hash. Callers are responsible for authenticating their users
-        // BEFORE putting an id in this header — the server trusts it within
-        // the caller's own silo and it can never cross into another caller's.
-        let siteUserId;
-        if (rawUserId !== undefined && rawUserId !== '') {
-            if (!SITE_USER_ID_PATTERN.test(rawUserId)) {
-                res.status(400).json({ error: 'Invalid X-User-Id: must match [A-Za-z0-9._-]{1,64}' });
-                return;
-            }
-            siteUserId = rawUserId;
-        }
-        // X-Surface-* (optional): where this request came from, for telemetry
-        // only. Same validation as X-User-Id, and a bad value is refused rather
-        // than dropped — a silently ignored header makes a dashboard lie about
-        // coverage. `X-Surface` is required for the others to mean anything.
-        let surface;
-        for (const [header, field] of SURFACE_HEADERS) {
-            const raw = req.headers[header];
-            if (raw === undefined || raw === '')
-                continue;
-            if (!SURFACE_VALUE_PATTERN.test(raw)) {
-                res.status(400).json({ error: `Invalid ${header}: must match [A-Za-z0-9._-]{1,64}` });
-                return;
-            }
-            if (field === 'name') {
-                surface = { name: raw };
-                continue;
-            }
-            if (!surface) {
-                res.status(400).json({ error: `${header} requires X-Surface to name the surface` });
-                return;
-            }
-            surface[field] = raw;
-        }
-        requestContextStorage.run({ apiKey, provider, siteUserId, surface }, () => {
-            next();
-        });
-    });
-    // Security: Rate Limiting
-    // Applied globally (not just to /a2a) so the per-agent dynamic routes
-    // (/:agentId/a2a/...) can't be used to bypass the cap. GET requests are
-    // exempted because task-status polling issues many GETs per task and is
-    // cheap; the limit targets the expensive POST task submissions.
-    // NOTE: the bearer-auth middleware above runs BEFORE this limiter, so only
-    // AUTHENTICATED callers ever reach it — its role is runaway/cost protection
-    // (a buggy client loop burning Gemini quota), not anonymous-abuse defense.
-    // Sized for the nihilistic-penguin daily advisory pipeline (~34 task
-    // submissions in one burst: 30 council + news + macro + architect + critic)
-    // plus concurrent interactive Discord use; the old 20/hour cap forced that
-    // pipeline into multi-window backoff crawls. GETs (task polling) stay exempt.
-    const limiter = rateLimit({
-        windowMs: 15 * 60 * 1000, // 15 minutes
-        max: 60, // 60 task submissions per 15 min per IP (~240/h runaway ceiling)
-        standardHeaders: true,
-        legacyHeaders: false,
-        skip: (req) => req.method === 'GET',
-        message: { error: 'Too many requests, please try again later.' }
-    });
-    app.use(limiter);
-    // ── Right-to-erasure: DELETE /memory ─────────────────────────────────────
-    // Permanently removes every long-term fact in the CALLING silo — the
-    // API-key hash plus X-User-Id, exactly as deriveUserId computes it for
-    // storage. A site deletes one of its users by passing that user's id in
-    // X-User-Id; it cannot name an arbitrary silo, so it can only erase what
-    // it could write. Sessions (adk_sessions) are a separate store — see
-    // lib/memory/README.md.
-    app.delete('/memory', async (_req, res) => {
-        if (!memoryService) {
-            res.status(404).json({ error: 'Long-term memory is not enabled on this server.' });
-            return;
-        }
-        const ctx = requestContextStorage.getStore();
-        if (!ctx) {
-            res.status(401).json({ error: 'No authentication context.' });
-            return;
-        }
-        const userKey = `${A2A_APP_NAME}/${deriveUserId(ctx)}`;
+    // The task tools keep each caller's list in Postgres, not the shared file.
+    if (pgStorage)
+        setTaskBackend(pgStorage.taskQueue);
+    // ── Limits in Redis (ADR 0021 item 5): one window across replicas ────────
+    // `redis` is an optional peer dependency: installed only by deployments
+    // that set A2A_REDIS_URL.
+    let limitStore;
+    const redisUrl = process.env.A2A_REDIS_URL?.trim();
+    if (redisUrl) {
+        let createClient;
         try {
-            const deleted = await memoryService.deleteUserMemory(userKey);
-            console.log(`[A2A] Memory erasure: ${deleted} fact(s) removed for silo ${userKey}`);
-            res.json({ deleted });
+            ({ createClient } = (await import(__rewriteRelativeImportExtension('redis'))));
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`[A2A] Memory erasure failed: ${msg}`);
-            res.status(500).json({ error: 'Memory deletion failed. See server logs.' });
+        catch {
+            console.error('[A2A] ✗ A2A_REDIS_URL is set but the `redis` package is not installed: npm install redis');
+            process.exit(1);
         }
-    });
-    const requestHandler = new DefaultRequestHandler(agentCard, new InMemoryTaskStore(), new SyndicateExecutor(config, sessionService, wantsLongTermMemory ? memoryService : undefined));
-    // Setup Static/Default Routing Interfaces (Backward Compatibility)
-    app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: requestHandler }));
-    app.use('/a2a/jsonrpc', jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
-    app.use('/a2a/rest', restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
-    // Dynamic Multi-Agent Routing Cache
-    const handlerCache = new Map();
-    // Security: agent IDs address a syndicate config (file, or "registry:<id>").
-    // Restrict to a safe charset so a crafted path segment cannot drive path
-    // traversal through loadSyndicate() or the filesystem fallbacks below.
-    function isValidAgentId(agentId) {
-        return /^[A-Za-z0-9_.:-]+$/.test(agentId) && !agentId.includes('..');
+        const client = createClient({ url: redisUrl });
+        client.on?.('error', (err) => console.warn(`[A2A] ⚠ Redis: ${err.message}`));
+        await client.connect();
+        limitStore = (limiter) => redisRateLimitStore({ command: (args) => client.sendCommand(args), prefix: `melchizedek:rl:${limiter}:` });
     }
-    async function getOrCreateHandlers(agentId) {
-        if (!isValidAgentId(agentId)) {
-            throw new Error(`Invalid agent id: '${agentId}'`);
-        }
-        let cached = handlerCache.get(agentId);
-        if (cached)
-            return cached;
-        let targetConfig;
-        // Fresh per-load bindings: the static routes get these via startServer's
-        // serverBindings; without them here, dynamic agents would interpolate
-        // {{current_date}} from stale YAML defaults (or leave it unresolved).
-        const routeBindings = {
-            current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
-        };
-        // Where the config came from is load-bearing operational information: a
-        // bare agent id prefers the REGISTRY and only falls back to the repo file
-        // when that lookup fails, so an id with a registry row ignores repo edits
-        // until `scripts/deploy_agent.ts` re-publishes it. On 2026-08-15 two
-        // rounds of routing fixes were pushed, deployed and restarted while
-        // production kept serving a registry copy from a week earlier, and
-        // nothing in the logs said so. Now it does.
-        let configSource = '';
+    // ── Policy: daily budgets (ADR 0026) ──────────────────────────────────────
+    let policy;
+    let budgetLabel = '';
+    const budgetsJson = process.env.A2A_BUDGETS?.trim();
+    if (budgetsJson) {
         try {
-            if (agentId.startsWith('registry:')) {
-                const registryId = agentId.replace('registry:', '');
-                const { loadSyndicateFromRegistry } = await import("../lib/loadSyndicate.js");
-                targetConfig = await loadSyndicateFromRegistry(registryId, { bindings: routeBindings });
-                configSource = `registry:${registryId}`;
+            const config = parseBudgets(budgetsJson);
+            let store;
+            if (pgStorage) {
+                store = postgresUsageStore(pgStorage.pool);
+                budgetLabel = 'postgres';
+            }
+            else if (hasSupabaseCredentials()) {
+                const { createClient } = await import('@supabase/supabase-js');
+                store = supabaseUsageStore(createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_ROLE_KEY));
+                budgetLabel = 'supabase';
             }
             else {
-                try {
-                    const { loadSyndicateFromRegistry } = await import("../lib/loadSyndicate.js");
-                    targetConfig = await loadSyndicateFromRegistry(agentId, { bindings: routeBindings });
-                    configSource = `registry:${agentId} (repo file NOT served — deploy_agent.ts publishes edits)`;
-                }
-                catch {
-                    if (agentId.endsWith('.yaml')) {
-                        targetConfig = loadSyndicate(agentId, { bindings: routeBindings });
-                        configSource = `file:${agentId}`;
-                    }
-                    else {
-                        try {
-                            targetConfig = loadSyndicate(`config/agents/${agentId}.yaml`, { bindings: routeBindings });
-                            configSource = `file:config/agents/${agentId}.yaml`;
-                        }
-                        catch {
-                            targetConfig = loadSyndicate(`${agentId}.yaml`, { bindings: routeBindings });
-                            configSource = `file:${agentId}.yaml`;
-                        }
-                    }
-                }
+                store = memoryUsageStore();
+                budgetLabel = 'process memory: per instance, reset on restart';
             }
-        }
-        catch (error) {
-            throw new Error(`Failed to load syndicate config for '${agentId}': ${error.message}`);
-        }
-        console.log(`[A2A] ⚙ Loaded '${agentId}' from ${configSource}`);
-        const card = compileAgentCard(targetConfig);
-        const handler = new DefaultRequestHandler(card, new InMemoryTaskStore(), new SyndicateExecutor(targetConfig, sessionService, targetConfig.memory_system === 'long-term' ? memoryService : undefined));
-        cached = {
-            agentCard: agentCardHandler({ agentCardProvider: handler }),
-            jsonRpc: jsonRpcHandler({ requestHandler: handler, userBuilder: UserBuilder.noAuthentication }),
-            rest: restHandler({ requestHandler: handler, userBuilder: UserBuilder.noAuthentication })
-        };
-        handlerCache.set(agentId, cached);
-        return cached;
-    }
-    // Dynamic Route Registration (Exposes /:agentId/a2a/...)
-    app.use('/:agentId/.well-known/agent-card.json', async (req, res, next) => {
-        console.log(`[A2A Server] GET /${req.params.agentId}/.well-known/agent-card.json`);
-        try {
-            const handlers = await getOrCreateHandlers(req.params.agentId);
-            handlers.agentCard(req, res, next);
-        }
-        catch (err) {
-            res.status(404).json({ error: err.message });
-        }
-    });
-    app.use('/:agentId/agent-card.json', async (req, res, next) => {
-        console.log(`[A2A Server] GET /${req.params.agentId}/agent-card.json`);
-        try {
-            const handlers = await getOrCreateHandlers(req.params.agentId);
-            handlers.agentCard(req, res, next);
+            policy = budgets(config, { store });
+            budgetLabel = `${Object.keys(config).join(', ')} (counted in ${budgetLabel})`;
         }
         catch (err) {
-            res.status(404).json({ error: err.message });
-        }
-    });
-    app.use('/:agentId/a2a/jsonrpc', async (req, res, next) => {
-        console.log(`[A2A Server] POST /${req.params.agentId}/a2a/jsonrpc`);
-        try {
-            const handlers = await getOrCreateHandlers(req.params.agentId);
-            handlers.jsonRpc(req, res, next);
-        }
-        catch (err) {
-            res.status(404).json({ error: err.message });
-        }
-    });
-    app.use('/:agentId/a2a/rest', async (req, res, next) => {
-        // Only log task submissions (POST), not the repeated GET polling requests
-        if (req.method !== 'GET') {
-            console.log(`[A2A] ${req.method} /${req.params.agentId}/a2a/rest`);
-        }
-        try {
-            const handlers = await getOrCreateHandlers(req.params.agentId);
-            handlers.rest(req, res, next);
-        }
-        catch (err) {
-            res.status(404).json({ error: err.message });
+            fatal(err instanceof Error ? err.message : String(err));
         }
+    }
+    const metricsToken = process.env.A2A_METRICS_TOKEN?.trim() || undefined;
+    if (metricsToken && (isPlaceholderValue(metricsToken) || metricsToken.length < 24)) {
+        fatal('A2A_METRICS_TOKEN must be a long random value (openssl rand -hex 32).');
+    }
+    let built;
+    try {
+        built = await createA2AApp({
+            defaultSyndicate: syndicateName,
+            publicUrl,
+            port,
+            serverSecret: bearerGate ? secret : undefined,
+            ...(authenticator ?? {}),
+            requireHardenedDb: !!publicUrl && process.env.ALLOW_UNHARDENED_DB !== 'true',
+            taskTimeoutMs: envInt('A2A_TASK_TIMEOUT_MS', 15 * 60 * 1000),
+            streamText: process.env.A2A_STREAM_TEXT?.trim().toLowerCase() === 'true',
+            allowSchemaMismatch: process.env.ALLOW_SCHEMA_MISMATCH?.trim().toLowerCase() === 'true',
+            turnLockWaitMs: envInt('A2A_TURN_LOCK_WAIT_MS', 30_000),
+            maxConcurrentTasks: envInt('A2A_MAX_CONCURRENT_TASKS', 0),
+            rateLimit: { windowMs: envInt('A2A_RATE_LIMIT_WINDOW_MS', 15 * 60 * 1000), max: envInt('A2A_RATE_LIMIT_MAX', 60) },
+            authFailureLimit: { windowMs: 15 * 60 * 1000, max: envInt('A2A_AUTH_FAILURE_MAX', 30) },
+            trustProxy: envTrustProxy(),
+            ...(limitStore ? { limitStore } : {}),
+            bodyLimit: process.env.A2A_BODY_LIMIT?.trim() || '1mb',
+            servedAgents,
+            registryAgents,
+            keyMode,
+            ...(pgStorage ? { storage: pgStorage } : {}),
+            ...(policy ? { policy } : {}),
+            metricsToken,
+            log: (m) => emit('info', `[A2A] ${m}`),
+            warn: (m) => emit('warn', `[A2A] ⚠ ${m}`),
+            ...(jsonLogs() ? { onTaskEnd: (r) => emit('info', `task ${r.status}`, { event: 'task', ...r }) } : {}),
+            ...extensions.options,
+            routes: (app) => {
+                extensions.routes?.(app);
+                extensions.options?.routes?.(app);
+            },
+        });
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            throw err;
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    const authMode = `${identityLabel || (secret ? 'bearer secret' : 'no secret (loopback only)')}; keys: ${keyMode === 'byok' ? "caller's X-API-Key (byok)" : "server's own"}`;
+    // The secret is not needed past this point; drop the reference.
+    secret = undefined;
+    const { app, config, sessionBackend, shutdown } = built;
+    const server = await new Promise((resolve) => {
+        const s = host ? app.listen(port, host, () => resolve(s)) : app.listen(port, () => resolve(s));
     });
-    const PORT = process.env.PORT || 4000;
-    app.listen(PORT, () => {
-        console.log(`[A2A] Exposer server boot complete on port ${PORT}`);
+    // Load balancers commonly hold idle connections for 60 s; Node's default
+    // keep-alive of 5 s makes them reuse a socket Node has just closed (502s).
+    server.keepAliveTimeout = envInt('A2A_KEEP_ALIVE_TIMEOUT_MS', 65_000);
+    server.headersTimeout = server.keepAliveTimeout + 1_000;
+    const base = publicUrl ?? `http://${host && host !== '0.0.0.0' ? host : 'localhost'}:${port}`;
+    emit('info', `[A2A] ✓ Serving '${config.syndicate_name}' on ${host ?? '0.0.0.0'}:${port}`);
+    emit('info', `[A2A]   card     ${base}/.well-known/agent-card.json`);
+    emit('info', `[A2A]   jsonrpc  ${base}/a2a/jsonrpc   rest ${base}/a2a/rest`);
+    emit('info', `[A2A]   auth     ${authMode}`);
+    emit('info', `[A2A]   storage  ${pgStorage ? 'postgres (multi-instance safe)' : sessionBackend === 'durable' ? 'supabase (tasks are per process: one replica)' : 'in-memory (lost on restart; one replica)'}`);
+    emit('info', `[A2A]   agents   ${servedAgents ? servedAgents.join(', ') : 'the default, plus any file in the agents directory at /:agentId/ (A2A_SERVED_AGENTS restricts)'}`);
+    if (registryAgents)
+        emit('info', `[A2A]   registry ${registryAgents.join(', ')} (bare ids loaded from adk_agent_registry)`);
+    if (keyMode === 'server' && sessionBackend === 'durable' && authKind === 'secret') {
+        emit('warn', '[A2A] ⚠ Key mode is "server": sessions and memory are scoped by X-User-Id (else "default").');
+        emit('warn', '[A2A]   Data written by earlier versions lives under key-hash silos (a2a-<hash>/…) that');
+        emit('warn', '[A2A]   only A2A_KEY_MODE=byok reaches. Keep byok until that data is migrated.');
+    }
+    if (budgetLabel)
+        emit('info', `[A2A]   budgets  ${budgetLabel}`);
+    if (metricsToken)
+        emit('info', `[A2A]   metrics  ${base}/metrics (bearer A2A_METRICS_TOKEN)`);
+    emit('info', `[A2A]   health   ${base}/healthz  ${base}/readyz`);
+    // ── Lifecycle ──────────────────────────────────────────────────────────────
+    let stopping = false;
+    const graceMs = envInt('A2A_SHUTDOWN_GRACE_MS', 25_000);
+    const stop = async (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        emit('info', `[A2A] ${signal}: draining — no new tasks; waiting up to ${graceMs} ms for running ones.`);
+        server.close();
+        const canceled = await shutdown(graceMs);
+        if (canceled > 0)
+            emit('warn', `[A2A] ⚠ ${canceled} task(s) did not finish in time and were canceled.`);
+        // Give canceled tasks a moment to publish their final status, then flush
+        // telemetry so the last turns reach the ledger, then release the pool.
+        await new Promise((r) => setTimeout(r, canceled > 0 ? 500 : 0));
+        await flushTracing().catch(() => { });
+        await pgStorage?.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void stop('SIGTERM'));
+    process.on('SIGINT', () => void stop('SIGINT'));
+    process.on('unhandledRejection', (reason) => {
+        emit('error', `[A2A] ⚠ Unhandled rejection: ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`);
     });
+    return server;
 }
-// Run-as-main guard. Compare against the REALPATH of argv[1]: when invoked
-// through the npm bin (`npx melchizedek-serve`), argv[1] is the .bin symlink
-// while import.meta.url is the resolved file — a naive string compare never
-// matches and the server silently does nothing (the 0.9.0 bin bug).
+// Run-as-main guard. Compare against the REALPATH of argv[1]: through the
+// npm bin, argv[1] is the .bin symlink while import.meta.url is the resolved
+// file, so a naive compare never matches (the 0.9.0 bin bug).
 const invokedAsMain = (() => {
     if (!process.argv[1])
         return false;
@@ -1064,13 +401,53 @@ const invokedAsMain = (() => {
     }
 })();
 if (invokedAsMain) {
-    const syndicateFile = process.argv[2] || 'syndicate.yaml';
-    startServer(syndicateFile).catch((error) => {
-        if (error?.code === 'ENOENT' && !process.argv[2]) {
-            // Package consumers rarely have a syndicate.yaml — name the fix.
-            console.error('[A2A] No default syndicate.yaml in your agents directory.\n' +
-                '      Pass your syndicate: melchizedek-serve <name>.yaml\n' +
-                '      (agents directory: option --, MELCHIZEDEK_AGENTS_DIR, or <cwd>/config/agents)');
+    const arg = process.argv[2];
+    if (arg === '--help' || arg === '-h') {
+        console.log([
+            'Usage: melchizedek-serve [<syndicate>.yaml | registry:<id>]',
+            '       melchizedek-serve --new-caller <name> [--scope <scope>] [--token-file <path>]',
+            '',
+            'Serves a syndicate over A2A. Environment variables are listed at the top of',
+            'scripts/a2a_server.ts and in .env.example.',
+            '',
+            '--new-caller mints a bearer token for one calling backend (A2A_AUTH=callers)',
+            'and prints the A2A_CALLERS entry, which holds only the token\'s SHA-256.',
+            '--scope keeps the caller on an existing scope (e.g. its a2a-<hash> silo).',
+            '--token-file writes the token to a new file (mode 600) instead of printing it.',
+        ].join('\n'));
+        process.exit(0);
+    }
+    if (arg === '--new-caller') {
+        const flag = (name) => {
+            const i = process.argv.indexOf(name);
+            return i > 0 ? process.argv[i + 1] : undefined;
+        };
+        const name = process.argv[3];
+        const scope = flag('--scope');
+        const tokenFile = flag('--token-file');
+        const token = randomBytes(32).toString('base64url');
+        const entry = `${name}:${hashCallerToken(token)}${scope ? `:${scope}` : ''}`;
+        try {
+            parseCallers(entry);
+        }
+        catch (err) {
+            fatal(err instanceof Error ? err.message : String(err));
+        }
+        if (tokenFile) {
+            writeFileSync(tokenFile, `${token}\n`, { mode: 0o600, flag: 'wx' });
+            console.log(`Token for '${name}' written to ${tokenFile} (mode 600). Hand it to the caller, then delete the file.`);
+        }
+        else {
+            console.log(`Token for '${name}' — give it to the caller as its bearer token. It is shown once and never stored:\n  ${token}`);
+        }
+        console.log(`\nAdd this entry to A2A_CALLERS (entries separated by ';'):\n  ${entry}`);
+        process.exit(0);
+    }
+    startServer(arg || 'syndicate.yaml').catch((error) => {
+        if (error?.code === 'ENOENT') {
+            console.error(`[A2A] Syndicate not found: ${arg || 'syndicate.yaml'}.\n`
+                + '      Pass your syndicate: melchizedek-serve <name>.yaml\n'
+                + '      (agents directory: MELCHIZEDEK_AGENTS_DIR, or <cwd>/config/agents)');
             process.exit(1);
         }
         console.error(error);