@mcp-abap-adt/llm-agent-server 16.2.0 → 18.0.0

package/dist/smart-agent/smart-server.js

@@ -4,10 +4,12 @@
 import { randomUUID } from 'node:crypto';
 import http from 'node:http';
 import { AdapterValidationError, normalizeAndValidateExternalTools, QueryEmbedding, toToolCallDelta, } from '@mcp-abap-adt/llm-agent';
-import { ClaudeSkillManager, CodexSkillManager, ConfigWatcher, DefaultSubAgentContextBuilder, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, makeLlm, SessionLogger, SmartAgentBuilder, SmartAgentSubAgent, } from '@mcp-abap-adt/llm-agent-libs';
+import { ClaudeSkillManager, CodexSkillManager, ConfigWatcher, DefaultSubAgentContextBuilder, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, makeLlm, SessionGraphFactory, SessionLogger, SessionRegistry, SmartAgentBuilder, SmartAgentSubAgent, SubAgentStateOracle, } from '@mcp-abap-adt/llm-agent-libs';
+import { MCPClientWrapper, McpClientAdapter, } from '@mcp-abap-adt/llm-agent-mcp';
 import { makeRag } from '@mcp-abap-adt/llm-agent-rag';
 import { PACKAGE_VERSION } from '../generated/version.js';
 import { resolveAgentEmbedder, resolveToolsStoreEmbedder, } from './resolve-agent-embedder.js';
+import { resolveSessionIdentity } from './session-identity-resolver.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -65,11 +67,438 @@ const CORS_HEADERS = {
 // ---------------------------------------------------------------------------
 // SmartServer
 // ---------------------------------------------------------------------------
-import { resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorPlanning, resolveToolSelectionStrategy, } from './config.js';
+import { buildDagCoordinatorDeps } from './build-dag-coordinator-deps.js';
+import { buildStepperRoot } from './build-stepper-root.js';
+import { assertCoordinatorConfigShape, normalizeLlmConfig, parseStepperCoordinatorConfig, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorDispatchKind, resolveCoordinatorPlanning, resolveLlmConfig, resolveLlmConfigStrict, resolveToolSelectionStrategy, } from './config.js';
+import { JsonlKnowledgeBackend } from './jsonl-knowledge-backend.js';
+import { InMemorySessionMetaStore } from './session-meta-store.js';
+import { StepperCoordinatorHandler } from './stepper-coordinator-handler.js';
 export { generateConfigTemplate, loadYamlConfig, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorPlanning, resolveEnvVars, resolveSmartServerConfig, resolveToolSelectionStrategy, YAML_TEMPLATE, } from './config.js';
+/**
+ * Drain every cached worker's `close` (if any), then clear the cache map.
+ * Used by config-reload (PUT /v1/config + hot-reload — Fix #14/18/21) and by
+ * server `close()` to release per-worker MCP connections that were attached
+ * to the discarded `SmartAgentHandle`s.
+ *
+ * IMPORTANT — in-flight caveat: this aborts any request that is mid-call on
+ * a worker's MCP client. That is acceptable for an admin action (config
+ * reload, server shutdown) where the alternative is leaking connections.
+ * Server `close()` calls this AFTER `lifecycle.disposeAll()` so per-session
+ * graphs that reference worker clients are torn down first.
+ *
+ * Uses `Promise.allSettled` so one failing close cannot block the others.
+ */
+export async function drainWorkerCache(cache) {
+    const closers = [];
+    for (const entry of cache.values()) {
+        if (entry.close) {
+            try {
+                closers.push(entry.close());
+            }
+            catch {
+                // sync throw (defensive — close is async by contract)
+            }
+        }
+    }
+    cache.clear();
+    if (closers.length > 0) {
+        await Promise.allSettled(closers);
+    }
+}
+/**
+ * Build-once-per-worker resolver. The first time a worker name is seen, it
+ * constructs the worker's main/classifier/(optional helper) LLM + embedder and
+ * caches the set; every later call (e.g. each per-session worker re-wire)
+ * returns the SAME set by reference — never reconstructing LLM clients
+ * (locked invariant: LLM/embedder clients are global, built once).
+ *
+ * Accepts optional `makeToolsRag`/`makeHistoryRag`/`makeMcpClients` factories;
+ * when provided, the resolver builds them ONCE on the first miss and caches
+ * them on the returned set. Subsequent calls return the cached resources by
+ * reference — never re-vectorizing or re-connecting MCP.
+ */
+export async function resolveWorkerLlmSet(input) {
+    const hit = input.cache.get(input.name);
+    if (hit)
+        return hit;
+    const mainLlm = await input.makeMain();
+    const classifierLlm = await input.makeClassifier();
+    const helperLlm = input.makeHelper ? await input.makeHelper() : undefined;
+    const embedder = input.makeEmbedder ? await input.makeEmbedder() : undefined;
+    const toolsRag = input.makeToolsRag ? await input.makeToolsRag() : undefined;
+    const historyRag = input.makeHistoryRag
+        ? await input.makeHistoryRag()
+        : undefined;
+    const mcpClients = input.makeMcpClients
+        ? await input.makeMcpClients()
+        : undefined;
+    const set = {
+        mainLlm,
+        classifierLlm,
+        helperLlm,
+        embedder,
+        toolsRag,
+        historyRag,
+        mcpClients,
+    };
+    input.cache.set(input.name, set);
+    return set;
+}
+/**
+ * Backfill the per-worker cache entry from the BUILT handle (review HIGH #7).
+ *
+ * The primary `buildSubAgent` populates `cached.mcpClients`/`toolsRag`/
+ * `historyRag` only when the worker config provided DI factories. Workers
+ * configured with `subCfg.mcp: ...` (regular config that triggers the
+ * builder's own auto-connect) or with `subCfg.rag: ...` whose RAG is owned
+ * by the builder leave those slots empty — so per-session re-wires would
+ * fall back to the PARENT's MCP/RAG, losing the worker's own connection.
+ *
+ * After the builder finishes, this helper captures what the handle actually
+ * holds and stores it BY REFERENCE on the cache entry. Subsequent per-session
+ * re-wires read the same slots and find the worker's own resources.
+ *
+ * Pure helper, mutates `entry` in place. No-op when the corresponding slot
+ * is already populated (DI path wins) or when the handle has no resource for
+ * that slot (worker simply didn't declare one).
+ */
+export async function backfillWorkerCacheFromHandle(entry, handle) {
+    if ((!entry.mcpClients || entry.mcpClients.length === 0) &&
+        handle.mcpClients &&
+        handle.mcpClients.length > 0) {
+        entry.mcpClients = handle.mcpClients;
+    }
+    if (!entry.toolsRag) {
+        const t = handle.ragRegistry.get('tools');
+        if (t)
+            entry.toolsRag = t;
+    }
+    if (!entry.historyRag) {
+        const h = handle.ragRegistry.get('history');
+        if (h)
+            entry.historyRag = h;
+    }
+    // Capture the per-worker shutdown function (Fix #21). If the entry already
+    // had a close from a previous build (e.g. the same worker name was rebuilt
+    // WITHOUT going through `drainWorkerCache` first — defence in depth), await
+    // the prior close before overwriting so its MCP connections do not leak.
+    if (handle.close) {
+        if (entry.close) {
+            try {
+                await entry.close();
+            }
+            catch {
+                // Best-effort; never block the new build on a stale close failure.
+            }
+        }
+        entry.close = handle.close;
+    }
+}
+/**
+ * Share the parent RAG registry with subagents (per-session worker re-wire).
+ * Session/user/global collections written at the top level become visible to
+ * workers; the per-call scope filter (`rag-query.ts`) isolates by
+ * `ctx.sessionId` / `ctx.options.userId`. A worker's own declared store is
+ * registered INTO this same registry under its namespace. When the parent
+ * registry is undefined (no top-level registry yet — e.g. unit test seam),
+ * return undefined so the builder allocates its own SimpleRagRegistry.
+ */
+export function resolveSubAgentRagRegistry(input) {
+    return input.parentRagRegistry;
+}
+/**
+ * Composes the cookie identity resolver + SessionGraphFactory + SessionRegistry
+ * into one lifecycle object the server's `_handle` consumes. The default MCP
+ * factory returns the shared GLOBAL clients by reference (one upstream
+ * connection); a creds-aware build swaps it out (out of scope here).
+ */
+export function buildSessionLifecycle(opts) {
+    const factory = new SessionGraphFactory({
+        mcpClientFactory: (_identity) => opts.mcpClients,
+        toolsRag: opts.toolsRag,
+        ragRegistry: opts.ragRegistry,
+        buildAgent: opts.buildAgent,
+        logger: opts.logger,
+    });
+    const registry = new SessionRegistry({
+        idleTtlMs: opts.idleTtlMs,
+        maxSessions: opts.maxSessions,
+        factory,
+    });
+    return {
+        resolve: (cookieHeader, isHttps) => resolveSessionIdentity({
+            cookieHeader,
+            cookieName: opts.cookieName,
+            maxAgeSeconds: Math.max(1, Math.floor(opts.idleTtlMs / 1000)),
+            isHttps,
+        }),
+        acquire: (sessionId) => registry.acquire(sessionId),
+        release: (sessionId, graph) => registry.release(sessionId, graph),
+        evictIdle: () => registry.evictIdle(),
+        disposeAll: () => registry.disposeAll(),
+        invalidateAll: () => registry.invalidateAll(),
+        registry,
+    };
+}
+/**
+ * Seed session-scope guidance entries into a BRAND-NEW session's knowledge-RAG
+ * (deployment-supplied tool-usage guidance the planner/executor read in "Known
+ * facts"). Idempotent: rehydrates via init() and writes ONLY when the session is
+ * empty (`fingerprint() === 'n=0'`), so resumes never duplicate. Entries are
+ * config DATA — the runtime stays MCP-agnostic (no tool knowledge in agent code).
+ */
+export async function seedSessionKnowledge(kr, seeds, nowIso) {
+    if (seeds.length === 0)
+        return;
+    await kr.init?.();
+    if (kr.fingerprint?.() !== 'n=0')
+        return; // not a brand-new session → skip
+    for (const s of seeds) {
+        await kr.write({
+            content: s.content,
+            metadata: {
+                traceId: 'seed',
+                turnId: 'seed',
+                stepperId: 'seed',
+                task: 'session-seed',
+                artifactType: s.artifactType,
+                createdAt: nowIso,
+            },
+        });
+    }
+}
+/**
+ * Record that a request for `sessionId` STARTED — create the meta row on first
+ * sight, else touch it and mark in-progress. Called from the live request path
+ * (`_withSession`) so GET /v1/sessions, resume and delete actually see sessions
+ * produced by normal chat/stream traffic (review Finding 3). `userIdentity` is
+ * the sessionId itself in the default no-auth build — matching how the
+ * /v1/sessions endpoints resolve identity (`resolved.identity.sessionId`).
+ */
+export async function recordSessionStart(store, sessionId, nowIso) {
+    const existing = await store.get(sessionId);
+    if (!existing) {
+        await store.create({
+            sessionId,
+            userIdentity: sessionId,
+            createdAt: nowIso,
+            lastUsedAt: nowIso,
+            status: 'in-progress',
+        });
+        return;
+    }
+    await store.touch(sessionId, nowIso);
+    await store.setStatus(sessionId, 'in-progress');
+}
+/**
+ * Record that a request for `sessionId` FINISHED — touch + mark idle (so it can
+ * be resumed). No-op if the row was deleted mid-flight.
+ */
+export async function recordSessionEnd(store, sessionId, nowIso) {
+    const existing = await store.get(sessionId);
+    if (!existing)
+        return;
+    await store.touch(sessionId, nowIso);
+    await store.setStatus(sessionId, 'idle');
+}
+/**
+ * List all sessions for a given user identity.
+ * Extracted for unit-testability (mirrors the /v1/usage handler pattern).
+ */
+export async function handleListSessions(store, identity) {
+    const sessions = await store.listForUser(identity);
+    return { sessions };
+}
+/**
+ * Resume (claim) a session by ID for a user identity.
+ * Sets the session status to 'idle' so it can be re-entered.
+ */
+export async function handleResumeSession(store, identity, id) {
+    const row = await store.get(id);
+    if (!row || row.userIdentity !== identity) {
+        return { ok: false, error: 'session not found' };
+    }
+    await store.setStatus(id, 'idle');
+    const updated = await store.get(id);
+    return { ok: true, session: updated };
+}
+/**
+ * Delete a session by ID for a user identity, and evict its RAG state.
+ */
+export async function handleDeleteSession(store, identity, id, evictFn) {
+    const row = await store.get(id);
+    if (!row || row.userIdentity !== identity) {
+        return { ok: false, error: 'session not found' };
+    }
+    await store.delete(id);
+    await evictFn(id);
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// MCP bridge for the Stepper path (B-1)
+// ---------------------------------------------------------------------------
+/**
+ * Build a `callMcp(name, args, signal?)` bridge over a list of `IMcpClient`s.
+ *
+ * Dispatch strategy (mirrors the 17.0 tool-loop):
+ * - Iterate the clients; the first client whose `listTools()` contains `name` wins.
+ * - On success: return the textual content (stringify structured payloads).
+ * - On error: return the error message as a string so the LLM executor can
+ *   feed the failure back to the model as a tool result (no throw).
+ * - If no client owns the tool: return an informative "Tool not found" string.
+ *
+ * Exported for testability — tests can call this with a fake IMcpClient list.
+ */
+/**
+ * Connect MCP clients from a YAML `mcp:` config block (single or array).
+ *
+ * Mirrors the builder's connection logic (builder.ts ~lines 897-920) so the
+ * Stepper path gets the same clients that the builder would have connected
+ * internally. Exported for testability.
+ *
+ * @param mcpCfg - single `SmartServerMcpConfig` or array thereof (from
+ *   `pipeline.mcp` or `this.cfg.mcp`). Accepts the union so callers can pass
+ *   either directly without pre-normalising.
+ */
+/** Deterministic cache key for tool args — stable regardless of key order. */
+function stableArgsKey(args) {
+    if (args === null || typeof args !== 'object')
+        return JSON.stringify(args);
+    if (Array.isArray(args))
+        return JSON.stringify(args.map((v) => v));
+    const obj = args;
+    const sorted = {};
+    for (const k of Object.keys(obj).sort())
+        sorted[k] = obj[k];
+    return JSON.stringify(sorted);
+}
+export async function connectMcpClientsFromConfig(mcpCfg) {
+    if (!mcpCfg)
+        return [];
+    const list = Array.isArray(mcpCfg) ? mcpCfg : [mcpCfg];
+    const connected = [];
+    for (const cfg of list) {
+        let wrapper;
+        if (cfg.type === 'stdio') {
+            wrapper = new MCPClientWrapper({
+                transport: 'stdio',
+                command: cfg.command,
+                args: cfg.args ?? [],
+            });
+        }
+        else {
+            wrapper = new MCPClientWrapper({
+                transport: 'auto',
+                url: cfg.url,
+                headers: cfg.headers,
+            });
+        }
+        await wrapper.connect();
+        connected.push(new McpClientAdapter(wrapper));
+    }
+    return connected;
+}
+export function buildMcpBridge(clients) {
+    return async (name, args, _signal) => {
+        const safeArgs = args != null && typeof args === 'object' && !Array.isArray(args)
+            ? args
+            : {};
+        for (const client of clients) {
+            const listed = await client.listTools();
+            if (!listed.ok)
+                continue;
+            const owns = listed.value.some((t) => t.name === name);
+            if (!owns)
+                continue;
+            const result = await client.callTool(name, safeArgs);
+            if (!result.ok) {
+                return result.error.message;
+            }
+            const { content } = result.value;
+            return typeof content === 'string' ? content : JSON.stringify(content);
+        }
+        return `Tool not found: ${name}`;
+    };
+}
+// ---------------------------------------------------------------------------
+// Raw-config mode routing gate (R6-F2)
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` ONLY when the raw coordinator config has an explicit `mode`
+ * string — the opt-in gate for the 18.0 Stepper runtime.
+ *
+ * IMPORTANT: Do NOT call `parseStepperCoordinatorConfig` to decide — that
+ * function defaults `mode` to `'planned-react'`, which would silently route
+ * every 17.0 legacy config onto the Stepper path. Gate on the RAW field
+ * presence only; parse is done INSIDE the Stepper branch after this check.
+ */
+export function usesStepper(coordCfg) {
+    if (!coordCfg)
+        return false;
+    // Explicit opt-in: `coordinator.mode` (preset alias) — a string in raw config.
+    if (typeof coordCfg.mode === 'string')
+        return true;
+    // OR an explicit `coordinator.flow` composition block (mode-less form). A flow
+    // with no mode is still a Stepper config; without this it would silently fall
+    // through to the plain smart pipeline.
+    if (typeof coordCfg.flow === 'object' && coordCfg.flow !== null)
+        return true;
+    // Legacy 17.0 configs with `coordinator.planner` but no `coordinator.mode`
+    // stay on the deprecated DagCoordinatorHandler (removed in 19.0).
+    return false;
+}
 export class SmartServer {
     cfg;
     noop = () => { };
+    /**
+     * GLOBAL per-worker LLM/embedder cache. Populated lazily by `buildSubAgent`
+     * the first time each worker name is seen; subsequent per-session re-wires
+     * pull from this cache by reference (never reconstructing LLM clients).
+     */
+    _workerLlmCache = new Map();
+    /** Lifecycle handle wired in `start()`; consumed by `_handle`. */
+    _lifecycle;
+    /** Hoisted globals used by `buildSessionAgent` to re-wire fresh per-session workers. */
+    _mainLlm;
+    _classifierLlm;
+    _helperLlm;
+    _fileLogger;
+    _mergedEmbedderFactories;
+    /**
+     * Captured DAG coordinator template — `deps` are stateless or LLM-bound and
+     * are reused across sessions; only `workers` + `stateOracle` are re-wired per
+     * session (review HIGH #1).
+     */
+    _dagCoordinatorTemplate;
+    /**
+     * 18.0 Stepper coordinator handler — stateless, session context comes through
+     * `ctx.sessionId` at execute time. Built once in `start()` when
+     * `coordinator.mode` is present in the raw config; reused across sessions.
+     */
+    _stepperCoordinatorHandler;
+    /**
+     * MCP clients connected for the Stepper path from the YAML `mcp:` config
+     * block. These are connected ONCE in `start()` (lazily resolved by
+     * `connectMcpClientsFromConfig`) and reused across every Stepper request.
+     *
+     * Populated only when `this.cfg.mcp` / `pipeline.mcp` is set AND no
+     * DI/plugin clients exist (DI precedence: `this.cfg.mcpClients` > plugin >
+     * yaml). Disposed via the server's `closeFns` on shutdown.
+     */
+    _stepperMcpClients;
+    /**
+     * The ONE shared knowledge backend for the Stepper path (set during build).
+     * Held so DELETE /v1/sessions/:id can evict a session's entries from it —
+     * critical for the long-lived in-memory backend, which would otherwise retain
+     * knowledge after a delete and rehydrate it on a same-id re-entry.
+     */
+    _stepperKnowledgeBackend;
+    /**
+     * Session meta-store for /v1/sessions endpoints (Task 17).
+     * Defaults to InMemorySessionMetaStore; a durable store can be injected via
+     * `cfg.sessionMetaStore` in a future extension.
+     */
+    _sessionMetaStore = new InMemorySessionMetaStore();
     constructor(config) {
         this.cfg = config;
     }
@@ -78,38 +507,63 @@ export class SmartServer {
         const fileLogger = {
             log: (e) => log(e),
         };
+        this._fileLogger = fileLogger;
         const pipeline = this.cfg.pipeline;
         // ---- Composition root: resolve config → interfaces --------------------
-        // LLM resolution
-        const mainTemp = Number(pipeline?.llm?.main?.temperature ?? this.cfg.llm.temperature ?? 0.7);
+        // LLM resolution — normalize flat/map cfg.llm and derive pipeline fallback.
+        const llmMap = normalizeLlmConfig(this.cfg.llm);
+        // Adapt pipeline.llm.main (uses `baseURL`) → SmartServerLlmConfig (uses
+        // `url`) so resolveLlmConfig's pipelineFallback parameter speaks one
+        // shape. Returns undefined when no pipeline.llm.main is configured.
+        const pipelineFallback = (() => {
+            const pm = pipeline?.llm?.main;
+            if (!pm)
+                return undefined;
+            return {
+                provider: pm.provider,
+                apiKey: pm.apiKey ?? '',
+                url: pm.baseURL,
+                model: pm.model,
+                temperature: pm.temperature,
+            };
+        })();
+        const topMain = resolveLlmConfig(llmMap, 'main', pipelineFallback);
+        const mainTemp = Number(pipeline?.llm?.main?.temperature ?? topMain?.temperature ?? 0.7);
         const mainLlm = pipeline?.llm?.main
             ? await makeLlm(pipeline.llm.main, mainTemp)
-            : await makeLlm({
-                // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                // rejects a missing flat-schema provider before this runs.
-                provider: this.cfg.llm.provider ?? 'deepseek',
-                apiKey: this.cfg.llm.apiKey,
-                baseURL: this.cfg.llm.url,
-                model: this.cfg.llm.model,
-            }, mainTemp);
+            : topMain
+                ? await makeLlm({
+                    provider: topMain.provider ?? 'deepseek',
+                    apiKey: topMain.apiKey,
+                    baseURL: topMain.url,
+                    model: topMain.model,
+                }, mainTemp)
+                : (() => {
+                    throw new Error('no LLM configured: provide top-level llm.main or pipeline.llm.main');
+                })();
         const classifierTemp = Number(pipeline?.llm?.classifier?.temperature ??
-            this.cfg.llm.classifierTemperature ??
+            topMain?.classifierTemperature ??
             0.1);
         const classifierLlm = pipeline?.llm?.classifier
             ? await makeLlm(pipeline.llm.classifier, classifierTemp)
             : pipeline?.llm?.main
                 ? await makeLlm(pipeline.llm.main, classifierTemp)
-                : await makeLlm({
-                    // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                    // rejects a missing flat-schema provider before this runs.
-                    provider: this.cfg.llm.provider ?? 'deepseek',
-                    apiKey: this.cfg.llm.apiKey,
-                    baseURL: this.cfg.llm.url,
-                    model: this.cfg.llm.model,
-                }, classifierTemp);
+                : topMain
+                    ? await makeLlm({
+                        provider: topMain.provider ?? 'deepseek',
+                        apiKey: topMain.apiKey,
+                        baseURL: topMain.url,
+                        model: topMain.model,
+                    }, classifierTemp)
+                    : (() => {
+                        throw new Error('no LLM configured: provide top-level llm.main or pipeline.llm.main');
+                    })();
         const helperLlm = pipeline?.llm?.helper
             ? await makeLlm(pipeline.llm.helper, Number(pipeline.llm.helper.temperature ?? 0.1))
             : undefined;
+        this._mainLlm = mainLlm;
+        this._classifierLlm = classifierLlm;
+        this._helperLlm = helperLlm;
         // ---- Plugin loader -------------------------------------------------------
         const pluginLoader = this.cfg.pluginLoader ??
             (() => {
@@ -143,6 +597,7 @@ export class SmartServer {
             ...plugins.embedderFactories,
             ...this.cfg.embedderFactories, // config takes precedence over plugins
         };
+        this._mergedEmbedderFactories = mergedEmbedderFactories;
         // Resolve the embedder ONCE so the same instance feeds both makeRag and the
         // subagent context-builder's toolSource (#137). See resolve-agent-embedder.
         let resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this.cfg.embedder, mergedEmbedderFactories);
@@ -267,8 +722,9 @@ export class SmartServer {
         // Build SubAgentRegistry from `subagents:` YAML block (if present).
         // Each sub-agent is a minimal SmartAgent reusing the parent's plugin
         // outputs (embedder factories, plugins) but with its own LLM/RAG/MCP/etc.
+        // Hoisted so the DAG branch below can reuse the same instances.
+        const registry = new Map();
         if (this.cfg.subAgentConfigs && this.cfg.subAgentConfigs.length > 0) {
-            const registry = new Map();
             for (const sub of this.cfg.subAgentConfigs) {
                 const subAgent = await this.buildSubAgent(sub.name, sub.config, fileLogger, mergedEmbedderFactories);
                 registry.set(sub.name, new SmartAgentSubAgent(sub.name, subAgent, {
@@ -285,51 +741,310 @@ export class SmartServer {
         // ---- Coordinator (autonomous plan-execute loop) ------------------------
         const coordCfg = this.cfg.coordinatorYaml;
         if (coordCfg) {
-            // Pick the planner LLM. Default 'main' → reuse mainLlm; 'planner' or
-            // 'helper' → helperLlm if present, else fall back to mainLlm.
-            const plannerLlm = coordCfg.plannerLlm === 'main' ? mainLlm : (helperLlm ?? mainLlm);
-            // For 'skill-steps' planning the default dispatch is 'hybrid' rather
-            // than 'subagent': skill-step `agent:` is optional, so steps without
-            // an explicit agent need a self-LLM fallback. Users can still pin
-            // dispatch: subagent explicitly when every step declares `agent:`.
-            const planningKind = coordCfg.planning ?? 'one-shot';
-            const dispatchKind = coordCfg.dispatch ??
-                (planningKind === 'skill-steps' ? 'hybrid' : 'subagent');
-            // Build the same kind of context builder SmartAgentBuilder uses, so
-            // YAML-configured deployments get the same default behavior. Uses the
-            // embedder resolved above — DI-injected (this.cfg.embedder) when present,
-            // otherwise constructed from `rag.embedder` (#137). Stays undefined for
-            // bare in-memory BM25 stores (no embedder), in which case toolSource is
-            // skipped and constrained subagents fall back to empty context.
-            const mainEmbedder = resolvedEmbedder;
-            const toolSource = mainEmbedder && toolsRag
-                ? async (text, k, signal) => {
-                    const embedding = new QueryEmbedding(text, mainEmbedder, {
-                        signal,
-                    });
-                    const r = await toolsRag.query(embedding, k, { signal });
-                    return r.ok ? r.value : [];
+            const rawCoordCfg = coordCfg;
+            if (usesStepper(rawCoordCfg)) {
+                // ── 18.0 Stepper path (opt-in via coordinator.mode) ──────────────────
+                // Parse only INSIDE this branch so parseStepperCoordinatorConfig's
+                // mode default ('planned-react') never fires for legacy configs (R6-F2).
+                const stepperCfg = parseStepperCoordinatorConfig(rawCoordCfg);
+                const logDir = this.cfg.logDir;
+                // KnowledgeRag factory: ONE backend instance shared across all requests.
+                // Both backends are keyed by sessionId internally, so a single instance
+                // gives correct per-session isolation AND persistence across same-cookie
+                // requests within the process. JsonlKnowledgeBackend (logDir set) adds
+                // durability across restarts; InMemoryKnowledgeBackend is the in-process
+                // default. (Previously a fresh InMemoryKnowledgeBackend was created per
+                // call, so subsequent same-session requests lost prior entries and were
+                // re-seeded — review fix.)
+                const knowledgeBackend = logDir
+                    ? new JsonlKnowledgeBackend(logDir)
+                    : new InMemoryKnowledgeBackend();
+                // Held on the instance so DELETE /v1/sessions/:id can evict a session's
+                // knowledge from THIS backend (not just remove the JSONL file).
+                this._stepperKnowledgeBackend = knowledgeBackend;
+                const knowledgeRagFor = async (sessionId) => {
+                    const kr = new KnowledgeRag(knowledgeBackend, sessionId);
+                    // Seed deployment-supplied guidance into a BRAND-NEW session only
+                    // (idempotent on resume). Config DATA — keeps the runtime MCP-agnostic.
+                    await seedSessionKnowledge(kr, stepperCfg.knowledgeSeed, new Date().toISOString());
+                    return kr;
+                };
+                // ToolsRag handle: real adapter over the server's tools RAG store + MCP
+                // catalog. Implements IToolsRagHandle for the Stepper runtime:
+                //   query(text, k) — semantic search via toolsRag+embedder when available;
+                //                     catalog-order fallback when neither is present.
+                //   lookup(name)   — returns the tool schema from the MCP catalog by name
+                //                     (populated lazily on first query()).
+                //
+                // Catalog note: when DI/plugin clients are present they are already
+                // connected. When the config carries a YAML `mcp:` block instead, the
+                // builder connects those clients INSIDE builder.build() and never
+                // exposes them here. We therefore connect the YAML mcp config ONCE and
+                // cache the result in _stepperMcpClients so every subsequent Stepper
+                // request reuses the same live connections without reconnecting.
+                //
+                // DI precedence: this.cfg.mcpClients > plugin clients > yaml mcp config.
+                // NOTE: connection is NOT safe to invoke twice on the same wrapper, so
+                // the cache guard below is critical — do NOT move this inside a
+                // per-request factory.
+                if (!mcpClients && !this._stepperMcpClients) {
+                    const yamlMcp = pipeline?.mcp ?? this.cfg.mcp;
+                    this._stepperMcpClients = await connectMcpClientsFromConfig(yamlMcp);
                 }
-                : undefined;
-            const contextBuilder = new DefaultSubAgentContextBuilder({ toolSource });
-            builder = builder.withCoordinator({
-                planning: resolveCoordinatorPlanning(planningKind, plannerLlm),
-                dispatch: resolveCoordinatorDispatch(dispatchKind, plannerLlm, contextBuilder),
-                // Default to 'explicit' — the presence of a `coordinator:` block in
-                // YAML is itself the opt-in signal. Users that want the auto-fallback
-                // semantics (no subagents and no skill steps → tool-loop) must set
-                // `activation: auto` explicitly.
-                activation: resolveCoordinatorActivation(coordCfg.activation ?? 'explicit'),
-                plannerLlm,
-                maxSteps: coordCfg.maxSteps,
-                maxRetriesPerStep: coordCfg.maxRetriesPerStep,
-                failPolicy: coordCfg.failPolicy,
-                maxLayer: coordCfg.maxLayer,
-            });
-            log({ event: 'coordinator_configured', config: coordCfg });
+                const stepperMcpClients = mcpClients ?? this._stepperMcpClients ?? [];
+                // Lazily-populated catalog: name → LlmTool.
+                let catalogCache;
+                const ensureCatalog = async () => {
+                    if (catalogCache)
+                        return catalogCache;
+                    const catalog = new Map();
+                    await Promise.allSettled(stepperMcpClients.map(async (client) => {
+                        const result = await client.listTools();
+                        if (result.ok) {
+                            for (const t of result.value) {
+                                if (!catalog.has(t.name)) {
+                                    catalog.set(t.name, t);
+                                }
+                            }
+                        }
+                    }));
+                    catalogCache = catalog;
+                    return catalog;
+                };
+                const toolsRagHandle = {
+                    async query(text, k) {
+                        const limit = k ?? 20;
+                        const catalog = await ensureCatalog();
+                        // Semantic path: requires both a vector store and an embedder.
+                        if (toolsRag && resolvedEmbedder) {
+                            const embedding = new QueryEmbedding(text, resolvedEmbedder);
+                            const ragResult = await toolsRag.query(embedding, limit);
+                            if (ragResult.ok) {
+                                const hits = [];
+                                for (const r of ragResult.value) {
+                                    const id = r.metadata.id;
+                                    if (id?.startsWith('tool:')) {
+                                        const name = id.slice(5).replace(/:.*$/, '');
+                                        const tool = catalog.get(name);
+                                        if (tool)
+                                            hits.push(tool);
+                                    }
+                                }
+                                if (hits.length > 0)
+                                    return hits;
+                            }
+                        }
+                        // Catalog-order fallback: return first `limit` tools from the MCP catalog.
+                        return [...catalog.values()].slice(0, limit);
+                    },
+                    lookup(name) {
+                        // Synchronous: returns from the in-memory cache populated by ensureCatalog.
+                        // Returns undefined before the first query() call — callers that need
+                        // a schema before any query should call query() first.
+                        return catalogCache?.get(name);
+                    },
+                };
+                // Mint helpers: stable UUIDs per spec §C.1/§C.2.
+                // The server wires randomUUID(); tests can inject deterministic minters.
+                const mintStepperId = () => randomUUID();
+                const mintTurnId = () => randomUUID();
+                const stepperMakeLlm = async (lc) => makeLlm({
+                    provider: lc.provider ?? 'deepseek',
+                    apiKey: lc.apiKey,
+                    baseURL: lc.url,
+                    model: lc.model,
+                }, Number(lc.temperature ?? mainTemp));
+                // Real callMcp bridge — delegates to the exported buildMcpBridge helper
+                // that iterates stepperMcpClients. Exported for testability (B-1).
+                const callMcp = buildMcpBridge(stepperMcpClients);
+                // DI/test override registry — left empty in production so buildStepperRoot
+                // builds the recursive child Steppers itself from `subagents` (below),
+                // sharing this run's role LLMs + shared token ledger.
+                const stepperRegistry = new Map();
+                // Declared subagents (name + description) → advertised to the planner and
+                // turned into recursive child Steppers in deep-stepper mode (Finding 1).
+                const stepperSubagents = (this.cfg.subAgentConfigs ?? []).map((s) => ({
+                    name: s.name,
+                    description: s.description,
+                }));
+                const stepperHandler = new StepperCoordinatorHandler({
+                    buildBuilt: async (_ctx, logLlmCall) => {
+                        // Per-RUN MCP result cache. Identical (tool, args) calls within ONE
+                        // run reuse the first result instead of re-hitting MCP — fixes the
+                        // redundant re-reads we saw in flow (gather → analyze → synthesize
+                        // each fetching the same source/includes) and the latency that
+                        // caused. Caching the Promise also dedups concurrent identical
+                        // calls. Fresh per request → never stale across requests.
+                        const runMcpCache = new Map();
+                        const cachedCallMcp = (name, args, signal) => {
+                            const key = `${name}:${stableArgsKey(args)}`;
+                            const hit = runMcpCache.get(key);
+                            if (hit)
+                                return hit;
+                            const p = callMcp(name, args, signal);
+                            runMcpCache.set(key, p);
+                            return p;
+                        };
+                        return buildStepperRoot({
+                            coordCfg: rawCoordCfg,
+                            registry: stepperRegistry,
+                            subagents: stepperSubagents,
+                            makeLlm: stepperMakeLlm,
+                            knowledgeRagFor: (sid) => {
+                                const backend = knowledgeBackend ?? new InMemoryKnowledgeBackend();
+                                return new KnowledgeRag(backend, sid);
+                            },
+                            toolsRag: toolsRagHandle,
+                            callMcp: cachedCallMcp,
+                            mintStepperId,
+                            llmMap,
+                            pipelineFallback,
+                            logLlmCall,
+                        });
+                    },
+                    knowledgeRagFor,
+                    toolsRag: toolsRagHandle,
+                    mintStepperId,
+                    mintTurnId,
+                });
+                this._stepperCoordinatorHandler = stepperHandler;
+                builder = builder.withStepperCoordinator(stepperHandler);
+                log({
+                    event: 'stepper_coordinator_configured',
+                    mode: stepperCfg.mode,
+                    config: rawCoordCfg,
+                });
+            }
+            else if (coordCfg.planner !== undefined) {
+                // ── Legacy DAG path (deprecated §K — remove in 19.0) ─────────────────
+                log({
+                    event: 'config_warning',
+                    message: 'coordinator.planner without coordinator.mode uses the deprecated DagCoordinatorHandler; ' +
+                        'set coordinator.mode to adopt the 18.0 Stepper runtime',
+                });
+                // Fail loud if the config mixes DAG and linear fields.
+                assertCoordinatorConfigShape(rawCoordCfg);
+                // planner shape/type already validated by assertCoordinatorConfigShape.
+                // Validate interpreter.type if present — only 'dag' is supported.
+                const interpKind = coordCfg.interpreter?.type;
+                if (interpKind !== undefined && interpKind !== 'dag') {
+                    throw new Error(`coordinator.interpreter: unknown type '${interpKind}' (only 'dag' is supported)`);
+                }
+                const built = await buildDagCoordinatorDeps({
+                    coordCfg: rawCoordCfg,
+                    llmMap,
+                    pipelineFallback,
+                    mainLlm,
+                    helperLlm,
+                    mainTemp,
+                    registry,
+                    makeLlm: async (lc) => makeLlm({
+                        provider: lc.provider ?? 'deepseek',
+                        apiKey: lc.apiKey,
+                        baseURL: lc.url,
+                        model: lc.model,
+                    }, Number(lc.temperature ?? mainTemp)),
+                    warn: (m) => log({ event: 'config_warning', message: m }),
+                });
+                // built is defined when coordCfg.planner !== undefined.
+                if (!built) {
+                    throw new Error('internal: buildDagCoordinatorDeps returned undefined despite planner present');
+                }
+                const { oracleName, ...deps } = built;
+                builder = builder.withDagCoordinator(deps);
+                // Capture template for per-session re-wire (workers + stateOracle are
+                // re-wired per session; everything else is stateless or LLM-bound).
+                this._dagCoordinatorTemplate = {
+                    deps: {
+                        planner: deps.planner,
+                        interpreter: deps.interpreter,
+                        activation: deps.activation,
+                        reviewer: deps.reviewer,
+                        errorStrategy: deps.errorStrategy,
+                        finalizer: deps.finalizer,
+                        maxRoundTrips: deps.maxRoundTrips,
+                    },
+                    oracleName,
+                };
+                log({ event: 'dag_coordinator_configured', config: coordCfg });
+            }
+            else {
+                // ── Linear / flat coordinator path ────────────────────────────────────
+                // Fail loud if config mixes fields with non-linear settings.
+                assertCoordinatorConfigShape(rawCoordCfg);
+                // Linear mode: route plannerLlm through the normalized map chain.
+                // Priority: map[name] → 'helper'/'planner' alias (helperLlm) →
+                //   pipelineFallback → mainLlm.
+                const linearPlannerName = coordCfg.plannerLlm;
+                // Role-resolution order:
+                //   1. explicit map[name]            → build from that entry
+                //   2. name === 'helper' | 'planner' → reuse prebuilt helperLlm
+                //   3. unknown name                  → resolveLlmConfig fallback chain (map.main → pipelineFallback)
+                //   4. no name                       → mainLlm
+                const linearPlannerCfgStrict = resolveLlmConfigStrict(llmMap, linearPlannerName);
+                const plannerLlm = linearPlannerCfgStrict
+                    ? await makeLlm({
+                        provider: linearPlannerCfgStrict.provider ?? 'deepseek',
+                        apiKey: linearPlannerCfgStrict.apiKey,
+                        baseURL: linearPlannerCfgStrict.url,
+                        model: linearPlannerCfgStrict.model,
+                    }, Number(linearPlannerCfgStrict.temperature ?? mainTemp))
+                    : linearPlannerName === 'helper' || linearPlannerName === 'planner'
+                        ? (helperLlm ?? mainLlm)
+                        : linearPlannerName
+                            ? // Unknown name, not an alias — try pipelineFallback last.
+                                await (async () => {
+                                    const fb = resolveLlmConfig(llmMap, linearPlannerName, pipelineFallback);
+                                    return fb
+                                        ? makeLlm({
+                                            provider: fb.provider ?? 'deepseek',
+                                            apiKey: fb.apiKey,
+                                            baseURL: fb.url,
+                                            model: fb.model,
+                                        }, Number(fb.temperature ?? mainTemp))
+                                        : mainLlm;
+                                })()
+                            : mainLlm;
+                const planningKind = coordCfg.planning ?? 'one-shot';
+                const dispatchKind = resolveCoordinatorDispatchKind(coordCfg.dispatch);
+                // Build the same kind of context builder SmartAgentBuilder uses, so
+                // YAML-configured deployments get the same default behavior. Uses the
+                // embedder resolved above — DI-injected (this.cfg.embedder) when present,
+                // otherwise constructed from `rag.embedder` (#137). Stays undefined for
+                // bare in-memory BM25 stores (no embedder), in which case toolSource is
+                // skipped and constrained subagents fall back to empty context.
+                const mainEmbedder = resolvedEmbedder;
+                const toolSource = mainEmbedder && toolsRag
+                    ? async (text, k, signal) => {
+                        const embedding = new QueryEmbedding(text, mainEmbedder, {
+                            signal,
+                        });
+                        const r = await toolsRag.query(embedding, k, { signal });
+                        return r.ok ? r.value : [];
+                    }
+                    : undefined;
+                const contextBuilder = new DefaultSubAgentContextBuilder({
+                    toolSource,
+                });
+                builder = builder.withCoordinator({
+                    planning: resolveCoordinatorPlanning(planningKind, plannerLlm),
+                    dispatch: resolveCoordinatorDispatch(dispatchKind, plannerLlm, contextBuilder),
+                    // Default to 'explicit' — the presence of a `coordinator:` block in
+                    // YAML is itself the opt-in signal. Users that want the auto-fallback
+                    // semantics (no subagents and no skill steps → tool-loop) must set
+                    // `activation: auto` explicitly.
+                    activation: resolveCoordinatorActivation(coordCfg.activation ?? 'explicit'),
+                    plannerLlm,
+                    maxSteps: coordCfg.maxSteps,
+                    maxRetriesPerStep: coordCfg.maxRetriesPerStep,
+                    failPolicy: coordCfg.failPolicy,
+                });
+                log({ event: 'coordinator_configured', config: coordCfg });
+            }
         }
         const agentHandle = await builder.build();
         const { agent: smartAgent, chat, streamChat, close: closeAgent, circuitBreakers, ragStores, modelProvider, } = agentHandle;
+        const { ragRegistry: globalRagRegistry, mcpClients: globalMcpClients } = agentHandle;
         // ---- API adapter map (built-in → config DI; DI wins) --------------------
         const { OpenAiApiAdapter, AnthropicApiAdapter } = await import('@mcp-abap-adt/llm-agent');
         const adapterMap = new Map();
@@ -345,6 +1060,45 @@ export class SmartServer {
             }
         }
         const closeFns = [closeAgent];
+        // Stepper-owned MCP clients (connected from YAML mcp: block when no
+        // DI/plugin clients existed). Dispose on server shutdown.
+        // TODO: IMcpClient does not currently expose a close() method; add
+        //   `for (const c of this._stepperMcpClients) await c.close?.();`
+        //   once the interface gains one.
+        if (this._stepperMcpClients && this._stepperMcpClients.length > 0) {
+            closeFns.push(async () => {
+                this._stepperMcpClients = undefined;
+            });
+        }
+        // ---- Per-session lifecycle (cookie identity + graph factory + registry) ----
+        const sessionCfg = this.cfg.session ?? {};
+        const idleTtlMs = sessionCfg.idleTtlMs ?? 7_200_000;
+        const lifecycle = buildSessionLifecycle({
+            idleTtlMs,
+            maxSessions: sessionCfg.maxSessions ?? 1000,
+            cookieName: sessionCfg.cookieName ?? 'sid',
+            mcpClients: globalMcpClients,
+            toolsRag,
+            ragRegistry: globalRagRegistry,
+            buildAgent: (parts) => this.buildSessionAgent(parts),
+            logger: fileLogger,
+        });
+        this._lifecycle = lifecycle;
+        const sweepMs = Math.min(idleTtlMs, 60_000);
+        const sweep = setInterval(() => {
+            void lifecycle.evictIdle();
+        }, sweepMs);
+        sweep.unref?.();
+        closeFns.push(async () => {
+            clearInterval(sweep);
+            await lifecycle.disposeAll();
+            // Fix #21: per-session graphs may reference worker MCP clients, so
+            // dispose them FIRST (above), THEN drain per-worker handle.close so the
+            // worker-owned MCP clients themselves disconnect. Ordering matters —
+            // closing MCP clients while a session graph is mid-use would cut its
+            // request short.
+            await drainWorkerCache(this._workerLlmCache);
+        });
         const startTime = Date.now();
         const healthChecker = new HealthChecker({
             agent: smartAgent,
@@ -383,7 +1137,59 @@ export class SmartServer {
                     agentUpdate.classificationEnabled = update.classificationEnabled;
                 if (Object.keys(agentUpdate).length > 0) {
                     smartAgent.applyConfigUpdate(agentUpdate);
+                    // Mirror onto `this.cfg.agent` so freshly-built session graphs
+                    // (which read `this.cfg.agent` in `buildSessionAgent`) observe the
+                    // update. Deep-merge to preserve untouched startup fields.
+                    // Note: `agentUpdate` includes flat fields ONLY whitelisted by
+                    // `AGENT_CONFIG_FIELDS` plus the two prompt fields, which we route
+                    // into `this.cfg.prompts` separately below.
+                    const agentPatch = {};
+                    for (const k of Object.keys(agentUpdate)) {
+                        if (k !== 'ragTranslatePrompt' && k !== 'historySummaryPrompt') {
+                            agentPatch[k] = agentUpdate[k];
+                        }
+                    }
+                    if (Object.keys(agentPatch).length > 0) {
+                        const mergedAgent = {
+                            ...(this.cfg.agent ??
+                                {}),
+                            ...agentPatch,
+                        };
+                        this.cfg.agent =
+                            mergedAgent;
+                    }
+                    if (update.prompts?.ragTranslate !== undefined ||
+                        update.prompts?.historySummary !== undefined) {
+                        const mergedPrompts = {
+                            ...(this.cfg.prompts ??
+                                {}),
+                        };
+                        if (update.prompts?.ragTranslate !== undefined) {
+                            mergedPrompts.ragTranslate = update.prompts.ragTranslate;
+                        }
+                        if (update.prompts?.historySummary !== undefined) {
+                            mergedPrompts.historySummary = update.prompts.historySummary;
+                        }
+                        this.cfg.prompts =
+                            mergedPrompts;
+                    }
                 }
+                // Per-session graphs (built by SessionGraphFactory) captured the OLD
+                // config and the OLD cached worker LLM set. Without invalidation,
+                // existing sessions keep the stale SmartAgent and a fresh acquire on a
+                // cookie-known sessionId still returns it. Clear the worker cache so
+                // the next build reads from the just-applied config, then drop every
+                // session graph. Failures are non-fatal — log and continue.
+                // Fix #21: drain per-worker SmartAgentHandle.close() BEFORE clearing
+                // the cache. Hot-reload runs from a synchronous emitter callback, so
+                // fire-and-forget here — same async-tolerance as the invalidateAll
+                // call below.
+                drainWorkerCache(this._workerLlmCache).catch((err) => {
+                    log({ event: 'config_reload_drain_error', error: String(err) });
+                });
+                this._lifecycle?.invalidateAll().catch((err) => {
+                    log({ event: 'config_reload_invalidate_error', error: String(err) });
+                });
                 // Apply RAG weight updates
                 if (update.vectorWeight !== undefined ||
                     update.keywordWeight !== undefined) {
@@ -422,9 +1228,17 @@ export class SmartServer {
                 resolve({
                     port: actualPort,
                     close: async () => {
+                        // 1. Stop accepting new connections AND wait for in-flight HTTP
+                        //    requests to drain. Until server.close() resolves, requests
+                        //    accepted before shutdown may still be running and pinning
+                        //    per-session graphs — disposing those graphs first would
+                        //    violate the active-request pinning guarantee.
+                        await new Promise((res, rej) => server.close((e) => (e ? rej(e) : res())));
+                        // 2. Now run lifecycle cleanup: sweep timer, lifecycle.disposeAll,
+                        //    config watcher stop, agent close. By this point no HTTP
+                        //    request is in flight, so disposing session graphs is safe.
                         for (const fn of closeFns)
                             await fn();
-                        await new Promise((res, rej) => server.close((e) => (e ? rej(e) : res())));
                     },
                     requestLogger,
                 });
@@ -447,37 +1261,93 @@ export class SmartServer {
      * rejected at config-parse time, so `subCfg.subAgentConfigs` is
      * always undefined here.
      */
-    async buildSubAgent(name, subCfg, parentLogger, embedderFactories) {
-        if (!subCfg.llm?.apiKey && !subCfg.pipeline?.llm?.main) {
+    async buildSubAgent(name, subCfg, parentLogger, embedderFactories, injected) {
+        // Normalize subagent llm: either flat { provider, apiKey, ... } or a map
+        // { main: {...}, planner: {...} }. normalizeLlmConfig wraps flat shape as
+        // { main: flat } so downstream code always reads from .main.
+        const subLlmMap = normalizeLlmConfig(subCfg.llm);
+        const subLlmMain = subLlmMap?.main;
+        if (!subLlmMain?.apiKey &&
+            subLlmMain?.provider !== 'sap-ai-sdk' &&
+            subLlmMain?.provider !== 'ollama' &&
+            !subCfg.pipeline?.llm?.main) {
             throw new Error(`subagent '${name}': LLM API key is required`);
         }
         const subPipeline = subCfg.pipeline;
-        const mainTemp = Number(subPipeline?.llm?.main?.temperature ?? subCfg.llm.temperature ?? 0.7);
-        const mainLlm = subPipeline?.llm?.main
-            ? await makeLlm(subPipeline.llm.main, mainTemp)
-            : await makeLlm({
-                // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                // rejects a missing flat-schema provider before this runs.
-                provider: subCfg.llm.provider ?? 'deepseek',
-                apiKey: subCfg.llm.apiKey,
-                baseURL: subCfg.llm.url,
-                model: subCfg.llm.model,
-            }, mainTemp);
+        // LLM/embedder clients: when the per-session re-wire injected them, use
+        // those cached instances by reference (NEVER reconstruct). Otherwise (the
+        // primary build()), build-once via the cache so the global agent build
+        // also populates it and later per-session re-wires reuse the SAME
+        // instances.
+        // Note: a per-worker embedder slot is carried in WorkerLlmSet and the
+        // injected record for forward-compat with Task A8/A10 per-session wiring.
+        // Today's buildSubAgent does not separately resolve an embedder here —
+        // embedders are carried by the worker's own store via makeRag's
+        // `injectedEmbedder` — so we ignore the embedder field below.
+        // Resolve (build-once or load from cache) the worker's own LLMs +
+        // toolsRag/historyRag/mcpClients. The cache is keyed by worker name; the
+        // primary build() populates it (no `injected` arg), and per-session
+        // re-wires (`injected` set) read from it via the same call below — the
+        // cache hit short-circuits all factories. This keeps the worker's
+        // declared RAG/MCP intact across per-session re-wires (review HIGH #1).
+        const subFlatLlm = subLlmMain;
+        const mainTemp = Number(subPipeline?.llm?.main?.temperature ?? subFlatLlm?.temperature ?? 0.7);
         const classifierTemp = Number(subPipeline?.llm?.classifier?.temperature ??
-            subCfg.llm.classifierTemperature ??
+            subFlatLlm?.classifierTemperature ??
             0.1);
-        const classifierLlm = subPipeline?.llm?.classifier
-            ? await makeLlm(subPipeline.llm.classifier, classifierTemp)
-            : subPipeline?.llm?.main
-                ? await makeLlm(subPipeline.llm.main, classifierTemp)
-                : await makeLlm({
-                    // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                    // rejects a missing flat-schema provider before this runs.
-                    provider: subCfg.llm.provider ?? 'deepseek',
-                    apiKey: subCfg.llm.apiKey,
-                    baseURL: subCfg.llm.url,
-                    model: subCfg.llm.model,
-                }, classifierTemp);
+        const cached = await resolveWorkerLlmSet({
+            name,
+            cache: this._workerLlmCache,
+            // Preserve the existing makeLlm derivation exactly.
+            makeMain: () => subPipeline?.llm?.main
+                ? makeLlm(subPipeline.llm.main, mainTemp)
+                : makeLlm({
+                    // ?? 'deepseek' is a TS type-narrowing net only; the config
+                    // validator rejects a missing flat-schema provider before
+                    // this runs.
+                    provider: subFlatLlm?.provider ?? 'deepseek',
+                    apiKey: subFlatLlm?.apiKey ?? '',
+                    baseURL: subFlatLlm?.url,
+                    model: subFlatLlm?.model,
+                }, mainTemp),
+            makeClassifier: () => subPipeline?.llm?.classifier
+                ? makeLlm(subPipeline.llm.classifier, classifierTemp)
+                : subPipeline?.llm?.main
+                    ? makeLlm(subPipeline.llm.main, classifierTemp)
+                    : makeLlm({
+                        provider: subFlatLlm?.provider ?? 'deepseek',
+                        apiKey: subFlatLlm?.apiKey ?? '',
+                        baseURL: subFlatLlm?.url,
+                        model: subFlatLlm?.model,
+                    }, classifierTemp),
+            makeHelper: subPipeline?.llm?.helper
+                ? ((h) => () => makeLlm(h, Number(h.temperature ?? 0.1)))(subPipeline.llm.helper)
+                : undefined,
+            // Worker-OWN tools RAG (from subCfg.rag, if declared). Built once;
+            // re-wired per-session by reference — never re-vectorized.
+            makeToolsRag: subCfg.rag
+                ? () => makeRag(subCfg.rag, {
+                    injectedEmbedder: subCfg.embedder,
+                    extraFactories: embedderFactories,
+                })
+                : undefined,
+            makeHistoryRag: subCfg.rag
+                ? () => makeRag({ ...subCfg.rag }, {
+                    injectedEmbedder: subCfg.embedder,
+                    extraFactories: embedderFactories,
+                })
+                : undefined,
+            // Worker-OWN MCP clients. DI list (subCfg.mcpClients) wins; otherwise
+            // SmartAgentBuilder's own MCP-connect path handles `subCfg.mcp` — we
+            // don't pre-build those here (connection is the builder's job and is
+            // not safe to invoke twice). The cache stores the DI clients only.
+            makeMcpClients: subCfg.mcpClients && subCfg.mcpClients.length > 0
+                ? async () => subCfg.mcpClients
+                : undefined,
+        });
+        const mainLlm = cached.mainLlm;
+        const classifierLlm = cached.classifierLlm;
+        const helperLlm = cached.helperLlm;
         let subBuilder = new SmartAgentBuilder({
             mcp: subPipeline?.mcp ?? subCfg.mcp,
             agent: subCfg.agent,
@@ -488,27 +1358,209 @@ export class SmartServer {
             .withClassifierLlm(classifierLlm)
             .withLogger(parentLogger)
             .withMode(subCfg.mode ?? 'smart');
-        if (subPipeline?.llm?.helper) {
-            const helperLlm = await makeLlm(subPipeline.llm.helper, Number(subPipeline.llm.helper.temperature ?? 0.1));
+        if (helperLlm) {
             subBuilder = subBuilder.withHelperLlm(helperLlm);
         }
-        if (subCfg.rag) {
-            const ragOptions = {
-                injectedEmbedder: subCfg.embedder,
-                extraFactories: embedderFactories,
-            };
-            subBuilder = subBuilder.setToolsRag(await makeRag(subCfg.rag, ragOptions));
-            subBuilder = subBuilder.setHistoryRag(await makeRag({ ...subCfg.rag }, ragOptions));
+        // SHARE the parent RAG registry + session logger when injected (per-session
+        // worker re-wire). The per-call scope filter isolates by ctx.sessionId.
+        const sharedReg = resolveSubAgentRagRegistry({
+            parentRagRegistry: injected?.ragRegistry,
+        });
+        if (sharedReg)
+            subBuilder = subBuilder.setRagRegistry(sharedReg);
+        if (injected?.requestLogger) {
+            subBuilder = subBuilder.withRequestLogger(injected.requestLogger);
+        }
+        // Tools/History RAG priority (review HIGH #1):
+        //   1) worker's OWN cached toolsRag (from subCfg.rag) — built once, reused
+        //      by reference across per-session re-wires (never re-vectorized);
+        //   2) parent's injected toolsRag (fallback for workers that did not
+        //      declare their own store).
+        // History RAG: only when the worker has its own cached instance — the
+        // parent's history RAG is owned by the parent agent and is not shared.
+        if (cached.toolsRag) {
+            subBuilder = subBuilder.setToolsRag(cached.toolsRag);
+            if (cached.historyRag) {
+                subBuilder = subBuilder.setHistoryRag(cached.historyRag);
+            }
+        }
+        else if (injected?.toolsRag) {
+            subBuilder = subBuilder.setToolsRag(injected.toolsRag);
         }
         if (subCfg.skillManager) {
             subBuilder = subBuilder.withSkillManager(subCfg.skillManager);
         }
-        if (subCfg.mcpClients && subCfg.mcpClients.length > 0) {
-            subBuilder = subBuilder.withMcpClients(subCfg.mcpClients);
+        // MCP clients priority (review HIGH #1):
+        //   1) worker's OWN cached MCP clients (from subCfg.mcpClients DI) — keeps
+        //      the worker pointed at its own upstream when the parent has none;
+        //   2) parent's injected GLOBAL MCP clients (fallback) — skips re-connect.
+        // If neither is set, fall through to the builder's own MCP-connect path
+        // (which honours `subCfg.mcp`).
+        if (cached.mcpClients && cached.mcpClients.length > 0) {
+            subBuilder = subBuilder.withMcpClients(cached.mcpClients);
+        }
+        else if (injected?.mcpClients && injected.mcpClients.length > 0) {
+            subBuilder = subBuilder.withMcpClients(injected.mcpClients);
         }
         const handle = await subBuilder.build();
+        // Backfill the per-worker cache from the BUILT handle (review HIGH #7).
+        // Only runs on the primary build path (no `injected`) so per-session
+        // re-wires never overwrite the cache. See backfillWorkerCacheFromHandle's
+        // doc-comment for the rationale.
+        if (!injected) {
+            const entry = this._workerLlmCache.get(name);
+            if (entry)
+                await backfillWorkerCacheFromHandle(entry, handle);
+        }
+        return handle.agent;
+    }
+    /**
+     * Builds a per-session SmartAgent from injected globals (review HIGH #1 +
+     * MEDIUM #3). Re-wires the SubAgent registry + DAG coordinator deps FRESH per
+     * session, sharing this session's logger + the global ragRegistry/toolsRag/
+     * mcpClients + the CACHED per-worker LLM/embedder (this._workerLlmCache). It
+     * NEVER reuses the primary build()'s global `registry`/DAG-deps and NEVER
+     * constructs new LLM clients.
+     */
+    async buildSessionAgent(parts) {
+        // Guard: globals must already be captured by the primary build() before any
+        // session graph is built (the registry calls this lazily on first acquire).
+        if (!this._mainLlm || !this._classifierLlm || !this._fileLogger) {
+            throw new Error('buildSessionAgent invoked before primary build() captured globals');
+        }
+        let b = new SmartAgentBuilder({
+            agent: this.cfg.agent,
+            prompts: this.cfg.prompts,
+            skipModelValidation: this.cfg.skipModelValidation,
+        })
+            .withMainLlm(this._mainLlm)
+            .withClassifierLlm(this._classifierLlm)
+            .withLogger(this._fileLogger)
+            .withMode(this.cfg.mode ?? 'smart')
+            .withMcpClients(parts.mcpClients) // skips connect + re-vectorize
+            .setRagRegistry(parts.ragRegistry)
+            .withRequestLogger(parts.logger); // per-session token-logger
+        if (this._helperLlm)
+            b = b.withHelperLlm(this._helperLlm);
+        if (parts.toolsRag)
+            b = b.setToolsRag(parts.toolsRag);
+        // FRESH per-session workers — re-wire the registry from the SAME subagent
+        // configs the primary build() used, injecting globals + this session's
+        // logger + the CACHED per-worker LLM/embedder. No LLM reconstruction.
+        if (this.cfg.subAgentConfigs && this.cfg.subAgentConfigs.length > 0) {
+            const registry = new Map();
+            for (const sub of this.cfg.subAgentConfigs) {
+                // Lazy build-on-miss (Fix #18). After PUT /v1/config or hot-reload
+                // clears `_workerLlmCache`, the next buildSessionAgent used to throw
+                // "worker LLM set not cached" because the cache was assumed
+                // pre-populated by the primary build(). buildSubAgent itself routes
+                // through `resolveWorkerLlmSet` which is build-on-miss, so calling
+                // it without an `injected` arg rebuilds the cache entry. We then
+                // re-read the entry to honour the per-worker slot priority below.
+                if (!this._workerLlmCache.has(sub.name)) {
+                    await this.buildSubAgent(sub.name, sub.config, this._fileLogger, this._mergedEmbedderFactories ?? {});
+                }
+                const cached = this._workerLlmCache.get(sub.name);
+                if (!cached) {
+                    // Defence in depth — should be impossible after the lazy build
+                    // above unless buildSubAgent's contract changes.
+                    throw new Error(`worker LLM set not cached for '${sub.name}'`);
+                }
+                // Per-worker injected slot priority (review HIGH #7):
+                //   worker-cached (from the primary build, includes backfilled
+                //   subCfg.mcp / subCfg.rag results) → parent's session-scoped
+                //   fallback. Encoded HERE so buildSubAgent does not need to know
+                //   the difference; it just consumes injected.mcpClients/toolsRag.
+                const injectedMcpClients = cached.mcpClients && cached.mcpClients.length > 0
+                    ? cached.mcpClients
+                    : parts.mcpClients;
+                const injectedToolsRag = cached.toolsRag ?? parts.toolsRag;
+                const subAgent = await this.buildSubAgent(sub.name, sub.config, this._fileLogger, this._mergedEmbedderFactories ?? {}, {
+                    ragRegistry: parts.ragRegistry,
+                    toolsRag: injectedToolsRag,
+                    mcpClients: injectedMcpClients,
+                    requestLogger: parts.logger,
+                    mainLlm: cached.mainLlm,
+                    classifierLlm: cached.classifierLlm,
+                    helperLlm: cached.helperLlm,
+                    embedder: cached.embedder,
+                });
+                registry.set(sub.name, new SmartAgentSubAgent(sub.name, subAgent, {
+                    description: sub.description,
+                }));
+            }
+            b = b.withSubAgents(registry);
+            if (this._stepperCoordinatorHandler) {
+                // Stepper coordinator is stateless — reuse the same handler instance
+                // across sessions (session context arrives via ctx.sessionId).
+                b = b.withStepperCoordinator(this._stepperCoordinatorHandler);
+            }
+            else if (this._dagCoordinatorTemplate) {
+                const tpl = this._dagCoordinatorTemplate;
+                const workers = new Map([...registry].filter(([name]) => name !== tpl.oracleName));
+                const raw = tpl.oracleName ? registry.get(tpl.oracleName) : undefined;
+                b = b.withDagCoordinator({
+                    ...tpl.deps,
+                    workers,
+                    stateOracle: raw ? new SubAgentStateOracle(raw) : undefined,
+                });
+            }
+        }
+        else if (this._stepperCoordinatorHandler) {
+            // No sub-agent configs but stepper coordinator configured — wire it directly.
+            // (Stepper coordinator is stateless and works without sub-agents.)
+            b = b.withStepperCoordinator(this._stepperCoordinatorHandler);
+        }
+        const handle = await b.build();
         return handle.agent;
     }
+    /**
+     * Resolve identity (mint cookie when needed), acquire the per-session graph,
+     * run `fn` pinned, and release in `finally`. Order in `finally`:
+     *   1. drop the per-traceId logger delta (server-owned free, review HIGH #2)
+     *   2. release the refcount pin
+     */
+    async _withSession(req, res, fn) {
+        const lifecycle = this._lifecycle;
+        if (!lifecycle) {
+            throw new Error('SmartServer lifecycle not initialized');
+        }
+        const traceId = randomUUID();
+        const isHttps = req.socket.encrypted === true ||
+            req.headers['x-forwarded-proto'] === 'https';
+        const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+        const sessionId = resolved.identity.sessionId;
+        if (resolved.minted && resolved.setCookie) {
+            res.setHeader('Set-Cookie', resolved.setCookie);
+        }
+        const graph = await lifecycle.acquire(sessionId);
+        // Register/touch the session in the meta store so /v1/sessions, resume and
+        // delete reflect real chat/stream traffic (review Finding 3). Best-effort:
+        // a meta-store hiccup must never break the actual request.
+        try {
+            await recordSessionStart(this._sessionMetaStore, sessionId, new Date().toISOString());
+        }
+        catch {
+            // swallow — session metadata is non-critical to serving the request
+        }
+        try {
+            await fn(graph, sessionId, traceId);
+        }
+        finally {
+            try {
+                await recordSessionEnd(this._sessionMetaStore, sessionId, new Date().toISOString());
+            }
+            catch {
+                // swallow — see above
+            }
+            graph.logger.dropRequest(traceId);
+            // Pass the graph instance — `invalidateAll()` may have detached this
+            // graph into the draining map while the request was in flight; we must
+            // release THIS specific instance, not whatever currently lives under
+            // `sessionId` in the registry.
+            lifecycle.release(sessionId, graph);
+        }
+    }
     async _handle(req, res, requestLogger, smartAgent, chat, streamChat, log, healthChecker, modelProvider, adapterMap) {
         const rawUrl = req.url ?? '/';
         const urlPath = rawUrl.split('?')[0].replace(/\/$/, '') || '/';
@@ -581,10 +1633,109 @@ export class SmartServer {
             return;
         }
         if (req.method === 'GET' && urlPath === '/v1/usage') {
+            const lifecycle = this._lifecycle;
+            if (!lifecycle) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(jsonError('Session lifecycle not initialized', 'server_error'));
+                return;
+            }
+            const isHttps = req.socket.encrypted === true ||
+                req.headers['x-forwarded-proto'] === 'https';
+            const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+            if (resolved.minted && resolved.setCookie) {
+                res.setHeader('Set-Cookie', resolved.setCookie);
+            }
+            const sessionId = resolved.identity.sessionId;
+            const graph = await lifecycle.acquire(sessionId);
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(graph.logger.getSummary()));
+            }
+            finally {
+                lifecycle.release(sessionId, graph);
+            }
+            return;
+        }
+        // GET /v1/sessions — list sessions for the current identity
+        if (req.method === 'GET' && urlPath === '/v1/sessions') {
+            const lifecycle = this._lifecycle;
+            if (!lifecycle) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(jsonError('Session lifecycle not initialized', 'server_error'));
+                return;
+            }
+            const isHttps = req.socket.encrypted === true ||
+                req.headers['x-forwarded-proto'] === 'https';
+            const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+            if (resolved.minted && resolved.setCookie) {
+                res.setHeader('Set-Cookie', resolved.setCookie);
+            }
+            const identity = resolved.identity.sessionId;
+            const body = await handleListSessions(this._sessionMetaStore, identity);
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(requestLogger.getSummary()));
+            res.end(JSON.stringify(body));
             return;
         }
+        // POST /v1/sessions/:id/resume — resume a session
+        {
+            const resumeMatch = urlPath.match(/^\/v1\/sessions\/([^/]+)\/resume$/);
+            if (req.method === 'POST' && resumeMatch) {
+                const sessionId = resumeMatch[1];
+                const lifecycle = this._lifecycle;
+                if (!lifecycle) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(jsonError('Session lifecycle not initialized', 'server_error'));
+                    return;
+                }
+                const isHttps = req.socket.encrypted === true ||
+                    req.headers['x-forwarded-proto'] === 'https';
+                const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+                if (resolved.minted && resolved.setCookie) {
+                    res.setHeader('Set-Cookie', resolved.setCookie);
+                }
+                const identity = resolved.identity.sessionId;
+                const body = await handleResumeSession(this._sessionMetaStore, identity, sessionId);
+                const status = body.ok ? 200 : 404;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(body));
+                return;
+            }
+        }
+        // DELETE /v1/sessions/:id — delete a session
+        {
+            const deleteMatch = urlPath.match(/^\/v1\/sessions\/([^/]+)$/);
+            if (req.method === 'DELETE' && deleteMatch) {
+                const sessionId = deleteMatch[1];
+                const lifecycle = this._lifecycle;
+                if (!lifecycle) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(jsonError('Session lifecycle not initialized', 'server_error'));
+                    return;
+                }
+                const isHttps = req.socket.encrypted === true ||
+                    req.headers['x-forwarded-proto'] === 'https';
+                const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+                if (resolved.minted && resolved.setCookie) {
+                    res.setHeader('Set-Cookie', resolved.setCookie);
+                }
+                const identity = resolved.identity.sessionId;
+                const evictFn = async (sid) => {
+                    // (a) Evict/dispose this session's graph from the registry.
+                    await lifecycle.registry.evictOne(sid);
+                    // (b) Evict the session's knowledge from the shared backend. This
+                    // clears the long-lived in-memory backend AND removes the JSONL files
+                    // (JsonlKnowledgeBackend.deleteSession), so a same-id re-entry never
+                    // rehydrates stale entries — matching the README "evicts its
+                    // knowledge-RAG entries" contract.
+                    await this._stepperKnowledgeBackend?.deleteSession(sid);
+                };
+                const body = await handleDeleteSession(this._sessionMetaStore, identity, sessionId, evictFn);
+                const status = body.ok ? 200 : 404;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(body));
+                return;
+            }
+        }
         // /v1/config or /config
         if (urlPath === '/v1/config' || urlPath === '/config') {
             if (req.method === 'GET') {
@@ -622,18 +1773,22 @@ export class SmartServer {
                 res.end(jsonError('Anthropic adapter not registered', 'not_found'));
                 return;
             }
-            await this._handleAdapterRequest(req, res, smartAgent, anthropicAdapter);
+            await this._withSession(req, res, async (graph, sessionId, traceId) => {
+                await this._handleAdapterRequest(req, res, graph.agent ?? smartAgent, anthropicAdapter, { sessionId, traceId, graph });
+            });
             return;
         }
         if (req.method === 'POST' &&
             (urlPath === '/v1/chat/completions' || urlPath === '/chat/completions')) {
-            await this._handleChat(req, res, requestLogger, smartAgent, chat, streamChat, log, modelProvider);
+            await this._withSession(req, res, async (graph, sessionId, traceId) => {
+                await this._handleChat(req, res, requestLogger, graph.agent ?? smartAgent, chat, streamChat, log, modelProvider, { sessionId, traceId, graph });
+            });
             return;
         }
         res.writeHead(404, { 'Content-Type': 'application/json' });
         res.end(jsonError(`Cannot ${req.method} ${urlPath}`, 'invalid_request_error'));
     }
-    async _handleAdapterRequest(req, res, agent, adapter) {
+    async _handleAdapterRequest(req, res, agent, adapter, session) {
         const raw = await readBody(req);
         let body;
         try {
@@ -656,13 +1811,22 @@ export class SmartServer {
             }
             throw err;
         }
+        const augmentedOptions = session
+            ? {
+                ...normalized.options,
+                sessionId: session.sessionId,
+                trace: { traceId: session.traceId },
+                toolAvailability: session.graph.toolAvailability,
+                pendingToolResults: session.graph.pendingToolResults,
+            }
+            : normalized.options;
         if (normalized.stream) {
             res.writeHead(200, {
                 'Content-Type': 'text/event-stream',
                 'Cache-Control': 'no-cache',
                 Connection: 'keep-alive',
             });
-            for await (const event of adapter.transformStream(agent.streamProcess(normalized.messages, normalized.options), normalized.context)) {
+            for await (const event of adapter.transformStream(agent.streamProcess(normalized.messages, augmentedOptions), normalized.context)) {
                 const eventLine = event.event ? `event: ${event.event}\n` : '';
                 res.write(`${eventLine}data: ${event.data}\n\n`);
             }
@@ -670,7 +1834,7 @@ export class SmartServer {
             return;
         }
         // Non-streaming
-        const result = await agent.process(normalized.messages, normalized.options);
+        const result = await agent.process(normalized.messages, augmentedOptions);
         res.setHeader('Content-Type', 'application/json');
         if (!result.ok) {
             res.writeHead(500);
@@ -685,7 +1849,7 @@ export class SmartServer {
         res.writeHead(200);
         res.end(JSON.stringify(adapter.formatResult(result.value, normalized.context)));
     }
-    async _handleChat(req, res, _requestLogger, smartAgent, _chat, _streamChat, log, modelProvider) {
+    async _handleChat(req, res, _requestLogger, smartAgent, _chat, _streamChat, log, modelProvider, session) {
         const rawBody = await readBody(req);
         let parsed;
         try {
@@ -725,8 +1889,13 @@ export class SmartServer {
             res.end(jsonError('at least one message with role "user" is required', 'invalid_request_error'));
             return;
         }
-        const traceId = randomUUID();
-        const sessionId = req.headers['x-session-id'] || 'default';
+        // Prefer the session injected by `_withSession` (cookie identity); fall
+        // back to the legacy x-session-id header / 'default' bucket only when no
+        // session was wired (defensive — production routes always inject one).
+        const traceId = session?.traceId ?? randomUUID();
+        const sessionId = session?.sessionId ??
+            req.headers['x-session-id'] ??
+            'default';
         const sessionLogger = new SessionLogger(this.cfg.logDir || null, sessionId, traceId);
         const toolsValidationMode = this.cfg.agent?.externalToolsValidationMode ?? 'permissive';
         const externalToolsValidation = normalizeAndValidateExternalTools(body.tools);
@@ -761,6 +1930,12 @@ export class SmartServer {
             trace: { traceId },
             sessionLogger,
             model: body.model,
+            ...(session
+                ? {
+                    toolAvailability: session.graph.toolAvailability,
+                    pendingToolResults: session.graph.pendingToolResults,
+                }
+                : {}),
             ...(body.temperature !== undefined
                 ? { temperature: body.temperature }
                 : {}),
@@ -1085,9 +2260,48 @@ export class SmartServer {
         // --- All validation passed — apply mutations ---
         if (resolvedModels) {
             smartAgent.reconfigure(resolvedModels);
+            // Mirror onto the hoisted globals consumed by `buildSessionAgent` so
+            // freshly-built session graphs pick up the new LLMs by reference
+            // (otherwise `this._mainLlm` etc. would keep pointing at the originals
+            // captured during `start()`).
+            if (resolvedModels.mainLlm)
+                this._mainLlm = resolvedModels.mainLlm;
+            if (resolvedModels.classifierLlm)
+                this._classifierLlm = resolvedModels.classifierLlm;
+            if (resolvedModels.helperLlm)
+                this._helperLlm = resolvedModels.helperLlm;
         }
         if (body.agent) {
-            smartAgent.applyConfigUpdate(body.agent);
+            const patch = body.agent;
+            smartAgent.applyConfigUpdate(patch);
+            // Mirror onto `this.cfg.agent` so freshly-built session graphs (which
+            // read `this.cfg.agent` in `buildSessionAgent`) observe the update.
+            // Deep-merge to preserve untouched startup fields; replacing the whole
+            // `agent` block would drop YAML defaults the validator already applied.
+            const merged = {
+                ...(this.cfg.agent ?? {}),
+                ...patch,
+            };
+            this.cfg.agent = merged;
+        }
+        // Invalidate per-session SmartAgents + the worker-LLM cache so the next
+        // request mints a session graph that observes the just-applied config.
+        // Without this, chat routes dispatch to `graph.agent` (the per-session
+        // SmartAgent) which was built with the OLD config, and the PUT is a
+        // no-op from the consumer's perspective. Failures are non-fatal so the
+        // 200 response isn't blocked by a dispose hiccup.
+        if (resolvedModels || body.agent) {
+            // Fix #21: drain per-worker SmartAgentHandle.close() BEFORE clearing the
+            // cache so MCP clients owned by the discarded handles disconnect.
+            await drainWorkerCache(this._workerLlmCache);
+            try {
+                await this._lifecycle?.invalidateAll();
+            }
+            catch {
+                // Swallow: cleanup errors must not turn a successful config update
+                // into a 500. The next request will still get a fresh build because
+                // `_workerLlmCache` is already cleared and dispose is idempotent.
+            }
         }
         // --- Return updated config ---
         const models = smartAgent.getActiveConfig();