From d6a8977d55884f5205e7b991965c90a7abb63a37 Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 11:03:10 +0800
Subject: [PATCH 01/10] feat(context): derive compaction and prompt budgets
 from model capability, add cost estimation

- Compactor context window now resolves live from the narrative slot's
  model capability (llm.toml hot-reload aware); COVEL_COMPACTOR_CONTEXT_WINDOW
  becomes an optional explicit override (fallback 32768).
- New CJK-aware estimateTokens replaces the chars/4 heuristic that
  undercounted Chinese text ~3x.
- Activate the applyBudget hard prune as last line of defense: estimator +
  getter-based contextBudget injected into turn-executor deps.
- Debug cost panel: per-model USD estimation via model-db pricing; model
  recovered by pairing llm.responded with the preceding llm.calling.
- ModelCapabilityInfo gains the flat per-M-token price fields actually
  returned by /api/model-db/lookup.

Riders on shared files: memorySystem module-setter typing cleanup
(actions.ts), withSessionLock ghost-comment reword (env.d.ts), dead
searchModelDb removal (llm.ts), orphaned lorebook i18n keys removal
(locales), doc-sync lines in CLAUDE.md / env-registry.md.
---
 CLAUDE.md                                     |   8 +-
 apps/server/src/app.ts                        |  20 ++
 apps/server/src/env.d.ts                      |  13 +-
 apps/server/src/routes/api/actions.ts         |  77 +++++---
 apps/server/src/routes/api/bootstrap.ts       |  25 ++-
 .../src/routes/api/bootstrap/compactor.ts     |  85 ++++++--
 apps/server/src/routes/api/plugin-rpc.ts      |   5 +
 .../bootstrap/turn-context-budget.test.ts     |  49 +++++
 apps/web/src/i18n/locales/en-US.json          |  17 +-
 apps/web/src/i18n/locales/zh-CN.json          |  17 +-
 apps/web/src/routes/debug/-cost-panel.tsx     | 183 ++++++++++++++++--
 .../debug/__tests__/-cost-panel.test.ts       |  88 ++++++++-
 apps/web/src/services/api/llm.ts              |  30 +--
 docs/guide/env-registry.md                    |  21 +-
 packages/context/src/budget.ts                |  22 +++
 packages/context/src/index.ts                 |   2 +-
 packages/context/tests/budget.test.ts         |  23 ++-
 packages/shared/src/env/groups/feature.ts     |   5 +-
 packages/shared/src/env/registry-readers.ts   |  15 +-
 packages/shared/tests/env-registry.test.ts    |   4 +-
 20 files changed, 582 insertions(+), 127 deletions(-)
 create mode 100644 apps/server/tests/bootstrap/turn-context-budget.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 4c0dc04e..d0b6965b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -186,7 +186,7 @@ All panels/blocks render through [json-render](https://github.com/vercel-labs/js
 - Configured via `llm.toml` `[covel.<slot>]` sections. If missing, single `story` → DeepSeek fallback boots the app.
 - **Tag-aware fallback**: an unconfigured slot falls back to the first slot with the same tag (`text`/`image`/`embedding`/`speech`/`transcription`). Cross-tag fallback is forbidden (an image request never silently routes to text).
 - Supports OpenAI, Anthropic, DeepSeek, Qwen (Aliyun DashScope).
-- **Model capabilities** (multimodal, features, token limits, pricing) auto-detected via: frontend localStorage override → `llm.toml` manual → `known-models.ts` (~60 common) → LiteLLM DB (2597 models, `pnpm --filter @covel/ai-provider update-model-db`) → protocol defaults. Directional modality: `input: InputModality[]` = accepts, `output: OutputModality[]` = produces.
+- **Model capabilities** (multimodal, features, token limits, pricing) auto-detected via: frontend localStorage override → `llm.toml` manual → `known-models.ts` (~60 common) → LiteLLM DB (2967 models, `pnpm --filter @covel/ai-provider update-model-db`) → protocol defaults. Directional modality: `input: InputModality[]` = accepts, `output: OutputModality[]` = produces.
 - **Media generation (image / TTS / STT)**: `ctx.images.generate()` and `ctx.speech.generate()`/`.transcribe()` (function-runtime plugins, preferred) route through pluggable per-modality wire registries — builtin `openai-images` (default) + `dashscope-wan` for image, `openai-speech` / `openai-transcription` for speech — selectable per-slot via `llm.toml` `providerRequestMetadata.imageWire|speechWire|transcriptionWire`. Both `generate` paths dedupe on promptHash and persist to MediaStore. Plugins register vendor wires via the PLUGIN.md `wires` frontmatter field (ids namespaced `<pluginId>/<wireId>`, trust-gated loading in `bootstrap/plugin-wires.ts`); bundled code may call `register{Image,Speech,Transcription}Wire()` directly. See [docs/reference/slots.md](./docs/reference/slots.md), [docs/reference/media-store.md](./docs/reference/media-store.md) and [docs/guide/plugin-authoring-advanced.md](./docs/guide/plugin-authoring-advanced.md#6-函数-runtime手动触发与后台执行).
 
 ## Critical Conventions (Read These)
@@ -288,7 +288,7 @@ Each SQL backend keeps a thin public factory plus focused method modules:
 
 - **vitest** is the single runner (`vitest run` for CI, `vitest` for watch). No Node `node:test`.
 - **Contract tests** (`store-contract.ts` + `contract/suites/`): every `DataStore` backend must pass the shared suite. Required for any new backend.
-- **Plugin tests**: use `@covel/plugin-test-utils` — `MockLLM`, `createTestHarness`, `makeTurnInput`, `makeTriggerContext`, `makeRuntimeResult`.
+- **Plugin tests**: use `@covel/plugin-test-utils` — `MockLLM`, `makeManualFunctionContext`, `expectAssetGenerated`, `makeTurnInput`, `makeTriggerContext`, `makeRuntimeResult`.
 - **IDB tests**: `fake-indexeddb` polyfill. **PG tests**: real local DB (`pnpm db:up`).
 - **E2E harness**: `scripts/e2e-plugin-verify.ts` is the API-driven, plugin-level, 7-phase harness (artefacts under `debugs/e2e-logs/`) — see [docs/guide/e2e-plugin-verify.md](./docs/guide/e2e-plugin-verify.md).
 - Coverage via `@vitest/coverage-v8` on all packages (`--coverage` flag).
@@ -323,8 +323,8 @@ Trace chain: `traceId → runId → branchId → turnId → runtimeId → plugin
 
 - **Runtime trace** (DB `trace_events`): structured turn hierarchy — LLM delta messages, tool calls, proposals, hooks, provider binding, context fragments. Delta recording avoids duplicating prompt history.
 - **Infrastructure log** (console, `[component]`-prefixed): startup, plugin loading, DB, SSE connections.
-- **Consumption**: `/api/traces/*`, `TraceExporter` interface (e.g. Langfuse), JSON export for players.
-- **Frontend `/debug`**: Session Timeline · Runtime Inspector · Prompt Viewer (full reconstruction + diff) · Data Explorer · Cost (token-usage aggregation from `llm.responded` / `gateway.responded` trace usage).
+- **Consumption**: `/api/traces/*` endpoints, JSON export for players.
+- **Frontend `/debug`**: Session Timeline · Runtime Inspector · Prompt Viewer (full reconstruction + diff) · Data Explorer · Cost (token-usage aggregation from `llm.responded` / `gateway.responded` trace usage, with per-model USD estimation via model-db pricing — model recovered by pairing each `llm.responded` with the preceding `llm.calling`).
 
 ## Deployment Tiers
 
diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts
index 44ea1730..f039fadd 100644
--- a/apps/server/src/app.ts
+++ b/apps/server/src/app.ts
@@ -239,6 +239,25 @@ const pluginUtils = {
 };
 const preferredMemorySlot = resolvePreferredMemorySlot(ai.slotRegistry);
 
+// Live budget view of the main narrative slot ("default" when configured,
+// else the isDefault/first preset). Resolved per call — never cached — so
+// llm.toml hot-reloads propagate to compaction thresholds and prompt budget.
+// ponytail: ignores per-session runtime_model_overrides and X-Slot-Config
+// overlays; wire the session's actual narrative slot if that ever matters.
+const resolveNarrativeBudget = () => {
+  const presetId = ai.slotRegistry.resolveSlot("default");
+  const capability = ai.presetRegistry.resolvePreset(presetId)?.capability;
+  if (!capability) return undefined;
+  return {
+    ...(capability.contextWindow !== undefined
+      ? { contextWindow: capability.contextWindow }
+      : {}),
+    ...(capability.maxOutputTokens !== undefined
+      ? { maxOutputTokens: capability.maxOutputTokens }
+      : {}),
+  };
+};
+
 // ── Bootstrap API ───────────────────────────────────────────────
 // Bundled plugins ship inside the repo / packaged app. The desktop shell
 // can additionally mount a user plugins directory via COVEL_USER_PLUGINS_DIR
@@ -293,6 +312,7 @@ const api = await bootstrapApi({
   preferredMemorySlot,
   perRequestMiddleware: [perRequestLlm],
   sessionLock,
+  resolveNarrativeBudget,
 });
 
 const seededWorldIds = new Set<string>();
diff --git a/apps/server/src/env.d.ts b/apps/server/src/env.d.ts
index a3db970a..0c65a0b2 100644
--- a/apps/server/src/env.d.ts
+++ b/apps/server/src/env.d.ts
@@ -17,7 +17,7 @@ import type {
 } from "@covel/runtime";
 import type { RpcApprovalGate } from "@covel/approval";
 import type { RuntimeManifest } from "@covel/shared";
-import type { CompactorRunner } from "@covel/context";
+import type { BudgetOptions, CompactorRunner } from "@covel/context";
 import type { SessionLock } from "./lib/session-lock.js";
 import type { EventDirectory } from "./routes/api/bootstrap/event-directory.js";
 
@@ -78,6 +78,12 @@ declare module "hono" {
     getConfigFn: GetConfigFn;
     resolveModel: ResolveModelFn;
     compactorRunner: CompactorRunner;
+    /**
+     * Prompt-assembly hard-prune budget (`applyBudget`), derived from the
+     * narrative slot's model capability. Optional so hand-built test DI
+     * need not wire it — turn routes spread it in conditionally.
+     */
+    turnContextBudget?: Omit<BudgetOptions, "estimator">;
     rpcExecutor: RpcExecutor;
     rpcRegistry: PluginRpcRegistry;
     rpcApprovalGate: RpcApprovalGate;
@@ -88,8 +94,9 @@ declare module "hono" {
      *   - everything else → `createInProcessSessionLock()` — `Map`-based
      *     chain, correct for single-process deployments.
      *
-     * Route handlers MUST use this instead of the legacy `withSessionLock`
-     * import so PG deployments automatically get cross-pod safety.
+     * Route handlers MUST use this instead of a hand-rolled lock; the
+     * historical `withSessionLock` import was replaced by this DI-injected
+     * `sessionLock` so PG deployments automatically get cross-pod safety.
      */
     sessionLock: SessionLock;
     /**
diff --git a/apps/server/src/routes/api/actions.ts b/apps/server/src/routes/api/actions.ts
index 1ed299ed..c6fe6b3b 100644
--- a/apps/server/src/routes/api/actions.ts
+++ b/apps/server/src/routes/api/actions.ts
@@ -19,6 +19,7 @@ import {
 } from "@covel/runtime";
 import type { CovelEventType, RuntimeManifest } from "@covel/shared";
 import { FORWARDED_EVENT_TYPES } from "@covel/shared";
+import { estimateTokens } from "@covel/context";
 import type { CompactorRunner } from "@covel/context";
 import { errorBody } from "../../api-error.js";
 import { rateLimiter } from "../../middleware/rate-limit.js";
@@ -39,6 +40,39 @@ import { checkSessionOwner } from "./session/session-guard.js";
 // SSE uses ProtocolEventType names directly — no legacy mapping.
 // Frontend handleSseEvent handles these standard types.
 
+/**
+ * Memory-system facade injected by bootstrap via `setMemorySystem()`. Kept
+ * out of `Env["Variables"]` because it never flows through Hono's
+ * `c.set`/`c.get` — see the module-level reference below.
+ */
+interface MemorySystemFacade {
+  readonly manager: {
+    loadBlocks(
+      sid: string,
+    ): Promise<
+      readonly { label: string; content: string; updatedAt: string }[]
+    >;
+    initializeDefaults(sid: string): Promise<void>;
+  };
+  readonly updater: {
+    updateAfterTurn(p: {
+      sessionId: string;
+      narrativeText: string;
+      toolCallSummaries?: readonly string[];
+      currentBlocks: readonly {
+        label: string;
+        content: string;
+        updatedAt: string;
+      }[];
+      locale?: string;
+    }): Promise<{
+      updated: boolean;
+      blocksChanged: readonly string[];
+      error?: string;
+    }>;
+  };
+}
+
 type Env = {
   Variables: {
     store: DataStore;
@@ -61,33 +95,6 @@ type Env = {
     compactorRunner: CompactorRunner;
     mediaStore?: MediaStore;
     hookPipeline?: HookPipeline;
-    memorySystem?: {
-      readonly manager: {
-        loadBlocks(
-          sid: string,
-        ): Promise<
-          readonly { label: string; content: string; updatedAt: string }[]
-        >;
-        initializeDefaults(sid: string): Promise<void>;
-      };
-      readonly updater: {
-        updateAfterTurn(p: {
-          sessionId: string;
-          narrativeText: string;
-          toolCallSummaries?: readonly string[];
-          currentBlocks: readonly {
-            label: string;
-            content: string;
-            updatedAt: string;
-          }[];
-          locale?: string;
-        }): Promise<{
-          updated: boolean;
-          blocksChanged: readonly string[];
-          error?: string;
-        }>;
-      };
-    };
     ensureEmbeddingLock?: (sessionId: string) => Promise<void>;
   };
 };
@@ -97,8 +104,8 @@ export const actionRoutes = new Hono<Env>();
 // Module-level memory system reference, set by bootstrap via setMemorySystem().
 // Using a module variable instead of Hono context because Hono's typed
 // c.set/c.get doesn't support optional cross-module types cleanly.
-let _memorySystem: Env["Variables"]["memorySystem"] | undefined;
-export function setMemorySystem(ms: Env["Variables"]["memorySystem"]) {
+let _memorySystem: MemorySystemFacade | undefined;
+export function setMemorySystem(ms: MemorySystemFacade | undefined) {
   _memorySystem = ms;
 }
 
@@ -124,6 +131,7 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
   const resolveModel = c.get("resolveModel");
   const eventBus = c.get("eventBus");
   const compactorRunner = c.get("compactorRunner");
+  const turnContextBudget = c.get("turnContextBudget");
   const sessionLock = c.get("sessionLock");
   const mediaStore = c.get("mediaStore");
   const eventDirectory = c.get("eventDirectory");
@@ -506,6 +514,14 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
                 });
               },
               compactor: compactorRunner,
+              // Prompt-assembly hard prune — last line of defense when
+              // compaction is skipped/vetoed/insufficient for the model window.
+              ...(turnContextBudget
+                ? {
+                    estimator: estimateTokens,
+                    contextBudget: turnContextBudget,
+                  }
+                : {}),
               memorySystem: _memorySystem,
               // Let the turn executor construct a unified SessionContextSnapshot.
               capabilityPluginIds,
@@ -614,6 +630,9 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
             toolExecutor,
             resolveModel,
             compactor: compactorRunner,
+            ...(turnContextBudget
+              ? { estimator: estimateTokens, contextBudget: turnContextBudget }
+              : {}),
             capabilityPluginIds,
             ...(eventDirectory ? { eventDirectory } : {}),
           },
diff --git a/apps/server/src/routes/api/bootstrap.ts b/apps/server/src/routes/api/bootstrap.ts
index bfa7d5c2..2b51029a 100644
--- a/apps/server/src/routes/api/bootstrap.ts
+++ b/apps/server/src/routes/api/bootstrap.ts
@@ -66,7 +66,11 @@ import { runtimeOutputRoutes } from "./runtime-outputs.js";
 import { pluginRpcRoutes } from "./plugin-rpc.js";
 import { approvalRoutes, sessionApprovalRoutes } from "./approvals.js";
 export { wrapStoreWithPluginDataEvents } from "./bootstrap/plugin-data-store-events.js";
-import { createBootstrapCompactorRunner } from "./bootstrap/compactor.js";
+import {
+  createBootstrapCompactorRunner,
+  createTurnContextBudget,
+  type ResolveNarrativeBudgetFn,
+} from "./bootstrap/compactor.js";
 import { discoverAndRegisterPlugins } from "./bootstrap/plugin-discovery.js";
 import { createBootstrapHookPipeline } from "./bootstrap/plugin-hooks.js";
 import { setupPluginTools } from "./bootstrap/tools.js";
@@ -175,6 +179,13 @@ export interface ApiBootstrapConfig {
   readonly mediaStore?: MediaStore;
   readonly mediaBackend?: MediaStoreBackend;
   readonly vectorBackend?: VectorBackend;
+  /**
+   * Live view of the main narrative slot's model budget (contextWindow /
+   * maxOutputTokens), built by the composition root against the AI
+   * registries. Drives the compaction threshold and the prompt-assembly
+   * hard prune. Absent (tests, minimal harnesses) → fixed fallback window.
+   */
+  readonly resolveNarrativeBudget?: ResolveNarrativeBudgetFn;
 }
 
 export interface ApiBootstrapResult {
@@ -493,12 +504,21 @@ export async function bootstrapApi(
   };
 
   const runtimeEnv = readRuntimeEnv();
+  const budgetSource = {
+    ...(runtimeEnv.compactorContextWindow !== undefined
+      ? { contextWindowOverride: runtimeEnv.compactorContextWindow }
+      : {}),
+    ...(config.resolveNarrativeBudget
+      ? { resolveNarrativeBudget: config.resolveNarrativeBudget }
+      : {}),
+  };
   const compactorRunner = createBootstrapCompactorRunner({
     manifestCache,
     store,
     llmAdapter: config.llmAdapter,
-    contextWindow: runtimeEnv.compactorContextWindow,
+    ...budgetSource,
   });
+  const turnContextBudget = createTurnContextBudget(budgetSource);
 
   // 8. Create memory system (Letta-style three-tier memory)
   const bootstrapMemory = createBootstrapMemorySystem({
@@ -545,6 +565,7 @@ export async function bootstrapApi(
     c.set("getConfigFn", getConfigFn);
     c.set("resolveModel", resolveModel);
     c.set("compactorRunner", compactorRunner);
+    c.set("turnContextBudget", turnContextBudget);
     c.set("hookPipeline", hookPipeline);
     c.set("eventDirectory", eventDirectory);
     // memorySystem injected via module-level setter, not Hono context
diff --git a/apps/server/src/routes/api/bootstrap/compactor.ts b/apps/server/src/routes/api/bootstrap/compactor.ts
index 5419eb70..ad6c077f 100644
--- a/apps/server/src/routes/api/bootstrap/compactor.ts
+++ b/apps/server/src/routes/api/bootstrap/compactor.ts
@@ -1,25 +1,61 @@
 import type { LLMAdapter } from "@covel/runtime";
 import type { DataStore } from "@covel/store";
 import {
+  estimateTokens,
   maybeCompact,
+  type BudgetOptions,
   type CompactorLLMAdapter,
   type CompactorRunner,
 } from "@covel/context";
 import type { ParsedPluginMd } from "@covel/plugin-loader";
 
-export interface CreateBootstrapCompactorRunnerParams {
+/**
+ * Last-resort context window when neither an explicit env override nor a
+ * model-capability lookup yields a value (e.g. an unknown model with no
+ * llm.toml capability block).
+ */
+const FALLBACK_CONTEXT_WINDOW = 32768;
+
+/** Matches applyBudget's own default; explicit here because getters can't omit. */
+const DEFAULT_RESERVED_FOR_RESPONSE = 4000;
+
+/**
+ * Live view of the main narrative slot's model budget. Implemented in the
+ * composition root (app.ts) against the AI registries so llm.toml hot-reloads
+ * are observed without a server restart — resolve on every call, never cache.
+ */
+export type ResolveNarrativeBudgetFn = () =>
+  | {
+      readonly contextWindow?: number;
+      readonly maxOutputTokens?: number;
+    }
+  | undefined;
+
+interface BudgetSourceParams {
+  /** Explicit COVEL_COMPACTOR_CONTEXT_WINDOW override — wins over capability. */
+  readonly contextWindowOverride?: number;
+  readonly resolveNarrativeBudget?: ResolveNarrativeBudgetFn;
+}
+
+/** Resolution order: env override > slot model capability > fallback. */
+function resolveContextWindow(params: BudgetSourceParams): number {
+  return (
+    params.contextWindowOverride ??
+    params.resolveNarrativeBudget?.()?.contextWindow ??
+    FALLBACK_CONTEXT_WINDOW
+  );
+}
+
+export interface CreateBootstrapCompactorRunnerParams extends BudgetSourceParams {
   readonly manifestCache: ReadonlyMap<string, readonly ParsedPluginMd[]>;
   readonly store: DataStore;
   readonly llmAdapter: LLMAdapter;
-  readonly contextWindow: number;
 }
 
-export function createBootstrapCompactorRunner({
-  manifestCache,
-  store,
-  llmAdapter,
-  contextWindow,
-}: CreateBootstrapCompactorRunnerParams): CompactorRunner {
+export function createBootstrapCompactorRunner(
+  params: CreateBootstrapCompactorRunnerParams,
+): CompactorRunner {
+  const { manifestCache, store, llmAdapter } = params;
   const allSummaryFocus = new Set<string>();
   for (const [, manifests] of manifestCache) {
     for (const parsed of manifests) {
@@ -29,15 +65,14 @@ export function createBootstrapCompactorRunner({
     }
   }
   const focusSections: readonly string[] = [...allSummaryFocus];
-  const simpleEstimator = (text: string): number => Math.ceil(text.length / 4);
 
   const fastSlotLlm: CompactorLLMAdapter = {
-    async complete(params) {
+    async complete(input) {
       const response = await llmAdapter.generate({
         model: "fast",
         messages: [
-          { role: "system", content: params.systemPrompt },
-          ...params.messages.map((m) => ({
+          { role: "system", content: input.systemPrompt },
+          ...input.messages.map((m) => ({
             role: m.role as "user",
             content: m.content,
           })),
@@ -61,9 +96,10 @@ export function createBootstrapCompactorRunner({
         messages,
         {
           store,
-          estimator: simpleEstimator,
+          estimator: estimateTokens,
           fastSlotLlm,
-          contextWindow,
+          // Resolved per run so llm.toml hot-reloads take effect immediately.
+          contextWindow: resolveContextWindow(params),
         },
         {
           focusSections,
@@ -74,3 +110,24 @@ export function createBootstrapCompactorRunner({
     },
   };
 }
+
+/**
+ * Budget config for the prompt-assembly hard prune (`applyBudget`) — the last
+ * line of defense when compaction is skipped, vetoed, or insufficient.
+ * Getter-based so each turn observes the current llm.toml capability.
+ */
+export function createTurnContextBudget(
+  params: BudgetSourceParams,
+): Omit<BudgetOptions, "estimator"> {
+  return {
+    get maxInputTokens(): number {
+      return resolveContextWindow(params);
+    },
+    get reservedForResponse(): number {
+      return (
+        params.resolveNarrativeBudget?.()?.maxOutputTokens ??
+        DEFAULT_RESERVED_FOR_RESPONSE
+      );
+    },
+  };
+}
diff --git a/apps/server/src/routes/api/plugin-rpc.ts b/apps/server/src/routes/api/plugin-rpc.ts
index 0323b601..411d76de 100644
--- a/apps/server/src/routes/api/plugin-rpc.ts
+++ b/apps/server/src/routes/api/plugin-rpc.ts
@@ -34,6 +34,7 @@
  */
 
 import { Hono } from "hono";
+import { estimateTokens } from "@covel/context";
 import { COMMUNITY_SERVER_CODE_ACTION } from "@covel/approval";
 import { createRpcHandlerStoreView } from "@covel/runtime";
 import { RpcDispatchError, RpcValidationError } from "@covel/runtime";
@@ -116,6 +117,7 @@ pluginRpcRoutes.post("/:id/plugin-rpc", rateLimiter({ max: 30 }), async (c) => {
     const resolveModel = c.get("resolveModel");
     const eventBus = c.get("eventBus");
     const compactorRunner = c.get("compactorRunner");
+    const turnContextBudget = c.get("turnContextBudget");
     const hookPipeline = c.get("hookPipeline");
     const sessionLock = c.get("sessionLock");
     const mediaStore = c.get("mediaStore");
@@ -260,6 +262,9 @@ pluginRpcRoutes.post("/:id/plugin-rpc", rateLimiter({ max: 30 }), async (c) => {
         // then can't tell the runtime ever finished. Wire it through so
         // manual-trigger turns produce the same trace surface as auto turns.
         compactor: compactorRunner,
+        ...(turnContextBudget
+          ? { estimator: estimateTokens, contextBudget: turnContextBudget }
+          : {}),
         capabilityPluginIds,
         ...(hookPipeline ? { hookPipeline } : {}),
         ...(eventDirectory ? { eventDirectory } : {}),
diff --git a/apps/server/tests/bootstrap/turn-context-budget.test.ts b/apps/server/tests/bootstrap/turn-context-budget.test.ts
new file mode 100644
index 00000000..99349e59
--- /dev/null
+++ b/apps/server/tests/bootstrap/turn-context-budget.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { createTurnContextBudget } from "../../src/routes/api/bootstrap/compactor.js";
+
+describe("createTurnContextBudget", () => {
+  it("prefers the explicit env override over capability", () => {
+    const budget = createTurnContextBudget({
+      contextWindowOverride: 8000,
+      resolveNarrativeBudget: () => ({
+        contextWindow: 128_000,
+        maxOutputTokens: 8192,
+      }),
+    });
+
+    expect(budget.maxInputTokens).toBe(8000);
+    // reservedForResponse still comes from capability — the override only
+    // pins the window.
+    expect(budget.reservedForResponse).toBe(8192);
+  });
+
+  it("derives window and reserve from the narrative slot capability", () => {
+    const budget = createTurnContextBudget({
+      resolveNarrativeBudget: () => ({
+        contextWindow: 200_000,
+        maxOutputTokens: 16_000,
+      }),
+    });
+
+    expect(budget.maxInputTokens).toBe(200_000);
+    expect(budget.reservedForResponse).toBe(16_000);
+  });
+
+  it("falls back to 32768 / 4000 when no source is available", () => {
+    const budget = createTurnContextBudget({});
+
+    expect(budget.maxInputTokens).toBe(32_768);
+    expect(budget.reservedForResponse).toBe(4000);
+  });
+
+  it("re-resolves capability on every access (llm.toml hot-reload)", () => {
+    let window = 64_000;
+    const budget = createTurnContextBudget({
+      resolveNarrativeBudget: () => ({ contextWindow: window }),
+    });
+
+    expect(budget.maxInputTokens).toBe(64_000);
+    window = 1_000_000;
+    expect(budget.maxInputTokens).toBe(1_000_000);
+  });
+});
diff --git a/apps/web/src/i18n/locales/en-US.json b/apps/web/src/i18n/locales/en-US.json
index a8735ad9..40b54e8a 100644
--- a/apps/web/src/i18n/locales/en-US.json
+++ b/apps/web/src/i18n/locales/en-US.json
@@ -906,17 +906,6 @@
       "enemy": "Enemy"
     }
   },
-  "lorebook": {
-    "title": "Lorebook",
-    "refresh": "Refresh",
-    "deleteConfirm": "Delete entry \"{{id}}\"? This cannot be undone.",
-    "noEntries": "No session lorebook entries yet",
-    "enable": "Enable",
-    "disable": "Disable",
-    "delete": "Delete",
-    "expand": "Expand",
-    "collapse": "Collapse"
-  },
   "graph": {
     "empty": "Graph is currently empty — waiting for NPCs to appear.",
     "clearSelection": "Clear selection",
@@ -1038,7 +1027,11 @@
       "calls": "LLM calls",
       "byRuntime": "By runtime",
       "byTurn": "By turn",
-      "note": "Token sums from llm.responded / gateway.responded. USD cost is a pending follow-up (model id not yet in the trace payload).",
+      "byModel": "By model",
+      "estCost": "Est. cost (USD)",
+      "unknownModel": "(unknown model)",
+      "noPrice": "no price",
+      "note": "Token sums from llm.responded / gateway.responded. USD cost estimated from model-db prices; usage without a model id or price is excluded (cost shown as a lower bound).",
       "noData": "No token usage recorded for this session.",
       "windowTitle": "Loaded window",
       "partialNote": "Only the most recent window is loaded — totals below are partial.",
diff --git a/apps/web/src/i18n/locales/zh-CN.json b/apps/web/src/i18n/locales/zh-CN.json
index 3d29d7f2..1fedfec0 100644
--- a/apps/web/src/i18n/locales/zh-CN.json
+++ b/apps/web/src/i18n/locales/zh-CN.json
@@ -906,17 +906,6 @@
       "enemy": "敌人"
     }
   },
-  "lorebook": {
-    "title": "知识库",
-    "refresh": "刷新",
-    "deleteConfirm": "删除词条 \"{{id}}\"？此操作无法撤销。",
-    "noEntries": "尚无 session lorebook 词条",
-    "enable": "启用",
-    "disable": "禁用",
-    "delete": "删除",
-    "expand": "展开",
-    "collapse": "收起"
-  },
   "graph": {
     "empty": "关系图当前为空——等待 NPC 出现。",
     "clearSelection": "清除选中",
@@ -1038,7 +1027,11 @@
       "calls": "LLM 调用",
       "byRuntime": "按 runtime",
       "byTurn": "按回合",
-      "note": "token 求和来自 llm.responded / gateway.responded。美元成本为待办 follow-up（model id 尚未进入 trace 负载）。",
+      "byModel": "按模型",
+      "estCost": "估算成本 (USD)",
+      "unknownModel": "（未知模型）",
+      "noPrice": "无价格",
+      "note": "token 求和来自 llm.responded / gateway.responded。美元成本按 model-db 价格估算；无 model id 或无价格的用量不计入（此时显示为下限值）。",
       "noData": "本会话暂无 token 用量记录。",
       "windowTitle": "已加载窗口",
       "partialNote": "仅加载最近一段窗口，下方合计为部分值。",
diff --git a/apps/web/src/routes/debug/-cost-panel.tsx b/apps/web/src/routes/debug/-cost-panel.tsx
index 5b56e3b6..5ede3c5a 100644
--- a/apps/web/src/routes/debug/-cost-panel.tsx
+++ b/apps/web/src/routes/debug/-cost-panel.tsx
@@ -1,20 +1,29 @@
-import { useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
+import { lookupModelCapability } from "@/services/api.js";
 import type * as api from "@/services/api.js";
 import type { VisibleTurn } from "./-debug-page-model.js";
 
 /**
- * Token usage panel — aggregates `usage` from the persisted `llm.responded` /
- * `gateway.responded` trace events (per runtime, per turn, session total).
+ * Token usage + estimated cost panel — aggregates `usage` from the persisted
+ * `llm.responded` / `gateway.responded` trace events (per runtime, per turn,
+ * per model, session total).
  *
  * Aggregates generically by event type + runtimeId, never hardcoding a plugin
- * ID. USD cost conversion is intentionally NOT done here: `llm.responded`
- * payloads do not yet carry the model id, so `usage × pricing` would be
- * incomplete — that is a separate follow-up (thread model into the trace
- * payload, then sum via the server-side `resolveCapability` for a single
- * pricing source of truth).
+ * ID. Model attribution: `llm.responded` payloads carry no model id, so each
+ * usage event is paired with the most recent `llm.calling` for the same
+ * runtimeId within the turn (events are stored in emission order, and
+ * calling/responded always pair up per call). `gateway.responded` carries a
+ * slot (presetId), not a model — its usage stays unattributed and is excluded
+ * from pricing, making the USD figure a lower bound when present.
+ *
+ * Pricing comes from `/api/model-db/lookup` (LiteLLM-derived per-M-token
+ * prices) via the existing `lookupModelCapability` service.
  */
 
+/** Sentinel for usage that cannot be attributed to a concrete model id. */
+export const UNKNOWN_MODEL = "(unknown)";
+
 interface Usage {
   readonly inputTokens: number;
   readonly outputTokens: number;
@@ -50,16 +59,25 @@ interface TurnAgg {
   outputTokens: number;
 }
 
+interface ModelAgg {
+  readonly model: string;
+  calls: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
 interface CostModel {
   readonly totalCalls: number;
   readonly totalInput: number;
   readonly totalOutput: number;
   readonly byRuntime: readonly RuntimeAgg[];
   readonly byTurn: readonly TurnAgg[];
+  readonly byModel: readonly ModelAgg[];
 }
 
 export function aggregate(turns: readonly VisibleTurn[]): CostModel {
   const runtimeMap = new Map<string, RuntimeAgg>();
+  const modelMap = new Map<string, ModelAgg>();
   const byTurn: TurnAgg[] = [];
   let totalCalls = 0;
   let totalInput = 0;
@@ -69,12 +87,32 @@ export function aggregate(turns: readonly VisibleTurn[]): CostModel {
     let turnCalls = 0;
     let turnInput = 0;
     let turnOutput = 0;
+    // Sequential pairing: remember the model announced by the latest
+    // `llm.calling` per runtime so the next `llm.responded` inherits it.
+    const lastModelByRuntime = new Map<string, string>();
     for (const event of turn.events) {
+      const payload = event.payload as Record<string, unknown>;
+      if (event.type === "llm.calling") {
+        const rid = payload.runtimeId as string | undefined;
+        const mdl = payload.model as string | undefined;
+        if (rid && mdl) lastModelByRuntime.set(rid, mdl);
+        continue;
+      }
       const usage = readUsage(event);
       if (!usage) continue;
-      const payload = event.payload as Record<string, unknown>;
       const runtimeId = (payload.runtimeId as string) || "(unknown)";
       const pluginId = (payload.pluginId as string) || "";
+      const model =
+        event.type === "llm.responded"
+          ? (lastModelByRuntime.get(runtimeId) ?? UNKNOWN_MODEL)
+          : UNKNOWN_MODEL;
+      const prevModel = modelMap.get(model);
+      modelMap.set(model, {
+        model,
+        calls: (prevModel?.calls ?? 0) + 1,
+        inputTokens: (prevModel?.inputTokens ?? 0) + usage.inputTokens,
+        outputTokens: (prevModel?.outputTokens ?? 0) + usage.outputTokens,
+      });
       // Immutable accumulate: replace the map entry with a fresh object
       // rather than mutating the stored one in place.
       const prev = runtimeMap.get(runtimeId);
@@ -106,7 +144,71 @@ export function aggregate(turns: readonly VisibleTurn[]): CostModel {
   const byRuntime = [...runtimeMap.values()].sort(
     (a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens),
   );
-  return { totalCalls, totalInput, totalOutput, byRuntime, byTurn };
+  const byModel = [...modelMap.values()].sort(
+    (a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens),
+  );
+  return { totalCalls, totalInput, totalOutput, byRuntime, byTurn, byModel };
+}
+
+// ── Pricing ──────────────────────────────────────────────────────
+
+interface ModelPrice {
+  readonly inputPerMToken?: number;
+  readonly outputPerMToken?: number;
+}
+
+/** Module-level lookup cache — model prices don't change within a page visit. */
+const priceCache = new Map<string, Promise<ModelPrice | null>>();
+
+function lookupPrice(model: string): Promise<ModelPrice | null> {
+  const cached = priceCache.get(model);
+  if (cached) return cached;
+  const promise = lookupModelCapability(model)
+    .then((cap) =>
+      cap &&
+      (cap.inputPerMToken !== undefined || cap.outputPerMToken !== undefined)
+        ? {
+            ...(cap.inputPerMToken !== undefined
+              ? { inputPerMToken: cap.inputPerMToken }
+              : {}),
+            ...(cap.outputPerMToken !== undefined
+              ? { outputPerMToken: cap.outputPerMToken }
+              : {}),
+          }
+        : null,
+    )
+    .catch(() => null);
+  priceCache.set(model, promise);
+  return promise;
+}
+
+/** Resolve per-M-token prices for the given models (null = no pricing data). */
+function useModelPrices(
+  models: readonly string[],
+): Record<string, ModelPrice | null> {
+  const [prices, setPrices] = useState<Record<string, ModelPrice | null>>({});
+  useEffect(() => {
+    let cancelled = false;
+    const missing = models.filter((m) => m !== UNKNOWN_MODEL && !(m in prices));
+    if (missing.length === 0) return;
+    void Promise.all(
+      missing.map(async (m) => [m, await lookupPrice(m)] as const),
+    ).then((entries) => {
+      if (cancelled) return;
+      setPrices((prev) => ({ ...prev, ...Object.fromEntries(entries) }));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [models, prices]);
+  return prices;
+}
+
+function costUsd(agg: ModelAgg, price: ModelPrice): number {
+  return (
+    (agg.inputTokens / 1_000_000) * (price.inputPerMToken ?? 0) +
+    (agg.outputTokens / 1_000_000) * (price.outputPerMToken ?? 0)
+  );
 }
 
 function fmt(n: number): string {
@@ -143,6 +245,27 @@ export function CostPanel({
     1,
     ...model.byRuntime.map((r) => r.inputTokens + r.outputTokens),
   );
+  const modelIds = useMemo(
+    () => model.byModel.map((m) => m.model),
+    [model.byModel],
+  );
+  const prices = useModelPrices(modelIds);
+  const cost = useMemo(() => {
+    let usd = 0;
+    let pricedTokens = 0;
+    let unpricedTokens = 0;
+    for (const agg of model.byModel) {
+      const price = agg.model === UNKNOWN_MODEL ? null : prices[agg.model];
+      const tokens = agg.inputTokens + agg.outputTokens;
+      if (price) {
+        usd += costUsd(agg, price);
+        pricedTokens += tokens;
+      } else {
+        unpricedTokens += tokens;
+      }
+    }
+    return { usd, pricedTokens, unpricedTokens };
+  }, [model.byModel, prices]);
 
   if (model.totalCalls === 0) {
     return (
@@ -200,15 +323,53 @@ export function CostPanel({
             label={t("debugger.cost.calls", "LLM calls")}
             value={fmt(model.totalCalls)}
           />
+          {cost.pricedTokens > 0 && (
+            <StatCard
+              label={t("debugger.cost.estCost", "Est. cost (USD)")}
+              value={`${cost.unpricedTokens > 0 ? "≥ " : "≈ "}$${cost.usd.toFixed(4)}`}
+            />
+          )}
         </div>
         <p className="ui-meta text-[9px] text-muted-foreground/70">
           {t(
             "debugger.cost.note",
-            "Token sums from llm.responded / gateway.responded. USD cost is a pending follow-up (model id not yet in the trace payload).",
+            "Token sums from llm.responded / gateway.responded. USD cost estimated from model-db prices; usage without a model id or price is excluded (cost shown as a lower bound).",
           )}
         </p>
       </section>
 
+      {/* By model */}
+      {model.byModel.length > 0 && (
+        <section className="space-y-2">
+          <h2 className="ui-meta text-[10px] uppercase tracking-wider text-muted-foreground">
+            {t("debugger.cost.byModel", "By model")}
+          </h2>
+          <div className="border border-[var(--rule-color)] divide-y divide-[var(--rule-color)]">
+            {model.byModel.map((m) => {
+              const price = m.model === UNKNOWN_MODEL ? null : prices[m.model];
+              return (
+                <div
+                  key={m.model}
+                  className="flex items-baseline justify-between gap-3 px-3 py-1.5 text-[11px]"
+                >
+                  <span className="font-mono truncate text-foreground">
+                    {m.model === UNKNOWN_MODEL
+                      ? t("debugger.cost.unknownModel", "(unknown model)")
+                      : m.model}
+                  </span>
+                  <span className="font-mono tabular-nums text-muted-foreground shrink-0">
+                    {fmt(m.inputTokens)} → {fmt(m.outputTokens)} · {m.calls}× ·{" "}
+                    {price
+                      ? `$${costUsd(m, price).toFixed(4)}`
+                      : t("debugger.cost.noPrice", "no price")}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        </section>
+      )}
+
       {/* By runtime */}
       <section className="space-y-2">
         <h2 className="ui-meta text-[10px] uppercase tracking-wider text-muted-foreground">
diff --git a/apps/web/src/routes/debug/__tests__/-cost-panel.test.ts b/apps/web/src/routes/debug/__tests__/-cost-panel.test.ts
index 5975da43..666b3463 100644
--- a/apps/web/src/routes/debug/__tests__/-cost-panel.test.ts
+++ b/apps/web/src/routes/debug/__tests__/-cost-panel.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import type * as api from "@/services/api.js";
-import { aggregate } from "../-cost-panel.js";
+import { aggregate, UNKNOWN_MODEL } from "../-cost-panel.js";
 import type { VisibleTurn } from "../-debug-page-model.js";
 
 function evt(type: string, payload: Record<string, unknown>): api.TraceEvent {
@@ -99,5 +99,91 @@ describe("cost-panel aggregate", () => {
     expect(m.totalCalls).toBe(0);
     expect(m.byRuntime).toHaveLength(0);
     expect(m.byTurn).toHaveLength(0);
+    expect(m.byModel).toHaveLength(0);
+  });
+
+  it("attributes llm.responded usage to the preceding llm.calling model", () => {
+    const turns = [
+      turn(1, "turn-1", [
+        evt("llm.calling", { runtimeId: "narrator", model: "deepseek-chat" }),
+        evt("llm.responded", {
+          runtimeId: "narrator",
+          pluginId: "narrator",
+          ...usage(100, 50),
+        }),
+        // Second tool-loop round on the same runtime, different model —
+        // sequential pairing must pick the latest calling event.
+        evt("llm.calling", { runtimeId: "narrator", model: "gpt-4o" }),
+        evt("llm.responded", {
+          runtimeId: "narrator",
+          pluginId: "narrator",
+          ...usage(30, 10),
+        }),
+      ]),
+    ];
+
+    const m = aggregate(turns);
+
+    expect(m.byModel).toHaveLength(2);
+    const deepseek = m.byModel.find((x) => x.model === "deepseek-chat")!;
+    expect(deepseek.inputTokens).toBe(100);
+    expect(deepseek.outputTokens).toBe(50);
+    const gpt = m.byModel.find((x) => x.model === "gpt-4o")!;
+    expect(gpt.inputTokens).toBe(30);
+    expect(gpt.calls).toBe(1);
+  });
+
+  it("groups unattributable usage under the unknown-model bucket", () => {
+    const turns = [
+      turn(1, "turn-1", [
+        // gateway.responded carries no model id.
+        evt("gateway.responded", {
+          runtimeId: "img",
+          pluginId: "img",
+          ...usage(5, 1),
+        }),
+        // llm.responded with no prior llm.calling for that runtime.
+        evt("llm.responded", {
+          runtimeId: "orphan",
+          pluginId: "orphan",
+          ...usage(7, 2),
+        }),
+      ]),
+    ];
+
+    const m = aggregate(turns);
+
+    expect(m.byModel).toHaveLength(1);
+    expect(m.byModel[0]!.model).toBe(UNKNOWN_MODEL);
+    expect(m.byModel[0]!.inputTokens).toBe(12);
+    expect(m.byModel[0]!.calls).toBe(2);
+  });
+
+  it("does not leak model pairing across turns", () => {
+    const turns = [
+      turn(1, "turn-1", [
+        evt("llm.calling", { runtimeId: "narrator", model: "deepseek-chat" }),
+        evt("llm.responded", {
+          runtimeId: "narrator",
+          pluginId: "narrator",
+          ...usage(10, 5),
+        }),
+      ]),
+      turn(2, "turn-2", [
+        // No llm.calling this turn — must NOT inherit turn-1's model.
+        evt("llm.responded", {
+          runtimeId: "narrator",
+          pluginId: "narrator",
+          ...usage(20, 8),
+        }),
+      ]),
+    ];
+
+    const m = aggregate(turns);
+
+    const deepseek = m.byModel.find((x) => x.model === "deepseek-chat")!;
+    expect(deepseek.inputTokens).toBe(10);
+    const unknown = m.byModel.find((x) => x.model === UNKNOWN_MODEL)!;
+    expect(unknown.inputTokens).toBe(20);
   });
 });
diff --git a/apps/web/src/services/api/llm.ts b/apps/web/src/services/api/llm.ts
index 636669bb..7355049e 100644
--- a/apps/web/src/services/api/llm.ts
+++ b/apps/web/src/services/api/llm.ts
@@ -37,6 +37,14 @@ export interface ModelCapabilityInfo {
   contextWindow?: number;
   maxOutputTokens?: number;
   pricing?: ModelPricing;
+  /**
+   * Flat per-M-token prices as actually returned by
+   * `GET /api/model-db/lookup` (see routes/model-db.ts) — that endpoint
+   * sends these alongside contextWindow/maxOutputTokens instead of a
+   * nested `pricing` object.
+   */
+  inputPerMToken?: number;
+  outputPerMToken?: number;
 }
 
 export interface LlmSlotInfo {
@@ -92,32 +100,10 @@ export interface ModelDbInfo {
   source?: string;
 }
 
-export interface ModelDbSearchResult {
-  id: string;
-  input: InputModality[];
-  output: OutputModality[];
-  features: ModelFeature[];
-  contextWindow: number;
-  maxOutputTokens: number;
-  mode: string;
-  inputPerMToken?: number;
-  outputPerMToken?: number;
-}
-
 export async function fetchModelDbInfo(): Promise<ModelDbInfo> {
   return request<ModelDbInfo>("/api/model-db");
 }
 
-export async function searchModelDb(
-  query: string,
-  limit = 20,
-): Promise<ModelDbSearchResult[]> {
-  const res = await request<{ results: ModelDbSearchResult[] }>(
-    `/api/model-db/search?q=${encodeURIComponent(query)}&limit=${limit}`,
-  );
-  return res.results;
-}
-
 export async function lookupModelCapability(
   model: string,
   provider?: string,
diff --git a/docs/guide/env-registry.md b/docs/guide/env-registry.md
index cd8c0c8c..9e5fd08d 100644
--- a/docs/guide/env-registry.md
+++ b/docs/guide/env-registry.md
@@ -10,16 +10,16 @@ Covel 的环境变量清单由 `packages/shared/src/env/registry.ts` 维护。
 
 ## 分组
 
-| group       | 用途                                                         |
-| ----------- | ------------------------------------------------------------ |
-| `storage`   | `STORE_BACKEND`、`DATABASE_URL`、SQLite / PostgreSQL 配置    |
-| `server`    | 端口、CORS、静态资源、部署层级、限流                         |
-| `desktop`   | Electron 注入给 server sidecar 的路径与桌面模式配置          |
-| `ai`        | LLM 配置、provider keys、Langfuse、模型数据库、prompt 根目录 |
-| `feature`   | 运行期功能开关                                               |
-| `web`       | Vite dev proxy 与浏览器侧公开变量                            |
-| `test`      | Playwright、live provider tests、e2e harness、开发脚本       |
-| `packaging` | Electron 签名、公证、updater 密钥                            |
+| group       | 用途                                                      |
+| ----------- | --------------------------------------------------------- |
+| `storage`   | `STORE_BACKEND`、`DATABASE_URL`、SQLite / PostgreSQL 配置 |
+| `server`    | 端口、CORS、静态资源、部署层级、限流                      |
+| `desktop`   | Electron 注入给 server sidecar 的路径与桌面模式配置       |
+| `ai`        | LLM 配置、provider keys、模型数据库、prompt 根目录        |
+| `feature`   | 运行期功能开关                                            |
+| `web`       | Vite dev proxy 与浏览器侧公开变量                         |
+| `test`      | Playwright、live provider tests、e2e harness、开发脚本    |
+| `packaging` | Electron 签名、公证、updater 密钥                         |
 
 ## 状态
 
@@ -57,6 +57,7 @@ Covel 的环境变量清单由 `packages/shared/src/env/registry.ts` 维护。
 - `COVEL_BIND_HOST` 默认 `127.0.0.1`（audit S-02）：本地 / 桌面部署只监听回环接口，网络上不可达。容器或多 pod 部署需显式设置 `COVEL_BIND_HOST=0.0.0.0`（`docker/docker-compose.yml` 已内置）——这是一次显式的部署决策，公开监听前请确认 `DEPLOYMENT_TIER` 与鉴权配置。
 - `TRUSTED_PROXY_IPS`、`COVEL_LLM_REPLAY`、`COVEL_LLM_REPLAY_DIR`、`COVEL_ALLOWED_LLM_HOSTS` 目前标记为 `documented`，后续实现可以直接提升为 `active`。
 - `COVEL_TRACE_TRUNCATE` 标记为 `planned`，对应 debug trace 设计文档中的未来开关。
+- `COVEL_COMPACTOR_CONTEXT_WINDOW` 为**可选的显式覆盖**：未设置时，压缩阈值与 prompt 硬裁剪预算按当前叙事 slot（`default`，缺省为 llm.toml 首个 slot）的模型 capability `contextWindow` 动态解析（llm.toml 热重载即时生效），capability 也缺失时回退 `32768`。设置后固定使用该值，不再查 capability。
 - `COVEL_SNAPSHOT_INTERVAL_TURNS` 默认 `5`，控制 `kind=auto` 快照的 checkpoint 节奏：`turnCount <= 1`（pre-game 与首个正式回合）总是写入，其后每 N 回合写一份；`1` 表示每回合。resume 路径无视该节流强制写入。构建快照 payload 需要全量读取消息历史与全部 session-scoped 集合，逐回合写入会导致 O(T²) 成本与存储膨胀（audit 2026-07-11 R-04）。
 - `COVEL_MEDIA_CLEANUP_ENABLED` 默认 `false`，控制 `POST /api/media/cleanup` 的可用性。即使设为 `true`，`DEPLOYMENT_TIER=commercial` 时该端点仍强制 503，等待管理员鉴权中间件接入。详见 [`docs/reference/api.md`](../reference/api.md) 媒体管理章节。
 - `COVEL_PG_LOCK_POOL_MAX` 默认 `16`，控制 PG advisory session-lock 专用连接池的 `max`。每个进行中的 turn 占用一条 reserved 连接；多并发 pod 可按峰值并发会话数调大。锁获取超时（30s）覆盖连接池排队 + advisory lock 轮询全程。
diff --git a/packages/context/src/budget.ts b/packages/context/src/budget.ts
index 171f82c5..ba79f1e1 100644
--- a/packages/context/src/budget.ts
+++ b/packages/context/src/budget.ts
@@ -36,6 +36,28 @@ function flattenContent(content: string | readonly ContentPart[]): string {
  */
 export type TokenEstimator = (text: string) => number;
 
+/**
+ * CJK ranges: radicals/kana/ideographs (2E80–9FFF), Hangul syllables
+ * (AC00–D7AF), compatibility ideographs (F900–FAFF), fullwidth forms
+ * (FF00–FFEF).
+ */
+const CJK_RE = /[⺀-鿿가-힯豈-﫿＀-￯]/g;
+
+/**
+ * Default character-heuristic token estimator, CJK-aware.
+ *
+ * The naive `chars / 4` rule undercounts CJK text ~3× (CJK runs at roughly
+ * 1–1.7 characters per token across common tokenizers), which let Chinese
+ * sessions blow past the real model window long before the estimate tripped
+ * any threshold. Count CJK characters at 1 token each (deliberately on the
+ * high side — overestimating triggers compaction early, which is the safe
+ * direction) and everything else at 4 chars per token.
+ */
+export function estimateTokens(text: string): number {
+  const cjkCount = text.match(CJK_RE)?.length ?? 0;
+  return cjkCount + Math.ceil((text.length - cjkCount) / 4);
+}
+
 /** Configuration for a single {@link applyBudget} call. */
 export interface BudgetOptions {
   /**
diff --git a/packages/context/src/index.ts b/packages/context/src/index.ts
index 34702adc..44a04170 100644
--- a/packages/context/src/index.ts
+++ b/packages/context/src/index.ts
@@ -27,7 +27,7 @@ export {
 export type { PromptSegments } from "./prompt-assembler.js";
 
 // ── Token Budget ────────────────────────────────────────────────
-export { applyBudget } from "./budget.js";
+export { applyBudget, estimateTokens } from "./budget.js";
 export type { TokenEstimator, BudgetOptions, BudgetResult } from "./budget.js";
 
 // ── Prompt Loader ────────────────────────────────────────────────
diff --git a/packages/context/tests/budget.test.ts b/packages/context/tests/budget.test.ts
index a9ef3b4a..1d9c5ca1 100644
--- a/packages/context/tests/budget.test.ts
+++ b/packages/context/tests/budget.test.ts
@@ -1,7 +1,28 @@
 import { describe, it, expect } from "vitest";
-import { applyBudget } from "@covel/context";
+import { applyBudget, estimateTokens } from "@covel/context";
 import type { TokenEstimator } from "@covel/context";
 
+describe("estimateTokens", () => {
+  it("estimates ASCII text at 4 chars per token", () => {
+    expect(estimateTokens("a".repeat(40))).toBe(10);
+  });
+
+  it("estimates CJK text at 1 token per character", () => {
+    expect(estimateTokens("春眠不觉晓")).toBe(5);
+    expect(estimateTokens("こんにちは")).toBe(5);
+    expect(estimateTokens("안녕하세요")).toBe(5);
+  });
+
+  it("handles mixed CJK and ASCII content", () => {
+    // 4 CJK chars (4 tokens) + 8 ASCII chars (2 tokens)
+    expect(estimateTokens("你好世界hello wo")).toBe(6);
+  });
+
+  it("returns 0 for empty string", () => {
+    expect(estimateTokens("")).toBe(0);
+  });
+});
+
 // Deterministic mock estimator: 1 token per 4 characters (rounded up).
 const mockEstimator: TokenEstimator = (text) => Math.ceil(text.length / 4);
 
diff --git a/packages/shared/src/env/groups/feature.ts b/packages/shared/src/env/groups/feature.ts
index fd9a247a..7e4db42a 100644
--- a/packages/shared/src/env/groups/feature.ts
+++ b/packages/shared/src/env/groups/feature.ts
@@ -6,8 +6,9 @@ export const FEATURE_ENV_VARS = [
     group: "feature",
     type: "integer",
     status: "active",
-    defaultValue: "32768",
-    description: "Compactor context window used for threshold comparisons.",
+    defaultValue: "(narrative slot model capability, else 32768)",
+    description:
+      "Explicit override for the context window used by the compactor and prompt budget. When unset, the active narrative slot's model capability contextWindow is used.",
   },
   {
     name: "COVEL_SNAPSHOT_INTERVAL_TURNS",
diff --git a/packages/shared/src/env/registry-readers.ts b/packages/shared/src/env/registry-readers.ts
index b12c915e..c6d179ce 100644
--- a/packages/shared/src/env/registry-readers.ts
+++ b/packages/shared/src/env/registry-readers.ts
@@ -198,10 +198,21 @@ export function readRuntimeEnv(source: EnvSource = defaultSource()) {
     logsDir: readEnvString("COVEL_LOGS_DIR", undefined, source),
     modelDbPath: readEnvString("COVEL_MODEL_DB_PATH", undefined, source),
     promptsDir: readEnvString("COVEL_PROMPTS_DIR", undefined, source),
-    compactorContextWindow: readEnvInt(
+    // Optional explicit override. When unset (undefined) the server derives
+    // the compaction window from the active narrative slot's model capability.
+    compactorContextWindow: readEnvIntOptional(
       "COVEL_COMPACTOR_CONTEXT_WINDOW",
-      32768,
       source,
     ),
   };
 }
+
+function readEnvIntOptional(
+  name: string,
+  source: EnvSource,
+): number | undefined {
+  const raw = readEnvString(name, undefined, source);
+  if (raw === undefined) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
diff --git a/packages/shared/tests/env-registry.test.ts b/packages/shared/tests/env-registry.test.ts
index 696b7840..3c592814 100644
--- a/packages/shared/tests/env-registry.test.ts
+++ b/packages/shared/tests/env-registry.test.ts
@@ -213,7 +213,9 @@ describe("env registry", () => {
     expect(env.nodeEnv).toBe("development");
     expect(env.serverPort).toBe(3001);
     expect(env.rateLimitRpm).toBe(60);
-    expect(env.compactorContextWindow).toBe(32768);
+    // Invalid → undefined (unset): the compactor then derives the window from
+    // the narrative slot's model capability instead of a fixed constant.
+    expect(env.compactorContextWindow).toBeUndefined();
   });
 
   it("lowercase-normalizes DEPLOYMENT_TIER", () => {

From f275a3d19af3e490b03ed54ee18377686c888fe3 Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 11:03:31 +0800
Subject: [PATCH 02/10] refactor: remove dead code and legacy residue across
 framework and apps

Deletions verified zero-reference (.ts and .js cross-checked; plugins are
plain JS):

- memory: unused compactor chain (production compaction lives in
  @covel/context maybeCompact) incl. CompactionConfig/Result types
- ai-provider: never-wired Langfuse trace hook + LANGFUSE_* env entries
- store: 18 superseded row-mapper re-exports (both SQL backends),
  mediaObjectKey, dead ALL_TABLE_NAMES re-export
- shared: orphan plugin type modules (character-presence, branch-reply,
  living-world-rules)
- runtime: HookPipelineRun, backward-compat re-export block in index.ts,
  collectEventsFrom export demoted to private
- create: createPlugin chain (CLI scaffold is an independent script);
  createWorld path kept
- plugin-test-utils: createTestHarness retired (documented rejection in
  scene-stage integration test); unused deps dropped, lockfile synced
- web: lorebook client (backend routes stay), schema-block-renderer,
  searchModelDb, fetchPluginDocs, getPluginData, syncSessionDimensions,
  legacy fetchTraceEvents, browser media-store, LEGACY_EVENTS fallback,
  LEGACY_SLOTS renamed to DEFAULT_FALLBACK_SLOTS
- server: pathExists, ui-spec-schema dead exports demoted,
  loadWorldPackages export demoted, withSessionLock ghost comments fixed
- root configs: stale apps/desktop-tauri entries
- docs: plugin-testing guide rewritten around the patterns actually in
  use; flow/authoring guides and create-plugin skill references synced;
  CHANGELOG CI wording matched to the real workflow
---
 .claude/skills/create-plugin/SKILL.md         |   2 +-
 .../references/plugin-testing.md              |  84 +---
 .gitignore                                    |   1 -
 .pre-commit-config.yaml                       |   2 +-
 .prettierignore                               |   2 -
 apps/server/src/routes/api/install/shared.ts  |  18 +-
 apps/server/src/routes/api/resume.ts          |   6 +-
 .../src/routes/misc-api/ui-spec-schema.ts     |   8 +-
 apps/server/src/world-seed-loader.ts          |   4 +-
 .../tests/api/chat-mode-http-e2e.test.ts      |   2 +-
 .../src/components/blocks/block-renderer.tsx  |  49 +--
 .../blocks/schema-block-renderer.tsx          | 392 -----------------
 apps/web/src/lib/desktop-bridge.ts            |  35 +-
 .../__tests__/api-explicit-auth.test.ts       |   2 +-
 apps/web/src/services/api.ts                  |   1 -
 apps/web/src/services/api/lorebook.ts         |  83 ----
 apps/web/src/services/api/packages.ts         |  18 -
 apps/web/src/services/api/plugin-data.ts      |  17 -
 apps/web/src/services/api/traces.ts           |   9 -
 apps/web/src/services/api/worlds.ts           |  12 -
 apps/web/src/services/storage/index.ts        |   1 -
 apps/web/src/services/storage/media-store.ts  |  11 -
 .../src/settings/panes/LlmAdvancedPane.tsx    |   4 +-
 docs/CHANGELOG.md                             |   2 +-
 docs/architecture/flow.md                     |   4 +-
 docs/guide/plugin-authoring-advanced.md       |  76 +---
 docs/guide/plugin-authoring-agent.md          |  92 +---
 docs/guide/plugin-testing.md                  |  61 ++-
 packages/ai-provider/src/index.ts             |   3 -
 packages/ai-provider/src/trace/langfuse.ts    | 141 ------
 packages/context/src/message-insertion.ts     |   2 +-
 packages/create/src/create-plugin.test.ts     | 201 ---------
 packages/create/src/create-plugin.ts          | 410 ------------------
 packages/create/src/index.ts                  |   6 -
 packages/create/src/world-writer.ts           |   4 +-
 packages/memory/src/compactor.ts              | 207 ---------
 packages/memory/src/index.ts                  |   5 +-
 packages/memory/src/memory-system.ts          |  39 +-
 packages/memory/src/types.ts                  |  59 +--
 packages/plugin-test-utils/package.json       |   4 +-
 packages/plugin-test-utils/src/index.ts       |   2 -
 .../plugin-test-utils/src/test-harness.ts     | 147 -------
 .../tests/plugin-test-utils.test.ts           |  38 --
 packages/runtime/src/hooks/types.ts           |  16 -
 packages/runtime/src/index.ts                 |   7 -
 .../runtime/src/trigger/turn-event-chain.ts   |   2 +-
 packages/shared/src/env/groups/ai.ts          |  23 -
 packages/shared/src/types/branch-reply.ts     |  90 ----
 .../shared/src/types/character-presence.ts    |  31 --
 packages/shared/src/types/index.ts            |  32 --
 .../shared/src/types/living-world-rules.ts    |  55 ---
 packages/store/src/media-store/utils.ts       |   6 -
 .../store/src/postgres/pg-store-mappers.ts    |  89 +---
 .../store/src/sqlite/sqlite-store-mappers.ts  |  88 +---
 pnpm-lock.yaml                                |   6 -
 55 files changed, 140 insertions(+), 2571 deletions(-)
 delete mode 100644 apps/web/src/components/blocks/schema-block-renderer.tsx
 delete mode 100644 apps/web/src/services/api/lorebook.ts
 delete mode 100644 apps/web/src/services/storage/media-store.ts
 delete mode 100644 packages/ai-provider/src/trace/langfuse.ts
 delete mode 100644 packages/create/src/create-plugin.test.ts
 delete mode 100644 packages/create/src/create-plugin.ts
 delete mode 100644 packages/memory/src/compactor.ts
 delete mode 100644 packages/plugin-test-utils/src/test-harness.ts
 delete mode 100644 packages/shared/src/types/branch-reply.ts
 delete mode 100644 packages/shared/src/types/character-presence.ts
 delete mode 100644 packages/shared/src/types/living-world-rules.ts

diff --git a/.claude/skills/create-plugin/SKILL.md b/.claude/skills/create-plugin/SKILL.md
index d45c5f1c..5bb83250 100644
--- a/.claude/skills/create-plugin/SKILL.md
+++ b/.claude/skills/create-plugin/SKILL.md
@@ -198,7 +198,7 @@ console.log('OK');
 | ----------------------------------------------- | -------------------------------------------------------------------------- |
 | 只有 PLUGIN.md（agent runtime + builtin tools） | 只跑 schema 校验（step 4）即可                                             |
 | 有 `tools/*.js` / `handler.js` / `hooks/*.js`   | + L2 单元测试（vitest，mock store）                                        |
-| 有 `input.inject` / 多 runtime / event 链       | + L3 集成测试（`createTestHarness` + `MockLLM`）或 L4 runtime case         |
+| 有 `input.inject` / 多 runtime / event 链       | + L3 集成测试（手搓 turn-executor + `MockLLM`）或 L4 runtime case          |
 | 准备发布对外（社区插件）                        | + L4 `pnpm test:runtime` mock/live；必要时 L5 HTTP E2E，**live 不要进 CI** |
 
 测试文件放 `plugins/<id>/tests/*.test.{js,ts}`，跑：
diff --git a/.claude/skills/create-plugin/references/plugin-testing.md b/.claude/skills/create-plugin/references/plugin-testing.md
index eee8b48f..9efdb7f9 100644
--- a/.claude/skills/create-plugin/references/plugin-testing.md
+++ b/.claude/skills/create-plugin/references/plugin-testing.md
@@ -6,7 +6,7 @@
 | ------------------ | ------------------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
 | L1 Schema          | `validatePluginManifest`                    | 即时                            | 每个 `PLUGIN.md`                                                 |
 | L2 单元            | Vitest + `@covel/plugin-test-utils`         | <1s                             | 写了 `tools/*.js`、`handler.js`、`hooks/*.js`                    |
-| L3 In-process turn | `createTestHarness` + `MockLLM`             | 1-3s                            | agent runtime、tool loop、`input.inject`、多 runtime/event 链    |
+| L3 In-process turn | 手搓 turn-executor + `MockLLM`              | 1-3s                            | agent runtime、tool loop、`input.inject`、多 runtime/event 链    |
 | L4 Runtime cases   | `pnpm test:runtime` (`@covel/test-runtime`) | 1-10s mock / 真实 provider 更慢 | 第三方插件、手动 runtime、后台 follower、外部 `~/.covel/plugins` |
 | L5 HTTP E2E        | `scripts/e2e-plugin-verify.ts`              | 30s+                            | 发布前验证 API/SSE/store/approval 全链路                         |
 
@@ -185,81 +185,25 @@ describe("trigger", () => {
 
 ---
 
-## L3 — `createTestHarness` + `MockLLM`
+## L3 — 手搓 turn-executor + `MockLLM`
 
-用于跑完整 runtime pipeline：发现插件 → 排序 manifests → 组装 context → 调 LLM/tool loop → commit proposals → 写 MemoryStore。
+> 旧的 `createTestHarness` 已退役（功能不足：无法注入合成 runtime，也不 commit proposal）。需要 in-process 跑完整 turn 时，用 `@covel/runtime` 公开导出手工组装；多数插件级需求优先走 L4（`pnpm test:runtime`）。
 
-```ts
-import { describe, expect, it } from "vitest";
-import path from "node:path";
-import {
-  MockLLM,
-  createTestHarness,
-  expectAssetGenerated,
-} from "@covel/plugin-test-utils";
-
-const PLUGINS_DIR = path.resolve(import.meta.dirname, "../../../plugins");
-
-describe("my-plugin integration", () => {
-  it("runs one turn and writes plugin-data", async () => {
-    const llm = new MockLLM({
-      responses: [
-        {
-          content: null,
-          finishReason: "tool_calls",
-          toolCalls: [
-            {
-              id: "tc-1",
-              name: "plugin-data-set",
-              arguments:
-                '{"namespace":"notes","key":"intro","value":{"title":"Intro"}}',
-            },
-          ],
-          usage: { inputTokens: 50, outputTokens: 10 },
-        },
-        {
-          content: "Done.",
-          finishReason: "stop",
-          toolCalls: [],
-          usage: { inputTokens: 60, outputTokens: 4 },
-        },
-      ],
-    });
+组装步骤（完整可运行范例：`packages/runtime/tests/scene-stage-integration.test.ts` 与 `packages/runtime/tests/emit-event-integration.test.ts`）：
 
-    const harness = await createTestHarness({
-      pluginsDir: PLUGINS_DIR,
-      activePlugins: ["my-plugin"],
-      llm,
-    });
-
-    const result = await harness.executeTurn("continue");
-    const rows = await harness.store.listPluginData(
-      "sess-harness",
-      "my-plugin",
-      "notes",
-    );
-
-    expect(result.runtimeResults[0]?.status).toBe("success");
-    expect(llm.calls.map((call) => call.toolNames ?? [])).toContainEqual(
-      expect.arrayContaining(["plugin-data-set"]),
-    );
-    expect(rows[0]?.key).toBe("intro");
-  });
-});
-```
+1. `discoverPlugins` / `loadPluginManifest` / `loadRuntime`（`@covel/plugin-loader`）加载真实插件 runtime；需要合成 runtime（如模拟 narrator 发 event）时手写 `RuntimeManifest` + `LLMAdapter`。
+2. `createMemoryStore()`（`@covel/store`）做后端，按需 `setPluginData` 预置数据。
+3. `createToolExecutor` + `executeTurn`（`@covel/runtime`）执行 turn，LLM 用 `MockLLM`（`responses[]` 按调用顺序消费，耗尽后回落 `defaultResponse`，多步 tool loop 优先用它）。
+4. 对每个 runtime result 调 `processRuntimeResult`（`@covel/runtime`）把 proposal commit 进 store，再断言 `store.listPluginData(...)` 等持久化结果。
 
 常用断言：
 
-| 目标                  | 写法                                                                 |
-| --------------------- | -------------------------------------------------------------------- |
-| prompt 里包含注入内容 | `llm.calls[n].messages`                                              |
-| 工具顺序              | `result.runtimeResults[0].toolCalls.map((c) => c.name)`              |
-| plugin_data 写入      | `harness.store.listPluginData("sess-harness", pluginId, namespace)`  |
-| asset.generate 输出   | `expectAssetGenerated(result, { modality: "image" })`                |
-| 手动触发              | `harness.executeTurn("", { manualTrigger: { runtimeId, payload } })` |
-| userSettings          | `harness.executeTurn("", { userSettings: { [pluginId]: {...} } })`   |
-
-`MockLLM` 的 `responses[]` 会按调用顺序消费，耗尽后回落到 `defaultResponse`。多步 tool loop 优先用 `responses[]`，不用手写 subclass。
+| 目标                  | 写法                                                    |
+| --------------------- | ------------------------------------------------------- |
+| prompt 里包含注入内容 | `llm.calls[n].messages`                                 |
+| 工具顺序              | `result.runtimeResults[0].toolCalls.map((c) => c.name)` |
+| plugin_data 写入      | `store.listPluginData(sessionId, pluginId, namespace)`  |
+| asset.generate 输出   | `expectAssetGenerated(result, { modality: "image" })`   |
 
 ---
 
diff --git a/.gitignore b/.gitignore
index 80c3808f..936c3cf4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -116,7 +116,6 @@ tmp/
 *.png
 !apps/web/public/icon.png
 !apps/desktop/resources/icon.png
-!apps/desktop-tauri/src-tauri/icons/**/*.png
 # World character portraits and scene backdrops are tracked assets (generated once, reused).
 !worlds/**/media/portraits/*.png
 !worlds/**/media/scenes/*.png
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b02bd8e6..85fdf7f1 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -22,7 +22,7 @@ repos:
       - id: destroyed-symlinks
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
-        exclude: ^(\.claude/|apps/desktop-tauri/src-tauri/src/main\.rs$)
+        exclude: ^\.claude/
       - id: check-added-large-files
         # 3 MB: covers tracked world character portraits (~1.7–2.4 MB PNGs)
         # while still catching accidental large blobs (videos, dumps, bundles).
diff --git a/.prettierignore b/.prettierignore
index 8d6a56de..2b8c92e1 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -13,9 +13,7 @@ output/
 audits/
 debugs/
 
-apps/desktop-tauri/src-tauri/resources/
 apps/desktop/staging/
-apps/desktop-tauri/src-tauri/target/
 apps/web/src/routeTree.gen.ts
 
 pnpm-lock.yaml
diff --git a/apps/server/src/routes/api/install/shared.ts b/apps/server/src/routes/api/install/shared.ts
index d420ce61..db222d6f 100644
--- a/apps/server/src/routes/api/install/shared.ts
+++ b/apps/server/src/routes/api/install/shared.ts
@@ -10,14 +10,7 @@
  *   - Target directory must not already exist (409) — upgrades require manual removal.
  */
 
-import {
-  mkdir,
-  mkdtemp,
-  rename,
-  rm,
-  writeFile,
-  access,
-} from "node:fs/promises";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import yauzl, { type Entry, type ZipFile } from "yauzl";
 import { errorBody } from "../../../api-error.js";
@@ -72,15 +65,6 @@ export interface ExtractedEntry {
   readonly content: Buffer;
 }
 
-export async function pathExists(p: string): Promise<boolean> {
-  try {
-    await access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Inspect the Unix file mode encoded in a zip entry's external attributes.
  * Returns `null` when the entry was produced by a non-Unix tool (mode=0).
diff --git a/apps/server/src/routes/api/resume.ts b/apps/server/src/routes/api/resume.ts
index 5e9a52c3..feb1bdee 100644
--- a/apps/server/src/routes/api/resume.ts
+++ b/apps/server/src/routes/api/resume.ts
@@ -12,8 +12,10 @@
  *     before entering the LLM tool loop. Concurrent requests with the same
  *     suspensionId lose the race and receive 409. This guarantees
  *     exactly-once execution of a suspended runtime.
- *   - The pipeline also runs under `withSessionLock(sessionId)` so sequential
- *     resumes for the same session do not interleave with turn execution.
+ *   - The pipeline also runs under the injected `sessionLock` (see
+ *     `env.d.ts`; historically a `withSessionLock` import, now DI-provided)
+ *     so sequential resumes for the same session do not interleave with turn
+ *     execution.
  *
  * Expiry (S4-T4.c): the suspension-touching routes opportunistically fire a
  * time-gated, best-effort global sweep of stale (unresolved, older-than-TTL)
diff --git a/apps/server/src/routes/misc-api/ui-spec-schema.ts b/apps/server/src/routes/misc-api/ui-spec-schema.ts
index 65e7d42c..a0dbd8f1 100644
--- a/apps/server/src/routes/misc-api/ui-spec-schema.ts
+++ b/apps/server/src/routes/misc-api/ui-spec-schema.ts
@@ -20,7 +20,7 @@ import type { UiSlotName } from "./shared.js";
  * explicit diagnostic, so a newer plugin pack on an older server degrades
  * loudly instead of silently rendering a broken panel.
  */
-export const CURRENT_UI_SPEC_VERSION = 1;
+const CURRENT_UI_SPEC_VERSION = 1;
 
 const i18nTextSchema = z.union([z.string(), z.record(z.string(), z.string())]);
 
@@ -29,7 +29,7 @@ const i18nTextSchema = z.union([z.string(), z.record(z.string(), z.string())]);
  * (forward compatibility) — callers pass the ORIGINAL spec through to the
  * frontend untouched, so Zod's stripping never mutates what ships.
  */
-export const uiSpecSchema = z
+const uiSpecSchema = z
   .object({
     specVersion: z
       .number()
@@ -89,7 +89,7 @@ export interface UiSpecDiagnostic {
 }
 
 /** Pull a spec's declared `id` for diagnostic labelling, if any. */
-export function uiSpecId(spec: unknown): string | undefined {
+function uiSpecId(spec: unknown): string | undefined {
   if (spec && typeof spec === "object") {
     const id = (spec as Record<string, unknown>).id;
     if (typeof id === "string" && id.length > 0) return id;
@@ -98,7 +98,7 @@ export function uiSpecId(spec: unknown): string | undefined {
 }
 
 /** Validate one spec, returning concrete per-field issues on failure. */
-export function validateUiSpec(
+function validateUiSpec(
   spec: unknown,
 ): { ok: true } | { ok: false; issues: UiSpecIssue[] } {
   const result = uiSpecSchema.safeParse(spec);
diff --git a/apps/server/src/world-seed-loader.ts b/apps/server/src/world-seed-loader.ts
index 2053de55..fc71b5a8 100644
--- a/apps/server/src/world-seed-loader.ts
+++ b/apps/server/src/world-seed-loader.ts
@@ -374,9 +374,7 @@ async function loadCharacterBlueprints(
  * Validates each world.yaml against worldManifestSchema.
  * Returns WorldRecord[] ready for upsert.
  */
-export async function loadWorldPackages(
-  worldsDir: string,
-): Promise<WorldRecord[]> {
+async function loadWorldPackages(worldsDir: string): Promise<WorldRecord[]> {
   if (!(await fileExists(worldsDir))) return [];
 
   const entries = await readdir(worldsDir, { withFileTypes: true });
diff --git a/apps/server/tests/api/chat-mode-http-e2e.test.ts b/apps/server/tests/api/chat-mode-http-e2e.test.ts
index b1052ce8..817f9177 100644
--- a/apps/server/tests/api/chat-mode-http-e2e.test.ts
+++ b/apps/server/tests/api/chat-mode-http-e2e.test.ts
@@ -6,8 +6,8 @@ import type {
   LLMAdapter,
   LLMResponse,
   LLMToolDefinition,
-  LLMMessage,
 } from "@covel/runtime";
+import type { LLMMessage } from "@covel/shared";
 import { createMemoryStore } from "@covel/store";
 import { bootstrapApi } from "../../src/routes/api/bootstrap.js";
 import { loadSingleWorld } from "../../src/world-seed-loader.js";
diff --git a/apps/web/src/components/blocks/block-renderer.tsx b/apps/web/src/components/blocks/block-renderer.tsx
index a9606fe9..1c60a7e5 100644
--- a/apps/web/src/components/blocks/block-renderer.tsx
+++ b/apps/web/src/components/blocks/block-renderer.tsx
@@ -1,35 +1,19 @@
 /**
- * Block renderer — schema + raw fallback only.
+ * Block schema registry.
  *
  * 消息渲染已经全部走 json-render + plugin-data 数据流（见
- * `apps/web/src/components/session/chat-messages.tsx`）。本模块只保留两个
- * 对外契约：
- *
- *   1. `setBlockSchemas(schemas)` — 供 session-store 在 boot 时注入插件声明的
- *      blockSchemas，schema-block-renderer 用它为没有 json-render spec 的历史
- *      block 兜底渲染。
- *   2. `getBlockRenderer(blockType)` — 返回 schema-driven renderer（若有）
- *      或 null；不再维护硬编码的 kebab→React 组件映射。
+ * `apps/web/src/components/session/chat-messages.tsx`）。本模块只保留一个
+ * 对外契约：`setBlockSchemas(schemas)` — 供 session-store 在 boot 时注入插件
+ * 声明的 blockSchemas。
  *
  * 所有自定义 React block 组件（action-guide-block / codex-entry-block / …）
  * 已被删除——插件用自己的 `ui/*.json` spec 通过 json-render 渲染。
  */
 
-import { SchemaBlockRenderer } from "./schema-block-renderer.js";
 import type { BlockSchemaDeclaration } from "@covel/shared";
 
-export interface BlockRendererProps {
-  data: Record<string, unknown>;
-  onSubmit: (value: string) => void;
-  onSelect?: (value: string) => void;
-  selectedValue?: string | null;
-  disabled?: boolean;
-}
-
-type BlockRendererComponent = React.ComponentType<BlockRendererProps>;
-
 // Module-level mutable state: a singleton registry updated once at boot
-// (via setBlockSchemas) and read by getBlockRenderer during render.
+// (via setBlockSchemas).
 let blockSchemas: Record<string, BlockSchemaDeclaration> = {};
 
 export function setBlockSchemas(
@@ -37,26 +21,3 @@ export function setBlockSchemas(
 ) {
   blockSchemas = schemas;
 }
-
-/**
- * Returns a component that can render the given block type using the
- * plugin-declared schema. Returns null when no schema is registered — the
- * caller should fall back to json-render (chat-messages.tsx) or raw JSON.
- */
-export function getBlockRenderer(
-  blockType: string,
-): BlockRendererComponent | null {
-  const schema = blockSchemas[blockType];
-  if (!schema) return null;
-
-  return function SchemaBlock(props: BlockRendererProps) {
-    return (
-      <SchemaBlockRenderer
-        schema={schema}
-        data={props.data}
-        onSubmit={props.onSubmit}
-        disabled={props.disabled}
-      />
-    );
-  };
-}
diff --git a/apps/web/src/components/blocks/schema-block-renderer.tsx b/apps/web/src/components/blocks/schema-block-renderer.tsx
deleted file mode 100644
index 76ea0a5d..00000000
--- a/apps/web/src/components/blocks/schema-block-renderer.tsx
+++ /dev/null
@@ -1,392 +0,0 @@
-import { useState } from "react";
-import i18n from "@/i18n";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Button } from "@/components/ui/button";
-import type { BlockSchemaDeclaration } from "@covel/shared";
-
-export interface SchemaBlockRendererProps {
-  schema: BlockSchemaDeclaration;
-  data: Record<string, unknown>;
-  onSubmit: (value: string) => void;
-  disabled?: boolean;
-}
-
-export function SchemaBlockRenderer({
-  schema,
-  data,
-  onSubmit,
-  disabled,
-}: SchemaBlockRendererProps) {
-  const [formValues, setFormValues] = useState<Record<string, unknown>>({});
-
-  if (schema.interactive && schema.submitSchema) {
-    return (
-      <InteractiveSchemaBlock
-        schema={schema}
-        data={data}
-        formValues={formValues}
-        setFormValues={setFormValues}
-        onSubmit={onSubmit}
-        disabled={disabled}
-      />
-    );
-  }
-
-  return <DisplaySchemaBlock schema={schema} data={data} />;
-}
-
-// ── Display (read-only) ───────────────────────────────────────────
-
-function DisplaySchemaBlock({
-  schema,
-  data,
-}: {
-  schema: BlockSchemaDeclaration;
-  data: Record<string, unknown>;
-}) {
-  const properties = (schema.dataSchema.properties ?? {}) as Record<
-    string,
-    Record<string, unknown>
-  >;
-
-  return (
-    <Card className="max-w-md">
-      <CardHeader className="py-3 px-4 border-b border-border">
-        <CardTitle className="text-sm">
-          {resolveDisplayName(schema.meta.displayName ?? "")}
-        </CardTitle>
-      </CardHeader>
-      <CardContent className="p-4 space-y-3">
-        {Object.entries(properties).map(([key, propSchema]) =>
-          renderDisplayField(key, propSchema, data[key]),
-        )}
-      </CardContent>
-    </Card>
-  );
-}
-
-function renderDisplayField(
-  key: string,
-  propSchema: Record<string, unknown>,
-  value: unknown,
-): React.ReactNode {
-  if (value === undefined || value === null) return null;
-
-  const type = propSchema.type as string;
-
-  if (type === "string") {
-    return (
-      <div key={key} className="space-y-1">
-        <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-          {key}
-        </p>
-        <p className="text-sm">{String(value)}</p>
-      </div>
-    );
-  }
-
-  if (type === "number" || type === "integer") {
-    return (
-      <div key={key} className="space-y-1">
-        <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-          {key}
-        </p>
-        <p className="text-sm font-mono">{String(value)}</p>
-      </div>
-    );
-  }
-
-  if (type === "boolean") {
-    return (
-      <div key={key} className="flex items-center gap-2">
-        <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-          {key}
-        </p>
-        <span className="text-xs px-1.5 py-0.5 border border-border bg-muted/30">
-          {value ? i18n.t("common.yes", "Yes") : i18n.t("common.no", "No")}
-        </span>
-      </div>
-    );
-  }
-
-  if (type === "array" && Array.isArray(value)) {
-    const itemSchema = (propSchema.items ?? {}) as Record<string, unknown>;
-    return (
-      <div key={key} className="space-y-2">
-        <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-          {key}
-        </p>
-        <div className="space-y-1.5">
-          {/* Items lack stable IDs; index key is acceptable for static display */}
-          {value.map((item, i) => (
-            <div key={i} className="border border-border p-2 text-sm">
-              {typeof item === "object" && item !== null
-                ? renderObjectFields(
-                    item as Record<string, unknown>,
-                    itemSchema,
-                  )
-                : String(item)}
-            </div>
-          ))}
-        </div>
-      </div>
-    );
-  }
-
-  if (type === "object" && typeof value === "object") {
-    return (
-      <div key={key} className="space-y-1">
-        <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-          {key}
-        </p>
-        <div className="border border-border p-2">
-          {renderObjectFields(value as Record<string, unknown>, propSchema)}
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div key={key} className="space-y-1">
-      <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-        {key}
-      </p>
-      <p className="text-sm font-mono text-muted-foreground">
-        {JSON.stringify(value)}
-      </p>
-    </div>
-  );
-}
-
-function renderObjectFields(
-  obj: Record<string, unknown>,
-  schema: Record<string, unknown>,
-) {
-  const props = (schema.properties ?? {}) as Record<
-    string,
-    Record<string, unknown>
-  >;
-  const keys =
-    Object.keys(props).length > 0 ? Object.keys(props) : Object.keys(obj);
-  return (
-    <div className="space-y-1.5">
-      {keys.map((k) => {
-        const val = obj[k];
-        if (val === undefined || val === null) return null;
-        return (
-          <div key={k} className="flex gap-2 text-sm">
-            <span className="text-muted-foreground shrink-0">{k}:</span>
-            <span>
-              {typeof val === "object" ? JSON.stringify(val) : String(val)}
-            </span>
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-
-// ── Interactive (form) ────────────────────────────────────────────
-
-function InteractiveSchemaBlock({
-  schema,
-  data,
-  formValues,
-  setFormValues,
-  onSubmit,
-  disabled,
-}: {
-  schema: BlockSchemaDeclaration;
-  data: Record<string, unknown>;
-  formValues: Record<string, unknown>;
-  setFormValues: React.Dispatch<React.SetStateAction<Record<string, unknown>>>;
-  onSubmit: (value: string) => void;
-  disabled?: boolean;
-}) {
-  const properties = (schema.dataSchema.properties ?? {}) as Record<
-    string,
-    Record<string, unknown>
-  >;
-
-  const title = data.title as string | undefined;
-  const description = data.description as string | undefined;
-
-  const handleFieldChange = (key: string, value: unknown) => {
-    setFormValues((prev) => ({ ...prev, [key]: value }));
-  };
-
-  const handleSubmit = () => {
-    const result = Object.keys(formValues).length > 0 ? formValues : data;
-    onSubmit(JSON.stringify(result));
-  };
-
-  // Render interactive fields from data's array-type fields
-  const arrayFields = Object.entries(properties).filter(
-    ([, ps]) => ps.type === "array",
-  );
-
-  return (
-    <Card className="max-w-md">
-      <CardHeader className="py-3 px-4 border-b border-border space-y-1">
-        <CardTitle className="text-sm">
-          {title ?? resolveDisplayName(schema.meta.displayName ?? "")}
-        </CardTitle>
-        {description && (
-          <p className="text-xs text-muted-foreground">{description}</p>
-        )}
-      </CardHeader>
-      <CardContent className="p-4 space-y-4">
-        {/* Render simple string/number fields from data */}
-        {Object.entries(properties).map(([key, propSchema]) => {
-          if (propSchema.type === "array") return null;
-          const value = data[key];
-          if (value === undefined || value === null) return null;
-          return renderDisplayField(key, propSchema, value);
-        })}
-
-        {/* Render interactive form fields from array data */}
-        {arrayFields.map(([key, propSchema]) => {
-          const items = data[key] as Array<Record<string, unknown>> | undefined;
-          if (!items || !Array.isArray(items)) return null;
-          const itemSchema = (propSchema.items ?? {}) as Record<
-            string,
-            unknown
-          >;
-
-          return (
-            <div key={key} className="space-y-3">
-              {items.map((item, idx) => {
-                const fieldKey =
-                  (item.key as string) ?? (item.id as string) ?? String(idx);
-                const label = (item.label as string) ?? fieldKey;
-                const fieldType = (item.type as string) ?? "text";
-                const placeholder = item.placeholder as string | undefined;
-                const options = item.options as string[] | undefined;
-                const required = item.required as boolean | undefined;
-
-                return (
-                  <div key={fieldKey} className="space-y-1.5">
-                    <label
-                      htmlFor={`schema-field-${fieldKey}`}
-                      className="text-xs font-medium uppercase tracking-wider"
-                    >
-                      {label}
-                      {required && (
-                        <span className="text-destructive ml-0.5">*</span>
-                      )}
-                    </label>
-                    {renderFormInput({
-                      id: `schema-field-${fieldKey}`,
-                      fieldType,
-                      placeholder,
-                      options,
-                      value: formValues[fieldKey] as string | undefined,
-                      onChange: (v) => handleFieldChange(fieldKey, v),
-                      disabled,
-                    })}
-                  </div>
-                );
-              })}
-            </div>
-          );
-        })}
-
-        <Button
-          className="w-full rounded-none uppercase tracking-widest text-xs font-semibold"
-          disabled={disabled}
-          onClick={handleSubmit}
-        >
-          {i18n.t("form.submit", "Submit")}
-        </Button>
-      </CardContent>
-    </Card>
-  );
-}
-
-function renderFormInput({
-  id,
-  fieldType,
-  placeholder,
-  options,
-  value,
-  onChange,
-  disabled,
-}: {
-  id: string;
-  fieldType: string;
-  placeholder?: string;
-  options?: string[];
-  value?: string;
-  onChange: (value: string) => void;
-  disabled?: boolean;
-}) {
-  const baseClass =
-    "w-full bg-background border border-border px-3 py-2 text-sm outline-none focus:ring-1 focus:ring-primary transition-all disabled:opacity-50";
-
-  if (fieldType === "select" && options) {
-    return (
-      <select
-        id={id}
-        className={baseClass}
-        value={value ?? ""}
-        onChange={(e) => onChange(e.target.value)}
-        disabled={disabled}
-      >
-        <option value="">
-          {placeholder ?? i18n.t("form.selectPlaceholder", "Select...")}
-        </option>
-        {options.map((opt) => (
-          <option key={opt} value={opt}>
-            {opt}
-          </option>
-        ))}
-      </select>
-    );
-  }
-
-  if (fieldType === "textarea") {
-    return (
-      <textarea
-        id={id}
-        className={`${baseClass} min-h-[80px] resize-y`}
-        placeholder={placeholder}
-        value={value ?? ""}
-        onChange={(e) => onChange(e.target.value)}
-        disabled={disabled}
-      />
-    );
-  }
-
-  if (fieldType === "number") {
-    return (
-      <input
-        id={id}
-        type="number"
-        className={baseClass}
-        placeholder={placeholder}
-        value={value ?? ""}
-        onChange={(e) => onChange(e.target.value)}
-        disabled={disabled}
-      />
-    );
-  }
-
-  return (
-    <input
-      id={id}
-      type="text"
-      className={baseClass}
-      placeholder={placeholder}
-      value={value ?? ""}
-      onChange={(e) => onChange(e.target.value)}
-      disabled={disabled}
-    />
-  );
-}
-
-// ── Helpers ───────────────────────────────────────────────────────
-
-function resolveDisplayName(name: string | Record<string, string>): string {
-  if (typeof name === "string") return name;
-  return name["zh-CN"] ?? name["en-US"] ?? Object.values(name)[0] ?? "";
-}
diff --git a/apps/web/src/lib/desktop-bridge.ts b/apps/web/src/lib/desktop-bridge.ts
index 2baf503a..18bcf1a8 100644
--- a/apps/web/src/lib/desktop-bridge.ts
+++ b/apps/web/src/lib/desktop-bridge.ts
@@ -1,9 +1,7 @@
 /**
  * Bridge between Electron native menus / main process and the web app.
  *
- * Primary channel: window.covelIpc (contextBridge, sandboxed, allowlisted).
- * Fallback: window CustomEvent for older main-process versions that still
- * dispatch via executeJavaScript.
+ * Channel: window.covelIpc (contextBridge, sandboxed, allowlisted).
  *
  * Safe to initialize in a browser — the IPC surface is simply absent there
  * and no listeners fire.
@@ -148,12 +146,6 @@ const IPC_CHANNELS = {
   serverStatus: "covel:server:status",
 } as const;
 
-const LEGACY_EVENTS: Record<string, keyof typeof IPC_CHANNELS> = {
-  "covel:open-settings": "openSettings",
-  "covel:new-world": "newWorld",
-  "covel:export-chat": "exportChat",
-};
-
 export function initDesktopBridge(handlers: DesktopBridgeHandlers): CleanupFn {
   const cleanups: CleanupFn[] = [];
   const ipc = getCovelIpc();
@@ -200,31 +192,6 @@ export function initDesktopBridge(handlers: DesktopBridgeHandlers): CleanupFn {
     }
   }
 
-  // Legacy CustomEvent fallback (kept one release for backwards compat).
-  const legacyListeners: Array<[string, EventListener]> = [];
-  for (const [eventName, handlerKey] of Object.entries(LEGACY_EVENTS)) {
-    const listener: EventListener = () => {
-      switch (handlerKey) {
-        case "openSettings":
-          handlers.onOpenSettings();
-          break;
-        case "newWorld":
-          handlers.onNewWorld();
-          break;
-        case "exportChat":
-          handlers.onExportChat();
-          break;
-      }
-    };
-    window.addEventListener(eventName, listener);
-    legacyListeners.push([eventName, listener]);
-  }
-  cleanups.push(() => {
-    for (const [event, handler] of legacyListeners) {
-      window.removeEventListener(event, handler);
-    }
-  });
-
   return () => {
     for (const cleanup of cleanups) cleanup();
   };
diff --git a/apps/web/src/services/__tests__/api-explicit-auth.test.ts b/apps/web/src/services/__tests__/api-explicit-auth.test.ts
index 22602813..86db32d5 100644
--- a/apps/web/src/services/__tests__/api-explicit-auth.test.ts
+++ b/apps/web/src/services/__tests__/api-explicit-auth.test.ts
@@ -80,7 +80,7 @@ describe("explicit session auth on indirect routes", () => {
       new File(["image"], "image.png", { type: "image/png" }),
     );
     await api.fetchUiSpecs("sess-1");
-    await api.fetchTraceEvents("sess-1");
+    await api.fetchTraceTurns("sess-1");
 
     for (let index = 0; index < 6; index++) {
       expect(headersAt(fetchMock, index)["X-Session-Token"]).toBe(
diff --git a/apps/web/src/services/api.ts b/apps/web/src/services/api.ts
index b54fb3ee..d547d828 100644
--- a/apps/web/src/services/api.ts
+++ b/apps/web/src/services/api.ts
@@ -48,7 +48,6 @@ export type {
 } from "./api/model-settings.js";
 export * from "./api/overlay.js";
 export * from "./api/plugin-data.js";
-export * from "./api/lorebook.js";
 export * from "./api/plugin-rpc.js";
 export * from "./api/approvals.js";
 export * from "./api/traces.js";
diff --git a/apps/web/src/services/api/lorebook.ts b/apps/web/src/services/api/lorebook.ts
deleted file mode 100644
index 2b8d3112..00000000
--- a/apps/web/src/services/api/lorebook.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-import { request } from "./request.js";
-
-// -- Lorebook (framework-owned) -------------------------------
-
-export interface LorebookEntry {
-  id: string;
-  sessionId?: string;
-  content: string;
-  keys: string[];
-  enabled: boolean;
-  strategy: string;
-  insertionOrder: number;
-  pluginId: string;
-  position: string;
-  extra?: unknown;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-export interface LorebookEntryInput {
-  id: string;
-  pluginId?: string;
-  content: string;
-  keys?: string[];
-  strategy?: "constant" | "selective";
-  position?: string;
-  insertionOrder?: number;
-  enabled?: boolean;
-  extra?: unknown;
-}
-
-export async function fetchLorebookEntries(
-  sessionId: string,
-): Promise<LorebookEntry[]> {
-  const res = await request<{ entries: LorebookEntry[] }>(
-    `/api/sessions/${encodeURIComponent(sessionId)}/lorebook`,
-  );
-  return res.entries;
-}
-
-export async function createLorebookEntry(
-  sessionId: string,
-  entry: LorebookEntryInput,
-): Promise<LorebookEntry> {
-  const res = await request<{ entry: LorebookEntry }>(
-    `/api/sessions/${encodeURIComponent(sessionId)}/lorebook`,
-    { method: "POST", body: JSON.stringify(entry) },
-  );
-  return res.entry;
-}
-
-export async function updateLorebookEntry(
-  sessionId: string,
-  entryId: string,
-  entry: Omit<LorebookEntryInput, "id">,
-): Promise<LorebookEntry> {
-  const res = await request<{ entry: LorebookEntry }>(
-    `/api/sessions/${encodeURIComponent(sessionId)}/lorebook/${encodeURIComponent(entryId)}`,
-    { method: "PUT", body: JSON.stringify(entry) },
-  );
-  return res.entry;
-}
-
-export async function updateLorebookEntryEnabled(
-  sessionId: string,
-  entryId: string,
-  enabled: boolean,
-): Promise<void> {
-  await request(
-    `/api/sessions/${encodeURIComponent(sessionId)}/lorebook/${encodeURIComponent(entryId)}`,
-    { method: "PATCH", body: JSON.stringify({ enabled }) },
-  );
-}
-
-export async function deleteLorebookEntry(
-  sessionId: string,
-  entryId: string,
-): Promise<void> {
-  await request(
-    `/api/sessions/${encodeURIComponent(sessionId)}/lorebook/${encodeURIComponent(entryId)}`,
-    { method: "DELETE" },
-  );
-}
diff --git a/apps/web/src/services/api/packages.ts b/apps/web/src/services/api/packages.ts
index 43e949b9..bd211ef0 100644
--- a/apps/web/src/services/api/packages.ts
+++ b/apps/web/src/services/api/packages.ts
@@ -115,21 +115,3 @@ export async function fetchPluginFlows(): Promise<PluginFlowResponse> {
     })),
   };
 }
-
-export interface PluginDocEntry {
-  pluginId: string;
-  content: string;
-  format: string;
-}
-
-export interface PluginDocsResponse {
-  docs: PluginDocEntry[];
-}
-
-export async function fetchPluginDocs(
-  pluginId: string,
-): Promise<PluginDocsResponse> {
-  return request<PluginDocsResponse>(
-    `/api/plugins/${encodeURIComponent(pluginId)}/docs`,
-  );
-}
diff --git a/apps/web/src/services/api/plugin-data.ts b/apps/web/src/services/api/plugin-data.ts
index 4a066711..fa21a759 100644
--- a/apps/web/src/services/api/plugin-data.ts
+++ b/apps/web/src/services/api/plugin-data.ts
@@ -22,23 +22,6 @@ export async function listPluginData(
   return res.items;
 }
 
-/** Get a single plugin data entry. */
-export async function getPluginData(
-  sessionId: string,
-  pluginId: string,
-  namespace: string,
-  key: string,
-): Promise<PluginDataEntry | null> {
-  try {
-    return await request<PluginDataEntry>(
-      `/api/sessions/${encodeURIComponent(sessionId)}/plugin-data/${encodeURIComponent(pluginId)}/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
-      { silentErrors: true },
-    );
-  } catch {
-    return null;
-  }
-}
-
 // -- UI Specs (plugin panel discovery) -------------------------
 
 export interface UISlotSpec {
diff --git a/apps/web/src/services/api/traces.ts b/apps/web/src/services/api/traces.ts
index d959407f..cd1dd559 100644
--- a/apps/web/src/services/api/traces.ts
+++ b/apps/web/src/services/api/traces.ts
@@ -74,15 +74,6 @@ export interface TraceDiscovery {
   pluginData: PluginDataDiscoveryIndex[];
 }
 
-export async function fetchTraceEvents(sessionId: string): Promise<{
-  sessionId: string;
-  count: number;
-  discovery?: TraceDiscovery;
-  events: TraceEvent[];
-}> {
-  return request(`/api/traces/${encodeURIComponent(sessionId)}`, { sessionId });
-}
-
 export async function fetchTraceTurns(sessionId: string): Promise<{
   sessionId: string;
   turnCount: number;
diff --git a/apps/web/src/services/api/worlds.ts b/apps/web/src/services/api/worlds.ts
index 0db31719..095eab68 100644
--- a/apps/web/src/services/api/worlds.ts
+++ b/apps/web/src/services/api/worlds.ts
@@ -114,18 +114,6 @@ export async function importDimensions(
   return mapWorldRecord(raw);
 }
 
-/** Re-sync world dimensions into an active session's plugin_data. */
-export async function syncSessionDimensions(
-  worldId: string,
-  sessionId: string,
-): Promise<{ success: boolean; syncedKeys: string[]; entryCount: number }> {
-  return request(`/api/worlds/${encodeURIComponent(worldId)}/sync-dimensions`, {
-    method: "POST",
-    body: JSON.stringify({ sessionId }),
-    sessionId,
-  });
-}
-
 // -- AI World Generation -------------------------------------------
 
 export interface GenerateWorldProgress {
diff --git a/apps/web/src/services/storage/index.ts b/apps/web/src/services/storage/index.ts
index 89f3f73a..4877c271 100644
--- a/apps/web/src/services/storage/index.ts
+++ b/apps/web/src/services/storage/index.ts
@@ -1,4 +1,3 @@
 export * from "./data-store.js";
 export * from "./legacy-keys.js";
-export * from "./media-store.js";
 export * from "./mode.js";
diff --git a/apps/web/src/services/storage/media-store.ts b/apps/web/src/services/storage/media-store.ts
deleted file mode 100644
index 7387c8fa..00000000
--- a/apps/web/src/services/storage/media-store.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import type { MediaStore } from "@covel/shared";
-import { BROWSER_STORAGE_DB_NAME } from "./data-store.js";
-
-export const BROWSER_MEDIA_STORE_DB_NAME = BROWSER_STORAGE_DB_NAME;
-
-export async function createBrowserMediaStore(
-  dbName = BROWSER_MEDIA_STORE_DB_NAME,
-): Promise<MediaStore> {
-  const { createIndexedDbMediaStore } = await import("@covel/store/idb");
-  return createIndexedDbMediaStore({ dbName });
-}
diff --git a/apps/web/src/settings/panes/LlmAdvancedPane.tsx b/apps/web/src/settings/panes/LlmAdvancedPane.tsx
index 912dcf49..bc8a8031 100644
--- a/apps/web/src/settings/panes/LlmAdvancedPane.tsx
+++ b/apps/web/src/settings/panes/LlmAdvancedPane.tsx
@@ -10,7 +10,7 @@ import { Button } from "@/components/ui/button.js";
 import { Label } from "@/components/ui/label.js";
 import { useSession } from "@/stores/session-store.js";
 
-const LEGACY_SLOTS = [
+const DEFAULT_FALLBACK_SLOTS = [
   "story",
   "plugin",
   "memory",
@@ -27,7 +27,7 @@ export function LlmAdvancedPane() {
   const configuredSlots = isConfigured
     ? Object.keys(state.llmConfig!.slots)
     : [];
-  const slots = isConfigured ? configuredSlots : LEGACY_SLOTS;
+  const slots = isConfigured ? configuredSlots : DEFAULT_FALLBACK_SLOTS;
 
   const [paramOverrides, setParamOverridesLocal] = useState<
     Record<string, ModelParameterOverrides>
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index c24c0fef..84ee68c2 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -21,7 +21,7 @@ Security and reliability hardening release. A full-repository audit and two foll
 ### Added
 
 - **Operator Access settings pane** to save / clear / show / hide the hosted operator token, reloading session and world data on change.
-- **Pull-request / push CI** running install → lint → `lint:ci` (typecheck + dependency hygiene) → tests → build → i18n/plugin checks; `DEPLOYMENT_TIER` is parsed against an explicit enum and fails closed to the most restrictive tier on an unknown value.
+- **Pull-request / push CI** running install → `pnpm lint` → `pnpm deps:check` (dependency hygiene) → tests → build → i18n/plugin checks; `DEPLOYMENT_TIER` is parsed against an explicit enum and fails closed to the most restrictive tier on an unknown value.
 
 ### Changed
 
diff --git a/docs/architecture/flow.md b/docs/architecture/flow.md
index fdc6b458..5e8e44b9 100644
--- a/docs/architecture/flow.md
+++ b/docs/architecture/flow.md
@@ -726,7 +726,7 @@ Turn 执行                    @covel/runtime                   核心执行引
 
 测试支持                      @covel/plugin-test-utils         插件作者测试工具
                              ├── MockLLM                      模拟 LLM 响应
-                             ├── createTestHarness()          完整测试环境
+                             ├── makeManualFunctionContext()  function handler 测试 context
                              └── factory functions             makeTurnInput, etc.
 ```
 
@@ -774,7 +774,7 @@ Turn 执行                    @covel/runtime                   核心执行引
 | **tools**             | `tool()`, `createPluginDataTools()`, `shortIdBatch()`           | bootstrap, plugin tools   |
 | **state**             | `createStateManager()`, `StateManager`                          | server, runtime           |
 | **approval**          | `createApprovalPipeline()`, `ApprovalPipeline.check()`          | tool executor             |
-| **plugin-test-utils** | `MockLLM`, `createTestHarness()`                                | plugin tests only         |
+| **plugin-test-utils** | `MockLLM`, `makeManualFunctionContext()`                        | plugin tests only         |
 
 ## 九、设计约束与原则
 
diff --git a/docs/guide/plugin-authoring-advanced.md b/docs/guide/plugin-authoring-advanced.md
index af965abe..e644bbfd 100644
--- a/docs/guide/plugin-authoring-advanced.md
+++ b/docs/guide/plugin-authoring-advanced.md
@@ -1,6 +1,6 @@
 # 插件开发指南 · 高级（TypeScript + 审批 + 发布）
 
-> 面向**专业开发者**：要吃下完整类型系统、写复杂的 `TestHarness` 断言、自定义审批规则、拆多 runtime 插件，并最终发布到社区。
+> 面向**专业开发者**：要吃下完整类型系统、写手搓 turn-executor 的集成测试、自定义审批规则、拆多 runtime 插件，并最终发布到社区。
 
 > **前置要求**：先完成 [零代码](./plugin-authoring-zero-code.md) 和 [进阶（agent + 本地 JS）](./plugin-authoring-agent.md)。
 
@@ -75,66 +75,36 @@ import type {
 } from "@covel/runtime";
 ```
 
-## 2. TestHarness 高级用法
+## 2. 集成测试进阶
 
-**自定义 MockLLM 响应队列：**
+**自定义 MockLLM 响应队列**（`responses[]` 按顺序消费，耗尽后回落 `defaultResponse`）：
 
 ```typescript
-const mockLLM = new MockLLM();
+import { MockLLM } from "@covel/plugin-test-utils";
 
-// 默认响应
-mockLLM.defaultResponse = {
-  content: "你来到了一片神秘的森林...",
-  toolCalls: [],
-  finishReason: "stop",
-  usage: { inputTokens: 100, outputTokens: 50 },
-};
-```
-
-**注入额外工具：**
-
-```typescript
-import { tool } from "@covel/tools";
-import { z } from "zod";
-
-const customTool = tool({
-  name: "test-helper",
-  description: "Test helper tool",
-  parameters: z.object({ value: z.string() }),
-  execute: async (params) => ({ echoed: params.value }),
-});
-
-const harness = await createTestHarness({
-  pluginsDir: path.resolve(__dirname, "../../"),
-  tools: [customTool], // 额外注册的工具
+const mockLLM = new MockLLM({
+  responses: [
+    {
+      content: "",
+      toolCalls: [
+        { id: "tc-1", name: "emit-event", arguments: '{"topic":"scene.set"}' },
+      ],
+      finishReason: "tool_calls",
+      usage: { inputTokens: 10, outputTokens: 5 },
+    },
+    {
+      content: "你来到了一片神秘的森林...",
+      toolCalls: [],
+      finishReason: "stop",
+      usage: { inputTokens: 100, outputTokens: 50 },
+    },
+  ],
 });
 ```
 
-**断言 Store 状态：**
-
-```typescript
-const harness = await createTestHarness({ pluginsDir: "..." });
-await harness.executeTurn("开始游戏");
-
-// 通过 store 检查持久化的数据
-const store = harness.store;
-// store 实现了 DataStore 接口，可以查询 state、events、records 等
-```
-
-**多轮测试：**
+**手搓 turn-executor 跑完整 turn**：需要验证 agent tool loop、同 turn event 链或 proposal commit 时，用 `@covel/runtime` 公开导出手工组装 —— `discoverPlugins` / `loadPluginManifest` / `loadRuntime`（`@covel/plugin-loader`）加载真实 runtime，`createMemoryStore` 做后端，`createToolExecutor` + `executeTurn` 执行，`processRuntimeResult` 落库 proposal。完整可运行范例见 [`packages/runtime/tests/scene-stage-integration.test.ts`](../../packages/runtime/tests/scene-stage-integration.test.ts) 与 [`packages/runtime/tests/emit-event-integration.test.ts`](../../packages/runtime/tests/emit-event-integration.test.ts)，入口选择见 [plugin-testing.md](./plugin-testing.md)。
 
-```typescript
-const harness = await createTestHarness({ pluginsDir: "..." });
-
-// 第一轮
-const result1 = await harness.executeTurn("开始游戏");
-
-// 第二轮（TestHarness 自动递增 turnId）
-const result2 = await harness.executeTurn("我要去探索森林");
-
-// 断言跨轮状态变化
-expect(mockLLM.calls).toHaveLength(2);
-```
+**断言 Store 状态**：MemoryStore 实现完整 `DataStore` 接口，turn 执行 + `processRuntimeResult` 之后可直接 `store.listPluginData(...)` / `store.getState(...)` 断言持久化结果。
 
 ## 3. 审批管线
 
diff --git a/docs/guide/plugin-authoring-agent.md b/docs/guide/plugin-authoring-agent.md
index dc69e7f8..1ecf41ab 100644
--- a/docs/guide/plugin-authoring-agent.md
+++ b/docs/guide/plugin-authoring-agent.md
@@ -10,7 +10,7 @@
 > - 用 `interaction` 返回字段让工具产出玩家交互块（form / choice / confirmation）
 > - 用 `input.inject` 声明跨 runtime 的 prompt 注入依赖
 > - 用 `covel.registerRpc` 暴露结构化 action 给前端 / 外部代理
-> - 用 `@covel/plugin-test-utils` 的 `TestHarness + MockLLM` 写插件集成测试
+> - 用 `@covel/plugin-test-utils` + `MockLLM` 写插件测试
 
 ---
 
@@ -330,11 +330,11 @@ curl -X POST http://localhost:3001/api/sessions/$SESSION_ID/plugin-rpc \
 
 ## 5. 测试你的插件
 
-使用 `@covel/plugin-test-utils` 提供的 `TestHarness` 进行集成测试。
+使用 `@covel/plugin-test-utils` 做单元测试，用 runtime cases（`pnpm test:runtime`）做端到端验证。
 
 推荐最少覆盖四类行为：
 
-1. manifest / runtime 发现与加载
+1. manifest / runtime 发现与加载（`pnpm test:runtime` 天然覆盖）
 2. local tool 参数与返回结构
 3. handler / agent runtime 的核心输出
 4. `plugin_data` 与 `ui.message / ui.right` 的契约
@@ -344,88 +344,40 @@ curl -X POST http://localhost:3001/api/sessions/$SESSION_ID/plugin-rpc \
 ```json
 {
   "devDependencies": {
-    "@covel/plugin-loader": "workspace:*",
     "@covel/plugin-test-utils": "workspace:*",
     "vitest": "^4.1.2"
   }
 }
 ```
 
-**tests/my-plugin.test.ts：**
+**local tool 单元测试（tests/my-plugin.test.js）** —— 直接 import 工具工厂，注入 toolkit 与 mock store 后调用 `execute`（完整真实范例：[`plugins/codex/tests/codex.test.js`](../../plugins/codex/tests/codex.test.js)）：
 
-```typescript
+```js
 import { describe, it, expect } from "vitest";
-import { createTestHarness, MockLLM } from "@covel/plugin-test-utils";
-import path from "node:path";
-
-describe("my-codex", () => {
-  it("should discover and load plugin manifest", async () => {
-    const harness = await createTestHarness({
-      pluginsDir: path.resolve(__dirname, "../../"), // 指向 plugins/ 目录
-      activePlugins: ["my-codex"], // 只激活要测试的插件
-    });
-
-    // 验证 manifest 被正确解析
-    expect(harness.manifests).toHaveLength(1);
-    expect(harness.manifests[0].name).toBe("my-codex");
-    expect(harness.manifests[0].priority).toBe(650);
-  });
-
-  it("should execute a turn and get result", async () => {
-    // 配置 MockLLM 返回包含工具调用的响应
-    const mockLLM = new MockLLM({
-      defaultResponse: {
-        content: "",
-        toolCalls: [
-          {
-            id: "tc-1",
-            name: "unlock-codex-entries",
-            arguments: {
-              entries: [
-                {
-                  category: "location",
-                  title: "青萍山",
-                  content: "青萍宗所在的灵脉山峰，山腰以下是外门。",
-                  tags: ["地点", "宗门"],
-                  rarity: "common",
-                },
-              ],
-            },
-          },
-        ],
-        finishReason: "tool_calls",
-        usage: { inputTokens: 200, outputTokens: 100 },
-      },
-    });
-
-    const harness = await createTestHarness({
-      pluginsDir: path.resolve(__dirname, "../../"),
-      activePlugins: ["my-codex"],
-      llm: mockLLM,
+import { tool, z, shortIdBatch, getPendingProposals } from "@covel/tools";
+import createUnlockCodexEntries from "../tools/unlock-codex-entries.js";
+
+describe("unlock-codex-entries", () => {
+  it("unlocks a location entry", async () => {
+    const unlockTool = createUnlockCodexEntries({
+      tool,
+      z,
+      shortIdBatch,
+      store: mockPluginDataStore, // in-memory stub，见 codex.test.js
     });
 
-    const result = await harness.executeTurn("我来到了青萍山的坊市");
-
-    // 验证 LLM 被调用
-    expect(mockLLM.calls).toHaveLength(1);
-
-    // 验证 system prompt 包含插件提示词
-    const systemMessage = mockLLM.calls[0].messages.find(
-      (m) => m.role === "system",
+    const result = await unlockTool.execute(
+      { entries: [{ category: "location", title: "青萍山", content: "…" }] },
+      { sessionId: "sess-1", turnId: "turn-1", pluginId: "my-codex" },
     );
-    expect(systemMessage?.content).toContain("知识图鉴系统");
+
+    // 写入以 proposal 形式挂在返回值上，由框架 commit
+    expect(getPendingProposals(result).length).toBeGreaterThan(0);
   });
 });
 ```
 
-**TestHarness API：**
-
-| 属性/方法                          | 类型                                                   | 说明                                  |
-| ---------------------------------- | ------------------------------------------------------ | ------------------------------------- |
-| `executeTurn(message, overrides?)` | `(string, Partial<TurnInput>?) => Promise<TurnResult>` | 执行一轮游戏                          |
-| `store`                            | `DataStore`                                            | 内存 store，可读取/断言状态           |
-| `manifests`                        | `RuntimeManifest[]`                                    | 已加载的 runtime 清单（按优先级排序） |
-| `llm`                              | `LLMAdapter`                                           | 使用的 LLM 适配器（可断言调用记录）   |
+function runtime handler 用 `makeManualFunctionContext` 直接调用（真实范例：[`plugins/character-presence/tests/handler.test.js`](../../plugins/character-presence/tests/handler.test.js)）。需要跑完整 turn（tool loop / event 链 / proposal commit）时，参考 [plugin-testing.md](./plugin-testing.md) 的手搓 turn-executor 模式。
 
 **测试数据工厂：**
 
diff --git a/docs/guide/plugin-testing.md b/docs/guide/plugin-testing.md
index f32c400c..aaeef7a4 100644
--- a/docs/guide/plugin-testing.md
+++ b/docs/guide/plugin-testing.md
@@ -10,7 +10,7 @@ See also: [plugin-authoring.md](./plugin-authoring.md) · [e2e-plugin-verify.md]
 | --------------- | ------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------- |
 | Manifest schema | `validatePluginManifest`                    | `PLUGIN.md` frontmatter 是否符合 strict schema                                    | 否                          |
 | 单元测试        | Vitest + `@covel/plugin-test-utils`         | 纯函数、local tool、function handler、trigger helper                              | 否                          |
-| In-process turn | `createTestHarness` + `MockLLM`             | agent runtime、tool loop、plugin_data 写入、跨 runtime 协作                       | 否                          |
+| In-process turn | `@covel/runtime` `executeTurn` + `MockLLM`  | agent runtime、tool loop、plugin_data 写入、跨 runtime 协作                       | 否                          |
 | Runtime cases   | `@covel/test-runtime` / `pnpm test:runtime` | 插件自带 `tests/runtime-cases.json`、外部 `~/.covel/plugins` 调试、mock/live 切换 | mock 否，live 需要 key      |
 | HTTP E2E        | `scripts/e2e-plugin-verify.ts`              | 真实 API、SSE、session kernel、approval、store 路径                               | 需要 server，可用 mock slot |
 
@@ -18,7 +18,7 @@ See also: [plugin-authoring.md](./plugin-authoring.md) · [e2e-plugin-verify.md]
 
 - 只改 `PLUGIN.md`：跑 schema 校验。
 - 写了 `tools/*.js`、`handler.js`、`hooks/*.js`：加 Vitest 单元测试。
-- 涉及 agent tool loop、`input.inject`、多 runtime 或 event 链：加 `createTestHarness` 或 `pnpm test:runtime`。
+- 涉及 agent tool loop、`input.inject`、多 runtime 或 event 链：手搓 turn-executor 集成测试（见下）或 `pnpm test:runtime`。
 - 发布前要验证完整 HTTP 行为：跑 `scripts/e2e-plugin-verify.ts`。
 
 ## `@covel/plugin-test-utils`
@@ -26,54 +26,49 @@ See also: [plugin-authoring.md](./plugin-authoring.md) · [e2e-plugin-verify.md]
 源码入口：
 
 - [`packages/plugin-test-utils/src/index.ts`](../../packages/plugin-test-utils/src/index.ts)
-- [`packages/plugin-test-utils/src/test-harness.ts`](../../packages/plugin-test-utils/src/test-harness.ts)
 - [`packages/plugin-test-utils/src/mock-llm.ts`](../../packages/plugin-test-utils/src/mock-llm.ts)
 - [`packages/plugin-test-utils/src/manual-context.ts`](../../packages/plugin-test-utils/src/manual-context.ts)
+- [`packages/plugin-test-utils/src/contract.ts`](../../packages/plugin-test-utils/src/contract.ts)
 
 主要导出：
 
 | 导出                                                         | 用途                                                               |
 | ------------------------------------------------------------ | ------------------------------------------------------------------ |
 | `MockLLM`                                                    | 记录 LLM 调用；支持 `defaultResponse` 和按顺序消费的 `responses[]` |
-| `createTestHarness`                                          | 从 `pluginsDir` 发现插件，创建 MemoryStore，执行一整个 turn        |
 | `makeTurnInput` / `makeTriggerContext` / `makeRuntimeResult` | 减少 fixture 样板代码                                              |
 | `makeManualFunctionContext`                                  | 直接测试 function runtime handler                                  |
 | `expectAssetGenerated`                                       | 断言 runtime output 的 `assetGenerations[]` 中有合法 MediaRef      |
 
-最小 harness 示例：
+function handler 单元测试（真实范例：[`plugins/character-presence/tests/handler.test.js`](../../plugins/character-presence/tests/handler.test.js)）——用 `makeManualFunctionContext` 构造 handler context，直接调用 handler，再用 `@covel/tools` 的 `getPendingProposals` 断言 proposal：
 
-```ts
+```js
 import { describe, expect, it } from "vitest";
-import path from "node:path";
-import { MockLLM, createTestHarness } from "@covel/plugin-test-utils";
-
-const PLUGINS_DIR = path.resolve(import.meta.dirname, "../../../plugins");
-
-describe("my-plugin", () => {
-  it("runs one turn", async () => {
-    const llm = new MockLLM({
-      defaultResponse: {
-        content: "Done.",
-        toolCalls: [],
-        finishReason: "stop",
-        usage: { inputTokens: 10, outputTokens: 2 },
-      },
-    });
-
-    const harness = await createTestHarness({
-      pluginsDir: PLUGINS_DIR,
-      activePlugins: ["my-plugin"],
-      llm,
-    });
-
-    const result = await harness.executeTurn("continue");
-
-    expect(result.runtimeResults[0]?.status).toBe("success");
-    expect(llm.calls).toHaveLength(1);
-  });
+import { makeManualFunctionContext } from "@covel/plugin-test-utils";
+import { getPendingProposals } from "@covel/tools";
+import handler from "../handler.js";
+
+it("saves data via a plugin.data proposal", async () => {
+  const result = await handler(
+    makeManualFunctionContext({
+      pluginId: "my-plugin",
+      manualPayload: { text: "hello" },
+    }),
+  );
+
+  const proposals = getPendingProposals(result);
+  expect(proposals[0]).toMatchObject({ type: "plugin.data" });
 });
 ```
 
+事件触发 / 媒体生成类 handler 通常手写 context 对象（`vi.fn()` 桩掉 `pluginData` / `images` / `logger`），并用 `expectAssetGenerated` 断言产物——完整范例见 [`plugins/scene-stage/tests/background-gen.test.js`](../../plugins/scene-stage/tests/background-gen.test.js)。
+
+### In-process turn（手搓 turn-executor）
+
+需要跑完整 turn（agent tool loop、event 链、proposal commit）时，直接用 `@covel/runtime` 的公开导出手工组装：`discoverPlugins` / `loadPluginManifest` / `loadRuntime`（`@covel/plugin-loader`）发现并加载真实 runtime，`createMemoryStore` 做后端，`createToolExecutor` + `executeTurn` 执行，`processRuntimeResult` 落库 proposal，LLM 用 `MockLLM` 或按步骤出 tool-call 的自定义 `LLMAdapter`。完整范例：
+
+- [`packages/runtime/tests/scene-stage-integration.test.ts`](../../packages/runtime/tests/scene-stage-integration.test.ts) — 合成 emitter runtime 发 `scene.set`，同 turn event 链触发真实 scene-stage resolver 并 commit `plugin.data`。
+- [`packages/runtime/tests/emit-event-integration.test.ts`](../../packages/runtime/tests/emit-event-integration.test.ts) — 该模式的最初出处。
+
 运行包级测试：
 
 ```bash
diff --git a/packages/ai-provider/src/index.ts b/packages/ai-provider/src/index.ts
index 9525fda9..90fc47b2 100644
--- a/packages/ai-provider/src/index.ts
+++ b/packages/ai-provider/src/index.ts
@@ -135,6 +135,3 @@ export {
   type ModelDbFile,
   type ModelDbPersistence,
 } from "./capability/index.js";
-
-// Trace
-export { createLangfuseHook } from "./trace/langfuse.js";
diff --git a/packages/ai-provider/src/trace/langfuse.ts b/packages/ai-provider/src/trace/langfuse.ts
deleted file mode 100644
index b21108e1..00000000
--- a/packages/ai-provider/src/trace/langfuse.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-import type { ProviderLifecycleHook, UsageSummary } from "../types.js";
-import { readEnvString } from "@covel/shared";
-
-/** Minimal interface for Langfuse span objects. */
-interface LangfuseSpan {
-  end(opts?: Record<string, unknown>): void;
-}
-
-/** Minimal interface for Langfuse trace objects. */
-interface LangfuseTrace {
-  span(opts: Record<string, unknown>): LangfuseSpan;
-}
-
-/** Minimal interface for the Langfuse client. */
-interface LangfuseClient {
-  trace(opts: Record<string, unknown>): LangfuseTrace;
-}
-
-/**
- * Create a Langfuse lifecycle hook for AI provider tracing.
- *
- * Requires the `langfuse` package to be installed (optional dependency).
- * Returns null if Langfuse env vars are not configured.
- *
- * Expected env vars:
- * - LANGFUSE_PUBLIC_KEY
- * - LANGFUSE_SECRET_KEY
- * - LANGFUSE_BASE_URL (optional, defaults to Langfuse cloud)
- */
-export async function createLangfuseHook(): Promise<ProviderLifecycleHook | null> {
-  const publicKey = readEnvString("LANGFUSE_PUBLIC_KEY");
-  const secretKey = readEnvString("LANGFUSE_SECRET_KEY");
-  const baseUrl = readEnvString("LANGFUSE_BASE_URL");
-
-  if (!publicKey || !secretKey) return null;
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let LangfuseCtor:
-    | (new (opts: Record<string, unknown>) => LangfuseClient)
-    | undefined;
-  try {
-    const mod = await import("langfuse");
-    LangfuseCtor = mod.Langfuse as typeof LangfuseCtor;
-  } catch {
-    return null;
-  }
-
-  if (!LangfuseCtor) return null;
-
-  const langfuse: LangfuseClient = new LangfuseCtor({
-    publicKey,
-    secretKey,
-    ...(baseUrl ? { baseUrl } : {}),
-  });
-
-  const activeSpans = new Map<string, LangfuseSpan>();
-
-  return {
-    onRequestStart(event) {
-      const spanKey = `${event.traceId ?? "anon"}-${event.provider}-${event.model}`;
-      try {
-        const trace = langfuse.trace({
-          id: event.traceId,
-          name: `ai.${event.mode}`,
-          metadata: {
-            provider: event.provider,
-            protocol: event.protocol,
-            model: event.model,
-          },
-        });
-
-        const span = trace.span({
-          name: `${event.provider}/${event.model}`,
-          metadata: {
-            mode: event.mode,
-            protocol: event.protocol,
-          },
-        });
-
-        activeSpans.set(spanKey, span);
-      } catch (err) {
-        console.warn(
-          "[ai-provider] Langfuse trace creation failed:",
-          err instanceof Error ? err.message : err,
-        );
-      }
-    },
-
-    onRequestSuccess(event) {
-      const spanKey = `${event.traceId ?? "anon"}-${event.provider}-${event.model}`;
-      const span = activeSpans.get(spanKey);
-      if (!span) return;
-
-      try {
-        span.end({
-          output: { usage: event.usage },
-          metadata: {
-            durationMs: event.durationMs,
-            ...(event.usage
-              ? {
-                  inputTokens: event.usage.inputTokens,
-                  outputTokens: event.usage.outputTokens,
-                }
-              : {}),
-          },
-        });
-      } catch (err) {
-        console.warn(
-          "[ai-provider] Langfuse span.end failed:",
-          err instanceof Error ? err.message : err,
-        );
-      }
-
-      activeSpans.delete(spanKey);
-    },
-
-    onRequestError(event) {
-      const spanKey = `${event.traceId ?? "anon"}-${event.provider}-${event.model}`;
-      const span = activeSpans.get(spanKey);
-      if (!span) return;
-
-      try {
-        span.end({
-          level: "ERROR",
-          statusMessage:
-            event.error instanceof Error
-              ? event.error.message
-              : "Unknown error",
-          metadata: { durationMs: event.durationMs },
-        });
-      } catch (err) {
-        console.warn(
-          "[ai-provider] Langfuse span.end (error) failed:",
-          err instanceof Error ? err.message : err,
-        );
-      }
-
-      activeSpans.delete(spanKey);
-    },
-  };
-}
diff --git a/packages/context/src/message-insertion.ts b/packages/context/src/message-insertion.ts
index 10ee7e00..57d779ef 100644
--- a/packages/context/src/message-insertion.ts
+++ b/packages/context/src/message-insertion.ts
@@ -26,7 +26,7 @@ export interface RenderedDepthContribution {
   readonly order: number;
 }
 
-/** See `context-builder.ts::toLLMMessage` — kept in lock-step. */
+/** Map a persisted history record into the LLM message shape. */
 export function toLLMMessage(msg: MessageHistoryRecord): LLMMessage {
   return {
     role: msg.role as "system" | "user" | "assistant",
diff --git a/packages/create/src/create-plugin.test.ts b/packages/create/src/create-plugin.test.ts
deleted file mode 100644
index 1e7cae1b..00000000
--- a/packages/create/src/create-plugin.test.ts
+++ /dev/null
@@ -1,201 +0,0 @@
-/**
- * Unit tests for createPlugin() — run inside a temp dir so we never
- * touch the repo's real plugins/ tree.
- */
-
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { createPlugin } from "./create-plugin.js";
-
-async function exists(p: string): Promise<boolean> {
-  try {
-    await stat(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-describe("createPlugin", () => {
-  let tmp = "";
-  beforeEach(async () => {
-    tmp = await mkdtemp(path.join(tmpdir(), "covel-create-plugin-"));
-  });
-  afterEach(async () => {
-    if (tmp) await rm(tmp, { recursive: true, force: true });
-  });
-
-  it("rejects invalid names", async () => {
-    await expect(
-      createPlugin({
-        name: "InvalidName",
-        template: "zero-code",
-        outputDir: tmp,
-      }),
-    ).rejects.toThrow(/Invalid plugin name/);
-  });
-
-  it("writes a zero-code plugin with README.md + PLUGIN.md + package.json and nothing else", async () => {
-    const result = await createPlugin({
-      name: "my-tiny",
-      template: "zero-code",
-      outputDir: tmp,
-    });
-    expect(result.success).toBe(true);
-    expect(result.name).toBe("my-tiny");
-    expect(result.files).toHaveLength(3);
-    const readme = await readFile(
-      path.join(result.pluginDir, "README.md"),
-      "utf8",
-    );
-    expect(readme).toContain("# my-tiny");
-    expect(readme).toContain("人类和开发者看的说明");
-    const pluginMd = await readFile(
-      path.join(result.pluginDir, "PLUGIN.md"),
-      "utf8",
-    );
-    expect(pluginMd).toContain("name: my-tiny");
-    expect(pluginMd).toContain("trigger:\n  type: manual");
-    expect(pluginMd).not.toContain("priority:");
-    expect(
-      await exists(path.join(result.pluginDir, "tools", "my-tiny-tool.js")),
-    ).toBe(false);
-  });
-
-  it("ignores caller-supplied priority for zero-code manual plugins", async () => {
-    const result = await createPlugin({
-      name: "manual-only",
-      template: "zero-code",
-      outputDir: tmp,
-      priority: 650,
-    });
-    const pluginMd = await readFile(
-      path.join(result.pluginDir, "PLUGIN.md"),
-      "utf8",
-    );
-    expect(pluginMd).toContain("trigger:\n  type: manual");
-    expect(pluginMd).not.toContain("priority:");
-    expect(result.notes).toContain(
-      "Zero-code plugins use a manual trigger, so the supplied priority was ignored.",
-    );
-  });
-
-  it("writes an agent plugin with an entry module and a tool skeleton", async () => {
-    const result = await createPlugin({
-      name: "my-agent",
-      template: "agent",
-      outputDir: tmp,
-    });
-    const toolPath = path.join(result.pluginDir, "tools", "my-agent-tool.js");
-    expect(await exists(toolPath)).toBe(true);
-    const tool = await readFile(toolPath, "utf8");
-    expect(tool).toContain("name: 'my-agent-tool'");
-    expect(tool).toContain("export default function");
-    expect(tool).toContain("withPendingProposals");
-    expect(tool).not.toContain("from 'zod'");
-    const entry = await readFile(
-      path.join(result.pluginDir, "server", "index.js"),
-      "utf8",
-    );
-    expect(entry).toContain("covel.registerTool(makeTool(covel.toolkit))");
-    expect(entry).toContain("from '../tools/my-agent-tool.js'");
-    const pluginMd = await readFile(
-      path.join(result.pluginDir, "PLUGIN.md"),
-      "utf8",
-    );
-    expect(pluginMd).toContain("entry: ./server/index.js");
-    expect(pluginMd).toContain("tools:\n  plugin:\n    - my-agent-tool");
-  });
-
-  it.each(["zero-code", "agent", "function"] as const)(
-    "never scaffolds deprecated registration frontmatter (%s)",
-    async (template) => {
-      const result = await createPlugin({
-        name: `no-legacy-${template}`,
-        template,
-        outputDir: tmp,
-      });
-      const pluginMd = await readFile(
-        path.join(result.pluginDir, "PLUGIN.md"),
-        "utf8",
-      );
-      // tools.local / hooks / rpc / wires are deprecated (one release cycle);
-      // scaffolded plugins must be born on the unified `entry` pattern.
-      expect(pluginMd).not.toMatch(/^\s*local:/m);
-      expect(pluginMd).not.toMatch(/^hooks:/m);
-      expect(pluginMd).not.toMatch(/^rpc:/m);
-      expect(pluginMd).not.toMatch(/^wires:/m);
-    },
-  );
-
-  it("keeps the checked-in plugin-with-tools template free of deprecated frontmatter", async () => {
-    const templateMd = await readFile(
-      path.join(
-        import.meta.dirname,
-        "../../../templates/plugin-with-tools/PLUGIN.md",
-      ),
-      "utf8",
-    );
-    expect(templateMd).toContain("entry: ./server/index.js");
-    expect(templateMd).not.toMatch(/^\s*local:/m);
-    expect(templateMd).not.toMatch(/^hooks:/m);
-    expect(templateMd).not.toMatch(/^rpc:/m);
-    expect(templateMd).not.toMatch(/^wires:/m);
-  });
-
-  it("writes a function plugin with a runtime handler", async () => {
-    const result = await createPlugin({
-      name: "my-fn",
-      template: "function",
-      outputDir: tmp,
-    });
-    const runtimePath = path.join(result.pluginDir, "handler.js");
-    expect(await exists(runtimePath)).toBe(true);
-    const pluginMd = await readFile(
-      path.join(result.pluginDir, "PLUGIN.md"),
-      "utf8",
-    );
-    expect(pluginMd).toContain("runtimeType: function");
-    expect(pluginMd).toContain("handler: ./handler.js");
-  });
-
-  it("refuses to overwrite an existing directory unless force is true", async () => {
-    await createPlugin({
-      name: "twice",
-      template: "zero-code",
-      outputDir: tmp,
-    });
-    await expect(
-      createPlugin({
-        name: "twice",
-        template: "zero-code",
-        outputDir: tmp,
-      }),
-    ).rejects.toThrow(/already exists/);
-    const forced = await createPlugin({
-      name: "twice",
-      template: "zero-code",
-      outputDir: tmp,
-      force: true,
-    });
-    expect(forced.success).toBe(true);
-  });
-
-  it("applies the caller-supplied description and priority", async () => {
-    const result = await createPlugin({
-      name: "priced",
-      template: "agent",
-      outputDir: tmp,
-      description: "Bespoke description",
-      priority: 650,
-    });
-    const pluginMd = await readFile(
-      path.join(result.pluginDir, "PLUGIN.md"),
-      "utf8",
-    );
-    expect(pluginMd).toContain("Bespoke description");
-    expect(pluginMd).toContain("priority: 650");
-  });
-});
diff --git a/packages/create/src/create-plugin.ts b/packages/create/src/create-plugin.ts
deleted file mode 100644
index 9ad381aa..00000000
--- a/packages/create/src/create-plugin.ts
+++ /dev/null
@@ -1,410 +0,0 @@
-/**
- * Plugin scaffolder — generates a minimal Covel plugin in three flavours.
- *
- * Goal: let a plugin author go from idea to "file loads without errors"
- * in under one minute. The scaffolder produces a README.md + PLUGIN.md +
- * package.json set (plus an optional tool skeleton) and never talks to an LLM.
- *
- * Template choices:
- *   - `zero-code` : manual trigger + skill prompt only. No tools, no local code.
- *                   Ideal for "prompt-only" plugins the user wants to tweak.
- *   - `agent`     : auto trigger + LLM-backed runtime with one local tool.
- *                   Ideal for real gameplay plugins.
- *   - `function`  : runtimeType=function, pure-JS handler, no LLM.
- *                   Ideal for pure side-effect / data plumbing plugins.
- *
- * The scaffolder is intentionally dumb: it writes files, runs a minimal
- * validation, and returns the list of files written. CLI wrapping lives
- * in scripts/create-plugin.ts.
- */
-
-import { mkdir, writeFile, stat } from "node:fs/promises";
-import path from "node:path";
-
-export type PluginTemplate = "zero-code" | "agent" | "function";
-
-export interface CreatePluginOptions {
-  /** Plugin id — must match /^[a-z][a-z0-9-]{1,63}$/ and be unique on disk. */
-  readonly name: string;
-  /** Which template to scaffold. */
-  readonly template: PluginTemplate;
-  /** Human-readable description (defaults to "{{name}} plugin"). */
-  readonly description?: string;
-  /** Parent directory to write into — will contain `<name>/`. */
-  readonly outputDir: string;
-  /** Priority band (defaults per template). Ignored for zero-code/manual. */
-  readonly priority?: number;
-  /** Overwrite an existing directory. Defaults to false. */
-  readonly force?: boolean;
-}
-
-export interface CreatePluginResult {
-  readonly success: boolean;
-  /** Absolute paths of files written. */
-  readonly files: readonly string[];
-  /** Final plugin directory (absolute). */
-  readonly pluginDir: string;
-  /** Normalised plugin name (== directory name). */
-  readonly name: string;
-  /** Non-fatal notes for the caller to surface. */
-  readonly notes: readonly string[];
-}
-
-const NAME_RX = /^[a-z][a-z0-9-]{1,63}$/;
-
-function assertValidName(name: string): void {
-  if (!NAME_RX.test(name)) {
-    throw new Error(
-      `Invalid plugin name "${name}". Use 2–64 chars, lowercase letters, digits, or "-", starting with a letter.`,
-    );
-  }
-}
-
-async function pathExists(p: string): Promise<boolean> {
-  try {
-    await stat(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function defaultPriority(template: PluginTemplate): number | undefined {
-  // Stay inside After-Narrator band by default so new plugins pick up
-  // narrator output without fighting the narrator itself.
-  if (template === "zero-code") return undefined;
-  if (template === "function") return 800;
-  return 600;
-}
-
-function renderPluginMd(
-  options: Required<Pick<CreatePluginOptions, "name" | "template">> &
-    Pick<CreatePluginOptions, "priority"> & { description: string },
-): string {
-  const { name, template, priority, description } = options;
-  const common = `---
-name: ${name}
-description:
-  en: ${description}
-  zh: ${description}
-pluginType: plugin
-${priority === undefined ? "" : `priority: ${priority}\n`}`;
-  if (template === "zero-code") {
-    return (
-      common +
-      `model: plugin
-outputKind: system
-trigger:
-  type: manual
----
-
-# ${name}
-
-Describe the manual skill this runtime performs. Keep it focused on one
-plugin-owned responsibility and call \`runtime-done\` when the work is complete.
-`
-    );
-  }
-  if (template === "function") {
-    return (
-      common +
-      `outputKind: system
-runtimeType: function
-handler: ./handler.js
-trigger:
-  type: scheduled
-  interval: 1
----
-
-# ${name}
-
-Pure-function runtime. Edit \`handler.js\` to do the deterministic state update
-or data transformation you need. No LLM is involved.
-`
-    );
-  }
-  // agent
-  return (
-    common +
-    `model: plugin
-outputKind: system
-timeoutMs: 120000
-trigger:
-  type: scheduled
-  interval: 1
-entry: ./server/index.js
-tools:
-  plugin:
-    - ${name}-tool
----
-
-# ${name}
-
-Agent runtime. The block above is shared context; the Markdown below is the
-runtime prompt the LLM sees every turn.
-
-## Plugin Goal
-
-Replace this with the real goal. Examples: track player promises, maintain quest
-clues, record world-rule changes, or preserve reusable combat state.
-
-## Tool Contract
-
-Call \`${name}-tool\` only when the current narrative contains new information
-that should become plugin-owned state. After the tool call, immediately call
-\`runtime-done\`. If there is nothing useful to record, call \`runtime-done\`
-without writing.
-`
-  );
-}
-
-function renderPackageJson(name: string, template: PluginTemplate): string {
-  // Minimal, correctly-LAYERED deps per template (see plugin-authoring.md §F).
-  // The starter handler returns a plain object that the runtime normalizer
-  // commits, so it imports NOTHING at runtime — hence no `dependencies`. When
-  // you later import a shared helper at runtime (e.g. @covel/plugin-handlers-utils'
-  // makeProposal), add it to `dependencies` (NOT devDependencies) so the desktop
-  // packager stages it for players who enable the plugin.
-  const devDependencies =
-    template === "function"
-      ? {
-          // JSDoc `FunctionHandlerContext` type ref in handler.js (type-only).
-          "@covel/plugin-loader": "workspace:*",
-          "@covel/plugin-test-utils": "workspace:*",
-          vitest: "^4.1.4",
-        }
-      : template === "agent"
-        ? {
-            // JSDoc `PluginAPI` type ref in server/index.js (type-only);
-            // the tool itself is plain JS. Add @covel/tools etc. to
-            // `dependencies` once your tool grows to import them at runtime
-            // (see plugin-authoring.md §F).
-            "@covel/plugin-test-utils": "workspace:*",
-            "@covel/runtime": "workspace:*",
-            vitest: "^4.1.4",
-          }
-        : {
-            // zero-code starter imports no @covel package — only test scaffolding.
-            "@covel/plugin-test-utils": "workspace:*",
-            vitest: "^4.1.4",
-          };
-  const pkg = {
-    name: `@covel/plugin-${name}`,
-    version: "0.0.1-beta",
-    private: true,
-    type: "module",
-    scripts: {
-      test: "vitest run --passWithNoTests",
-      "test:watch": "vitest",
-    },
-    devDependencies,
-  };
-  return `${JSON.stringify(pkg, null, 2)}\n`;
-}
-
-function renderReadme(
-  options: Required<Pick<CreatePluginOptions, "name" | "template">> & {
-    description: string;
-  },
-): string {
-  const runtimeSummary =
-    options.template === "function"
-      ? "`handler.js` 中的纯函数 runtime，执行确定性代码，不调用模型。"
-      : options.template === "agent"
-        ? "`PLUGIN.md` 中的 agent runtime；Markdown 正文是运行时提示词，`tools/` 保存可选本地工具。"
-        : "`PLUGIN.md` 中的纯提示词手动 runtime；Markdown 正文是运行时提示词。";
-
-  return `# ${options.name}
-
-${options.description}
-
-## 功能
-
-用一到两段话说明这个插件解决什么玩家问题，以及玩家会在界面中看到什么。
-
-## 实现
-
-- 模板：\`${options.template}\`
-- Runtime: ${runtimeSummary}
-- 入口文件：\`PLUGIN.md\`
-
-## 开发
-
-1. 修改 \`README.md\`，维护给人类和开发者看的说明。
-2. 修改 \`PLUGIN.md\`，维护 runtime 元信息和模型指令。
-3. 添加测试后，在插件目录运行 \`pnpm test\`。
-`;
-}
-
-function renderAgentEntry(name: string): string {
-  return `/**
- * Unified server entry (PLUGIN.md \`entry\`).
- *
- * Registers the plugin's local tools through the PluginAPI facade.
- * \`covel.toolkit\` carries the same injection bag ({ tool, z, shortId,
- * withPendingProposals, store, ... }) the tool factories expect.
- */
-import makeTool from '../tools/${name}-tool.js';
-
-/** @param {import('@covel/runtime').PluginAPI} covel */
-export default function (covel) {
-  covel.registerTool(makeTool(covel.toolkit));
-}
-`;
-}
-
-function renderAgentTool(name: string): string {
-  return `/**
- * ${name}-tool — local tool registered by the plugin's entry module
- * (server/index.js) via covel.registerTool(makeTool(covel.toolkit)).
- *
- * covel.toolkit injects tool, z, shortId, and withPendingProposals. Return
- * pending proposals when the tool should persist plugin state.
- */
-
-export default function ({ tool, z, shortId, withPendingProposals }) {
-  return tool({
-    name: '${name}-tool',
-    description: 'Record one structured note for the ${name} plugin.',
-    parameters: z.object({
-      title: z.string().min(1).max(80).describe('Short title'),
-      text: z.string().min(1).max(500).describe('One or two concrete sentences'),
-      tags: z.array(z.string().min(1)).max(5).default([]).describe('Tags'),
-    }),
-    async execute(params, context) {
-      const key = shortId('note', params.title, context.sessionId);
-      const now = new Date().toISOString();
-      const note = {
-        kind: 'note',
-        title: params.title,
-        text: params.text,
-        tags: params.tags,
-        turnId: context.turnId,
-        createdAt: now,
-      };
-
-      return withPendingProposals({ recorded: true, key, note }, [
-        {
-          id: crypto.randomUUID(),
-          type: 'plugin.data',
-          source: {
-            pluginId: context.pluginId,
-            runtimeId: context.runtimeId,
-          },
-          turnId: context.turnId,
-          sessionId: context.sessionId,
-          payload: {
-            namespace: 'notes',
-            key,
-            value: note,
-          },
-          timestamp: now,
-        },
-      ]);
-    },
-  });
-}
-`;
-}
-
-function renderFunctionRuntime(name: string): string {
-  return `/**
- * ${name} — pure function runtime.
- *
- * Return a plain object. The runtime normalizer turns supported fields such as
- * pluginData[] into proposals during commit. To build proposals by hand, import
- * makeProposal from "@covel/plugin-handlers-utils" and add that package to the
- * "dependencies" field — runtime deps belong in dependencies, not
- * devDependencies (see docs/guide/plugin-authoring.md section F).
- *
- * @param {import('@covel/plugin-loader').FunctionHandlerContext} context
- */
-
-export default async function run(context) {
-  const title =
-    typeof context.manualPayload?.title === 'string'
-      ? context.manualPayload.title
-      : 'Scheduled checkpoint';
-  const now = new Date().toISOString();
-  const key = \`note-\${Date.now().toString(36)}\`;
-
-  return {
-    status: 'ok',
-    pluginData: [
-      {
-        namespace: 'notes',
-        key,
-        value: {
-          kind: 'function',
-          title,
-          text: 'Replace this with deterministic plugin logic.',
-          createdAt: now,
-        },
-      },
-    ],
-  };
-}
-`;
-}
-
-export async function createPlugin(
-  options: CreatePluginOptions,
-): Promise<CreatePluginResult> {
-  const { name, template, outputDir } = options;
-  assertValidName(name);
-
-  const pluginDir = path.resolve(outputDir, name);
-  const exists = await pathExists(pluginDir);
-  if (exists && !options.force) {
-    throw new Error(
-      `Directory already exists: ${pluginDir}\nUse force=true to overwrite.`,
-    );
-  }
-
-  const priority =
-    template === "zero-code"
-      ? undefined
-      : (options.priority ?? defaultPriority(template));
-  const description = options.description?.trim() || `${name} plugin`;
-
-  await mkdir(pluginDir, { recursive: true });
-
-  const files: string[] = [];
-  const writes: Array<[string, string]> = [
-    ["README.md", renderReadme({ name, template, description })],
-    ["PLUGIN.md", renderPluginMd({ name, template, priority, description })],
-    ["package.json", renderPackageJson(name, template)],
-  ];
-
-  if (template === "agent") {
-    writes.push([path.join("server", "index.js"), renderAgentEntry(name)]);
-    writes.push([path.join("tools", `${name}-tool.js`), renderAgentTool(name)]);
-  } else if (template === "function") {
-    writes.push(["handler.js", renderFunctionRuntime(name)]);
-  }
-
-  for (const [rel, content] of writes) {
-    const abs = path.join(pluginDir, rel);
-    await mkdir(path.dirname(abs), { recursive: true });
-    await writeFile(abs, content, "utf8");
-    files.push(abs);
-  }
-
-  const notes: string[] = [];
-  if (template === "zero-code" && options.priority !== undefined) {
-    notes.push(
-      "Zero-code plugins use a manual trigger, so the supplied priority was ignored.",
-    );
-  }
-  notes.push(
-    "Add the plugin to your dev config so it loads: either drop it under plugins/ in the repo, or point COVEL_PLUGINS_DIR at its parent folder.",
-  );
-
-  return {
-    success: true,
-    files,
-    pluginDir,
-    name,
-    notes,
-  };
-}
diff --git a/packages/create/src/index.ts b/packages/create/src/index.ts
index 9739f898..d2cea45b 100644
--- a/packages/create/src/index.ts
+++ b/packages/create/src/index.ts
@@ -1,8 +1,2 @@
 export { createWorld } from "./create-world.js";
-export { createPlugin } from "./create-plugin.js";
 export type { CreateWorldOptions, CreateResult } from "./types.js";
-export type {
-  CreatePluginOptions,
-  CreatePluginResult,
-  PluginTemplate,
-} from "./create-plugin.js";
diff --git a/packages/create/src/world-writer.ts b/packages/create/src/world-writer.ts
index f77856e7..4241f91c 100644
--- a/packages/create/src/world-writer.ts
+++ b/packages/create/src/world-writer.ts
@@ -10,8 +10,8 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
 
-export const GENERATED_WORLD_DATA_PATH = "data/world.data.yaml";
-export const GENERATED_DIMENSIONS_PATH = "data/dimensions.yaml";
+const GENERATED_WORLD_DATA_PATH = "data/world.data.yaml";
+const GENERATED_DIMENSIONS_PATH = "data/dimensions.yaml";
 
 /**
  * If the manifest contains inline `dimensions`, write them through the v1
diff --git a/packages/memory/src/compactor.ts b/packages/memory/src/compactor.ts
deleted file mode 100644
index e06fd0f4..00000000
--- a/packages/memory/src/compactor.ts
+++ /dev/null
@@ -1,207 +0,0 @@
-/**
- * Compactor — Summarize old messages and update core memory blocks.
- *
- * Inspired by Letta's compaction mechanism:
- *   1. When message count exceeds a sliding window threshold, partition into
- *      "to-compact" prefix + protected tail.
- *   2. Call the memory-slot LLM to generate a summary of the compacted messages.
- *   3. Store the summary in session_summaries.
- *   4. Tag the original messages so prompt-build substitutes the summary.
- *   5. Simultaneously update core memory blocks with key info from compacted messages.
- *
- * Original messages are NEVER deleted, only tagged.
- */
-
-import type { DataStore } from "@covel/store";
-import type {
-  CompactionConfig,
-  CompactionResult,
-  CoreMemoryBlock,
-  MemoryLLMAdapter,
-  MemoryManager,
-} from "./types.js";
-import { createMemoryUpdater } from "./updater.js";
-
-const DEFAULT_THRESHOLD = 0.6;
-const DEFAULT_PROTECT_USER_TURNS = 2;
-const DEFAULT_PROTECT_TAIL = 5;
-
-const COMPACTION_SYSTEM_PROMPT_ZH = `你是一个故事摘要生成器。请将以下对话历史压缩成一段简洁的摘要。
-
-要求：
-- 保留所有关键事件、人物动作、重要对话
-- 保留地点变化和时间线索
-- 丢弃重复描写、环境装饰、过渡性对话
-- 使用第三人称过去式
-- 300-500 字`;
-
-const COMPACTION_SYSTEM_PROMPT_EN = `You are a story summary generator. Compress the following conversation history into a concise summary.
-
-Requirements:
-- Preserve all key events, character actions, important dialogue
-- Preserve location changes and timeline markers
-- Discard repetitive descriptions, environmental decoration, transitional dialogue
-- Use third-person past tense
-- 300-500 words`;
-
-export interface CompactorDeps {
-  readonly store: DataStore;
-  readonly llm: MemoryLLMAdapter;
-  readonly memoryManager: MemoryManager;
-}
-
-export function createCompactor(
-  deps: CompactorDeps,
-  config?: CompactionConfig,
-) {
-  const threshold = config?.threshold ?? DEFAULT_THRESHOLD;
-  const protectUserTurns =
-    config?.protectLastNUserTurns ?? DEFAULT_PROTECT_USER_TURNS;
-  const protectTail = config?.protectLastNMessages ?? DEFAULT_PROTECT_TAIL;
-  const locale = config?.locale ?? "zh-CN";
-
-  return {
-    async compact(params: {
-      sessionId: string;
-      estimatedTokens: number;
-      contextWindow: number;
-      messages: readonly {
-        id: string;
-        role: string;
-        content: string;
-        turnId?: string;
-        createdAt: string;
-      }[];
-    }): Promise<CompactionResult> {
-      const { sessionId, estimatedTokens, contextWindow, messages } = params;
-
-      // Check if compaction is needed
-      if (estimatedTokens < contextWindow * threshold) {
-        return {
-          compacted: false,
-          messagesBefore: messages.length,
-          messagesAfter: messages.length,
-        };
-      }
-
-      if (messages.length <= protectTail) {
-        return {
-          compacted: false,
-          messagesBefore: messages.length,
-          messagesAfter: messages.length,
-        };
-      }
-
-      // Partition: find the protection boundary
-      // Protect the last N user turns + last N messages overall
-      let protectFrom = messages.length - protectTail;
-
-      // Walk backward to find the Nth user message
-      let userTurnsSeen = 0;
-      for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i].role === "user") {
-          userTurnsSeen++;
-          if (userTurnsSeen >= protectUserTurns) {
-            protectFrom = Math.min(protectFrom, i);
-            break;
-          }
-        }
-      }
-
-      // At least 3 messages to compact (otherwise not worth it)
-      if (protectFrom < 3) {
-        return {
-          compacted: false,
-          messagesBefore: messages.length,
-          messagesAfter: messages.length,
-        };
-      }
-
-      const toCompact = messages.slice(0, protectFrom);
-      const toKeep = messages.slice(protectFrom);
-
-      // Build compaction input
-      const historyText = toCompact
-        .map((m) => `[${m.role}] ${m.content}`)
-        .join("\n\n");
-
-      const lang = locale.startsWith("zh") ? "zh" : "en";
-
-      try {
-        // Generate summary
-        const response = await deps.llm.complete({
-          systemPrompt:
-            lang === "zh"
-              ? COMPACTION_SYSTEM_PROMPT_ZH
-              : COMPACTION_SYSTEM_PROMPT_EN,
-          messages: [{ role: "user", content: historyText }],
-          model: config?.modelSlot,
-        });
-
-        const summary = response.content.trim();
-        const summaryId = `summary-${Date.now()}`;
-        const now = new Date().toISOString();
-
-        // Persist summary
-        await deps.store.saveSessionSummary({
-          id: summaryId,
-          sessionId,
-          turnRangeStart: toCompact[0].turnId ?? toCompact[0].id,
-          turnRangeEnd:
-            toCompact[toCompact.length - 1].turnId ??
-            toCompact[toCompact.length - 1].id,
-          content: summary,
-          focusSections: [],
-          createdAt: now,
-        });
-
-        // Tag compacted messages (mark them so prompt-build can skip them)
-        const compactedIds = toCompact.map((m) => m.id);
-        await deps.store.tagTurnMessagesCompacted(
-          sessionId,
-          compactedIds,
-          summaryId,
-        );
-
-        // Also trigger a core memory block refresh with the compacted info
-        // so key facts survive the compaction
-        try {
-          const currentBlocks = await deps.memoryManager.loadBlocks(sessionId);
-          const updater = createMemoryUpdater(deps.memoryManager, deps.llm, {
-            modelSlot: config?.modelSlot,
-            locale,
-            ...(config?.blocks ? { blocks: config.blocks } : {}),
-            // Forward the per-session resolver so world-declared blocks are
-            // also refreshed during compaction (not just on the post-turn path).
-            ...(config?.resolveBlocks
-              ? { resolveBlocks: config.resolveBlocks }
-              : {}),
-          });
-          await updater.updateAfterTurn({
-            sessionId,
-            narrativeText: summary,
-            currentBlocks,
-            locale,
-          });
-        } catch {
-          // Non-fatal: memory update during compaction is best-effort
-        }
-
-        return {
-          compacted: true,
-          summaryId,
-          messagesBefore: messages.length,
-          messagesAfter: toKeep.length,
-          summary,
-        };
-      } catch (err) {
-        // Compaction failure is non-fatal — keep full history
-        return {
-          compacted: false,
-          messagesBefore: messages.length,
-          messagesAfter: messages.length,
-        };
-      }
-    },
-  };
-}
diff --git a/packages/memory/src/index.ts b/packages/memory/src/index.ts
index bb1f70f5..d782fc1e 100644
--- a/packages/memory/src/index.ts
+++ b/packages/memory/src/index.ts
@@ -5,7 +5,8 @@
  *   - Core Memory Blocks: editable text in the context window
  *   - Recall Memory: searchable conversation history
  *   - Archival Memory: long-term cross-plugin knowledge
- *   - Compaction: automatic summarization of old messages
+ *
+ * (Compaction lives in `@covel/context`'s `maybeCompact`, not this package.)
  *
  * Public surface is intentionally narrow: consumers compose the whole system
  * via `createMemorySystem`. The individual tier factories stay package-internal.
@@ -26,8 +27,6 @@ export type {
   RecallSearcher,
   ArchivalSearchResult,
   ArchivalSearcher,
-  CompactionConfig,
-  CompactionResult,
   MemorySystemDeps,
   MemorySystem,
 } from "./types.js";
diff --git a/packages/memory/src/memory-system.ts b/packages/memory/src/memory-system.ts
index fe2a731d..07de1e0d 100644
--- a/packages/memory/src/memory-system.ts
+++ b/packages/memory/src/memory-system.ts
@@ -1,13 +1,13 @@
 /**
  * Unified Memory System facade.
  *
- * Creates and wires all three memory tiers + compaction into a single
- * object that the server bootstrap injects into the turn executor.
+ * Creates and wires all three memory tiers into a single object that the
+ * server bootstrap injects into the turn executor. (Compaction lives in
+ * `@covel/context`'s `maybeCompact` — this package never compacted in
+ * production.)
  */
 
 import type {
-  CompactionConfig,
-  CompactionResult,
   CoreMemoryConfig,
   MemoryLLMAdapter,
   MemoryManager,
@@ -22,7 +22,6 @@ import { createMemoryManager } from "./core-memory.js";
 import { createMemoryUpdater } from "./updater.js";
 import { createKeywordRecallSearcher } from "./recall-search.js";
 import { createKeywordArchivalSearcher } from "./archival-search.js";
-import { createCompactor } from "./compactor.js";
 import { DEFAULT_CORE_MEMORY_BLOCKS } from "./types.js";
 import { supportsVector } from "@covel/store";
 import { createVectorRecallSearcher } from "./vector-recall-search.js";
@@ -36,13 +35,12 @@ import {
 export interface CreateMemorySystemOptions {
   readonly coreMemory?: CoreMemoryConfig;
   readonly updater?: MemoryUpdaterConfig;
-  readonly compaction?: CompactionConfig;
 }
 
 /**
  * Create a fully wired memory system.
  *
- * Model slot resolution for the updater/compactor:
+ * Model slot resolution for the updater:
  *   explicit option (set by the bootstrap layer in production) → canonical
  *   "memory" slot → gateway default. See {@link resolveModelSlot}.
  *
@@ -60,12 +58,11 @@ export function createMemorySystem(
 ): MemorySystem {
   const { store, llm, resolveSlot } = deps;
 
-  const explicitModelSlot =
-    options?.updater?.modelSlot ?? options?.compaction?.modelSlot;
+  const explicitModelSlot = options?.updater?.modelSlot;
   const modelSlot = explicitModelSlot ?? resolveModelSlot(resolveSlot);
 
-  // Single source of truth for the block schema across manager/updater/compactor
-  // so post-turn extraction, rendering, and post-compaction refresh all agree.
+  // Single source of truth for the block schema across manager/updater so
+  // post-turn extraction and rendering agree.
   const blocks = options?.coreMemory?.blocks ?? DEFAULT_CORE_MEMORY_BLOCKS;
 
   const manager: MemoryManager = createMemoryManager(store, {
@@ -120,18 +117,6 @@ export function createMemorySystem(
     ingestor = createNoopIngestor();
   }
 
-  const compactor = createCompactor(
-    { store, llm, memoryManager: manager },
-    {
-      ...options?.compaction,
-      blocks,
-      ...(options?.coreMemory?.resolveBlocks
-        ? { resolveBlocks: options.coreMemory.resolveBlocks }
-        : {}),
-      modelSlot,
-    },
-  );
-
   return {
     manager,
     updater: updaterInstance,
@@ -141,10 +126,6 @@ export function createMemorySystem(
     async ingest(sessionId) {
       return ingestor.ingest(sessionId);
     },
-
-    async compact(params): Promise<CompactionResult> {
-      return compactor.compact(params);
-    },
   };
 }
 
@@ -164,8 +145,8 @@ const MEMORY_SLOT = "memory";
  * runs for a bare standalone boot or a test that omits the slot.
  *
  * It probes the single canonical `"memory"` slot; when that is unconfigured it
- * returns `undefined` and the updater/compactor fall back to the gateway's
- * default slot. No other slot names are hardcoded here — a prior `"story"`
+ * returns `undefined` and the updater falls back to the gateway's default
+ * slot. No other slot names are hardcoded here — a prior `"story"`
  * fallback was removed because it baked an unrelated magic slot id into the
  * memory package (the gateway's own default-slot resolution covers that case).
  */
diff --git a/packages/memory/src/types.ts b/packages/memory/src/types.ts
index 8d39a13f..c76fc1d9 100644
--- a/packages/memory/src/types.ts
+++ b/packages/memory/src/types.ts
@@ -7,8 +7,8 @@
  *   2. Recall Memory — Searchable conversation history (keyword search).
  *   3. Archival Memory — Long-term cross-plugin knowledge (lorebook + characters).
  *
- * Compaction — Older messages are summarized and replaced in prompts.
- *   Core memory blocks are updated simultaneously so key information survives.
+ * Compaction (summarizing older messages) lives in `@covel/context`'s
+ * `maybeCompact`, not this package.
  */
 
 import type {
@@ -182,7 +182,7 @@ export interface MemoryManager {
 // ── Memory Updater (post-turn LLM-driven refresh) ───────────────
 
 /**
- * Minimal LLM adapter for the memory updater/compactor. Aliased to the shared
+ * Minimal LLM adapter for the memory updater. Aliased to the shared
  * {@link SimpleCompletionAdapter} (single source of truth in `@covel/shared`)
  * with the default `"user" | "assistant"` role union, since the core-memory
  * layer models both player and assistant turns. Re-exported under this name
@@ -309,42 +309,6 @@ export interface ArchivalSearcher {
   ): Promise<readonly ArchivalSearchResult[]>;
 }
 
-// ── Compaction ──────────────────────────────────────────────────
-
-export interface CompactionConfig {
-  /** Fraction of context window that triggers compaction. Default: 0.6. */
-  readonly threshold?: number;
-  /** Number of trailing user messages to protect. Default: 2. */
-  readonly protectLastNUserTurns?: number;
-  /** Always protect at least this many tail messages. Default: 5. */
-  readonly protectLastNMessages?: number;
-  /** Model slot for the summarizer. Resolution: memory → story. */
-  readonly modelSlot?: string;
-  readonly locale?: string;
-  /**
-   * Block schema forwarded to the post-compaction core-memory refresh so the
-   * compactor uses the same labels/hints as the main updater. Defaults to
-   * {@link DEFAULT_CORE_MEMORY_BLOCKS}.
-   */
-  readonly blocks?: readonly CoreMemoryBlockSchema[];
-  /**
-   * Per-session block resolver (see {@link CoreMemoryConfig.resolveBlocks}).
-   * Forwarded to the post-compaction updater so world-declared blocks are also
-   * refreshed during compaction, not just on the normal post-turn path.
-   */
-  readonly resolveBlocks?: (
-    sessionId: string,
-  ) => Promise<readonly CoreMemoryBlockSchema[] | undefined>;
-}
-
-export interface CompactionResult {
-  readonly compacted: boolean;
-  readonly summaryId?: string;
-  readonly messagesBefore: number;
-  readonly messagesAfter: number;
-  readonly summary?: string;
-}
-
 // ── Unified Memory System ───────────────────────────────────────
 
 /**
@@ -396,21 +360,4 @@ export interface MemorySystem {
     readonly recall: number;
     readonly archival: number;
   }>;
-
-  /**
-   * Run compaction if needed.
-   * Returns the compaction result (including whether it actually compacted).
-   */
-  compact(params: {
-    sessionId: string;
-    estimatedTokens: number;
-    contextWindow: number;
-    messages: readonly {
-      id: string;
-      role: string;
-      content: string;
-      turnId?: string;
-      createdAt: string;
-    }[];
-  }): Promise<CompactionResult>;
 }
diff --git a/packages/plugin-test-utils/package.json b/packages/plugin-test-utils/package.json
index 07ee741c..51bf8dfa 100644
--- a/packages/plugin-test-utils/package.json
+++ b/packages/plugin-test-utils/package.json
@@ -16,9 +16,7 @@
   "dependencies": {
     "@covel/plugin-loader": "workspace:*",
     "@covel/runtime": "workspace:*",
-    "@covel/shared": "workspace:*",
-    "@covel/store": "workspace:*",
-    "@covel/tools": "workspace:*"
+    "@covel/shared": "workspace:*"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
diff --git a/packages/plugin-test-utils/src/index.ts b/packages/plugin-test-utils/src/index.ts
index 941b716e..c537cb3b 100644
--- a/packages/plugin-test-utils/src/index.ts
+++ b/packages/plugin-test-utils/src/index.ts
@@ -1,7 +1,5 @@
 export { MockLLM } from "./mock-llm.js";
 export type { MockLLMCall, MockLLMConfig } from "./mock-llm.js";
-export { createTestHarness } from "./test-harness.js";
-export type { TestHarness, TestHarnessConfig } from "./test-harness.js";
 export {
   makeTurnInput,
   makeTriggerContext,
diff --git a/packages/plugin-test-utils/src/test-harness.ts b/packages/plugin-test-utils/src/test-harness.ts
deleted file mode 100644
index 8375e2b6..00000000
--- a/packages/plugin-test-utils/src/test-harness.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-/**
- * TestHarness — one-call setup for plugin integration testing.
- *
- * Discovers plugins, creates in-memory store, wires up tool executor,
- * and provides a simple `executeTurn()` method.
- */
-
-import type { TurnInput, TurnResult, RuntimeManifest } from "@covel/shared";
-import type { LLMAdapter } from "@covel/runtime";
-import type { HookPipeline } from "@covel/runtime";
-import type { DataStore } from "@covel/store";
-import type { ToolModule } from "@covel/tools";
-import {
-  discoverPlugins,
-  loadPluginManifest,
-  loadRuntime,
-} from "@covel/plugin-loader";
-import type { LoadedRuntime } from "@covel/plugin-loader";
-import { executeTurn, createToolExecutor } from "@covel/runtime";
-import type { TurnExecutorDeps } from "@covel/runtime";
-import { createMemoryStore } from "@covel/store";
-import { builtinUITools } from "@covel/tools";
-import { MockLLM } from "./mock-llm.js";
-
-export interface TestHarnessConfig {
-  /** Path to the plugins directory. */
-  readonly pluginsDir: string;
-  /** Optional custom LLM adapter (defaults to MockLLM with empty response). */
-  readonly llm?: LLMAdapter;
-  /** Additional tools to register alongside builtins. */
-  readonly tools?: readonly ToolModule[];
-  /** Plugin IDs to activate (defaults to all discovered). */
-  readonly activePlugins?: readonly string[];
-  /** Optional hook pipeline to inject into turn execution (e.g. for testing global hooks). */
-  readonly hookPipeline?: HookPipeline;
-}
-
-export interface TestHarness {
-  /** Execute a turn with the given player message. */
-  readonly executeTurn: (
-    message: string,
-    overrides?: Partial<TurnInput>,
-  ) => Promise<TurnResult>;
-  /** The in-memory store backing this harness. */
-  readonly store: DataStore;
-  /** Discovered runtime manifests (sorted by priority). */
-  readonly manifests: readonly RuntimeManifest[];
-  /** The LLM adapter in use (for inspection/assertion). */
-  readonly llm: LLMAdapter;
-}
-
-/**
- * Create a fully-wired test harness for plugin integration testing.
- *
- * Discovers plugins from the filesystem, creates an in-memory store,
- * registers tools, and returns a harness with a simple `executeTurn()` method.
- *
- * @param config - Harness configuration: plugins directory, optional LLM adapter, extra tools, and active plugin filter.
- * @returns A `TestHarness` with an in-memory store, discovered manifests, and a ready-to-use `executeTurn` method.
- *
- * @example
- * ```typescript
- * import { createTestHarness } from '@covel/plugin-test-utils';
- * import { MockLLM } from '@covel/plugin-test-utils';
- *
- * const harness = await createTestHarness({
- *   pluginsDir: './plugins',
- *   llm: new MockLLM({ defaultResponse: { content: 'Hello!', toolCalls: [], finishReason: 'stop', usage: { inputTokens: 10, outputTokens: 5 } } }),
- *   activePlugins: ['narrator'],
- * });
- *
- * const result = await harness.executeTurn('Start the adventure');
- * console.log(result.runtimeResults);
- * ```
- */
-export async function createTestHarness(
-  config: TestHarnessConfig,
-): Promise<TestHarness> {
-  const store = createMemoryStore();
-  const llm = config.llm ?? new MockLLM();
-
-  // Discover and load plugins
-  const discoveries = await discoverPlugins(config.pluginsDir);
-  const allManifests: RuntimeManifest[] = [];
-  const loadedCache = new Map<string, LoadedRuntime>();
-
-  for (const discovery of discoveries) {
-    if (config.activePlugins && !config.activePlugins.includes(discovery.id)) {
-      continue;
-    }
-    const parsed = await loadPluginManifest(discovery);
-    for (const p of parsed) {
-      allManifests.push(p.manifest);
-      const loaded = await loadRuntime(discovery, p.manifest.name);
-      loadedCache.set(p.manifest.name, loaded);
-    }
-  }
-
-  // Sort by priority — UI-only manifests (priority === undefined) sort to the end.
-  allManifests.sort(
-    (a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity),
-  );
-
-  // Build tool map
-  const toolMap = new Map<string, ToolModule>();
-  for (const t of builtinUITools) {
-    toolMap.set(t.name, t);
-  }
-  for (const t of config.tools ?? []) {
-    toolMap.set(t.name, t);
-  }
-
-  const toolExecutor = createToolExecutor({
-    findTool: (name) => toolMap.get(name),
-    store,
-  });
-
-  let turnCount = 0;
-
-  const harness: TestHarness = {
-    store,
-    manifests: allManifests,
-    llm,
-    executeTurn: async (message: string, overrides?: Partial<TurnInput>) => {
-      turnCount++;
-      const turnInput: TurnInput = {
-        sessionId: "sess-harness",
-        turnId: `turn-${turnCount}`,
-        playerMessage: message,
-        ...overrides,
-      };
-
-      const deps: TurnExecutorDeps = {
-        loadRuntime: async (manifest) => loadedCache.get(manifest.name),
-        llm,
-        getConfig: () => ({}),
-        store,
-        toolExecutor,
-        hookPipeline: config.hookPipeline,
-      };
-
-      return executeTurn(turnInput, allManifests, deps);
-    },
-  };
-
-  return harness;
-}
diff --git a/packages/plugin-test-utils/tests/plugin-test-utils.test.ts b/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
index dcd5a590..9866dbe7 100644
--- a/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
+++ b/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
@@ -1,8 +1,6 @@
 import { describe, it, expect } from "vitest";
-import path from "node:path";
 import {
   MockLLM,
-  createTestHarness,
   expectAssetGenerated,
   makeManualFunctionContext,
   makeTurnInput,
@@ -10,8 +8,6 @@ import {
   makeRuntimeResult,
 } from "@covel/plugin-test-utils";
 
-const PLUGINS_DIR = path.resolve(import.meta.dirname, "../../../plugins");
-
 // ── Factories ───────────────────────────────────────────────────
 
 describe("makeTurnInput", () => {
@@ -206,37 +202,3 @@ describe("MockLLM", () => {
     expect(response.content).toBe("你进入了黑暗的洞穴。");
   });
 });
-
-// ── TestHarness ─────────────────────────────────────────────────
-
-describe("createTestHarness", () => {
-  it("should discover plugins and create a working harness", async () => {
-    const harness = await createTestHarness({ pluginsDir: PLUGINS_DIR });
-    expect(harness.manifests.length).toBeGreaterThan(0);
-    expect(harness.store).toBeDefined();
-    expect(harness.llm).toBeDefined();
-  });
-
-  it("should execute a turn and return results", async () => {
-    const llm = new MockLLM({
-      defaultResponse: {
-        content: "你站在山脚下...",
-        toolCalls: [],
-        finishReason: "stop",
-        usage: { inputTokens: 100, outputTokens: 50 },
-      },
-    });
-    const harness = await createTestHarness({ pluginsDir: PLUGINS_DIR, llm });
-    const result = await harness.executeTurn("开始游戏");
-
-    expect(result.runtimeResults.length).toBeGreaterThan(0);
-    expect(result.runtimeResults[0].status).toBe("success");
-  });
-
-  it("should use in-memory store", async () => {
-    const harness = await createTestHarness({ pluginsDir: PLUGINS_DIR });
-    // Store should be empty initially
-    const sessions = await harness.store.listSessions("any-world");
-    expect(sessions).toEqual([]);
-  });
-});
diff --git a/packages/runtime/src/hooks/types.ts b/packages/runtime/src/hooks/types.ts
index 5a6aaece..68002d19 100644
--- a/packages/runtime/src/hooks/types.ts
+++ b/packages/runtime/src/hooks/types.ts
@@ -9,7 +9,6 @@
  * runtime and the plugin-facing `HookEventName` can never drift apart.
  */
 
-import type { EventBus } from "@covel/events";
 import type { HookEnforce, HookEventName } from "@covel/shared";
 
 // ── Hook event names ─────────────────────────────────────────────
@@ -142,20 +141,5 @@ export interface HookRegistration<P = unknown> {
   readonly enforce?: HookEnforce;
 }
 
-// ── Hook pipeline interface ──────────────────────────────────────
-
-export interface HookPipelineRun<P> {
-  /**
-   * Run all registered handlers for the given event using HOOK_SEMANTICS.
-   * Sequential hooks return accumulated `replace`; parallel hooks return continue.
-   */
-  run<Q extends P>(
-    event: HookEvent,
-    ctx: HookContext,
-    payload: Q,
-    opts?: { readonly eventBus?: EventBus; readonly emitter?: unknown },
-  ): Promise<HookResult<Q>>;
-}
-
 // `HookDeclaration` (the PLUGIN.md frontmatter shape) is re-exported from
 // @covel/shared at the top of this file — see the `export type` there.
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index a4e056c8..a7cc2574 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -138,13 +138,6 @@ export type { SaveAutoSnapshotOptions } from "./snapshot/auto-snapshot.js";
 // ── Types ────────────────────────────────────────────────────────
 export type { TriggerContext, ScheduledGroup } from "./types.js";
 
-// Re-export context types for backward compatibility
-export type {
-  AssembledContext,
-  ContextBuildParams,
-  LLMMessage,
-} from "@covel/context";
-
 // ── Prompt Delta (PR-1 translation layer) ──────────────────────
 export { computePromptDelta, applyPromptDelta } from "./llm/prompt-delta.js";
 export type { PromptMessage } from "./llm/prompt-delta.js";
diff --git a/packages/runtime/src/trigger/turn-event-chain.ts b/packages/runtime/src/trigger/turn-event-chain.ts
index fe5505ab..7081c880 100644
--- a/packages/runtime/src/trigger/turn-event-chain.ts
+++ b/packages/runtime/src/trigger/turn-event-chain.ts
@@ -61,7 +61,7 @@ function eventFanoutTriggerContext(
  * Collect emitted runtime events into a topic -> payload map. First emission
  * wins inside a depth to keep fan-out deterministic.
  */
-export function collectEventsFrom(
+function collectEventsFrom(
   result: RuntimeResult,
   sink: Map<string, Record<string, unknown>>,
 ): void {
diff --git a/packages/shared/src/env/groups/ai.ts b/packages/shared/src/env/groups/ai.ts
index eef578da..6ae74d88 100644
--- a/packages/shared/src/env/groups/ai.ts
+++ b/packages/shared/src/env/groups/ai.ts
@@ -15,29 +15,6 @@ export const AI_ENV_VARS = [
     status: "active",
     description: "Prompt template root directory override.",
   },
-  {
-    name: "LANGFUSE_PUBLIC_KEY",
-    group: "ai",
-    type: "string",
-    status: "active",
-    description: "Langfuse public key for LLM trace export.",
-  },
-  {
-    name: "LANGFUSE_SECRET_KEY",
-    group: "ai",
-    type: "secret",
-    status: "active",
-    secret: true,
-    description: "Langfuse secret key for LLM trace export.",
-  },
-  {
-    name: "LANGFUSE_BASE_URL",
-    group: "ai",
-    type: "url",
-    status: "active",
-    defaultValue: "https://cloud.langfuse.com",
-    description: "Langfuse API base URL.",
-  },
   {
     name: "COVEL_LLM_RETRY_DISABLED",
     group: "ai",
diff --git a/packages/shared/src/types/branch-reply.ts b/packages/shared/src/types/branch-reply.ts
deleted file mode 100644
index 29adf7c3..00000000
--- a/packages/shared/src/types/branch-reply.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-export type BranchReplyAction = "createCandidates" | "acceptCandidate";
-
-export interface BranchReplyCandidate {
-  readonly id: string;
-  readonly index: number;
-  readonly text: string;
-  /**
-   * `original` — seeded from / kept as the engine's actual reply (candidate[0]).
-   * `regenerated` — a genuine LLM rephrasing produced by the regenerate action.
-   * `manual` — supplied verbatim via an explicit `candidates` payload.
-   */
-  readonly source: "original" | "regenerated" | "manual";
-  readonly createdAt: string;
-}
-
-export interface BranchReplyTurnRecord {
-  readonly schemaVersion: 1;
-  readonly turnId: string;
-  readonly baseText: string;
-  readonly candidates: readonly BranchReplyCandidate[];
-  readonly selectedCandidateId?: string;
-  readonly acceptedCandidateId?: string;
-  readonly acceptedText?: string;
-  /**
-   * Runtime id of the narrating engine this record projects onto (discovered
-   * from the seed turn's `completedResults`, never hardcoded). The
-   * prompt-history rewriter uses it to rewrite the narrator's assistant message
-   * rather than branch-reply's own auto-appended seed message. Absent on
-   * records seeded/created without a known narrator runtime.
-   */
-  readonly runtimeId?: string;
-  readonly status: "ready" | "accepted";
-  readonly createdAt: string;
-  readonly updatedAt: string;
-}
-
-export interface BranchReplyMessageState {
-  readonly __turnId: string;
-  readonly schemaVersion: 1;
-  readonly turnId: string;
-  readonly status: "ready" | "accepted";
-  readonly selectedCandidateId?: string;
-  readonly acceptedCandidateId?: string;
-  readonly candidates: readonly BranchReplyCandidate[];
-  readonly candidateCount: number;
-  readonly updatedAt: string;
-}
-
-export interface BranchReplyCreateCandidatesPayload {
-  readonly action: "createCandidates";
-  readonly turnId?: string;
-  readonly baseText?: string;
-  readonly count?: number;
-  readonly candidates?: readonly string[];
-  readonly selectedCandidateId?: string;
-}
-
-export interface BranchReplyAcceptCandidatePayload {
-  readonly action: "acceptCandidate";
-  readonly turnId?: string;
-  readonly candidateId: string;
-  readonly text?: string;
-}
-
-export type BranchReplyManualPayload =
-  | BranchReplyCreateCandidatesPayload
-  | BranchReplyAcceptCandidatePayload;
-
-export type BranchReplyRuntimeResult =
-  | {
-      // Auto-seed path (no manualPayload): seeds candidate[0] from the active
-      // engine's narrative. `seeded: false` on empty / system / already-seeded
-      // turns (no proposal emitted).
-      readonly action: "seed";
-      readonly turnId: string;
-      readonly seeded: boolean;
-      readonly candidateCount?: number;
-    }
-  | {
-      readonly action: "createCandidates";
-      readonly turnId: string;
-      readonly candidateCount: number;
-      readonly selectedCandidateId?: string;
-    }
-  | {
-      readonly action: "acceptCandidate";
-      readonly turnId: string;
-      readonly acceptedCandidateId: string;
-      readonly acceptedText: string;
-    };
diff --git a/packages/shared/src/types/character-presence.ts b/packages/shared/src/types/character-presence.ts
deleted file mode 100644
index b2c1cd99..00000000
--- a/packages/shared/src/types/character-presence.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import type { MediaRef } from "./media.js";
-
-export interface CharacterPresenceMediaRefs {
-  readonly avatar?: MediaRef;
-  readonly sprite?: MediaRef;
-  readonly voice?: MediaRef;
-  readonly media?: Readonly<Record<string, MediaRef>>;
-}
-
-export interface CharacterPresence extends CharacterPresenceMediaRefs {
-  readonly schemaVersion: 1;
-  readonly characterId: string;
-  readonly displayName?: string;
-  readonly style?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-}
-
-export interface CharacterPresenceRecord {
-  readonly presence: CharacterPresence;
-  readonly updatedAt: string;
-}
-
-export interface CharacterPresenceSavePayload {
-  readonly presence?: CharacterPresence;
-  readonly presenceJson?: string;
-}
-
-export interface CharacterPresenceSaveResult {
-  readonly saved: boolean;
-  readonly characterId: string;
-}
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index 2e8b24a1..4f436ab8 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -250,40 +250,8 @@ export type {
   PlayerIdentitySaveResult,
 } from "./player-identity.js";
 
-export type {
-  BranchReplyAction,
-  BranchReplyCandidate,
-  BranchReplyTurnRecord,
-  BranchReplyMessageState,
-  BranchReplyCreateCandidatesPayload,
-  BranchReplyAcceptCandidatePayload,
-  BranchReplyManualPayload,
-  BranchReplyRuntimeResult,
-} from "./branch-reply.js";
-
 export { playerIdentityToCharacterUpsert } from "./player-identity.js";
 
-export type {
-  CharacterPresenceMediaRefs,
-  CharacterPresence,
-  CharacterPresenceRecord,
-  CharacterPresenceSavePayload,
-  CharacterPresenceSaveResult,
-} from "./character-presence.js";
-
-export type {
-  LivingWorldRuleKind,
-  LivingWorldRuleCategory,
-  LivingWorldRulePosition,
-  LivingWorldRuleBudgetClass,
-  LivingWorldRuleCoordinate,
-  LivingWorldRuleOwner,
-  LivingWorldRule,
-  LivingWorldRuleRecord,
-  LivingWorldRuleSavePayload,
-  LivingWorldRuleSaveResult,
-} from "./living-world-rules.js";
-
 export type {
   RuntimeOutput,
   RuntimeOutputResult,
diff --git a/packages/shared/src/types/living-world-rules.ts b/packages/shared/src/types/living-world-rules.ts
deleted file mode 100644
index 2565d0a1..00000000
--- a/packages/shared/src/types/living-world-rules.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-export type LivingWorldRuleKind = "constant" | "triggered" | "evolving";
-export type LivingWorldRuleCategory =
-  | "character"
-  | "scene"
-  | "relationship"
-  | "world"
-  | "style";
-export type LivingWorldRulePosition =
-  | "before_plugin"
-  | "after_plugin"
-  | "at_depth";
-export type LivingWorldRuleBudgetClass = "sticky" | "flexible" | "droppable";
-
-export interface LivingWorldRuleCoordinate {
-  readonly position: LivingWorldRulePosition;
-  readonly depth?: number;
-}
-
-export interface LivingWorldRuleOwner {
-  readonly pluginId?: string;
-  readonly characterId?: string;
-}
-
-export interface LivingWorldRule {
-  readonly schemaVersion: 1;
-  readonly id: string;
-  readonly title?: string;
-  readonly content: string;
-  readonly kind?: LivingWorldRuleKind;
-  readonly category?: LivingWorldRuleCategory;
-  readonly keys?: readonly string[];
-  readonly enabled?: boolean;
-  readonly coordinate?: LivingWorldRuleCoordinate;
-  readonly insertionOrder?: number;
-  readonly budgetClass?: LivingWorldRuleBudgetClass;
-  readonly owner?: LivingWorldRuleOwner;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-}
-
-export interface LivingWorldRuleRecord {
-  readonly rule: LivingWorldRule;
-  readonly lorebookEntryId: string;
-  readonly updatedAt: string;
-}
-
-export interface LivingWorldRuleSavePayload {
-  readonly rule?: LivingWorldRule;
-  readonly ruleJson?: string;
-}
-
-export interface LivingWorldRuleSaveResult {
-  readonly saved: boolean;
-  readonly ruleId: string;
-  readonly lorebookEntryId: string;
-}
diff --git a/packages/store/src/media-store/utils.ts b/packages/store/src/media-store/utils.ts
index 6d0a919e..37fe85f5 100644
--- a/packages/store/src/media-store/utils.ts
+++ b/packages/store/src/media-store/utils.ts
@@ -117,12 +117,6 @@ export function bytesToReadableStream(
   });
 }
 
-export function mediaObjectKey(id: string, prefix?: string): string {
-  const key = `${id.slice(0, 2)}/${id.slice(2, 4)}/${id}.bin`;
-  if (!prefix) return key;
-  return `${prefix.replace(/\/+$/, "")}/${key}`;
-}
-
 export function normalizeBytes(value: Uint8Array | Buffer): Uint8Array {
   return new Uint8Array(
     value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength),
diff --git a/packages/store/src/postgres/pg-store-mappers.ts b/packages/store/src/postgres/pg-store-mappers.ts
index 68389c55..74ae3697 100644
--- a/packages/store/src/postgres/pg-store-mappers.ts
+++ b/packages/store/src/postgres/pg-store-mappers.ts
@@ -1,94 +1,13 @@
 /**
- * PostgreSQL row→record mappers and compatibility exports.
+ * PostgreSQL schema DDL re-exports.
  *
- * The actual mapping logic lives in the backend-agnostic
- * `../common/mappers.ts`; this module is only the PostgreSQL serialization
- * gateway. PG `jsonb` columns arrive already deserialized, so the canonical
- * mappers are bound to {@link pgJsonReader} (an identity/`null`-collapse
- * reader). Each export keeps its historical single-argument `(row)` signature.
- *
- * Scope note: this gateway only covers the record domains that are NOT yet
- * routed through the shared `common/sql-*-records.ts` query layer (session,
- * session content/journal). The world / plugin-data / working-memory /
- * lorebook / state / runtime / snapshot / suspension mappers moved to direct
- * canonical calls inside the shared query modules, so their PG wrappers were
- * removed.
+ * Row→record mapping for PG lives directly in the shared
+ * `common/sql-*-records.ts` query layer (bound to `pgJsonReader`); this
+ * module now only forwards DDL constants from `pg-schema-ddl.ts`.
  */
 
-import { pgJsonReader } from "../common/json-readers.js";
-import * as canonical from "../common/mappers.js";
-import type {
-  ApprovalRecord,
-  CharacterRecord,
-  EventRecord,
-  MessageRecord,
-  PlayerInputRecord,
-  SessionRecord,
-  SessionSummaryRecord,
-  TraceEventRecord,
-  TurnMessageRecord,
-} from "../types.js";
-import type * as schema from "./schema.js";
-
 export {
   CREATE_MEDIA_TABLES_SQL,
   CREATE_TABLES_SQL,
-  ALL_TABLE_NAMES,
   DROP_ALL_SQL,
 } from "./pg-schema-ddl.js";
-
-// ── Row → Record mappers (PG gateway, jsonb already deserialized) ─
-
-export function toSessionRecord(
-  row: typeof schema.sessions.$inferSelect,
-): SessionRecord {
-  return canonical.toSessionRecord(row, pgJsonReader);
-}
-
-export function toEventRecord(
-  row: typeof schema.events.$inferSelect,
-): EventRecord {
-  return canonical.toEventRecord(row, pgJsonReader);
-}
-
-export function toApprovalRecord(
-  row: typeof schema.approvals.$inferSelect,
-): ApprovalRecord {
-  return canonical.toApprovalRecord(row);
-}
-
-export function toMessageRecord(
-  row: typeof schema.messages.$inferSelect,
-): MessageRecord {
-  return canonical.toMessageRecord(row, pgJsonReader);
-}
-
-export function toCharacterRecord(
-  row: typeof schema.characters.$inferSelect,
-): CharacterRecord {
-  return canonical.toCharacterRecord(row, pgJsonReader);
-}
-
-export function toTraceEventRecord(
-  row: typeof schema.traceEvents.$inferSelect,
-): TraceEventRecord {
-  return canonical.toTraceEventRecord(row, pgJsonReader);
-}
-
-export function toTurnMessageRecord(
-  row: typeof schema.turnMessages.$inferSelect,
-): TurnMessageRecord {
-  return canonical.toTurnMessageRecord(row, pgJsonReader);
-}
-
-export function toPlayerInputRecord(
-  row: typeof schema.playerInputs.$inferSelect,
-): PlayerInputRecord {
-  return canonical.toPlayerInputRecord(row, pgJsonReader);
-}
-
-export function toSessionSummaryRecord(
-  row: typeof schema.sessionSummaries.$inferSelect,
-): SessionSummaryRecord {
-  return canonical.toSessionSummaryRecord(row, pgJsonReader);
-}
diff --git a/packages/store/src/sqlite/sqlite-store-mappers.ts b/packages/store/src/sqlite/sqlite-store-mappers.ts
index 695c4b2a..6be0b69a 100644
--- a/packages/store/src/sqlite/sqlite-store-mappers.ts
+++ b/packages/store/src/sqlite/sqlite-store-mappers.ts
@@ -1,89 +1,9 @@
 /**
- * SQLite row→record mappers and compatibility exports.
+ * SQLite schema DDL re-export.
  *
- * The actual mapping logic lives in the backend-agnostic
- * `../common/mappers.ts`; this module is only the SQLite serialization
- * gateway. SQLite stores JSON columns as text, so the canonical mappers are
- * bound to {@link sqliteJsonReader} which parses them. Each export keeps its
- * historical single-argument `(row)` signature.
- *
- * Scope note: this gateway only covers the record domains that are NOT yet
- * routed through the shared `common/sql-*-records.ts` query layer (session,
- * session content/journal, plugin configs). The world / plugin-data /
- * working-memory / lorebook / state / runtime / snapshot / suspension mappers
- * moved to direct canonical calls inside the shared query modules, so their
- * SQLite wrappers were removed.
+ * Row→record mapping for SQLite lives directly in the shared
+ * `common/sql-*-records.ts` query layer (bound to `sqliteJsonReader`); this
+ * module now only forwards `createTables` from `sqlite-schema-ddl.ts`.
  */
 
-import { sqliteJsonReader } from "../common/json-readers.js";
-import * as canonical from "../common/mappers.js";
-import type {
-  ApprovalRecord,
-  CharacterRecord,
-  EventRecord,
-  MessageRecord,
-  PlayerInputRecord,
-  SessionRecord,
-  SessionSummaryRecord,
-  TraceEventRecord,
-  TurnMessageRecord,
-} from "../types.js";
-import type * as schema from "./schema.js";
-
 export { createTables } from "./sqlite-schema-ddl.js";
-
-// ── Row → Record mappers (SQLite gateway, JSON columns are text) ──
-
-export function toSessionRecord(
-  row: typeof schema.sessions.$inferSelect,
-): SessionRecord {
-  return canonical.toSessionRecord(row, sqliteJsonReader);
-}
-
-export function toEventRecord(
-  row: typeof schema.events.$inferSelect,
-): EventRecord {
-  return canonical.toEventRecord(row, sqliteJsonReader);
-}
-
-export function toApprovalRecord(
-  row: typeof schema.approvals.$inferSelect,
-): ApprovalRecord {
-  return canonical.toApprovalRecord(row);
-}
-
-export function toMessageRecord(
-  row: typeof schema.messages.$inferSelect,
-): MessageRecord {
-  return canonical.toMessageRecord(row, sqliteJsonReader);
-}
-
-export function toCharacterRecord(
-  row: typeof schema.characters.$inferSelect,
-): CharacterRecord {
-  return canonical.toCharacterRecord(row, sqliteJsonReader);
-}
-
-export function toTraceEventRecord(
-  row: typeof schema.traceEvents.$inferSelect,
-): TraceEventRecord {
-  return canonical.toTraceEventRecord(row, sqliteJsonReader);
-}
-
-export function toTurnMessageRecord(
-  row: typeof schema.turnMessages.$inferSelect,
-): TurnMessageRecord {
-  return canonical.toTurnMessageRecord(row, sqliteJsonReader);
-}
-
-export function toPlayerInputRecord(
-  row: typeof schema.playerInputs.$inferSelect,
-): PlayerInputRecord {
-  return canonical.toPlayerInputRecord(row, sqliteJsonReader);
-}
-
-export function toSessionSummaryRecord(
-  row: typeof schema.sessionSummaries.$inferSelect,
-): SessionSummaryRecord {
-  return canonical.toSessionSummaryRecord(row, sqliteJsonReader);
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fc9ef4e6..94d6a35f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -455,12 +455,6 @@ importers:
       '@covel/shared':
         specifier: workspace:*
         version: link:../shared
-      '@covel/store':
-        specifier: workspace:*
-        version: link:../store
-      '@covel/tools':
-        specifier: workspace:*
-        version: link:../tools
     devDependencies:
       typescript:
         specifier: ^6.0.3

From 391d05268412d265f31cd128e587d46203e288ef Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 11:03:43 +0800
Subject: [PATCH 03/10] fix(plugins): close authoring-contract gaps found by
 drift audit

- Add the supply-chain .npmrc (minimum-release-age) to all 20 bundled
  plugins, matching the plugin-authoring appendix; scaffold already
  copies it from templates via dotfile-inclusive copyDir.
- Add scene-prompts PLUGIN.en.md so English sessions get an English
  agent prompt (was the only CJK-bodied schedulable agent without one).
- Migrate haruka-academy world.yaml from deprecated top-level
  required/recommended/excludedPlugins to pluginPolicy (fold shim kept
  for third-party worlds).
---
 docs/guide/plugin-authoring.md     |  2 +-
 plugins/branch-reply/.npmrc        |  3 +
 plugins/char-creator/.npmrc        |  3 +
 plugins/character-blueprint/.npmrc |  3 +
 plugins/character-presence/.npmrc  |  3 +
 plugins/chat-mode-narrator/.npmrc  |  3 +
 plugins/codex/.npmrc               |  3 +
 plugins/cost-gate/.npmrc           |  3 +
 plugins/director/.npmrc            |  3 +
 plugins/guide/.npmrc               |  3 +
 plugins/living-world-rules/.npmrc  |  3 +
 plugins/memory/.npmrc              |  3 +
 plugins/narrator/.npmrc            |  3 +
 plugins/npc-graph/.npmrc           |  3 +
 plugins/player-identity/.npmrc     |  3 +
 plugins/pregame/.npmrc             |  3 +
 plugins/scene-cast/.npmrc          |  3 +
 plugins/scene-prompts/.npmrc       |  3 +
 plugins/scene-prompts/PLUGIN.en.md | 93 ++++++++++++++++++++++++++++++
 plugins/scene-stage/.npmrc         |  3 +
 plugins/story-guard/.npmrc         |  3 +
 plugins/world-init/.npmrc          |  3 +
 worlds/haruka-academy/world.yaml   | 36 ++++++------
 23 files changed, 172 insertions(+), 19 deletions(-)
 create mode 100644 plugins/branch-reply/.npmrc
 create mode 100644 plugins/char-creator/.npmrc
 create mode 100644 plugins/character-blueprint/.npmrc
 create mode 100644 plugins/character-presence/.npmrc
 create mode 100644 plugins/chat-mode-narrator/.npmrc
 create mode 100644 plugins/codex/.npmrc
 create mode 100644 plugins/cost-gate/.npmrc
 create mode 100644 plugins/director/.npmrc
 create mode 100644 plugins/guide/.npmrc
 create mode 100644 plugins/living-world-rules/.npmrc
 create mode 100644 plugins/memory/.npmrc
 create mode 100644 plugins/narrator/.npmrc
 create mode 100644 plugins/npc-graph/.npmrc
 create mode 100644 plugins/player-identity/.npmrc
 create mode 100644 plugins/pregame/.npmrc
 create mode 100644 plugins/scene-cast/.npmrc
 create mode 100644 plugins/scene-prompts/.npmrc
 create mode 100644 plugins/scene-prompts/PLUGIN.en.md
 create mode 100644 plugins/scene-stage/.npmrc
 create mode 100644 plugins/story-guard/.npmrc
 create mode 100644 plugins/world-init/.npmrc

diff --git a/docs/guide/plugin-authoring.md b/docs/guide/plugin-authoring.md
index 47523a1b..0742acb4 100644
--- a/docs/guide/plugin-authoring.md
+++ b/docs/guide/plugin-authoring.md
@@ -249,7 +249,7 @@ minimum-release-age=10080
 | 仅测试用                                | `devDependencies` | `@covel/plugin-test-utils`、`vitest`               |
 
 - `function` runtime 必须把 handler 运行时依赖放 `dependencies`；`agent` / `zero-code` 没有 handler.js，通常不声明任何 `@covel` 运行时依赖。
-- 脚手架（`@covel/create`）已按模板生成正确分层；从已有插件 fork 时手动核对，**不要把运行时依赖留在 `devDependencies`**（dev 能跑、打包后会缺）。
+- 脚手架（`scripts/create-plugin.js`）已按模板生成正确分层；从已有插件 fork 时手动核对，**不要把运行时依赖留在 `devDependencies`**（dev 能跑、打包后会缺）。
 
 **共用包提取阈值（避免过度抽象）：**
 
diff --git a/plugins/branch-reply/.npmrc b/plugins/branch-reply/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/branch-reply/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/char-creator/.npmrc b/plugins/char-creator/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/char-creator/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/character-blueprint/.npmrc b/plugins/character-blueprint/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/character-blueprint/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/character-presence/.npmrc b/plugins/character-presence/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/character-presence/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/chat-mode-narrator/.npmrc b/plugins/chat-mode-narrator/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/chat-mode-narrator/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/codex/.npmrc b/plugins/codex/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/codex/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/cost-gate/.npmrc b/plugins/cost-gate/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/cost-gate/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/director/.npmrc b/plugins/director/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/director/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/guide/.npmrc b/plugins/guide/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/guide/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/living-world-rules/.npmrc b/plugins/living-world-rules/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/living-world-rules/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/memory/.npmrc b/plugins/memory/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/memory/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/narrator/.npmrc b/plugins/narrator/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/narrator/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/npc-graph/.npmrc b/plugins/npc-graph/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/npc-graph/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/player-identity/.npmrc b/plugins/player-identity/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/player-identity/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/pregame/.npmrc b/plugins/pregame/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/pregame/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/scene-cast/.npmrc b/plugins/scene-cast/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/scene-cast/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/scene-prompts/.npmrc b/plugins/scene-prompts/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/scene-prompts/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/scene-prompts/PLUGIN.en.md b/plugins/scene-prompts/PLUGIN.en.md
new file mode 100644
index 00000000..58f49299
--- /dev/null
+++ b/plugins/scene-prompts/PLUGIN.en.md
@@ -0,0 +1,93 @@
+---
+name: scene-prompts
+displayName:
+  zh: 场景快捷回复
+  en: Scene Prompts
+description:
+  zh: 根据当前场景给出几句可直接采用的行动短句。
+  en: Suggests short actions that fit the current scene and can be used right away.
+pluginType: plugin
+priority: 600
+model: plugin
+outputKind: system
+timeoutMs: 120000
+# This runtime's only job is to call generate-scene-prompts. Some models drift
+# into continuing the narrative and finish with zero tool calls; the gate gives
+# one corrective retry before releasing so the choices don't silently vanish.
+requireToolUse: true
+# Discovered by the stage choices layer via this capability (not a hardcoded
+# plugin id — framework↔plugin isolation rule). A third-party plugin declaring
+# `scene-prompts` transparently replaces this one as the stage's prompt source.
+capabilities:
+  - scene-prompts
+tags:
+  - mode:dialogue
+  - role:quick-reply
+  - cost:llm
+  - ui:message-block
+trigger:
+  type: scheduled
+  interval: 1
+# Engine-agnostic guidance. The upstream gate discovers the active narrative
+# engine by capability (narrative-engine → chat-mode-narrator in dialogue,
+# narrator in traditional) instead of naming one, so the same plugin gates
+# correctly in either mode and still skips when that engine failed. The inject
+# lists both known engines; the absent one resolves to nothing, so exactly the
+# active engine's fresh prose fills <narrator-output>.
+upstreamRequired:
+  - capability: narrative-engine
+input:
+  inject:
+    - kind: runtime
+      from: chat-mode-narrator
+      field: narrativeOutput
+      as: "<narrator-output>"
+    - kind: runtime
+      from: narrator
+      field: narrativeOutput
+      as: "<narrator-output>"
+entry: ./server/index.js
+tools:
+  plugin:
+    - generate-scene-prompts
+ui:
+  message:
+    - ./ui/scene-prompts-block.json
+postHistory:
+  role: system
+  content: |
+    This runtime's workflow (two mandatory steps):
+    1. You MUST call `generate-scene-prompts` once, producing scene-specific
+       player action phrases based on the latest narrative.
+    2. As soon as the tool returns, immediately call `runtime-done` once to finish.
+    Fixed execution: one `generate-scene-prompts`, one `runtime-done`, and stay
+    silent between the two tool calls.
+---
+
+You are the Scene Prompts agent. Your job is to give the player a set of scene-specific short phrases they can send directly as their next player message once the narrative has advanced.
+
+## Current Narrative Result
+
+The latest narrative turn is in the `<narrator-output>` block above (injected by the active mode's narrative engine).
+
+## Your Task
+
+1. Call `generate-scene-prompts` once
+2. As soon as the tool returns, immediately call `runtime-done`
+
+## Prompt Types
+
+- `observe`: observe, confirm, listen, wait for the other party's reaction
+- `ask`: ask, follow up, request an explanation
+- `act`: move, use an item, attempt a skill, advance the on-scene action
+- `social`: reassure, probe, negotiate, command, make overtures
+
+## Generation Rules
+
+- `scene` summarizes the current scene or decision point in 4-16 characters
+- `prompts` generates 3-6 entries, each 8-45 characters
+- Every prompt must be first-person or imperative action text the player can send directly
+- Prioritize the key objects, locations, characters, dangers, and clues in the current narrative
+- Use concrete actions and targets
+- Always call `generate-scene-prompts` exactly once
+- Immediately call `runtime-done` once the call succeeds
diff --git a/plugins/scene-stage/.npmrc b/plugins/scene-stage/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/scene-stage/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/story-guard/.npmrc b/plugins/story-guard/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/story-guard/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/plugins/world-init/.npmrc b/plugins/world-init/.npmrc
new file mode 100644
index 00000000..864283b9
--- /dev/null
+++ b/plugins/world-init/.npmrc
@@ -0,0 +1,3 @@
+# 供应链防护：拒绝安装发布不足 7 天的依赖版本（10080 分钟）
+# 仅在本插件作为独立项目安装时生效；在 Covel 主仓 workspace 内会被根配置接管。
+minimum-release-age=10080
diff --git a/worlds/haruka-academy/world.yaml b/worlds/haruka-academy/world.yaml
index 939a54a0..77bfee23 100644
--- a/worlds/haruka-academy/world.yaml
+++ b/worlds/haruka-academy/world.yaml
@@ -17,26 +17,26 @@ tags:
   - romance
   - slice-of-life
   - chat-mode
-requiredPlugins:
-  - pregame
-  - world-init
-  - char-creator
-recommendedPlugins:
-  - chat-mode-narrator
-  - scene-cast
-  - scene-stage
-  - scene-prompts
-  - character-blueprint
-  - character-presence
-  - living-world-rules
-  - branch-reply
-  - npc-graph
-excludedPlugins:
-  - narrator
-  - guide
-  - codex
 pluginPolicy:
   preset: dialogue-mode
+  requiredPlugins:
+    - pregame
+    - world-init
+    - char-creator
+  recommendedPlugins:
+    - chat-mode-narrator
+    - scene-cast
+    - scene-stage
+    - scene-prompts
+    - character-blueprint
+    - character-presence
+    - living-world-rules
+    - branch-reply
+    - npc-graph
+  excludedPlugins:
+    - narrator
+    - guide
+    - codex
   preferTags:
     - mode:dialogue
     - role:character

From 7bcfd960543664607b36c79d76d6f22876363889 Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 11:13:34 +0800
Subject: [PATCH 04/10] refactor: remove write-only blockSchemas chain, retire
 unread env entry, set compat-layer sunset

- Remove the blockSchemas dead chain end to end: the registry was written
  at boot but never read after message rendering moved to json-render.
  Drops block-renderer.tsx, boot-time fetch/set, fetchBlockSchemas client,
  GET /api/block-schemas route, BlockSchemaDeclaration/Meta shared types,
  and the api.md row.
- Remove the never-read COVEL_ALLOWED_LLM_HOSTS registry entry; the SSRF
  guard is open by design (CLAUDE.md / env-registry wording updated).
- Give the deprecated PLUGIN.md registration fields (tools.local / hooks /
  rpc / wires) an explicit sunset: planned removal in v0.0.17 (deprecation
  note, boot warning, plugins.md).
---
 CLAUDE.md                                     |  2 +-
 .../src/routes/api/bootstrap/plugin-entry.ts  |  2 +-
 apps/server/src/routes/misc-api.ts            | 24 +--------------
 .../src/components/blocks/block-renderer.tsx  | 23 --------------
 apps/web/src/services/api/llm.ts              |  9 ------
 .../__tests__/session-store-plugins.test.ts   |  4 ---
 apps/web/src/stores/session-store/boot.ts     | 18 ++++-------
 docs/guide/env-registry.md                    |  2 +-
 docs/reference/api.md                         |  1 -
 docs/reference/plugins.md                     |  2 +-
 packages/shared/src/env/groups/ai.ts          |  7 -----
 packages/shared/src/types/index.ts            |  2 --
 packages/shared/src/types/plugin.ts           |  4 ++-
 packages/shared/src/types/ui.ts               | 30 -------------------
 14 files changed, 14 insertions(+), 116 deletions(-)
 delete mode 100644 apps/web/src/components/blocks/block-renderer.tsx

diff --git a/CLAUDE.md b/CLAUDE.md
index d0b6965b..c33a5d8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -295,7 +295,7 @@ Each SQL backend keeps a thin public factory plus focused method modules:
 
 ## Security & Operations
 
-- **SSRF guard**: `validateBaseUrl()` in `ai-provider/adapters/http.ts` is **open by default** — any public https host is allowed. Blocks: RFC1918 / link-local IPs (`10.x` / `172.16-31.x` / `192.168.x` / `169.254.x` / `fc00::` / `fe80::`), cloud metadata hostnames (`metadata.google.internal`, `metadata.internal`), non-https on remote hosts, non-http(s) protocols. Loopback (`localhost` / `127.0.0.1` / `::1`) bypasses the https requirement for Ollama-style local dev. Additionally, core provider requests (`postJson` / `getJson` / `postFormData`) and the plugin `ctx.http` helper resolve DNS through a pinning dispatcher (`adapters/http/dns-safety.ts`): every A/AAAA answer must be publicly routable (loopback hostnames must resolve to loopback), closing the string-check-to-connect DNS-rebinding gap. `COVEL_ALLOWED_LLM_HOSTS` appears in env-registry as `status: 'documented'` but **is not read** by the guard — third-party plugin authors targeting custom provider hosts do not need any env shim.
+- **SSRF guard**: `validateBaseUrl()` in `ai-provider/adapters/http.ts` is **open by default** — any public https host is allowed. Blocks: RFC1918 / link-local IPs (`10.x` / `172.16-31.x` / `192.168.x` / `169.254.x` / `fc00::` / `fe80::`), cloud metadata hostnames (`metadata.google.internal`, `metadata.internal`), non-https on remote hosts, non-http(s) protocols. Loopback (`localhost` / `127.0.0.1` / `::1`) bypasses the https requirement for Ollama-style local dev. Additionally, core provider requests (`postJson` / `getJson` / `postFormData`) and the plugin `ctx.http` helper resolve DNS through a pinning dispatcher (`adapters/http/dns-safety.ts`): every A/AAAA answer must be publicly routable (loopback hostnames must resolve to loopback), closing the string-check-to-connect DNS-rebinding gap. There is **no host allowlist env** — the guard is open by design; third-party plugin authors targeting custom provider hosts do not need any env shim (the never-read `COVEL_ALLOWED_LLM_HOSTS` registry entry was removed).
 - **Env-key origin binding (S-01)**: server-env / platform API keys flow to the gateway as `envApiKeys`, separate from request-supplied `X-Provider-Keys` (`apiKeys`). The provider registry only attaches an env key when the resolved target's baseUrl origin matches trusted config (llm.toml / registered provider defaults) — a request-scoped custom preset (`X-Slot-Config` overlay) that redirects a provider to another origin gets no env key and no trusted default headers; it must supply its own key.
 - **Hosted auth (S-02/C-01/C-02)**: `demo` / `commercial` tiers enforce a per-session **owner token** (minted at session create, hash-persisted in `SessionRecord.metadata`, returned once) on every session-scoped route, and an **operator token** (`COVEL_DESKTOP_REST_TOKEN`, also a master key that passes any owner check) on global/admin routes (session create/list, world writes, AI/model, community server-code activation). `validateSecurityPosture` fails boot on a hosted tier missing the operator token / media secret / CORS origin. The server binds `127.0.0.1` by default (`COVEL_BIND_HOST` opts into `0.0.0.0`). `self` / desktop / dev are a strict no-op (single-user local play unchanged). Community server code (`entry` / handler / hook / wire / runtime JS) is import-gated behind two-phase approval (a `covel:plugin-server-code` grant, then the action grant). Full model: [docs/reference/api.md](./docs/reference/api.md) 鉴权 section.
 - **Signed media URLs**: `middleware/media-token.ts` signs `MediaRef` URLs with `COVEL_MEDIA_TOKEN_SECRET`. Desktop shells must provision it or generated images/portraits fail to load; web uses an ephemeral per-boot secret.
diff --git a/apps/server/src/routes/api/bootstrap/plugin-entry.ts b/apps/server/src/routes/api/bootstrap/plugin-entry.ts
index 93044b8a..53c7047a 100644
--- a/apps/server/src/routes/api/bootstrap/plugin-entry.ts
+++ b/apps/server/src/routes/api/bootstrap/plugin-entry.ts
@@ -438,7 +438,7 @@ function warnLegacyRegistrationFields(
     console.warn(
       `[plugin-entry] ${pluginId}: PLUGIN.md field(s) ${[...legacy].join(", ")} are deprecated — ` +
         `migrate to a single "entry" module (export default function (covel) { ... }). ` +
-        `Legacy fields keep working for this release cycle.`,
+        `Legacy fields are planned for removal in v0.0.17.`,
     );
   }
 }
diff --git a/apps/server/src/routes/misc-api.ts b/apps/server/src/routes/misc-api.ts
index 29e8a42e..ff63c545 100644
--- a/apps/server/src/routes/misc-api.ts
+++ b/apps/server/src/routes/misc-api.ts
@@ -1,5 +1,5 @@
 /**
- * Miscellaneous API routes — presets, packages, commands, block-schemas, llm-config, provider-keys.
+ * Miscellaneous API routes — presets, packages, commands, llm-config, provider-keys.
  *
  * These endpoints are consumed by the frontend boot sequence.
  */
@@ -93,28 +93,6 @@ export function createMiscApiRoutes(
     return c.json(payload);
   });
 
-  // GET /api/block-schemas — list block schemas from plugin manifests
-  app.get("/api/block-schemas", (c) => {
-    const schemas: Record<string, unknown> = {};
-    const all = registry.getAll();
-    for (const [, entry] of all) {
-      const manifests =
-        entry.manifests ?? (entry.manifest ? [entry.manifest] : []);
-      for (const m of manifests) {
-        // blockSchemas may be declared in rawFrontmatter (from PLUGIN.md) or plugin.json
-        const bs = (m.rawFrontmatter as Record<string, unknown>).blockSchemas;
-        if (bs && typeof bs === "object") {
-          for (const [key, val] of Object.entries(
-            bs as Record<string, unknown>,
-          )) {
-            schemas[key] = val;
-          }
-        }
-      }
-    }
-    return c.json({ schemas });
-  });
-
   // GET /api/ui-specs — list UI specs from plugin manifests, grouped by slot.
   // When ?sessionId= is provided, filter to that session's activePlugins so the
   // panel only shows plugins actually enabled for the current session.
diff --git a/apps/web/src/components/blocks/block-renderer.tsx b/apps/web/src/components/blocks/block-renderer.tsx
deleted file mode 100644
index 1c60a7e5..00000000
--- a/apps/web/src/components/blocks/block-renderer.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-/**
- * Block schema registry.
- *
- * 消息渲染已经全部走 json-render + plugin-data 数据流（见
- * `apps/web/src/components/session/chat-messages.tsx`）。本模块只保留一个
- * 对外契约：`setBlockSchemas(schemas)` — 供 session-store 在 boot 时注入插件
- * 声明的 blockSchemas。
- *
- * 所有自定义 React block 组件（action-guide-block / codex-entry-block / …）
- * 已被删除——插件用自己的 `ui/*.json` spec 通过 json-render 渲染。
- */
-
-import type { BlockSchemaDeclaration } from "@covel/shared";
-
-// Module-level mutable state: a singleton registry updated once at boot
-// (via setBlockSchemas).
-let blockSchemas: Record<string, BlockSchemaDeclaration> = {};
-
-export function setBlockSchemas(
-  schemas: Record<string, BlockSchemaDeclaration>,
-) {
-  blockSchemas = schemas;
-}
diff --git a/apps/web/src/services/api/llm.ts b/apps/web/src/services/api/llm.ts
index 7355049e..02b6c1a0 100644
--- a/apps/web/src/services/api/llm.ts
+++ b/apps/web/src/services/api/llm.ts
@@ -173,15 +173,6 @@ export function mergeCapability(
   };
 }
 
-// -- Block Schemas -------------------------------------------------
-
-export async function fetchBlockSchemas(): Promise<Record<string, unknown>> {
-  const res = await request<{ schemas: Record<string, unknown> }>(
-    "/api/block-schemas",
-  );
-  return res.schemas;
-}
-
 // -- AI Ping -------------------------------------------------------
 
 /**
diff --git a/apps/web/src/stores/__tests__/session-store-plugins.test.ts b/apps/web/src/stores/__tests__/session-store-plugins.test.ts
index 0559ac10..d261ba93 100644
--- a/apps/web/src/stores/__tests__/session-store-plugins.test.ts
+++ b/apps/web/src/stores/__tests__/session-store-plugins.test.ts
@@ -92,10 +92,6 @@ vi.mock("../../../services/data-service.js", () => ({
   })),
 }));
 
-vi.mock("../../../components/blocks/block-renderer.js", () => ({
-  setBlockSchemas: vi.fn(),
-}));
-
 vi.mock("i18next", () => ({
   default: { language: "zh-CN", t: vi.fn((k: string) => k) },
 }));
diff --git a/apps/web/src/stores/session-store/boot.ts b/apps/web/src/stores/session-store/boot.ts
index 712618ec..c7323c89 100644
--- a/apps/web/src/stores/session-store/boot.ts
+++ b/apps/web/src/stores/session-store/boot.ts
@@ -1,12 +1,10 @@
 import i18n from "i18next";
-import { setBlockSchemas } from "@/components/blocks/block-renderer.js";
 import { emitToast } from "@/lib/toast-channel.js";
 import { migrateLocalStorageToIdb } from "@/services/app-kv-store.js";
 import * as api from "@/services/api";
 import type { DataService } from "@/services/data-service.js";
 import { registerPluginUserSettings } from "@/settings/registry/plugin.js";
 import { getSettings, registerKnownProviders } from "@/settings/store.js";
-import type { BlockSchemaDeclaration } from "@covel/shared";
 import type { SessionDispatch } from "./types.js";
 
 interface BootSessionStoreOptions {
@@ -49,16 +47,12 @@ export async function bootSessionStore({
   await migrateLocalStorageToIdb();
 
   try {
-    const [presets, packagesRes, worlds, schemas, llmConfig] =
-      await Promise.all([
-        api.listPresets(),
-        api.listPackages(),
-        ds.listWorlds(),
-        api.fetchBlockSchemas().catch(() => ({})),
-        api.fetchLlmConfig().catch(() => null),
-      ]);
-
-    setBlockSchemas(schemas as Record<string, BlockSchemaDeclaration>);
+    const [presets, packagesRes, worlds, llmConfig] = await Promise.all([
+      api.listPresets(),
+      api.listPackages(),
+      ds.listWorlds(),
+      api.fetchLlmConfig().catch(() => null),
+    ]);
 
     for (const pkg of packagesRes.packages) {
       if (pkg.userSettings && pkg.userSettings.length > 0) {
diff --git a/docs/guide/env-registry.md b/docs/guide/env-registry.md
index 9e5fd08d..38dc6a5b 100644
--- a/docs/guide/env-registry.md
+++ b/docs/guide/env-registry.md
@@ -55,7 +55,7 @@ Covel 的环境变量清单由 `packages/shared/src/env/registry.ts` 维护。
 - `DEPLOYMENT_TIER=self` 对应本地自部署；localhost 请求可以读取 server 注入的 provider key 元数据。`demo` / `commercial` 会硬性强制 session owner token 鉴权（见 [`docs/reference/api.md`](../reference/api.md) 鉴权章节）。未知值会被规范化并 fail-closed 到最严格的 `commercial`。
 - `COVEL_DESKTOP_REST_TOKEN` 是运维 master / operator 凭证：以该值作为 Bearer token 可通过任意会话的 owner 校验（管理工具 / e2e harness 用），并且是 hosted（`demo` / `commercial`）层级创建/列出会话、世界写入与维度导入、AI 世界生成、模型探测/刷新以及 community server-code 激活的必需凭证。`DEPLOYMENT_TIER=demo|commercial` 启动时若未配置该 token，`validateSecurityPosture` 会直接拒绝启动（fail-closed）。`self` / 桌面 / dev 层级不要求也不校验它。这是当前单运维方信任模型，不提供多租户身份或代码沙箱（见 [`docs/reference/api.md`](../reference/api.md) 鉴权章节）。
 - `COVEL_BIND_HOST` 默认 `127.0.0.1`（audit S-02）：本地 / 桌面部署只监听回环接口，网络上不可达。容器或多 pod 部署需显式设置 `COVEL_BIND_HOST=0.0.0.0`（`docker/docker-compose.yml` 已内置）——这是一次显式的部署决策，公开监听前请确认 `DEPLOYMENT_TIER` 与鉴权配置。
-- `TRUSTED_PROXY_IPS`、`COVEL_LLM_REPLAY`、`COVEL_LLM_REPLAY_DIR`、`COVEL_ALLOWED_LLM_HOSTS` 目前标记为 `documented`，后续实现可以直接提升为 `active`。
+- `TRUSTED_PROXY_IPS`、`COVEL_LLM_REPLAY`、`COVEL_LLM_REPLAY_DIR` 目前标记为 `documented`，后续实现可以直接提升为 `active`。（`COVEL_ALLOWED_LLM_HOSTS` 已移除：SSRF guard 设计上即 open-by-default，从未读取该变量，也无实现计划。）
 - `COVEL_TRACE_TRUNCATE` 标记为 `planned`，对应 debug trace 设计文档中的未来开关。
 - `COVEL_COMPACTOR_CONTEXT_WINDOW` 为**可选的显式覆盖**：未设置时，压缩阈值与 prompt 硬裁剪预算按当前叙事 slot（`default`，缺省为 llm.toml 首个 slot）的模型 capability `contextWindow` 动态解析（llm.toml 热重载即时生效），capability 也缺失时回退 `32768`。设置后固定使用该值，不再查 capability。
 - `COVEL_SNAPSHOT_INTERVAL_TURNS` 默认 `5`，控制 `kind=auto` 快照的 checkpoint 节奏：`turnCount <= 1`（pre-game 与首个正式回合）总是写入，其后每 N 回合写一份；`1` 表示每回合。resume 路径无视该节流强制写入。构建快照 payload 需要全量读取消息历史与全部 session-scoped 集合，逐回合写入会导致 O(T²) 成本与存储膨胀（audit 2026-07-11 R-04）。
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 1b9b7a4d..740dc877 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -467,7 +467,6 @@ Fork 不继承 community server-code grant；child 中对应插件保持未激
 | ---- | ------------------------------ | --------------------------------------------------------------------------------------- |
 | GET  | `/api/presets`                 | 列出配置的模型预设                                                                      |
 | GET  | `/api/packages`                | 列出已加载插件包（含 runtime/tool/`userSettings`/`tags`/`relations` 信息）              |
-| GET  | `/api/block-schemas`           | 列出插件 block schema                                                                   |
 | GET  | `/api/ui-specs?sessionId=<id>` | 列出插件 UI 声明（按 slot 分组）；带 `sessionId` 时按会话激活集过滤，不带则返回全部插件 |
 | GET  | `/api/llm-config`              | 返回 slot 配置与能力信息；llm.toml 解析失败回退默认时附带 `error` 字段                  |
 | POST | `/api/llm-config/reload`       | 重读 llm.toml 并原地应用到运行中的 gateway（无需重启）；返回 `{ ok, slots, error? }`    |
diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md
index bcf4a6c6..ee90381e 100644
--- a/docs/reference/plugins.md
+++ b/docs/reference/plugins.md
@@ -895,7 +895,7 @@ tools:
     - plugin-data-get
 ```
 
-> **弃用说明**：`tools.local` / `hooks` / `rpc` / `wires` 四个 frontmatter 注册字段自本版本起弃用（启动时每插件 warn 一次），保留一个发布周期后移除。内置插件已全部迁移到 `entry`。
+> **弃用说明**：`tools.local` / `hooks` / `rpc` / `wires` 四个 frontmatter 注册字段自 v0.0.14 起弃用（启动时每插件 warn 一次），**计划于 v0.0.17 移除**。内置插件已全部迁移到 `entry`；社区插件请尽快迁移。
 
 ### wires（媒体厂商 wire 注册，已弃用 — 改用 entry 的 `covel.registerWires`）
 
diff --git a/packages/shared/src/env/groups/ai.ts b/packages/shared/src/env/groups/ai.ts
index 6ae74d88..3e9a69e8 100644
--- a/packages/shared/src/env/groups/ai.ts
+++ b/packages/shared/src/env/groups/ai.ts
@@ -39,11 +39,4 @@ export const AI_ENV_VARS = [
     defaultValue: "debugs/llm-cache",
     description: "Documented dev LLM replay cache directory.",
   },
-  {
-    name: "COVEL_ALLOWED_LLM_HOSTS",
-    group: "ai",
-    type: "string",
-    status: "documented",
-    description: "Documented custom LLM host allowlist.",
-  },
 ] as const satisfies readonly EnvVarDefinition[];
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index 4f436ab8..9d339f62 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -136,8 +136,6 @@ export type {
   UIRenderPartsInstruction,
   UIRenderLegacyInstruction,
   UIRenderInstruction,
-  BlockSchemaMeta,
-  BlockSchemaDeclaration,
 } from "./ui.js";
 
 export {
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
index 34b8bbe2..864ca891 100644
--- a/packages/shared/src/types/plugin.ts
+++ b/packages/shared/src/types/plugin.ts
@@ -332,7 +332,9 @@ export interface ToolsConfig {
   /**
    * Relative paths to local tool modules.
    * @deprecated Register tools imperatively in the unified `entry` module and
-   * list their names under `plugin` instead. Kept working for one cycle.
+   * list their names under `plugin` instead. All bundled plugins migrated in
+   * v0.0.14; this shim (and the legacy `hooks`/`rpc`/`wires` frontmatter
+   * fields) is planned for removal in v0.0.17.
    */
   readonly local?: readonly string[];
   /**
diff --git a/packages/shared/src/types/ui.ts b/packages/shared/src/types/ui.ts
index a6c5ed75..86c29a59 100644
--- a/packages/shared/src/types/ui.ts
+++ b/packages/shared/src/types/ui.ts
@@ -140,33 +140,3 @@ export function normalizeUIRenderInstruction(
 /**
  * JSON Schema-based block schema declaration for plugin UI rendering.
  */
-export interface BlockSchemaMeta {
-  /** Human-readable display name (string or locale-keyed). */
-  readonly displayName?: string | Record<string, string>;
-  readonly [key: string]: unknown;
-}
-
-export interface BlockSchemaDeclaration {
-  /** Block type identifier (matches UIComponentType or custom). */
-  readonly blockType: string;
-  /** Human-readable display name. */
-  readonly displayName?: string;
-  /** JSON Schema describing the block's data shape. */
-  readonly dataSchema: {
-    readonly type: string;
-    readonly properties?: Record<string, unknown>;
-    readonly required?: readonly string[];
-    readonly [key: string]: unknown;
-  };
-  /** Whether the block accepts user input (form submission). */
-  readonly interactive?: boolean;
-  /** JSON Schema for form submission payload (interactive blocks). */
-  readonly submitSchema?: {
-    readonly type: string;
-    readonly properties?: Record<string, unknown>;
-    readonly required?: readonly string[];
-    readonly [key: string]: unknown;
-  };
-  /** Block metadata (display name, description, etc.). */
-  readonly meta: BlockSchemaMeta;
-}

From 7452f693c260f79453dacb17ca3c9d01e5973afe Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 11:47:37 +0800
Subject: [PATCH 05/10] docs: sync all reference and guide docs to the current
 architecture

Cluster-by-cluster verification of docs/ against the codebase (every fix
backed by a file:line check):

- flow.md: model-db count 2967, createGateway factory names, full
  11-type proposal enum, compactor + applyBudget window resolution,
  plugin-test-utils surface, slot examples aligned with slots.md
- api.md: drop deleted plugin-data-contract route; add missing
  DELETE /api/worlds/:id, /api/plugin-flows, media-token, install
  endpoints; rewrite event-type tables around the CovelEvent union
- protocol.md: fix stale file/line anchors, add proposalType to hook
  trace payloads
- plugins.md/tools.md: fix world-init ui spec name, branch-reply slot
  column, chat-mode-narrator requires, player-init runtime shape
  (agent + guard, not function), approval policy path; mojibake repair
- ui-panels/ui-components: drop fixed Lorebook tab claim, add missing
  character-presence and scene-cast panels, component count 48
- CLAUDE.md: 27 store tables (with real pointer), app.ts size, ~48
  component catalog
- glossary.md: split pluginType (core-plugin/plugin) from trust tier
  (builtin/official/community) - two independent axes
- README/guides: verified, minor sync only

Historical docs (CHANGELOG, explorations, superpowers, audits)
deliberately untouched.
---
 CLAUDE.md                               |   6 +-
 README.md                               |   4 +-
 README.zh-CN.md                         |   4 +-
 docs/architecture/flow.md               |  43 +++---
 docs/glossary.md                        |   2 +-
 docs/guide/desktop-config.en.md         |   8 +-
 docs/guide/desktop-config.md            |   2 +-
 docs/guide/plugin-authoring-advanced.md |   2 +-
 docs/guide/plugin-authoring.md          |   3 +-
 docs/reference/api.md                   | 179 ++++++++++++------------
 docs/reference/media-store.md           |  12 +-
 docs/reference/plugins.md               |  58 ++++----
 docs/reference/protocol.md              |  26 ++--
 docs/reference/tools.md                 |   2 +-
 docs/reference/ui-components.md         |  63 +++++----
 docs/reference/ui-panels.md             |  94 ++-----------
 16 files changed, 232 insertions(+), 276 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c33a5d8b..ee537ec8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -178,7 +178,7 @@ Detailed field reference, per-plugin table, and trigger semantics: [docs/referen
 
 ### Plugin UI (declarative, json-render)
 
-All panels/blocks render through [json-render](https://github.com/vercel-labs/json-render) with a framework-defined ~25-component catalog. Plugins declare `ui: { right, message, left }` in PLUGIN.md, pointing at JSON specs under `ui/`. `GET /api/ui-specs` aggregates them; frontend discovers panels at boot. `plugin-data.changed` SSE events drive re-renders. Three-tier resolution: custom React (`.tsx`) → json-render spec (`.json`) → raw JSON fallback. Details in [docs/reference/ui-panels.md](./docs/reference/ui-panels.md).
+All panels/blocks render through [json-render](https://github.com/vercel-labs/json-render) with a framework-defined ~48-component catalog ([docs/reference/ui-components.md](./docs/reference/ui-components.md)). Plugins declare `ui: { right, message, left }` in PLUGIN.md, pointing at JSON specs under `ui/`. `GET /api/ui-specs` aggregates them; frontend discovers panels at boot. `plugin-data.changed` SSE events drive re-renders. Three-tier resolution: custom React (`.tsx`) → json-render spec (`.json`) → raw JSON fallback. Details in [docs/reference/ui-panels.md](./docs/reference/ui-panels.md).
 
 ### Model slot system
 
@@ -275,14 +275,14 @@ Each SQL backend keeps a thin public factory plus focused method modules:
 - `*-store-mappers.ts` / `*-store-values.ts` — row conversion and JSON helpers.
 - `*-data-crud.ts`, `*-runtime-records.ts`, `*-session-*`, `*-snapshot*`, `*-state*`, `*-world*` — focused persistence surfaces.
 
-22 tables via Drizzle; full list and transactions contract in [docs/reference/transactions.md](./docs/reference/transactions.md).
+27 tables via Drizzle; authoritative list in `packages/store/src/{sqlite,postgres}/schema.ts`, transactions contract in [docs/reference/transactions.md](./docs/reference/transactions.md).
 
 - **`sessions.runtime_model_overrides`** — JSONB map of `runtimeId → slot name`, snapshotted into `TurnInput` each turn and consulted by `runtime-slot-resolver` before `manifest.model` / gateway default. Keys still flow via `X-Provider-Keys` + localStorage.
 - **JSONB writes**: use `sql.json(value as JSONValue)` — **never** `JSON.stringify()` (double-serialisation bug).
 
 ## Server Bootstrap
 
-`bootstrapApi()` in `apps/server/src/routes/api/bootstrap.ts` wires a fully composed Hono app (plugin discovery + registries + middleware injection); `app.ts` is a thin composition root (~80 lines). All endpoints under `/api/` prefix. Full endpoint reference: [docs/reference/api.md](./docs/reference/api.md).
+`bootstrapApi()` in `apps/server/src/routes/api/bootstrap.ts` wires a fully composed Hono app (plugin discovery + registries + middleware injection); `app.ts` is the composition root (~420 lines: env/key loading, store + AI stack setup, middleware, then delegates to `bootstrapApi()`). All endpoints under `/api/` prefix. Full endpoint reference: [docs/reference/api.md](./docs/reference/api.md).
 
 ## Testing Conventions
 
diff --git a/README.md b/README.md
index 1286f175..1ff5aa7e 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **English** · [简体中文](./README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-v0.0.14-8b5cf6)](https://github.com/ackness/covel/releases/tag/v0.0.14)
+[![Version](https://img.shields.io/badge/version-v0.0.15-8b5cf6)](https://github.com/ackness/covel/releases/tag/v0.0.15)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Stage](https://img.shields.io/badge/stage-early--access-orange)]()
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ackness/covel)
@@ -13,7 +13,7 @@
 
 Covel is an AI RPG where the world keeps running between your turns: NPCs track how they feel about you, lore accumulates as you play, and memory carries the thread across the session. Every mechanic behind that is an **autonomous agent shipped as a plugin** — disable one, swap one, or write your own.
 
-> **Current public release: v0.0.14**, early access — APIs, data formats, and plugin frontmatter may change between versions. Prebuilt binaries target macOS Apple Silicon and Windows x64; other platforms build from source.
+> **Current public release: v0.0.15**, early access — APIs, data formats, and plugin frontmatter may change between versions. Prebuilt binaries target macOS Apple Silicon and Windows x64; other platforms build from source.
 
 ## Highlights
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 68543d76..6f283a0f 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,7 +4,7 @@
 
 [English](./README.md) · **简体中文**
 
-[![Version](https://img.shields.io/badge/version-v0.0.14-8b5cf6)](https://github.com/ackness/covel/releases/tag/v0.0.14)
+[![Version](https://img.shields.io/badge/version-v0.0.15-8b5cf6)](https://github.com/ackness/covel/releases/tag/v0.0.15)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Stage](https://img.shields.io/badge/stage-early--access-orange)]()
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ackness/covel)
@@ -13,7 +13,7 @@
 
 Covel 是一款 AI 驱动的 RPG，回合之间世界仍在运转：NPC 记录着对你的态度、世界典籍随游玩积累、记忆贯穿整局。支撑这一切的每个机制都是一个**以插件形式分发的自主 agent** —— 禁用一个、替换一个，或者自己写一个。
 
-> **当前公开版本：v0.0.14**，早期阶段 —— API、数据格式、插件 frontmatter 可能随版本变化。官方预编译包面向 macOS Apple Silicon 与 Windows x64，其余平台从源码构建。
+> **当前公开版本：v0.0.15**，早期阶段 —— API、数据格式、插件 frontmatter 可能随版本变化。官方预编译包面向 macOS Apple Silicon 与 Windows x64，其余平台从源码构建。
 
 ## 亮点
 
diff --git a/docs/architecture/flow.md b/docs/architecture/flow.md
index 5e8e44b9..9ac2dd82 100644
--- a/docs/architecture/flow.md
+++ b/docs/architecture/flow.md
@@ -133,7 +133,7 @@ flowchart TB
 | `0`       | `0–99`               | Pre-Game band（如 `pregame`、`world-init`、`char-creator`）                                                                                                                                    |
 | `>= 1`    | `100–1000`           | 主循环（narrator `500` / guide / codex / npc-graph extractor / character-tracker 同 `600` …）。同优先级的下游 runtime 通过 `upstreamRequired` + `input.inject` 声明依赖，由 DAG 调度器并发执行 |
 
-**Proposal 类型**（全部过 commit chain）：`narrative.append`、`interaction.request`、`state.patch`、`event.emit`、`plugin.data` / `plugin.data.batch`、`working_memory.set`、`lorebook.upsert`。runtime 输出若带 legacy `phase` 字段会被 `normalizeOutput` 静默忽略（兼容老插件，不报错、不产生 proposal）。
+**Proposal 类型**（全部过 commit chain，源自 `ProposalPayloadMap`）：`narrative.append`、`interaction.request`、`state.patch`、`event.emit`、`ui.render`、`asset.generate`、`plugin.data` / `plugin.data.batch`、`character.upsert`、`working_memory.set`、`lorebook.upsert`。runtime 输出若带 legacy `phase` 字段会被 `normalizeOutput` 静默忽略（兼容老插件，不报错、不产生 proposal）。
 
 ## 三、消息翻译层（玩家 ↔ LLM Agent）
 
@@ -353,7 +353,7 @@ plugins/my-plugin/
 │                                            │  Button      │      │
 │                                            │  EntryCard   │      │
 │                                            │  Alert       │      │
-│                                            │  ...25个组件  │      │
+│                                            │  ...48个组件  │      │
 │                                            └─────────────┘      │
 │                                                                  │
 │  plugin-data.changed ──► pluginData store  ──► MessagePluginSurface │
@@ -689,9 +689,9 @@ sequenceDiagram
 
 启动 → LLM 初始化            @covel/ai-provider               多供应商 LLM 抽象
                              ├── presetRegistry               管理 LLM 预设 (llm.toml)
-                             ├── slotRegistry                 slot 路由 (default/fast/story)
-                             ├── createGatewayAdapter()       统一 generate() 接口
-                             └── model-db                     2597 模型能力数据库
+                             ├── slotRegistry                 slot 路由 (default/fast/balance/image)
+                             ├── createGateway()              统一 generate() 接口
+                             └── model-db                     2967 模型能力数据库
 
 启动 → 依赖注入              @covel/tools                     工具系统
                              ├── tool()                       工具定义 wrapper
@@ -715,7 +715,11 @@ Turn 执行                    @covel/runtime                   核心执行引
 上下文组装                    @covel/context                   Prompt 组装
                              ├── buildContext()               模板变量 + 注入块 + 消息历史
                              ├── interpolateTemplate()        {{ }} 占位符替换
-                             └── Compactor                    长对话压缩
+                             ├── applyBudget()                硬裁剪兜底（窗口按叙事 slot 的
+                             │                                  模型 capability 动态解析）
+                             └── Compactor                    长对话压缩（同一窗口来源，
+                                                                COVEL_COMPACTOR_CONTEXT_WINDOW
+                                                                可选覆盖）
 
 类型共享                      @covel/shared                   跨包类型定义
                              ├── types/plugin.ts              RuntimeManifest, UISpec, etc.
@@ -727,6 +731,7 @@ Turn 执行                    @covel/runtime                   核心执行引
 测试支持                      @covel/plugin-test-utils         插件作者测试工具
                              ├── MockLLM                      模拟 LLM 响应
                              ├── makeManualFunctionContext()  function handler 测试 context
+                             ├── expectAssetGenerated()       断言 asset.generate proposal
                              └── factory functions             makeTurnInput, etc.
 ```
 
@@ -762,19 +767,19 @@ Turn 执行                    @covel/runtime                   核心执行引
 
 ### 8.3 各包核心接口
 
-| 包                    | 核心导出                                                        | 调用方                    |
-| --------------------- | --------------------------------------------------------------- | ------------------------- |
-| **shared**            | `RuntimeManifest`, `UISpec`, `ProtocolEventType`, Zod schemas   | 所有包                    |
-| **plugin-loader**     | `discoverPlugins()`, `loadRuntime()`, `PluginRegistry`          | server bootstrap          |
-| **ai-provider**       | `createGatewayAdapter()`, `PresetRegistry`, `SlotRegistry`      | server bootstrap, runtime |
-| **context**           | `buildContext()`, `interpolateTemplate()`                       | runtime (per-runtime)     |
-| **runtime**           | `executeTurn()`, `createToolExecutor()`, `shouldTrigger()`      | server actions route      |
-| **store**             | `DataStore` interface, `createMemoryStore()`, `createPgStore()` | server, tools, runtime    |
-| **events**            | `createEventBus()`, `EventBus.emit()`, `EventBus.onEmit()`      | server, plugin-data-tools |
-| **tools**             | `tool()`, `createPluginDataTools()`, `shortIdBatch()`           | bootstrap, plugin tools   |
-| **state**             | `createStateManager()`, `StateManager`                          | server, runtime           |
-| **approval**          | `createApprovalPipeline()`, `ApprovalPipeline.check()`          | tool executor             |
-| **plugin-test-utils** | `MockLLM`, `makeManualFunctionContext()`                        | plugin tests only         |
+| 包                    | 核心导出                                                            | 调用方                    |
+| --------------------- | ------------------------------------------------------------------- | ------------------------- |
+| **shared**            | `RuntimeManifest`, `UISpec`, `ProtocolEventType`, Zod schemas       | 所有包                    |
+| **plugin-loader**     | `discoverPlugins()`, `loadRuntime()`, `PluginRegistry`              | server bootstrap          |
+| **ai-provider**       | `createGateway()`, `createPresetRegistry()`, `createSlotRegistry()` | server bootstrap, runtime |
+| **context**           | `buildContext()`, `interpolateTemplate()`                           | runtime (per-runtime)     |
+| **runtime**           | `executeTurn()`, `createToolExecutor()`, `shouldTrigger()`          | server actions route      |
+| **store**             | `DataStore` interface, `createMemoryStore()`, `createPgStore()`     | server, tools, runtime    |
+| **events**            | `createEventBus()`, `EventBus.emit()`, `EventBus.onEmit()`          | server, plugin-data-tools |
+| **tools**             | `tool()`, `createPluginDataTools()`, `shortIdBatch()`               | bootstrap, plugin tools   |
+| **state**             | `createStateManager()`, `StateManager`                              | server, runtime           |
+| **approval**          | `createApprovalPipeline()`, `ApprovalPipeline.check()`              | tool executor             |
+| **plugin-test-utils** | `MockLLM`, `makeManualFunctionContext()`, `expectAssetGenerated()`  | plugin tests only         |
 
 ## 九、设计约束与原则
 
diff --git a/docs/glossary.md b/docs/glossary.md
index 55478596..9f00d41e 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -32,7 +32,7 @@ See: `apps/web/src/lib/session-plugin-selection.ts`, [docs/reference/plugins.md]
 
 ## PluginType
 
-The trust/ownership tier of a plugin: `core-plugin` (bundled, auto-loaded), `official` (whitelisted), or `community` (deferred until user approves). Governs tool approval policy, prompt injection scope, and update channels.
+Two separate axes describe a plugin's provenance. `pluginType` is a manifest field with two values — `core-plugin` (bundled, non-disableable) or `plugin` (optional, disableable) — and only gates core-vs-third-party dispatch. Trust tier (`builtin`, `official`, or `community`, derived from load path, not the name) is the field that governs auto-load and tool-approval policy.
 
 See: [docs/reference/plugins.md](./reference/plugins.md), [docs/reference/tools.md](./reference/tools.md).
 
diff --git a/docs/guide/desktop-config.en.md b/docs/guide/desktop-config.en.md
index c68e1305..6c159405 100644
--- a/docs/guide/desktop-config.en.md
+++ b/docs/guide/desktop-config.en.md
@@ -16,9 +16,11 @@ On first launch the desktop app creates `~/.covel/`. Config and user plugins liv
 <data_root>/                 ← default ~/.covel/data; redirectable
   covel.db                   ← SQLite database
   worlds/                    ← user-created worlds
-  logs/                      ← app logs (auto-rotated)
-    electron-*.log           ← Electron main process
-    server-*.log             ← Node backend (pino-roll)
+  logs/                      ← app logs (size-rotated, one NDJSON record per line)
+    desktop.log              ← Electron main-process events
+    server.log               ← Node sidecar stdout/stderr
+    desktop.log.1 … .N       ← rotated copies, oldest dropped past max_files
+    server.log.1 … .N
   server.port                ← last boot port (diagnostics)
 ```
 
diff --git a/docs/guide/desktop-config.md b/docs/guide/desktop-config.md
index cbd3cb51..539fd2e8 100644
--- a/docs/guide/desktop-config.md
+++ b/docs/guide/desktop-config.md
@@ -77,7 +77,7 @@ server 会按 `*_API_KEY` 扫描所有条目注入 provider 运行时。Key 名
 
 ## 桌面 REST 写接口的 token 门
 
-桌面版 sidecar 会在每次启动时生成一个一次性 bearer token，并以 `COVEL_DESKTOP_REST_TOKEN` 注入子进程环境。所有写接口（`PUT /api/config/keys`、`PUT /api/config/settings`、`PUT /api/config/data-root`、`POST /api/config/open-folder`）会校验请求头 `Authorization: Bearer <token>`，缺失或不匹配返回 `401`。读接口（`GET /api/config/info`、`GET /api/config/keys`（仅返回 provider 列表）、`GET /api/config/settings`）保持开放。
+桌面版 sidecar 会在每次启动时生成一个一次性 bearer token，并以 `COVEL_DESKTOP_REST_TOKEN` 注入子进程环境。所有写接口（`PUT /api/config/keys`、`PUT /api/config/settings`、`PUT /api/config/data-root`、`POST /api/config/open-folder`）以及 `GET /api/config/settings`（返回完整 settings.json 内容）都会校验请求头 `Authorization: Bearer <token>`，缺失或不匹配返回 `401`。真正开放的只有 `GET /api/config/info` 和 `GET /api/config/keys`（仅返回 provider 列表，不含 key 值）。
 
 `GET /api/config/info` 的响应里增加了 `requiresAuth` 字段，前端据此决定是否需要附带 Authorization 头。Electron 渲染进程通过 `covel:get-info` IPC 拿到 `restToken` 字段，自动注入到所有写请求。开发模式下若未设置该 env，token 门不启用，纯 web tier 与 `pnpm dev:web` 流程保持原样。
 
diff --git a/docs/guide/plugin-authoring-advanced.md b/docs/guide/plugin-authoring-advanced.md
index e644bbfd..53057166 100644
--- a/docs/guide/plugin-authoring-advanced.md
+++ b/docs/guide/plugin-authoring-advanced.md
@@ -680,7 +680,7 @@ my-plugin/
 
 - 数据库表名或 ORM 模型
 - 内核调度器、路由器等内部模块
-- 前端组件（UI 通过 blockSchema 或交互协议集成）
+- 前端组件（UI 通过 json-render spec 或交互协议集成）
 - 直接 SDK 调用（LLM 调用通过 model slot 绑定）
 
 ## 8. 插件国际化（i18n）
diff --git a/docs/guide/plugin-authoring.md b/docs/guide/plugin-authoring.md
index 0742acb4..5915519a 100644
--- a/docs/guide/plugin-authoring.md
+++ b/docs/guide/plugin-authoring.md
@@ -93,8 +93,7 @@ CI 的 `check-plugin-i18n` 校验 `ui/*.json` spec、`PLUGIN.md` frontmatter，*
 第三方开发者和 AI Agent 可以先调用 discovery API，再决定该读哪份文档或写哪个字段：
 
 - `GET /api/framework/capabilities`：框架支持的 manifest 枚举、builtin tools、proposal types、world-data target/schema URI、plugin-data 写入路径。
-- `GET /api/plugins/:id/contract`：某个插件声明的 runtimes、capabilities、tools、rpc actions、UI slots、`dataSchemas` 和 plugin-data namespace。
-- `GET /api/plugins/:id/plugin-data-contract`：某个插件的 plugin-data namespace/schema 子集。
+- `GET /api/plugins/:id/contract`：某个插件声明的 runtimes、capabilities、tools、rpc actions、UI slots、`dataSchemas` 和 plugin-data namespace/schema 契约。
 - `GET /api/sessions/:id/plugin-data/:pluginId/_index`：某个 session 下插件实际已有的 namespace/key 索引，不返回 value。
 
 这组 API 回答“当前框架和插件声明支持什么”；具体字段含义仍以 `docs/reference/`、插件 JSON Schema 和插件自己的 `PLUGIN.md` 为准。
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 740dc877..1ced1672 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -185,17 +185,18 @@ curl -X DELETE http://localhost:3001/api/sessions/<sessionId>
 
 ### 世界管理
 
-| 方法  | 路径                                   | 描述                                                                             |
-| ----- | -------------------------------------- | -------------------------------------------------------------------------------- |
-| GET   | `/api/worlds`                          | 列出所有世界                                                                     |
-| GET   | `/api/worlds/:id`                      | 获取世界详情                                                                     |
-| POST  | `/api/worlds`                          | 创建/更新世界                                                                    |
-| PATCH | `/api/worlds/:id`                      | 部分更新世界（支持顶层 `dimensions`，并与现有 `metadata` 合并）                  |
-| GET   | `/api/worlds/:id/dimensions/export`    | 导出世界维度（YAML/JSON）                                                        |
-| POST  | `/api/worlds/:id/dimensions/import`    | 导入世界维度                                                                     |
-| POST  | `/api/worlds/:id/sync-dimensions`      | 将世界维度同步到活跃 session 的 `plugin_data` 与 lorebook 常量词条，并清理旧 key |
-| POST  | `/api/worlds/:id/world-data/preflight` | 只读构建 worldData import plan，返回 diagnostics、planned count 和目标摘要       |
-| POST  | `/api/worlds/:id/sync-data`            | 基于 provenance ledger 同步 importer 管理的 worldData row，支持 dry-run 与 force |
+| 方法   | 路径                                   | 描述                                                                              |
+| ------ | -------------------------------------- | --------------------------------------------------------------------------------- |
+| GET    | `/api/worlds`                          | 列出所有世界                                                                      |
+| GET    | `/api/worlds/:id`                      | 获取世界详情                                                                      |
+| POST   | `/api/worlds`                          | 创建/更新世界                                                                     |
+| PATCH  | `/api/worlds/:id`                      | 部分更新世界（支持顶层 `dimensions`，并与现有 `metadata` 合并）                   |
+| DELETE | `/api/worlds/:id`                      | 删除世界（内置 `source:"file"` 世界禁止删除，返回 403；hosted 需 operator token） |
+| GET    | `/api/worlds/:id/dimensions/export`    | 导出世界维度（YAML/JSON）                                                         |
+| POST   | `/api/worlds/:id/dimensions/import`    | 导入世界维度                                                                      |
+| POST   | `/api/worlds/:id/sync-dimensions`      | 将世界维度同步到活跃 session 的 `plugin_data` 与 lorebook 常量词条，并清理旧 key  |
+| POST   | `/api/worlds/:id/world-data/preflight` | 只读构建 worldData import plan，返回 diagnostics、planned count 和目标摘要        |
+| POST   | `/api/worlds/:id/sync-data`            | 基于 provenance ledger 同步 importer 管理的 worldData row，支持 dry-run 与 force  |
 
 ### 会话管理
 
@@ -252,14 +253,23 @@ curl -X DELETE http://localhost:3001/api/sessions/<sessionId>
 
 ### 全局插件
 
-| 方法   | 路径                                    | 描述                                                                                                                                                                                                                                                    |
-| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET    | `/api/framework/capabilities`           | 框架级能力索引：manifest 枚举、工具、proposal、world-data URI                                                                                                                                                                                           |
-| GET    | `/api/plugins`                          | 列出所有已加载插件                                                                                                                                                                                                                                      |
-| GET    | `/api/plugins/:id`                      | 获取插件详情                                                                                                                                                                                                                                            |
-| DELETE | `/api/plugins/:id`                      | 卸载第三方插件（删除 `~/.covel/plugins/<id>`）。桌面端要求 bearer token；无 token 的生产部署要求 `COVEL_INSTALL_API_ENABLED=1`。错误码：鉴权失败 `401/403`、id 格式非法 `400`、内置 ID `409`、未安装 `404`；成功返回 `{ ok, id, restartRequired:true }` |
-| GET    | `/api/plugins/:id/contract`             | 获取插件完整开发契约                                                                                                                                                                                                                                    |
-| GET    | `/api/plugins/:id/plugin-data-contract` | 获取插件数据 namespace/schema 契约                                                                                                                                                                                                                      |
+| 方法   | 路径                          | 描述                                                                                                                                                                                                                                                    |
+| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/api/framework/capabilities` | 框架级能力索引：manifest 枚举、工具、proposal、world-data URI                                                                                                                                                                                           |
+| GET    | `/api/plugins`                | 列出所有已加载插件                                                                                                                                                                                                                                      |
+| GET    | `/api/plugins/:id`            | 获取插件详情                                                                                                                                                                                                                                            |
+| DELETE | `/api/plugins/:id`            | 卸载第三方插件（删除 `~/.covel/plugins/<id>`）。桌面端要求 bearer token；无 token 的生产部署要求 `COVEL_INSTALL_API_ENABLED=1`。错误码：鉴权失败 `401/403`、id 格式非法 `400`、内置 ID `409`、未安装 `404`；成功返回 `{ ok, id, restartRequired:true }` |
+| GET    | `/api/plugins/:id/contract`   | 获取插件完整开发契约（含 `dataSchemas` / plugin-data namespace 契约）                                                                                                                                                                                   |
+| GET    | `/api/plugin-flows`           | 框架编排的 pre-game 流程预览数据（插件列表 + 分段步骤），供准备页可视化                                                                                                                                                                                 |
+
+### 拖拽导入（Install）
+
+`.zip` 包拖拽导入插件/世界。鉴权同 `DELETE /api/plugins/:id`：桌面端要求 bearer token；无 token 的生产部署要求 `COVEL_INSTALL_API_ENABLED=1`。
+
+| 方法 | 路径                  | 描述                                                                                                                                               |
+| ---- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| POST | `/api/install/plugin` | multipart 字段 `file`：接受根级 `PLUGIN.md`+`package.json` 或多 runtime 布局的 `.zip`，解压到用户插件目录，返回 `{ ok, id, restartRequired:true }` |
+| POST | `/api/install/world`  | multipart 字段 `file`：接受根级 `world.yaml`+`WORLD.md` 的 `.zip`，解压到用户世界目录，返回 `{ ok, id, restartRequired:false }`                    |
 
 ### 状态查询
 
@@ -455,11 +465,12 @@ Fork 不继承 community server-code grant；child 中对应插件保持未激
 
 ### 媒体管理
 
-| 方法 | 路径                            | 描述                                                                                                                                       |
-| ---- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| GET  | `/api/media/:id?token=<signed>` | 内容寻址媒体下载（HMAC token + 会话引用校验）                                                                                              |
-| POST | `/api/media?sessionId=<id>`     | 玩家图片上传：原始字节 body（`Content-Type` = 文件 MIME，仅 `image/*`，≤20MB），内容寻址入库 + 记会话 owner/ref，返回 `{ id, mime, size }` |
-| POST | `/api/media/cleanup`            | 破坏性维护端点：默认禁用 (`COVEL_MEDIA_CLEANUP_ENABLED`)，商业层 503，`dryRun:false` 需 `X-Confirm-Cleanup: yes`                           |
+| 方法 | 路径                                | 描述                                                                                                                                       |
+| ---- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| GET  | `/api/media/:id?token=<signed>`     | 内容寻址媒体下载（HMAC token + 会话引用校验）                                                                                              |
+| GET  | `/api/sessions/:id/media-token?id=` | 为指定 mediaId 颁发短时签名 token，供上面的下载端点使用                                                                                    |
+| POST | `/api/media?sessionId=<id>`         | 玩家图片上传：原始字节 body（`Content-Type` = 文件 MIME，仅 `image/*`，≤20MB），内容寻址入库 + 记会话 owner/ref，返回 `{ id, mime, size }` |
+| POST | `/api/media/cleanup`                | 破坏性维护端点：默认禁用 (`COVEL_MEDIA_CLEANUP_ENABLED`)，商业层 503，`dryRun:false` 需 `X-Confirm-Cleanup: yes`                           |
 
 ### 配置信息
 
@@ -1834,29 +1845,6 @@ UI 与第三方调用方应优先按 `capabilities` / `outputKind` / `source` 
 
 `declaredPluginDataNamespaces` 来自 `dataSchemas` 和 `input.inject: plugin-data`。运行时动态 key（如 `entries/<entryId>`、`images/<turnId>`）不会在这里枚举；需要结合 schema、插件文档或 `_index` 端点查看当前 session 的实际 key。
 
-#### `GET /api/plugins/:id/plugin-data-contract`
-
-返回 `GET /api/plugins/:id/contract` 的 plugin-data 子集，适合只关心数据保存/导入契约的工具。
-
-**响应节选:**
-
-```json
-{
-  "pluginId": "codex",
-  "dataSchemas": {
-    "entries": {
-      "namespace": "entries",
-      "schemaVersion": 1,
-      "acceptsWorldData": true,
-      "schema": "./schemas/entries.schema.json"
-    }
-  },
-  "declaredPluginDataNamespaces": ["entries"],
-  "writablePluginDataNamespaces": ["entries"],
-  "readablePluginDataNamespaces": ["entries"]
-}
-```
-
 ---
 
 ### 会话插件管理
@@ -2925,57 +2913,64 @@ Covel 有两条独立的 SSE 流，**信封格式和帧格式都不同**：
 
 > 关键差异：`/api/actions` 使用 data-only 帧，前端**无法**通过 `EventSource.addEventListener` 订阅；`/api/events/stream` 才是命名事件。
 
-### 事件类型枚举（`ProtocolEventType`）
-
-完整定义见 `packages/shared/src/types/protocol.ts`。
-
-| 类型                       | 分类         | 说明                                                |
-| -------------------------- | ------------ | --------------------------------------------------- |
-| `narrative.delta`          | 叙事         | 叙事文本增量（逐 token 流式）                       |
-| `narrative.completed`      | 叙事         | 叙事文本完成                                        |
-| `interaction.requested`    | 交互         | 请求玩家输入（表单/选择/确认）                      |
-| `interaction.completed`    | 交互         | 玩家交互完成                                        |
-| `ui.rendered`              | UI           | `ui.render` proposal commit 后发出                  |
-| `ui.part.update`           | UI           | UI part 状态更新（每个 part 一条）                  |
-| `state.changed`            | 状态         | 游戏状态变更                                        |
-| `state.snapshot`           | 状态         | 状态快照                                            |
-| `state.snapshot.created`   | 状态         | 自动 / 手动 / fork 写入 snapshot 后发出             |
-| `session.forked`           | 会话         | `POST /api/sessions/:id/fork` 物化子 session 后发出 |
-| `execution.started`        | 执行生命周期 | Turn 执行开始                                       |
-| `runtime.started`          | 执行生命周期 | 单个 Runtime 开始执行                               |
-| `runtime.completed`        | 执行生命周期 | 单个 Runtime 执行完成                               |
-| `runtime.failed`           | 执行生命周期 | Runtime 执行失败                                    |
-| `execution.completed`      | 执行生命周期 | Turn 执行完成                                       |
-| `record.updated`           | 会话生命周期 | 记录更新（角色、任务等）                            |
-| `event.emitted`            | 会话生命周期 | 事件发射                                            |
-| `asset.progress`           | 资产         | 多模态生成进度（`0..100`）                          |
-| `asset.generated`          | 资产         | `asset.generate` proposal commit 后发出             |
-| `world.dimensions.changed` | 世界         | 世界维度文件变更（热更新）                          |
-| `plugin-data.changed`      | 插件数据     | `plugin-data-set` / DELETE / batch 等所有写路径     |
-| `turn.suspended`           | 流程控制     | `suspend()` 工具序列化 pendingContinuation          |
-| `turn.resumed`             | 流程控制     | `POST /api/sessions/:id/resume` 重启 runtime        |
-| `error.occurred`           | 系统         | 执行错误                                            |
-| `connection.restored`      | 系统         | 连接恢复                                            |
-
-### 实现私有事件（不在 `ProtocolEventType` 内）
-
-下列事件**只**经 `/api/actions` 流转发，未来稳定后才会进 enum。当前消费方需做兼容性处理：
-
-| 事件                                                  | 来源                         | 说明                                                                  |
-| ----------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------- |
-| `runtime.skipped`                                     | `actions.ts`                 | runtime 因 cooldown / startTurn / maxTriggerCount 跳过                |
-| `character.upserted`                                  | `session-commit-handlers.ts` | `character.upsert` proposal commit 后发出（与 `record.updated` 平行） |
-| `tool.calling` / `tool.completed` / `tool.failed`     | TurnEmitter                  | 工具调用 trace（debug timeline 用）                                   |
-| `llm.calling` / `llm.responded` / `message.completed` | TurnEmitter                  | LLM 调用 trace                                                        |
-| `block.emitted` / `state.patch.applied`               | TurnEmitter                  | 块发出 / state patch 应用 trace                                       |
-| `hook.fired` / `hook.rewrote` / `hook.aborted`        | TurnEmitter                  | Hook 行为 trace                                                       |
+### 事件类型枚举（`CovelEventType`）
+
+完整定义见 `packages/shared/src/types/protocol.ts`。所有 server→client 事件已收口为单一 discriminated union `CovelEvent`；`ProtocolEventType` 现为 `CovelEvent['type']` 的历史别名（保留向后兼容）。事件是否转发到 `/api/actions` 流由 `COVEL_EVENT_META[type].forwardToActionStream` 决定，转发白名单 `FORWARDED_EVENT_TYPES` 完全从该元数据派生。完整分类表见 [protocol.md § 一、事件类型](./protocol.md#一事件类型covelevent)。
+
+| 类型                       | 分类         | 说明                                                                                            |
+| -------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `narrative.delta`          | 叙事         | 叙事文本增量（逐 token 流式）                                                                   |
+| `narrative.completed`      | 叙事         | 叙事文本完成                                                                                    |
+| `interaction.requested`    | 交互         | 请求玩家输入（表单/选择/确认）                                                                  |
+| `interaction.completed`    | 交互         | 玩家交互完成                                                                                    |
+| `ui.rendered`              | UI           | `ui.render` proposal commit 后发出                                                              |
+| `ui.part.update`           | UI           | UI part 状态更新（每个 part 一条）                                                              |
+| `state.changed`            | 状态         | 游戏状态变更                                                                                    |
+| `state.snapshot`           | 状态         | 状态快照                                                                                        |
+| `state.snapshot.created`   | 状态         | 自动 / 手动 / fork 写入 snapshot 后发出                                                         |
+| `session.forked`           | 会话         | `POST /api/sessions/:id/fork` 物化子 session 后发出                                             |
+| `execution.started`        | 执行生命周期 | Turn 执行开始                                                                                   |
+| `runtime.started`          | 执行生命周期 | 单个 Runtime 开始执行                                                                           |
+| `runtime.completed`        | 执行生命周期 | 单个 Runtime 执行完成                                                                           |
+| `runtime.failed`           | 执行生命周期 | Runtime 执行失败                                                                                |
+| `execution.completed`      | 执行生命周期 | Turn 执行完成                                                                                   |
+| `record.updated`           | 会话生命周期 | 记录更新（角色、任务等）                                                                        |
+| `event.emitted`            | 会话生命周期 | 事件发射                                                                                        |
+| `asset.progress`           | 资产         | 多模态生成进度（`0..100`）                                                                      |
+| `asset.generated`          | 资产         | `asset.generate` proposal commit 后发出                                                         |
+| `world.dimensions.changed` | 世界         | 世界维度文件变更（热更新）                                                                      |
+| `plugin-data.changed`      | 插件数据     | `plugin-data-set` / DELETE / batch 等所有写路径                                                 |
+| `turn.suspended`           | 流程控制     | `suspend()` 工具序列化 pendingContinuation                                                      |
+| `turn.resumed`             | 流程控制     | `POST /api/sessions/:id/resume` 重启 runtime                                                    |
+| `working_memory.changed`   | 流程控制     | `working_memory.set` proposal commit 后直接写入 `/api/actions`（commit-direct，不经转发白名单） |
+| `error.occurred`           | 系统         | 执行错误                                                                                        |
+| `connection.restored`      | 系统         | 连接恢复                                                                                        |
+
+### 转发的运行时内部事件（已纳入 `CovelEventType`）
+
+下列事件已是 `CovelEvent` union 的正式成员（不再是「未进 enum 的私有事件」），并在 `COVEL_EVENT_META` 中标记是否 `forwardToActionStream`。前端穷尽校验强制处理或显式忽略每一种：
+
+| 事件                                                                   | 来源                              | 转发到 `/api/actions` | 说明                                                                    |
+| ---------------------------------------------------------------------- | --------------------------------- | :-------------------: | ----------------------------------------------------------------------- |
+| `runtime.skipped`                                                      | `actions.ts`                      |          否           | runtime 因 cooldown / startTurn / maxTriggerCount 跳过                  |
+| `character.upserted`                                                   | `session-commit-emitter.ts`       |          是           | `character.upsert` proposal commit 后发出（与 `record.updated` 平行）   |
+| `tool.calling` / `tool.completed` / `tool.failed`                      | TurnEmitter                       |          是           | 工具调用 trace（debug timeline 用）                                     |
+| `llm.calling` / `llm.responded` / `message.completed`                  | TurnEmitter                       |          是           | LLM 调用 trace                                                          |
+| `block.emitted` / `state.patch.applied`                                | TurnEmitter                       |          是           | 块发出 / state patch 应用 trace                                         |
+| `hook.fired` / `hook.rewrote` / `hook.aborted`                         | TurnEmitter                       |          是           | Hook 行为 trace                                                         |
+| `gateway.calling` / `gateway.responded` / `gateway.failed`             | TurnEmitter（`withGatewayTrace`） |          是           | function-runtime `ctx.gateway` provider 调用 trace（与 `llm.*` 对等）   |
+| `function.executing` / `function.completed`                            | TurnEmitter                       |          否           | function-runtime handler 边界 trace，仅经订阅通道 / `trace_events`      |
+| `recursive.calling` / `recursive.completed` / `recursive.failed`       | TurnEmitter                       |          否           | 递归 runtime trace，仅经订阅通道（topic `trace`）                       |
+| `utils.fetch.calling` / `utils.fetch.responded` / `utils.fetch.failed` | `withUtilsTrace`                  |          否           | 插件自带 wire 的 provider HTTP 调用 trace（`ctx.utils.fetchWithRetry`） |
+
+详见 [protocol.md § 转发的运行时内部事件](./protocol.md#转发的运行时内部事件apiactions-转发已纳入-covelevent)。
 
 ### 信封格式
 
 ```typescript
 // /api/actions data-only 帧每条 data: 的形态
 interface SseEnvelope {
-  type: string; // 见上表 + 实现私有事件
+  type: string; // 见上方两张事件表（CovelEventType 的成员）
   requestId: string;
   traceId: string;
   sessionId: string;
diff --git a/docs/reference/media-store.md b/docs/reference/media-store.md
index 90663819..0ceea288 100644
--- a/docs/reference/media-store.md
+++ b/docs/reference/media-store.md
@@ -20,14 +20,20 @@ interface MediaStore {
     ownerPluginId?: string,
   ): Promise<void>;
   addRef(id: string, sessionId: string, pluginId?: string): Promise<void>;
+  removeRef(id: string, sessionId: string): Promise<void>;
   isReferencedBy(id: string, sessionId: string): Promise<boolean>;
   listAssets(): Promise<readonly MediaAssetRecord[]>;
+  listByMetadata(
+    sessionId: string,
+    filter: Readonly<Record<string, unknown>>,
+  ): Promise<readonly MediaAssetRecord[]>;
   listRefs(): Promise<readonly MediaRefRecord[]>;
   cleanup(
     protectedIds: ReadonlySet<string>,
     policy?: MediaLifecyclePolicy,
   ): Promise<MediaCleanupResult>;
   openReadStream?(ref: MediaRef): Promise<ReadableStream<Uint8Array>>;
+  close?(): void | Promise<void>;
 }
 ```
 
@@ -81,7 +87,7 @@ generated bytes land in `MediaStore` via `ctx.images.generate()` /
 
 ### `listByMetadata(sessionId, filter)`
 
-Returns assets owned by `sessionId` whose `meta` contains every key/value in `filter` — an exact, shallow subset match, one shared implementation (`filterAssetsByMetadata` in `packages/store/src/media-store/utils.ts`) reused by all four backends. A `filter` value of `undefined` matches both a missing key and a key explicitly stored as `undefined` (`meta[k] === v` — both sides read `undefined`). Only primitive values (string/number/boolean/`null`) compare meaningfully; objects and arrays never match because `===` on them is reference equality. Result sets are expected to stay small — per-session media volume is tens of records, so this is a full scan (`ponytail:` comment in `utils.ts` — push down to SQL when volume outgrows that).
+Returns assets owned by `sessionId` whose `meta` contains every key/value in `filter` — an exact, shallow subset match, one shared implementation (`filterAssetsByMetadata` in `packages/store/src/media-store/filter.ts`) reused by all four backends. A `filter` value of `undefined` matches both a missing key and a key explicitly stored as `undefined` (`meta[k] === v` — both sides read `undefined`). Only primitive values (string/number/boolean/`null`) compare meaningfully; objects and arrays never match because `===` on them is reference equality. Result sets are expected to stay small — per-session media volume is tens of records, so this is a full scan (`ponytail:` comment in `filter.ts` — push down to SQL when volume outgrows that). `filter.ts` is kept free of Node built-ins (unlike `utils.ts`) so the browser-reachable IndexedDB backend can import it without pulling `node:crypto`/`node:path` into the web bundle.
 
 ### `promptHash` idempotency
 
@@ -89,7 +95,7 @@ Returns assets owned by `sessionId` whose `meta` contains every key/value in `fi
 
 ## Ownership
 
-`recordOwnership()` sets the first owner for an asset. `addRef()` grants another session read access for fork and snapshot flows. `isReferencedBy()` returns true for the owner session and for sessions with an explicit reference row.
+`recordOwnership()` sets the first owner for an asset (first-writer-wins; a second call with a different `sessionId` does not overwrite it). `addRef()` grants another session read access for fork and snapshot flows; `removeRef()` idempotently removes one session's explicit ref (does not delete bytes or ownership metadata). `isReferencedBy()` returns true for the owner session and for sessions with an explicit reference row.
 
 `addRef()` is **idempotent on `(sessionId, mediaId)`** — the `media_refs` UNIQUE constraint ignores `plugin_id` (which is recorded as first-source metadata only). This is the safe behaviour because SQL `UNIQUE` treats every `NULL` as distinct, so a constraint that includes a nullable `plugin_id` would silently allow unbounded duplicate rows when callers passed `undefined`. The new key shape matches Memory and IndexedDB, which use `(sessionId, mediaId)` as their map key.
 
@@ -126,4 +132,4 @@ An empty policy returns an inventory-style dry run with zero selected deletions.
 
 ## Tests
 
-The shared contract lives in `packages/store/src/contract/media-store-contract.ts`. Current coverage runs against Memory, SQLite/local-fs, and PostgreSQL when `DATABASE_URL` points at a reachable database.
+The shared contract lives in `packages/store/src/contract/media-store-contract.ts`. Current coverage runs against Memory, SQLite/local-fs, IndexedDB (via `fake-indexeddb`), and PostgreSQL when `DATABASE_URL` points at a reachable database (`packages/store/tests/media-store.test.ts`).
diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md
index ee90381e..1fa4abbc 100644
--- a/docs/reference/plugins.md
+++ b/docs/reference/plugins.md
@@ -105,7 +105,7 @@ Pre-Game band（priority `0-99`，由 `packages/runtime/src/schedule/scheduler.t
 | character-presence             | plugin      | —      | manual（按需 / world-data 导入）                                          | —         | 角色头像 / 立绘 / 语音媒体；`dataSchemas` presence/assets                                      |
 | player-identity                | plugin      | —      | manual（按需）                                                            | —         | 玩家人设（`persona-provider`，注入 activePersona）                                             |
 | living-world-rules             | plugin      | —      | manual（按需 / world-data 导入）                                          | —         | 长期世界规则 → `lorebook.upsert` 注入叙事；`dataSchemas` rules                                 |
-| branch-reply                   | plugin      | 700    | auto（每回合播种）+ manual（重生成/采纳）                                 | `system`  | 回复候选 + `prompt-history-rewriter`（自动播种叙事原文，重生成走 LLM；投影历史折叠已采纳回合） |
+| branch-reply                   | plugin      | 700    | auto（每回合播种）+ manual（重生成/采纳）                                 | —         | 回复候选 + `prompt-history-rewriter`（自动播种叙事原文，重生成走 LLM；投影历史折叠已采纳回合） |
 | scene-stage/background-gen     | plugin      | 900    | event（topic: `scene-stage.generate.requested`，`execution: background`） | —         | 后台增量生成缺失的场景背景图（`ctx.images`），产出 `asset.generate`                            |
 | memory                         | core-plugin | —      | UI-only（无 runtime）                                                     | —         | 长期记忆摘要面板 + 通过 `memoryBlocks` 声明默认核心记忆块（剧情/角色关系/场景/玩家状态）       |
 | cost-gate                      | plugin      | —      | hook-only（opt-in，默认禁用）                                             | —         | 跨切面：每会话 token 预算门控（hooks：PostLLMResponse/PreSchedule/TurnStart/SessionEnd）       |
@@ -159,7 +159,7 @@ Pre-Game band（priority `0-99`，由 `packages/runtime/src/schedule/scheduler.t
 | capabilities  | `[world-data-provider]`                                       |
 | tools.plugin  | `set-world-schema`, `set-world-entries-batch`                 |
 | tools.builtin | `plugin-data-get`, `plugin-data-list`                         |
-| ui.right      | `./ui/world-entries.json`, `./ui/world-schema.json`           |
+| ui.right      | `./ui/world-overview.json`, `./ui/world-schema.json`          |
 
 **Guard 门控**: `guard.js` 在 LLM 调用前执行（纯函数，零 LLM 开销），按优先级决定角色属性 schema，命中任一即返回 `{ skip: true }` 跳过 LLM：
 
@@ -323,7 +323,7 @@ namespace="meta"   key=ontology   value=NpcGraphOntology (Phase 3 wire-up)
 
 ## char-creator（角色子系统）
 
-🔵 core · ⚙ pure function（player-init）· 🧠 uses LLM（character-tracker）
+🔵 core · 🧠 uses LLM（player-init，guard 门控）· 🧠 uses LLM（character-tracker）
 
 **Quick use**：你要玩家在首轮填一张"角色创建表单"生成主角；并且每轮自动跟踪叙事里出现的 NPC、角色状态变化（受伤、死亡、装备、关系）并写进 `characters` 表。两个子 runtime 共用同一个 `character-panel.json` 侧边栏。
 
@@ -333,18 +333,18 @@ namespace="meta"   key=ontology   value=NpcGraphOntology (Phase 3 wire-up)
 
 ### char-creator/player-init
 
-| 字段        | 值                                                                                |
-| ----------- | --------------------------------------------------------------------------------- |
-| pluginType  | `core-plugin`（不可禁用）                                                         |
-| priority    | 50（Pre-Game 带）                                                                 |
-| runtimeType | `function`                                                                        |
-| handler     | `./handler.js`                                                                    |
-| trigger     | `scheduled`，`interval: 1`，`maxTriggerCount: 2`（首轮生成表单 + 表单提交后写库） |
-| guard       | `./guard.js` — 若 player 已存在则 skip                                            |
-| model       | `plugin`                                                                          |
-| ui.right    | `../../ui/character-panel.json`                                                   |
+| 字段             | 值                                                         |
+| ---------------- | ---------------------------------------------------------- |
+| pluginType       | `core-plugin`（不可禁用）                                  |
+| priority         | 50（Pre-Game 带）                                          |
+| runtimeType      | `agent`（默认，LLM 生成开场表单；guard 命中时跳过）        |
+| trigger          | `auto`（`guard` 门控）                                     |
+| upstreamRequired | `[pregame, world-init/schema-gen]`                         |
+| guard            | `./guard.js` — 若 player 已存在或已收到表单提交则 skip LLM |
+| model            | `plugin`                                                   |
+| ui.right         | `../../ui/character-panel.json`                            |
 
-**两步流程**（当前由 deterministic handler 完成）：
+**两步流程**（第 1 步由 LLM agent 完成，第 2 步由 `guard.js` 确定性完成）：
 
 1. **第 1 步 - 生成表单**（`<player-submission>` 为空时）：
    - 读取世界 schema
@@ -506,19 +506,19 @@ Pre-Game runtime（priority ≤ 99）由框架强制保护，`PreSchedule` 收
 
 **路径**: `plugins/chat-mode-narrator/`
 
-| 字段            | 值                                                                                                                                                                    |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| pluginType      | `plugin`                                                                                                                                                              |
-| priority        | 500（Narrator 带，每轮）                                                                                                                                              |
-| trigger         | `auto`                                                                                                                                                                |
-| outputKind      | `story`                                                                                                                                                               |
-| model           | `story`                                                                                                                                                               |
-| capabilities    | `[narrative, chat-mode]`                                                                                                                                              |
-| tags            | `mode:dialogue` · `role:narrator`                                                                                                                                     |
-| relations       | `conflicts: narrator`；`requires: scene-cast, scene-stage, scene-prompts, character-blueprint, character-presence, player-identity, living-world-rules, branch-reply` |
-| tools.builtin   | `emit-event`                                                                                                                                                          |
-| advertiseEvents | `true`（segment 5 注入 `<available-events>` 目录）                                                                                                                    |
-| input.inject    | `scene-cast/activeCastContext` → `<active-cast>`；`npc-graph/rag-retriever/npcContext` → `<npc-relationships>`                                                        |
+| 字段            | 值                                                                                                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| pluginType      | `plugin`                                                                                                                                             |
+| priority        | 500（Narrator 带，每轮）                                                                                                                             |
+| trigger         | `auto`                                                                                                                                               |
+| outputKind      | `story`                                                                                                                                              |
+| model           | `story`                                                                                                                                              |
+| capabilities    | `[narrative, chat-mode]`                                                                                                                             |
+| tags            | `mode:dialogue` · `role:narrator`                                                                                                                    |
+| relations       | `conflicts: narrator`；`requires: scene-cast, scene-stage, scene-prompts, character-blueprint, character-presence, living-world-rules, branch-reply` |
+| tools.builtin   | `emit-event`                                                                                                                                         |
+| advertiseEvents | `true`（segment 5 注入 `<available-events>` 目录）                                                                                                   |
+| input.inject    | `scene-cast/activeCastContext` → `<active-cast>`；`npc-graph/rag-retriever/npcContext` → `<npc-relationships>`                                       |
 
 **userSettings**（世界用 `pluginSettings.chat-mode-narrator` 预置，玩家可覆盖）：
 
@@ -997,13 +997,13 @@ maxRecursionDepth: 5
 
 ### guard
 
-Agent runtime 的前置门控函数。在 LLM 调用前执行（纯函数，零 token 开销），可用于检查前置条件、导入数据等��
+Agent runtime 的前置门控函数。在 LLM 调用前执行（纯函数，零 token 开销），可用于检查前置条件、导入数据等。
 
 ```yaml
 guard: ../../guard.js
 ```
 
-Guard 函数接收与 function runtime 相同��� `FunctionHandlerContext`，返回值规则：
+Guard 函数接收与 function runtime 相同的 `FunctionHandlerContext`，返回值规则：
 
 - `{ skip: true, ... }` — 跳过 LLM 调用，guard 输出作为 runtime 结果
 - `{ skip: false, ... }` — 继续执行 LLM agent
diff --git a/docs/reference/protocol.md b/docs/reference/protocol.md
index af0deec3..bb5d941d 100644
--- a/docs/reference/protocol.md
+++ b/docs/reference/protocol.md
@@ -257,15 +257,15 @@ Web 收到 reset 或重连后会以 revision guard 重新拉取 session snapshot
 
 下列事件由 server 透过 actions SSE 流转发用于 debug / trace。它们现在**已经是 `CovelEvent` union 的成员**（不再是「未进 enum 的私有事件」），并在 `COVEL_EVENT_META` 中标记 `forwardToActionStream: true`。server 的转发白名单 `FORWARDED_EVENT_TYPES` 完全从该元数据**派生**（不再手写 Set）。web 的 actions handler 对这些类型显式 no-op（它们经订阅通道驱动 `/debug` 时间线），但因已在 union 内，新增同类事件会被前端穷尽校验强制做出「处理或忽略」的决定。
 
-| 事件                                                       | 来源                                                                                           | 用途                                                                           |
-| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `runtime.skipped`                                          | `apps/server/src/routes/api/actions.ts`                                                        | runtime 因 cooldown / startTurn / maxTriggerCount 被跳过                       |
-| `character.upserted`                                       | `packages/runtime/src/commit/session-commit-handlers.ts`（`character.upsert` proposal commit） | 与 `record.updated` 平行的角色快照事件                                         |
-| `tool.calling` / `tool.completed` / `tool.failed`          | TurnEmitter                                                                                    | LLM 工具调用 trace                                                             |
-| `llm.calling` / `llm.responded` / `message.completed`      | TurnEmitter                                                                                    | LLM 调用 trace                                                                 |
-| `block.emitted` / `state.patch.applied`                    | TurnEmitter                                                                                    | 块发出 / state patch 应用 trace                                                |
-| `hook.fired` / `hook.rewrote` / `hook.aborted`             | TurnEmitter                                                                                    | Hook 行为 trace                                                                |
-| `gateway.calling` / `gateway.responded` / `gateway.failed` | TurnEmitter（`withGatewayTrace`）                                                              | function-runtime `ctx.gateway` provider 调用 trace（与 `llm.*` 对等，A2-P1-5） |
+| 事件                                                       | 来源                                                                                          | 用途                                                                           |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `runtime.skipped`                                          | `apps/server/src/routes/api/actions.ts`                                                       | runtime 因 cooldown / startTurn / maxTriggerCount 被跳过                       |
+| `character.upserted`                                       | `packages/runtime/src/commit/session-commit-emitter.ts`（`character.upsert` proposal commit） | 与 `record.updated` 平行的角色快照事件                                         |
+| `tool.calling` / `tool.completed` / `tool.failed`          | TurnEmitter                                                                                   | LLM 工具调用 trace                                                             |
+| `llm.calling` / `llm.responded` / `message.completed`      | TurnEmitter                                                                                   | LLM 调用 trace                                                                 |
+| `block.emitted` / `state.patch.applied`                    | TurnEmitter                                                                                   | 块发出 / state patch 应用 trace                                                |
+| `hook.fired` / `hook.rewrote` / `hook.aborted`             | TurnEmitter                                                                                   | Hook 行为 trace                                                                |
+| `gateway.calling` / `gateway.responded` / `gateway.failed` | TurnEmitter（`withGatewayTrace`）                                                             | function-runtime `ctx.gateway` provider 调用 trace（与 `llm.*` 对等，A2-P1-5） |
 
 > `function.executing` / `function.completed` 为 function-runtime 的 handler 边界 trace 事件（TurnEmitter），`forwardToActionStream: false`——**仅经订阅通道 / trace_events 下发**，与 `recursive.*` 同类，不进入 `/api/actions`。`gateway.*` 则 `forwardToActionStream: true`（对齐 `llm.calling/responded`），故列在上表。两组都已纳入 `CovelEvent` union（发射端受 `CovelEventType` 闭合约束）。
 >
@@ -283,7 +283,7 @@ Web 收到 reset 或重连后会以 revision guard 重新拉取 session snapshot
 
 ### 回合执行（SSE 流式响应）
 
-`/api/actions` 接受的 `type` 字段（实际由 `apps/server/src/routes/api/actions.ts:79` 的 `SUPPORTED_ACTIONS` 数组定义）：
+`/api/actions` 接受的 `type` 字段（实际由 `apps/server/src/routes/api/actions.ts:148` 的 `SUPPORTED_ACTIONS` 数组定义）：
 
 | 命令            | 方法 | 端点                                     | 响应                  |
 | --------------- | ---- | ---------------------------------------- | --------------------- |
@@ -470,9 +470,9 @@ These events ride the standard SSE envelope and are also persisted into `trace_e
 | `block.emitted`       | `{ runtimeId, pluginId, proposalId, source, block }`                                                                                                                                                                                                                                                                                       |
 | `ui.rendered`         | `{ runtimeId, pluginId, proposalId, source, render, block? }` — `/actions` SSE forwards this so chat can render committed `ui.render` blocks live; older trace-only payloads may omit `block`, in which case clients synthesize it from `render`.                                                                                          |
 | `state.patch.applied` | `{ runtimeId, pluginId, proposalId, patch: { packageName, summary, ops } }`                                                                                                                                                                                                                                                                |
-| `hook.fired`          | `{ event, hookName, pluginId, runtimeId?, targetId?, targetType }`                                                                                                                                                                                                                                                                         |
-| `hook.rewrote`        | `{ event, hookName, pluginId, runtimeId?, targetId?, diff? }`                                                                                                                                                                                                                                                                              |
-| `hook.aborted`        | `{ event, hookName, pluginId, runtimeId?, targetId?, reason }`                                                                                                                                                                                                                                                                             |
+| `hook.fired`          | `{ event, hookName, pluginId, runtimeId?, targetId?, targetType, proposalType? }`                                                                                                                                                                                                                                                          |
+| `hook.rewrote`        | `{ event, hookName, pluginId, runtimeId?, targetId?, diff?, proposalType? }`                                                                                                                                                                                                                                                               |
+| `hook.aborted`        | `{ event, hookName, pluginId, runtimeId?, targetId?, reason, proposalType? }`                                                                                                                                                                                                                                                              |
 
 Delta narrative continues to ride `narrative.delta` for realtime UI; only `message.completed` is persisted to keep `trace_events` compact.
 
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index a1858eae..6dc54752 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -670,7 +670,7 @@ interface ToolClient {
 
 ## 审批策略
 
-工具调用经过 `ApprovalPipeline` 审批检查，当前规则（配置在 `apps/server/src/routes/api/bootstrap.ts`）：
+工具调用经过 `ApprovalPipeline` 审批检查，当前规则（配置在 `apps/server/src/routes/api/bootstrap/tools.ts`）：
 
 | 来源分类        | 规则      | 说明                           |
 | --------------- | --------- | ------------------------------ |
diff --git a/docs/reference/ui-components.md b/docs/reference/ui-components.md
index 907466e7..fe4089cf 100644
--- a/docs/reference/ui-components.md
+++ b/docs/reference/ui-components.md
@@ -43,33 +43,38 @@ Reference for the json-render components available to plugin UI specs. This page
 
 ### Display
 
-| Component         | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                 | Key props                                                                                                                                                                                                                                                                          |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Text`            | Paragraph text with variant controls.                                                                                                                                                                                                                                                                                                                                                                                                   | `content` _(I18nText)_, `variant` (`muted`), `weight` (`bold`), `size` (`xs` / `sm` / `lg`), `align` (`center`)                                                                                                                                                                    |
-| `Badge`           | Small coloured pill.                                                                                                                                                                                                                                                                                                                                                                                                                    | `label` _(I18nText)_, `color` (`red` / `amber` / `blue` / `green` / `purple` / `cyan`)                                                                                                                                                                                             |
-| `Icon`            | Lucide icon by name.                                                                                                                                                                                                                                                                                                                                                                                                                    | `name` (kebab-case, e.g. `book-open`), `size` (`xs` / `sm` / `md` / `lg`)                                                                                                                                                                                                          |
-| `TagList`         | Flat list of string tags.                                                                                                                                                                                                                                                                                                                                                                                                               | `tags` (string[])                                                                                                                                                                                                                                                                  |
-| `Prose`           | Narrative paragraphs with `**bold**` support, split on double newline.                                                                                                                                                                                                                                                                                                                                                                  | `content` (string)                                                                                                                                                                                                                                                                 |
-| `Source`          | Small attribution label.                                                                                                                                                                                                                                                                                                                                                                                                                | `label` (string)                                                                                                                                                                                                                                                                   |
-| `Image`           | Renders an image from a MediaRef resolved through the media store. Falls back to a placeholder tile when no ref is bound. With `zoom: true` the image becomes click-to-enlarge via the shared `MediaPreviewDialog`; with `framed: true` it sits in a rounded bordered card (hover highlight) matching the image-generation gallery's thumbnails.                                                                                        | `ref` _(MediaRef, preferred)_, `src` _(MediaRef accepted for early specs)_, `alt` (string), `aspectRatio` (CSS ratio, default `"1/1"`), `rounded` (`none` / `sm` / `md` / `lg`), `fit` (`cover` / `contain`), `zoom` (boolean — click to enlarge), `framed` (boolean — card frame) |
-| `Media`           | Renders image / audio / video / file assets from a MediaRef resolved through the media store.                                                                                                                                                                                                                                                                                                                                           | `ref` _(MediaRef, preferred)_, `src` _(MediaRef accepted for early specs)_, `as` (`auto` / `image` / `audio` / `video`), `alt`, `aspectRatio`, `rounded`, `fit`                                                                                                                    |
-| `AudioPlayer`     | Theme-aware self-drawn audio player. Replaces native `<audio controls>` chrome with a flat playlist row using `--color-primary` / `--color-muted` / `--color-border` / `--radius-card`. Includes play/pause, scrubbable progress bar (pointer + keyboard), `M:SS / M:SS` time, speed selector (0.75× / 1× / 1.25× / 1.5× / 2×), and download button. Falls back to an "audio unavailable" tile when ref is missing or resolution fails. | `ref` _(MediaRef)_, `src` _(MediaRef accepted)_, `alt` (string, also used as default download filename stem), `downloadName` (override filename), `className`                                                                                                                      |
-| `ImageGallery`    | Framework-provided compact gallery for image-generation plugins. Reads the plugin `images` namespace, hides long prompts, and provides preview/download/re-draw controls.                                                                                                                                                                                                                                                               | `pluginId`                                                                                                                                                                                                                                                                         |
-| `ImageJobs`       | Framework-provided image task viewer. Reads `_jobs`, shows prompt details, copy/re-draw controls, and groups generated image thumbnails under matching prompts.                                                                                                                                                                                                                                                                         | `pluginId`                                                                                                                                                                                                                                                                         |
-| `PortraitGallery` | Framework-provided player-facing character-portrait gallery. Reads the plugin's `presence` namespace and renders each character's portrait as a framed, click-to-enlarge thumbnail with a hover "replace" action — the player picks an image file, it uploads via `POST /api/media`, and the resulting `MediaRef` is written back as the character's presence (no sha256 / MIME / size hand-entry).                                     | `pluginId`                                                                                                                                                                                                                                                                         |
+| Component               | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                 | Key props                                                                                                                                                                                                                                                                          |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Text`                  | Paragraph text with variant controls.                                                                                                                                                                                                                                                                                                                                                                                                   | `content` _(I18nText)_, `variant` (`muted`), `weight` (`bold`), `size` (`xs` / `sm` / `lg`), `align` (`center`)                                                                                                                                                                    |
+| `Badge`                 | Small coloured pill.                                                                                                                                                                                                                                                                                                                                                                                                                    | `label` _(I18nText)_, `color` (`red` / `amber` / `blue` / `green` / `purple` / `cyan`)                                                                                                                                                                                             |
+| `Icon`                  | Lucide icon by name.                                                                                                                                                                                                                                                                                                                                                                                                                    | `name` (kebab-case, e.g. `book-open`), `size` (`xs` / `sm` / `md` / `lg`)                                                                                                                                                                                                          |
+| `TagList`               | Flat list of string tags.                                                                                                                                                                                                                                                                                                                                                                                                               | `tags` (string[])                                                                                                                                                                                                                                                                  |
+| `Prose`                 | Narrative paragraphs with `**bold**` support, split on double newline.                                                                                                                                                                                                                                                                                                                                                                  | `content` (string)                                                                                                                                                                                                                                                                 |
+| `Source`                | Small attribution label.                                                                                                                                                                                                                                                                                                                                                                                                                | `label` (string)                                                                                                                                                                                                                                                                   |
+| `Image`                 | Renders an image from a MediaRef resolved through the media store. Falls back to a placeholder tile when no ref is bound. With `zoom: true` the image becomes click-to-enlarge via the shared `MediaPreviewDialog`; with `framed: true` it sits in a rounded bordered card (hover highlight) matching the image-generation gallery's thumbnails.                                                                                        | `ref` _(MediaRef, preferred)_, `src` _(MediaRef accepted for early specs)_, `alt` (string), `aspectRatio` (CSS ratio, default `"1/1"`), `rounded` (`none` / `sm` / `md` / `lg`), `fit` (`cover` / `contain`), `zoom` (boolean — click to enlarge), `framed` (boolean — card frame) |
+| `Media`                 | Renders image / audio / video / file assets from a MediaRef resolved through the media store.                                                                                                                                                                                                                                                                                                                                           | `ref` _(MediaRef, preferred)_, `src` _(MediaRef accepted for early specs)_, `as` (`auto` / `image` / `audio` / `video`), `alt`, `aspectRatio`, `rounded`, `fit`                                                                                                                    |
+| `AudioPlayer`           | Theme-aware self-drawn audio player. Replaces native `<audio controls>` chrome with a flat playlist row using `--color-primary` / `--color-muted` / `--color-border` / `--radius-card`. Includes play/pause, scrubbable progress bar (pointer + keyboard), `M:SS / M:SS` time, speed selector (0.75× / 1× / 1.25× / 1.5× / 2×), and download button. Falls back to an "audio unavailable" tile when ref is missing or resolution fails. | `ref` _(MediaRef)_, `src` _(MediaRef accepted)_, `alt` (string, also used as default download filename stem), `downloadName` (override filename), `className`                                                                                                                      |
+| `ImageGallery`          | Framework-provided compact gallery for image-generation plugins. Reads the plugin `images` namespace, hides long prompts, and provides preview/download/re-draw controls.                                                                                                                                                                                                                                                               | `pluginId`                                                                                                                                                                                                                                                                         |
+| `ImageJobs`             | Framework-provided image task viewer. Reads `_jobs`, shows prompt details, copy/re-draw controls, and groups generated image thumbnails under matching prompts.                                                                                                                                                                                                                                                                         | `pluginId`                                                                                                                                                                                                                                                                         |
+| `PortraitGallery`       | Framework-provided player-facing character-portrait gallery. Reads the plugin's `presence` namespace and renders each character's portrait as a framed, click-to-enlarge thumbnail with a hover "replace" action — the player picks an image file, it uploads via `POST /api/media`, and the resulting `MediaRef` is written back as the character's presence (no sha256 / MIME / size hand-entry).                                     | `pluginId`                                                                                                                                                                                                                                                                         |
+| `BranchReplyCandidates` | Candidate-reply switcher for `branch-reply` plugin data. Draft/send route through the session draft path; accept/regenerate call plugin-rpc directly. Renders nothing when there are no non-original candidates.                                                                                                                                                                                                                        | `value`/`candidateSet`/`replySet`/`data` (candidate payload), `pluginId`, `runtimeId` (enable accept/regenerate RPC), `title`/`draftLabel`/`sendLabel`/`acceptLabel`/`regenerateLabel` _(I18nText)_                                                                                |
 
 ### Data
 
-| Component   | Purpose                                                                                                    | Key props                                                                                                                                                                                                 |
-| ----------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Card`      | Bordered container.                                                                                        | `variant` (`glow` / `subtle`)                                                                                                                                                                             |
-| `CardList`  | Vertical stack of `Card` children.                                                                         | —                                                                                                                                                                                                         |
-| `EntryCard` | Rich codex-entry card with category icon and rarity accent.                                                | `title` _(I18nText)_, `category` (string), `content` _(I18nText)_, `tags` (string[]), `rarity` (`legendary` / `rare` / `uncommon` / `common`), `icon`, `color`, `collapsible`, `defaultExpanded`, `isNew` |
-| `StatBar`   | Label + `value/max` numeric bar.                                                                           | `label` _(I18nText)_, `value` (number), `max` (number)                                                                                                                                                    |
-| `Progress`  | Percent-style progress bar.                                                                                | `label` _(I18nText)_, `value` (number), `max` (number)                                                                                                                                                    |
-| `Accordion` | Vertical wrapper for `Section` children.                                                                   | —                                                                                                                                                                                                         |
-| `Section`   | Collapsible header + body.                                                                                 | `title` _(I18nText)_, `icon`, `defaultOpen` (boolean)                                                                                                                                                     |
-| `JsonView`  | Shape-aware render of any JSON value (primitives inline, arrays as tag list, objects as key: value pairs). | `value` (any)                                                                                                                                                                                             |
+| Component                | Purpose                                                                                                                                                                                                                                                                                           | Key props                                                                                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Card`                   | Bordered container.                                                                                                                                                                                                                                                                               | `variant` (`glow` / `subtle`)                                                                                                                                                                             |
+| `CardList`               | Vertical stack of `Card` children.                                                                                                                                                                                                                                                                | —                                                                                                                                                                                                         |
+| `EntryCard`              | Rich codex-entry card with category icon and rarity accent.                                                                                                                                                                                                                                       | `title` _(I18nText)_, `category` (string), `content` _(I18nText)_, `tags` (string[]), `rarity` (`legendary` / `rare` / `uncommon` / `common`), `icon`, `color`, `collapsible`, `defaultExpanded`, `isNew` |
+| `StatBar`                | Label + `value/max` numeric bar.                                                                                                                                                                                                                                                                  | `label` _(I18nText)_, `value` (number), `max` (number)                                                                                                                                                    |
+| `Progress`               | Percent-style progress bar.                                                                                                                                                                                                                                                                       | `label` _(I18nText)_, `value` (number), `max` (number)                                                                                                                                                    |
+| `Accordion`              | Vertical wrapper for `Section` children.                                                                                                                                                                                                                                                          | —                                                                                                                                                                                                         |
+| `Section`                | Collapsible header + body.                                                                                                                                                                                                                                                                        | `title` _(I18nText)_, `icon`, `defaultOpen` (boolean)                                                                                                                                                     |
+| `JsonView`               | Shape-aware render of any JSON value (primitives inline, arrays as tag list, objects as key: value pairs).                                                                                                                                                                                        | `value` (any)                                                                                                                                                                                             |
+| `CharacterBlueprintList` | List of preset (world-author-authored) character blueprints — name/role/description/tags/attributes/persona, read-only. Used by the `character-blueprint` plugin's blueprints panel.                                                                                                              | `value` (array of blueprint records)                                                                                                                                                                      |
+| `SceneCastList`          | Player-facing "who's in this scene" list — name + role only per speaker; internal selection signals/scores stay in plugin_data. Used by `scene-cast`.                                                                                                                                             | `speakers` (array of speaker records)                                                                                                                                                                     |
+| `CharacterFieldsView`    | Schema-aware renderer for a character's `fields` object. Resolves the attribute schema via `useCharacterAttributeSchema` (scans plugin ids for the well-known `schema`/`character-attributes` path — no hardcoded provider) and groups fields by category (bio/stats/abilities/equipment/social). | `value` (character `fields` object)                                                                                                                                                                       |
+| `CharacterAvatar`        | Small portrait badge for a character row; click to enlarge via `MediaPreviewDialog`. Generic by design — the spec passes which plugin/namespace holds presence records (e.g. `char-creator` wires it to `character-presence`/`presence`). Renders nothing when the character has no portrait.     | `characterId`, `sourcePlugin`, `sourceNamespace` (default `presence`), `idField` (default `characterId`), `refField` (default `avatar`), `size` (number, default `28`)                                    |
 
 ### Interactive
 
@@ -77,6 +82,7 @@ Reference for the json-render components available to plugin UI specs. This page
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Button`          | Click target with selection-feedback wiring for plugin-declared interactions.                                                                                                                           | `label` _(I18nText)_, `variant` (`default` / `primary` / `danger` / `ghost`), `size` (`compact` / `md`); `on.click.action` = `draftMessage` / `selectChoice` / …                                                                                                             |
 | `Input`           | Text input.                                                                                                                                                                                             | `label` _(I18nText)_, `placeholder` _(I18nText)_, `value` (bind via `$bindState`)                                                                                                                                                                                            |
+| `Textarea`        | Multi-line text input (monospace, resizable).                                                                                                                                                           | `label` _(I18nText)_, `placeholder` _(I18nText)_, `rows` (number, default `8`), `value` (bind via `$bindState`)                                                                                                                                                              |
 | `SearchInput`     | Input with a search glyph.                                                                                                                                                                              | `placeholder` _(I18nText)_, `value`                                                                                                                                                                                                                                          |
 | `Select`          | Dropdown.                                                                                                                                                                                               | `label` _(I18nText)_, `options` (`[{ value, label }]`), `value`                                                                                                                                                                                                              |
 | `Switch`          | Boolean toggle.                                                                                                                                                                                         | `label` _(I18nText)_, `checked` (bind via `$bindState`)                                                                                                                                                                                                                      |
@@ -107,9 +113,16 @@ Reference for the json-render components available to plugin UI specs. This page
 | `GraphCanvas`     | Force-directed graph via `react-force-graph-2d` (lazy-loaded, ~60 KB gzip). Reads `pluginData[pluginId][nodesNamespace]` and `[edgesNamespace]`. | `pluginId`, `nodesNamespace`, `edgesNamespace`, `height?` |
 | `WorldDimensions` | Renders the active world's structured dimensions (geography / factions / power system / …). Reads from session context; no bindings required.    | —                                                         |
 
+### Multimodal
+
+| Component          | Purpose                                                                                                                                                                   | Key props                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `AssetRender`      | Surfaces a single `AssetGenerateView` proposal, routed by `view.modality` to the modality-specific renderer (image / audio / generic link).                               | `view` (`AssetGenerateView`), `sessionId?` (overrides active-session lookup) |
+| `AssetTurnSidebar` | Fans out every generated asset recorded for a turn (from `state.assetsByTurn`, populated by the `asset.generated` SSE handler). Renders nothing for turns with no assets. | `turnId`, `sessionId?`                                                       |
+
 ## Summary
 
-36 components total as of this writing. Authoritative inventory: the exported `covelRegistry` in `apps/web/src/lib/catalog.tsx`; renderer implementations live under `apps/web/src/lib/catalog/`. If you add a new component:
+48 components total as of this writing. Authoritative inventory: the exported `covelRegistry` in `apps/web/src/lib/catalog.tsx`; renderer implementations live under `apps/web/src/lib/catalog/`. If you add a new component:
 
 1. Register it in `covelRegistry` with a short doc comment above the renderer.
 2. Add a row here in the matching section.
diff --git a/docs/reference/ui-panels.md b/docs/reference/ui-panels.md
index 2aa186e5..dfd6d0dd 100644
--- a/docs/reference/ui-panels.md
+++ b/docs/reference/ui-panels.md
@@ -33,7 +33,7 @@
 
 ### 设计原则
 
-- **Lorebook Tab 由框架固定**，其余右侧面板由插件通过 `ui.right` 声明
+- **所有右侧面板均由插件通过 `ui.right` 声明**（无框架固定 Tab；Lorebook 只有 HTTP API，见下方「世界文档」章节后的说明）
 - **框架不知道具体插件**，通过 `/api/ui-specs` 发现面板
 - **json-render 渲染**，插件提供 JSON spec，框架提供组件 catalog
 - **pluginData 驱动数据**，通过 `plugin-data.changed` SSE 事件实时更新
@@ -53,17 +53,19 @@ session 建立 → GET /api/ui-specs?sessionId=<id>
 
 ### 当前注册的面板
 
-| 插件/runtime             | 面板 ID             | 图标               | group       | 数据 namespace | 描述                                                                                                |
-| ------------------------ | ------------------- | ------------------ | ----------- | -------------- | --------------------------------------------------------------------------------------------------- |
-| char-creator/player-init | character           | users              | character   | characters     | 角色列表（player + NPC + companion）                                                                |
-| character-blueprint      | character-blueprint | id-card            | character   | blueprints     | 预设角色（世界作者预置的登场角色模板，只读；作为 `character` 组的子 Tab）                           |
-| codex                    | codex               | book-open          | codex       | entries        | 知识图鉴                                                                                            |
-| living-world-rules       | living-world-rules  | book-marked        | world-data  | rules          | 世界规则（长期设定 / 禁忌，只读；随 world-data 导入播种，作为 `world-data` 组的子 Tab）             |
-| memory                   | memory              | brain              | memory      | （框架托管）   | 核心记忆面板：剧情摘要 / 当前场景 / 角色关系 / 玩家状态。纯 UI，由 `@covel/memory` 在每轮结束后写入 |
-| npc-graph/extractor      | npc-graph           | network            | npc-graph   | nodes + edges  | NPC 关系图（force-directed 可视化）                                                                 |
-| scene-stage/resolver     | scene-stage         | image              | scene-stage | stage          | 当前场景舞台（只读）：场景名 + 昼夜徽标 + `sourceLabel` 状态文案（`pending` 时"背景生成中…"）       |
-| world-init/schema-gen    | world-overview      | layout-dashboard   | world-data  | (汇总)         | 世界总览（词条 + 维度的概览页）                                                                     |
-| world-init/schema-gen    | world-schema        | sliders-horizontal | world-data  | schema         | 角色属性 schema                                                                                     |
+| 插件/runtime             | 面板 ID             | 图标               | group         | 数据 namespace | 描述                                                                                                |
+| ------------------------ | ------------------- | ------------------ | ------------- | -------------- | --------------------------------------------------------------------------------------------------- |
+| char-creator/player-init | character           | users              | character     | characters     | 角色列表（player + NPC + companion）                                                                |
+| character-blueprint      | character-blueprint | id-card            | character     | blueprints     | 预设角色（世界作者预置的登场角色模板，只读；作为 `character` 组的子 Tab）                           |
+| character-presence       | character-presence  | image              | character-art | presence       | 角色立绘画廊（`PortraitGallery`，只读展示 + 玩家可上传替换头像）                                    |
+| codex                    | codex               | book-open          | codex         | entries        | 知识图鉴                                                                                            |
+| living-world-rules       | living-world-rules  | book-marked        | world-data    | rules          | 世界规则（长期设定 / 禁忌，只读；随 world-data 导入播种，作为 `world-data` 组的子 Tab）             |
+| memory                   | memory              | brain              | memory        | （框架托管）   | 核心记忆面板：剧情摘要 / 当前场景 / 角色关系 / 玩家状态。纯 UI，由 `@covel/memory` 在每轮结束后写入 |
+| npc-graph/extractor      | npc-graph           | network            | npc-graph     | nodes + edges  | NPC 关系图（force-directed 可视化）                                                                 |
+| scene-cast               | scene-cast          | users-round        | （无）        | active-cast    | 当前场景在场角色（只读，仅 name + role；内部选择信号留在 plugin_data）                              |
+| scene-stage/resolver     | scene-stage         | image              | scene-stage   | stage          | 当前场景舞台（只读）：场景名 + 昼夜徽标 + `sourceLabel` 状态文案（`pending` 时"背景生成中…"）       |
+| world-init/schema-gen    | world-overview      | layout-dashboard   | world-data    | (汇总)         | 世界总览（词条 + 维度的概览页）                                                                     |
+| world-init/schema-gen    | world-schema        | sliders-horizontal | world-data    | schema         | 角色属性 schema                                                                                     |
 
 > `world-data` 组（groupLabel "世界资料"）汇聚三个 spec：`world-init` 的 `world-overview` / `world-schema`，以及 `living-world-rules` 的 `living-world-rules`（世界规则）。合并为单个 activity-bar tab，内部横向子 Tab 在总览 / 属性 / 世界规则 之间切换。（旧 `world-entries` 子 Tab 已移除：对导入型世界它只是 `world-overview` 已格式化渲染的同一份 dimensions 的原始 JSON 重复；`entries` 的 lorebook/prompt 写入不变，`/debug` Data Explorer 仍可查看。）
 > `character` 组汇聚 `char-creator` 的 character-panel（活角色列表，character-tracker runtime 共享 namespace `characters`，由 `create-character` / `update-character` builtin 工具写入）与 `character-blueprint` 的预设角色面板（世界作者预置的登场角色模板，只读）。前者是当前存档的活状态，后者是导入的只读源；同一批角色导入后会 mirror 成活的 `CharacterRecord`，两个子 Tab 分别呈现"源"与"当前"。
@@ -370,73 +372,7 @@ guide 分析叙事 → `generate-guide` 写入 `plugin_data[message]`
 
 ## 组件 Catalog
 
-框架内置 ~25 个 json-render 组件，所有插件共享：
-
-### 布局
-
-| 组件      | 用途               |
-| --------- | ------------------ |
-| Stack     | 垂直排列，可设 gap |
-| Row       | 水平排列           |
-| Grid      | 网格布局           |
-| Separator | 分隔线             |
-
-### 展示
-
-| 组件    | 用途                                 |
-| ------- | ------------------------------------ |
-| Text    | 文本（支持 variant/weight/size）     |
-| Badge   | 彩色标签                             |
-| Icon    | Lucide 图标                          |
-| TagList | 标签列表                             |
-| Prose   | Markdown 叙事文本（段落分割 + 加粗） |
-| Source  | 来源归属标签                         |
-
-### 数据
-
-| 组件      | 用途                                                    |
-| --------- | ------------------------------------------------------- |
-| Card      | 卡片容器                                                |
-| CardList  | 卡片列表                                                |
-| EntryCard | 图鉴条目卡片（分类图标 + 稀有度 + 标签）                |
-| StatBar   | 数值条（label + value/max + 进度条）                    |
-| Progress  | 进度条                                                  |
-| Accordion | 折叠面板容器（与 `repeat` + `Section` 组合）            |
-| Section   | 可折叠 section（props: `title`, `icon`, `defaultOpen`） |
-| JsonView  | 递归渲染任意 JSON 值（props: `value`）                  |
-
-### 交互
-
-| 组件        | 用途                           |
-| ----------- | ------------------------------ |
-| Button      | 按钮（default/primary/danger） |
-| Input       | 文本输入                       |
-| SearchInput | 带搜索图标的输入框             |
-| Select      | 下拉选择                       |
-| Switch      | 开关                           |
-| FilterBar   | 分类筛选栏                     |
-
-### 表单
-
-| 组件         | 用途                        |
-| ------------ | --------------------------- |
-| Form         | 表单容器                    |
-| FormHeader   | 表单标题栏                  |
-| FormField    | 单个表单字段（text/select） |
-| SubmitButton | 提交按钮（支持 disabled）   |
-
-### 消息
-
-| 组件          | 用途                               |
-| ------------- | ---------------------------------- |
-| PlayerMessage | 玩家消息气泡（右对齐）             |
-| Alert         | 通知（info/success/warning/error） |
-
-### 可视化
-
-| 组件        | 用途                                                                                                                                                                                                                                                                                                                     |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| GraphCanvas | 力导向关系图（react-force-graph-2d）。读取 `pluginId` 下两个 namespace 的数据（节点 + 边），按 `node.type` 着色，按边的 `strength` 正负染色。点击节点弹出档案。基于 lazy import，仅在打开面板时加载 ~60KB gzip 的额外 chunk。Props: `pluginId`, `nodesNamespace`, `edgesNamespace`, `height?`。当前由 `npc-graph` 使用。 |
+组件目录已抽出到独立页面，见 [docs/reference/ui-components.md](./ui-components.md)（当前 48 个组件，权威来源为 `apps/web/src/lib/catalog.tsx` 导出的 `covelRegistry`）。
 
 ## 数据流
 

From 3a20d2daf61637307cb9fb4a8e20778fd97dedf6 Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 13:58:31 +0800
Subject: [PATCH 06/10] refactor: apply verified six-dimension audit fixes

Explore/verify workflow audit (24 confirmed findings); this lands all
small, safe fixes:

- dead code: unused @covel/context re-exports in runtime barrel,
  cloneVectorRows, 8 unused ui-* CSS classes (incl. paper theme ref)
- stale docs: remove CLAUDE.md section for the deleted LLM replay
  cache, correct TRUSTED_PROXY_IPS status in env-registry, retag
  shipped S4-T4.c TTL sweep from TODO to spec, fix stale comments
- logging: settings REST backend now surfaces failed PUTs (res.ok),
  keep stacks in turn-executor warn paths, add [shutdown] prefixes,
  log Data Explorer catch paths and model-db refresh failures
- consistency: shared readJsonBody helper in api-error.ts; 13 routes
  now return 400 invalid_json_body instead of 500 on malformed JSON
- perf: plugin-data-store snapshots scoped per (pluginId, namespace)
  so unrelated plugin-data writes no longer re-render every panel
---
 CLAUDE.md                                     | 12 ----
 apps/server/src/api-error.ts                  | 23 ++++++-
 apps/server/src/graceful-shutdown.ts          | 15 ++---
 apps/server/src/routes/api/ai.ts              |  6 +-
 apps/server/src/routes/api/bootstrap.ts       |  7 +-
 apps/server/src/routes/api/characters.ts      |  6 +-
 apps/server/src/routes/api/events.ts          |  8 ++-
 apps/server/src/routes/api/plugin-data.ts     |  6 +-
 apps/server/src/routes/api/session.ts         | 18 ++++--
 apps/server/src/routes/api/state.ts           |  6 +-
 .../server/src/routes/api/suspension-sweep.ts |  2 +-
 apps/server/src/routes/api/working-memory.ts  |  6 +-
 apps/server/src/routes/api/worlds/crud.ts     | 10 ++-
 .../server/src/routes/api/worlds/data-sync.ts |  6 +-
 .../src/routes/api/worlds/dimensions.ts       |  6 +-
 apps/server/src/routes/config-api.ts          | 20 +-----
 apps/server/src/routes/model-db.ts            |  1 +
 apps/web/src/index.css                        | 64 +------------------
 apps/web/src/stores/plugin-data-store.ts      | 55 ++++++++++------
 apps/web/src/themes/builtins/paper/theme.css  |  1 -
 docs/guide/env-registry.md                    |  4 +-
 packages/runtime/src/index.ts                 |  7 --
 .../src/turn-executor/post-turn-memory.ts     |  2 +-
 .../src/turn-executor/session-context.ts      |  5 +-
 .../turn-executor/turn-result-finalizer.ts    |  2 +-
 .../tests/scene-stage-integration.test.ts     | 10 +--
 packages/settings/src/backends/json-file.ts   | 10 ++-
 packages/shared/src/env/groups/server.ts      |  2 +-
 packages/store/src/memory/vector-methods.ts   | 18 ------
 packages/store/src/types.ts                   |  2 +-
 30 files changed, 145 insertions(+), 195 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ee537ec8..ee9d8f19 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -305,18 +305,6 @@ Each SQL backend keeps a thin public factory plus focused method modules:
 - **Error sanitising**: the `app.onError` handler (`routes/api/bootstrap.ts` + `app.ts`) returns `"Internal server error"` in prod (stacks/paths only to `console.error`); dev returns `err.message`.
 - **Debug artefacts**: always write under `debugs/` (never repo root) — gitignored.
 
-### Dev-mode LLM replay cache
-
-Only active when `COVEL_LLM_REPLAY` is set. Zero overhead / zero behaviour change when unset.
-
-| Mode     | Behaviour                                                 |
-| -------- | --------------------------------------------------------- |
-| `auto`   | Hit = replay, miss = call provider + record (dev default) |
-| `record` | Always call provider, overwrite cache                     |
-| `replay` | Read-only; miss throws (for breakpoint reproduction)      |
-
-Cache dir: `COVEL_LLM_REPLAY_DIR` (default `debugs/llm-cache/`). Key = `sha256(method + url + canonicalJson(body))`. `authorization` / `api_key` are redacted in hash input and on disk. Streaming is T-eed via `TransformStream` (10 MB buffer cap, skip over).
-
 ## Observability
 
 Trace chain: `traceId → runId → branchId → turnId → runtimeId → pluginId`.
diff --git a/apps/server/src/api-error.ts b/apps/server/src/api-error.ts
index 52cb4256..f0a5fee3 100644
--- a/apps/server/src/api-error.ts
+++ b/apps/server/src/api-error.ts
@@ -1,4 +1,4 @@
-import type { ErrorHandler } from "hono";
+import type { Context, ErrorHandler } from "hono";
 
 /**
  * Standard API error envelope.
@@ -40,6 +40,27 @@ export function errorBody<Code extends string = string>(
   return body;
 }
 
+/**
+ * Parse a JSON request body, or return a 400 envelope Response so a malformed
+ * body converges on the standard error shape instead of throwing into the
+ * global 500 handler. Callers do
+ * `const parsed = await readJsonBody(c); if (parsed instanceof Response) return parsed;`
+ * then read `parsed.body`. Pass a type param to preserve the shape the route
+ * expects (`readJsonBody<Record<string, unknown>>(c)`).
+ */
+export async function readJsonBody<T = unknown>(
+  c: Context,
+): Promise<{ body: T } | Response> {
+  try {
+    return { body: (await c.req.json()) as T };
+  } catch {
+    return c.json(
+      errorBody("Invalid JSON body", { code: "invalid_json_body" }),
+      400,
+    );
+  }
+}
+
 /**
  * Redact sensitive query params (signed media `token`, SSE `session_token`
  * owner auth) from a URL before it hits logs — the raw string is kept
diff --git a/apps/server/src/graceful-shutdown.ts b/apps/server/src/graceful-shutdown.ts
index 9dc7d4b7..5a57834b 100644
--- a/apps/server/src/graceful-shutdown.ts
+++ b/apps/server/src/graceful-shutdown.ts
@@ -32,29 +32,28 @@ export const registerGracefulShutdown = (
     }
 
     shuttingDown = true;
-    console.log(`Received ${signal}, shutting down server...`);
+    console.log(`[shutdown] Received ${signal}, shutting down server...`);
 
     const shutdownTimer = setTimeout(() => {
-      console.log(`Server shutdown timed out after ${FORCE_EXIT_AFTER_MS}ms`);
+      console.log(
+        `[shutdown] Server shutdown timed out after ${FORCE_EXIT_AFTER_MS}ms`,
+      );
       process.exit(1);
     }, FORCE_EXIT_AFTER_MS);
 
     const finish = async (error?: Error): Promise<void> => {
       if (error) {
-        console.log(`Server shutdown failed: ${error.message}`);
+        console.error("[shutdown] Server shutdown failed:", error);
         process.exit(1);
         return;
       }
 
-      console.log("Server stopped.");
+      console.log("[shutdown] Server stopped.");
       if (options.drain) {
         try {
           await options.drain();
         } catch (err) {
-          console.error(
-            "[shutdown] resource drain failed:",
-            err instanceof Error ? err.message : String(err),
-          );
+          console.error("[shutdown] resource drain failed:", err);
         }
       }
       clearTimeout(shutdownTimer);
diff --git a/apps/server/src/routes/api/ai.ts b/apps/server/src/routes/api/ai.ts
index 61c49ea6..55d18bb1 100644
--- a/apps/server/src/routes/api/ai.ts
+++ b/apps/server/src/routes/api/ai.ts
@@ -17,7 +17,7 @@ import type { LLMAdapter } from "@covel/runtime";
 import type { DataStore, WorldRecord } from "@covel/store";
 import { rateLimiter, singleFlight } from "../../middleware/rate-limit.js";
 import { loadSingleWorld } from "../../world-seed-loader.js";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 import { checkHostedOperator } from "./session/session-guard.js";
 
 type Env = {
@@ -110,7 +110,9 @@ aiRoutes.post(
   async (c) => {
     const llm = c.get("llmAdapter");
     const store = c.get("store");
-    const body = await c.req.json<Record<string, unknown>>();
+    const parsed = await readJsonBody<Record<string, unknown>>(c);
+    if (parsed instanceof Response) return parsed;
+    const body = parsed.body;
 
     const concept = body.concept ?? body.prompt;
     if (typeof concept !== "string" || !concept.trim()) {
diff --git a/apps/server/src/routes/api/bootstrap.ts b/apps/server/src/routes/api/bootstrap.ts
index 2b51029a..3e5c90b9 100644
--- a/apps/server/src/routes/api/bootstrap.ts
+++ b/apps/server/src/routes/api/bootstrap.ts
@@ -258,7 +258,7 @@ export async function bootstrapApi(
   const store = wrapStoreWithPluginDataEvents(config.store, eventBus);
 
   // One-time startup sweep of stale suspensions accumulated while the server
-  // was down (TODO S4-T4.c). Fire-and-forget — never blocks boot.
+  // was down (spec S4-T4.c). Fire-and-forget — never blocks boot.
   void maybeSweepExpiredSuspensions(store, { force: true }).catch(
     (err: unknown) =>
       console.warn(
@@ -442,9 +442,8 @@ export async function bootstrapApi(
     }
   }
 
-  // 7. getConfigFn — per-request config injection
-  //    Actual config pre-loading happens in the actions.ts route handler
-  //    before calling executeTurn, bridging async store reads to sync getConfig interface.
+  // 7. getConfigFn — per-runtime config injection seam. No production caller
+  //    passes it today, so ctx.config / {{ config.* }} always resolve to {}.
   const getConfigFn =
     config.getConfigFn ??
     ((
diff --git a/apps/server/src/routes/api/characters.ts b/apps/server/src/routes/api/characters.ts
index 4696546c..499d1061 100644
--- a/apps/server/src/routes/api/characters.ts
+++ b/apps/server/src/routes/api/characters.ts
@@ -8,7 +8,7 @@ import type { DataStore, CharacterRecord } from "@covel/store";
 import type { EventBus } from "@covel/events";
 import type { Proposal } from "@covel/shared";
 import type { HookPipeline } from "@covel/runtime";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 import { frameworkProposalSource } from "../../lib/framework-source.js";
 import { resolveSessionParam } from "./session/session-guard.js";
 
@@ -38,7 +38,9 @@ characterRoutes.post("/:id/characters", async (c) => {
   const store = c.get("store");
   const sessionId = guard.session.id;
 
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
 
   if (!body.id || typeof body.id !== "string") {
     return c.json(errorBody("id (string) is required"), 400);
diff --git a/apps/server/src/routes/api/events.ts b/apps/server/src/routes/api/events.ts
index d9d2929a..93da9924 100644
--- a/apps/server/src/routes/api/events.ts
+++ b/apps/server/src/routes/api/events.ts
@@ -9,7 +9,7 @@ import type { EventBus } from "@covel/events";
 import type { DataStore } from "@covel/store";
 import type { CovelMessage } from "@covel/shared";
 import { isEnvTruthy, readRuntimeEnv } from "@covel/shared";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 import { checkSessionOwnerById } from "./session/session-guard.js";
 
 type Env = {
@@ -31,12 +31,14 @@ eventRoutes.post("/emit", async (c) => {
   }
 
   const eventBus = c.get("eventBus");
-  const body = await c.req.json<{
+  const parsed = await readJsonBody<{
     topic?: string;
     payload?: Record<string, unknown>;
     sessionId?: string;
     targetRuntime?: string;
-  }>();
+  }>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
 
   if (!body.topic || !body.sessionId) {
     return c.json(errorBody("topic and sessionId are required"), 400);
diff --git a/apps/server/src/routes/api/plugin-data.ts b/apps/server/src/routes/api/plugin-data.ts
index 635b679c..1384e51f 100644
--- a/apps/server/src/routes/api/plugin-data.ts
+++ b/apps/server/src/routes/api/plugin-data.ts
@@ -14,7 +14,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import type { DataStore } from "@covel/store";
 import type { PluginRegistry } from "@covel/plugin-loader";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 import { buildPluginDataIndex } from "./discovery.js";
 import { resolveSessionParam } from "./session/session-guard.js";
 
@@ -157,7 +157,9 @@ pluginDataRoutes.put(
     const accessErr = validatePluginAccess(registry, pluginId, sessionId, true);
     if (accessErr) return c.json(errorBody(accessErr.error), accessErr.status);
 
-    const raw = await c.req.json<unknown>();
+    const jsonBody = await readJsonBody(c);
+    if (jsonBody instanceof Response) return jsonBody;
+    const raw = jsonBody.body;
     // zod 4.4: bare z.unknown() is required; .optional() keeps 4.3 behaviour.
     const bodySchema = z.object({ value: z.unknown().optional() });
     const parsed = bodySchema.safeParse(raw);
diff --git a/apps/server/src/routes/api/session.ts b/apps/server/src/routes/api/session.ts
index 95468330..7800c06b 100644
--- a/apps/server/src/routes/api/session.ts
+++ b/apps/server/src/routes/api/session.ts
@@ -35,7 +35,7 @@ import {
   runSessionEndHook,
   runWithHookScope,
 } from "@covel/runtime";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 import { normalizeLocale } from "../../lib/validators.js";
 import { signMediaTokenForSession } from "../../middleware/media-token.js";
 import {
@@ -216,7 +216,9 @@ sessionRoutes.post("/", async (c) => {
   const pluginRegistry = c.get("pluginRegistry");
   const worldsDirs = c.get("worldsDirs");
   const covelHome = c.get("covelHome");
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
 
   const parsedCreate = parseCreateSessionBody(body);
   if (!parsedCreate.ok) {
@@ -451,7 +453,9 @@ sessionRoutes.patch("/:id", async (c) => {
   if (!guard.ok) return guard.response;
   const session = guard.session;
 
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   const now = new Date().toISOString();
   const parsedPatch = buildSessionPatchUpdates(body, now);
   if (!parsedPatch.ok) {
@@ -546,7 +550,9 @@ sessionRoutes.post("/:id/plugins/enable", async (c) => {
   if (!guard.ok) return guard.response;
   const session = guard.session;
 
-  const body = await c.req.json<{ pluginId: string }>();
+  const parsed = await readJsonBody<{ pluginId: string }>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   if (!body.pluginId || !pluginRegistry.get(body.pluginId)) {
     return c.json(errorBody(`Plugin "${body.pluginId}" not found`), 404);
   }
@@ -618,7 +624,9 @@ sessionRoutes.post("/:id/plugins/disable", async (c) => {
   if (!guard.ok) return guard.response;
   const session = guard.session;
 
-  const body = await c.req.json<{ pluginId: string }>();
+  const parsed = await readJsonBody<{ pluginId: string }>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   if (!body.pluginId || typeof body.pluginId !== "string") {
     return c.json(errorBody("pluginId is required"), 400);
   }
diff --git a/apps/server/src/routes/api/state.ts b/apps/server/src/routes/api/state.ts
index 4d578e80..59e43882 100644
--- a/apps/server/src/routes/api/state.ts
+++ b/apps/server/src/routes/api/state.ts
@@ -99,8 +99,9 @@ stateRoutes.get("/:id/state", async (c) => {
         data,
       };
     }
-  } catch {
+  } catch (err) {
     // Non-critical: characters table optional on slim stores.
+    console.warn(`[state] characters query failed for session ${id}:`, err);
   }
 
   // ── plugin_data grouped by (pluginId, namespace) ──────────────────
@@ -136,8 +137,9 @@ stateRoutes.get("/:id/state", async (c) => {
         data: entry.data,
       };
     }
-  } catch {
+  } catch (err) {
     // Non-critical: session may have no plugin_data rows yet.
+    console.warn(`[state] plugin_data query failed for session ${id}:`, err);
   }
 
   return c.json({ tables });
diff --git a/apps/server/src/routes/api/suspension-sweep.ts b/apps/server/src/routes/api/suspension-sweep.ts
index b0be7a2f..40497a35 100644
--- a/apps/server/src/routes/api/suspension-sweep.ts
+++ b/apps/server/src/routes/api/suspension-sweep.ts
@@ -1,5 +1,5 @@
 /**
- * Stale-suspension TTL sweep (TODO S4-T4.c).
+ * Stale-suspension TTL sweep (spec S4-T4.c).
  *
  * Covel has no general scheduler, so expiry runs opportunistically — the
  * cutoff + cadence live ONLY here so every caller stays consistent:
diff --git a/apps/server/src/routes/api/working-memory.ts b/apps/server/src/routes/api/working-memory.ts
index 67a933fb..dceb9850 100644
--- a/apps/server/src/routes/api/working-memory.ts
+++ b/apps/server/src/routes/api/working-memory.ts
@@ -13,7 +13,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import type { DataStore } from "@covel/store";
 import { resolveSessionParam } from "./session/session-guard.js";
-import { errorBody } from "../../api-error.js";
+import { errorBody, readJsonBody } from "../../api-error.js";
 
 type Env = {
   Variables: {
@@ -86,7 +86,9 @@ workingMemoryRoutes.put("/:id/working-memory/:scope/:key", async (c) => {
     return c.json(errorBody("Key must not be empty"), 400);
   }
 
-  const raw = await c.req.json<unknown>();
+  const jsonBody = await readJsonBody(c);
+  if (jsonBody instanceof Response) return jsonBody;
+  const raw = jsonBody.body;
   const bodySchema = z.object({
     // zod 4.4: a bare z.unknown() field is required; .optional() preserves the
     // 4.3 behaviour (a missing value parsed as undefined) — don't 400 callers.
diff --git a/apps/server/src/routes/api/worlds/crud.ts b/apps/server/src/routes/api/worlds/crud.ts
index 11ff0995..b1bb637e 100644
--- a/apps/server/src/routes/api/worlds/crud.ts
+++ b/apps/server/src/routes/api/worlds/crud.ts
@@ -6,7 +6,7 @@ import { Hono } from "hono";
 import { rm } from "node:fs/promises";
 import path from "node:path";
 import type { WorldRecord } from "@covel/store";
-import { errorBody } from "../../../api-error.js";
+import { errorBody, readJsonBody } from "../../../api-error.js";
 import { resolveContainedPath } from "../../../world-data/safe-path.js";
 import { checkHostedOperator } from "../session/session-guard.js";
 import { type WorldEnv, resolveWorldMetadata } from "./shared.js";
@@ -36,7 +36,9 @@ worldCrudRoutes.post("/", async (c) => {
   const denied = checkHostedOperator(c);
   if (denied) return denied;
   const store = c.get("store");
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
 
   if (!body.id || typeof body.id !== "string") {
     return c.json(errorBody("id (string) is required"), 400);
@@ -77,7 +79,9 @@ worldCrudRoutes.patch("/:id", async (c) => {
     return c.json(errorBody("World not found"), 404);
   }
 
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   const now = new Date().toISOString();
   const metadataResult = resolveWorldMetadata(body, existing.metadata);
   if (metadataResult.error) {
diff --git a/apps/server/src/routes/api/worlds/data-sync.ts b/apps/server/src/routes/api/worlds/data-sync.ts
index 6dfd9188..40ce7431 100644
--- a/apps/server/src/routes/api/worlds/data-sync.ts
+++ b/apps/server/src/routes/api/worlds/data-sync.ts
@@ -9,7 +9,7 @@
 
 import { Hono } from "hono";
 import { FrameworkCapability } from "@covel/shared";
-import { errorBody } from "../../../api-error.js";
+import { errorBody, readJsonBody } from "../../../api-error.js";
 import {
   syncWorldDataForSession,
   preflightWorldDataForSession,
@@ -134,7 +134,9 @@ worldDataSyncRoutes.post("/:id/sync-dimensions", async (c) => {
   const pluginRegistry = c.get("pluginRegistry");
   const id = c.req.param("id");
 
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   const sessionId = body.sessionId;
   if (typeof sessionId !== "string") {
     return c.json(errorBody("sessionId (string) is required"), 400);
diff --git a/apps/server/src/routes/api/worlds/dimensions.ts b/apps/server/src/routes/api/worlds/dimensions.ts
index 17179795..3b0e2e5f 100644
--- a/apps/server/src/routes/api/worlds/dimensions.ts
+++ b/apps/server/src/routes/api/worlds/dimensions.ts
@@ -9,7 +9,7 @@ import { Hono } from "hono";
 import { stringify as stringifyYaml } from "yaml";
 import { validateDimensions } from "@covel/shared";
 import type { WorldRecord } from "@covel/store";
-import { errorBody } from "../../../api-error.js";
+import { errorBody, readJsonBody } from "../../../api-error.js";
 import { type WorldEnv } from "./shared.js";
 import { checkHostedOperator } from "../session/session-guard.js";
 
@@ -60,7 +60,9 @@ worldDimensionRoutes.post("/:id/dimensions/import", async (c) => {
     return c.json(errorBody("World not found"), 404);
   }
 
-  const body = await c.req.json<Record<string, unknown>>();
+  const parsed = await readJsonBody<Record<string, unknown>>(c);
+  if (parsed instanceof Response) return parsed;
+  const body = parsed.body;
   const dimensions = body.dimensions;
 
   if (!dimensions || typeof dimensions !== "object") {
diff --git a/apps/server/src/routes/config-api.ts b/apps/server/src/routes/config-api.ts
index 046714c8..fe47f6c7 100644
--- a/apps/server/src/routes/config-api.ts
+++ b/apps/server/src/routes/config-api.ts
@@ -18,7 +18,7 @@
  * X-Provider-Keys header flow driven by browser localStorage.
  */
 
-import { Hono, type Context } from "hono";
+import { Hono } from "hono";
 import { resolve, join, dirname, isAbsolute } from "node:path";
 import {
   readFileSync,
@@ -35,26 +35,10 @@ import {
   readRuntimeEnv,
   toApiKeyEnvMap,
 } from "@covel/shared";
-import { errorBody } from "../api-error.js";
+import { errorBody, readJsonBody } from "../api-error.js";
 import { parseEnvLines } from "../lib/env-file.js";
 import { makeDesktopRestTokenGuard } from "./privileged-auth.js";
 
-/**
- * Parse a JSON request body, or return a 400 envelope Response. Callers do
- * `const parsed = await readJsonBody(c); if (parsed instanceof Response) return parsed;`
- * then read `parsed.body`.
- */
-async function readJsonBody(c: Context): Promise<{ body: unknown } | Response> {
-  try {
-    return { body: await c.req.json() };
-  } catch {
-    return c.json(
-      errorBody("Invalid JSON body", { code: "invalid_json_body" }),
-      400,
-    );
-  }
-}
-
 export interface ConfigApiDeps {
   /** Mutable map shared with the gateway adapter. PUT handlers mutate in-place. */
   apiKeys: Record<string, string>;
diff --git a/apps/server/src/routes/model-db.ts b/apps/server/src/routes/model-db.ts
index f3fe7f9e..c9b8eae0 100644
--- a/apps/server/src/routes/model-db.ts
+++ b/apps/server/src/routes/model-db.ts
@@ -97,6 +97,7 @@ export function createModelDbRoutes(ai: AiStack): Hono {
         }
         return c.json({ ok: true, count: ai.modelDb.count, persisted });
       } catch (err) {
+        console.error("[model-db] refresh failed:", err);
         const message = err instanceof Error ? err.message : String(err);
         return c.json({ ok: false, error: message });
       }
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 9706f3d9..37f4a1cf 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -258,28 +258,13 @@
 }
 
 /* Rules / hairlines */
-.ui-rule,
-.ui-rule-h {
+.ui-rule {
   border: 0;
   border-top: var(--rule-thickness) var(--rule-style) var(--rule-color);
   height: 0;
   width: 100%;
 }
 
-.ui-rule-strong {
-  border: 0;
-  border-top: var(--rule-strong-thickness) var(--rule-style)
-    var(--rule-strong-color);
-  height: 0;
-  width: 100%;
-}
-
-.ui-rule-v {
-  width: var(--rule-thickness);
-  background: var(--rule-color);
-  align-self: stretch;
-}
-
 .ui-outline-rail {
   border-left-style: solid;
 }
@@ -373,44 +358,11 @@
   border-radius: var(--radius-card);
 }
 
-.ui-frame-elevated {
-  background: var(--surface-elevated);
-  border: var(--rule-thickness) var(--rule-style) var(--rule-color);
-  border-radius: var(--radius-card);
-  box-shadow: var(--shadow-card);
-}
-
-/* Plate: editorial figure-style print, with print number */
-.ui-plate {
-  position: relative;
-  padding: 1rem 1.125rem;
-  background: var(--surface-inset);
-  border-top: var(--rule-strong-thickness) var(--rule-style)
-    var(--rule-strong-color);
-  border-bottom: var(--rule-thickness) var(--rule-style) var(--rule-color);
-}
-
-.ui-plate-number {
-  position: absolute;
-  top: 0.25rem;
-  right: 0.625rem;
-  font-family: var(--type-meta);
-  font-size: 0.6rem;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
-  color: var(--color-muted-foreground);
-  opacity: 0.7;
-}
-
 /* Rail: vertical surface for left/right panels */
 .ui-rail {
   background: var(--surface-rail);
 }
 
-.ui-rail-divider {
-  border-color: var(--rule-color);
-}
-
 /* Panel header / footer (same surface as rail) */
 .ui-panel-header {
   height: var(--panel-header-height);
@@ -559,20 +511,6 @@
   background: color-mix(in oklab, var(--color-foreground) 7%, transparent);
 }
 
-.ui-btn-primary {
-  background: var(--color-foreground);
-  color: var(--surface-page);
-  border-color: var(--color-foreground);
-}
-
-.ui-btn-primary:hover {
-  background: color-mix(
-    in oklab,
-    var(--color-foreground) 88%,
-    var(--accent-primary) 12%
-  );
-}
-
 .ui-btn-quiet {
   border-color: transparent;
 }
diff --git a/apps/web/src/stores/plugin-data-store.ts b/apps/web/src/stores/plugin-data-store.ts
index 2a3b4c91..ac3b8e6b 100644
--- a/apps/web/src/stores/plugin-data-store.ts
+++ b/apps/web/src/stores/plugin-data-store.ts
@@ -16,7 +16,7 @@
  * Standalone external store using useSyncExternalStore.
  */
 
-import { useSyncExternalStore } from "react";
+import { useMemo, useSyncExternalStore } from "react";
 
 export type PluginData = Record<
   string,
@@ -156,13 +156,21 @@ export function usePluginData(): PluginData {
   return useSyncExternalStore(subscribe, getSnapshot);
 }
 
-/** React hook — returns data for a specific plugin + namespace. */
+/**
+ * React hook — returns data for a specific plugin + namespace.
+ *
+ * The snapshot is the per-(pluginId, namespace) slice, not the whole tree:
+ * writers only rebuild the object identity of slices they touch, so a
+ * `plugin-data.changed` event from another plugin/namespace returns the
+ * same reference and React bails out without re-rendering this panel.
+ */
 export function usePluginNamespace(
   pluginId: string,
   namespace: string,
 ): Record<string, unknown> {
-  const all = useSyncExternalStore(subscribe, getSnapshot);
-  return all[pluginId]?.[namespace] ?? EMPTY_NAMESPACE;
+  return useSyncExternalStore(subscribe, () =>
+    getPluginNamespaceSnapshot(pluginId, namespace),
+  );
 }
 
 // ── Background job (`_jobs`) namespace helpers ──────────────────
@@ -212,16 +220,19 @@ function asJobRecord(jobId: string, value: unknown): PluginJobRecord | null {
  * new status records into `_jobs`.
  */
 export function usePluginJobs(pluginId: string): readonly PluginJobRecord[] {
-  const all = useSyncExternalStore(subscribe, getSnapshot);
-  const ns = all[pluginId]?.["_jobs"];
-  if (!ns) return EMPTY_JOBS;
-  const jobs: PluginJobRecord[] = [];
-  for (const jobId of Object.keys(ns)) {
-    const record = asJobRecord(jobId, ns[jobId]);
-    if (record) jobs.push(record);
-  }
-  jobs.sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? ""));
-  return jobs;
+  const ns = useSyncExternalStore(subscribe, () =>
+    getPluginNamespaceSnapshot(pluginId, "_jobs"),
+  );
+  return useMemo(() => {
+    if (ns === EMPTY_NAMESPACE) return EMPTY_JOBS;
+    const jobs: PluginJobRecord[] = [];
+    for (const jobId of Object.keys(ns)) {
+      const record = asJobRecord(jobId, ns[jobId]);
+      if (record) jobs.push(record);
+    }
+    jobs.sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? ""));
+    return jobs;
+  }, [ns]);
 }
 
 const EMPTY_JOBS: readonly PluginJobRecord[] = Object.freeze([]);
@@ -236,10 +247,14 @@ const EMPTY_JOBS: readonly PluginJobRecord[] = Object.freeze([]);
  * Returns `null` when no world has produced a schema yet.
  */
 export function useCharacterAttributeSchema(): unknown {
-  const all = useSyncExternalStore(subscribe, getSnapshot);
-  for (const pluginId of Object.keys(all)) {
-    const value = all[pluginId]?.["schema"]?.["character-attributes"];
-    if (value) return value;
-  }
-  return null;
+  // Snapshot is the schema value itself (stable reference while untouched),
+  // so unrelated plugin-data writes don't re-render consumers.
+  return useSyncExternalStore(subscribe, () => {
+    const all = getActiveData();
+    for (const pluginId of Object.keys(all)) {
+      const value = all[pluginId]?.["schema"]?.["character-attributes"];
+      if (value) return value;
+    }
+    return null;
+  });
 }
diff --git a/apps/web/src/themes/builtins/paper/theme.css b/apps/web/src/themes/builtins/paper/theme.css
index 1e3f3faa..8cc80369 100644
--- a/apps/web/src/themes/builtins/paper/theme.css
+++ b/apps/web/src/themes/builtins/paper/theme.css
@@ -143,7 +143,6 @@ html[data-theme="paper"] .ui-section-title {
 }
 
 /* Dashed dividers feel right with the editorial paper tone */
-html[data-theme="paper"] .ui-rule-h,
 html[data-theme="paper"] .ui-rule {
   border-top-style: dashed;
 }
diff --git a/docs/guide/env-registry.md b/docs/guide/env-registry.md
index 38dc6a5b..2f25a108 100644
--- a/docs/guide/env-registry.md
+++ b/docs/guide/env-registry.md
@@ -55,12 +55,12 @@ Covel 的环境变量清单由 `packages/shared/src/env/registry.ts` 维护。
 - `DEPLOYMENT_TIER=self` 对应本地自部署；localhost 请求可以读取 server 注入的 provider key 元数据。`demo` / `commercial` 会硬性强制 session owner token 鉴权（见 [`docs/reference/api.md`](../reference/api.md) 鉴权章节）。未知值会被规范化并 fail-closed 到最严格的 `commercial`。
 - `COVEL_DESKTOP_REST_TOKEN` 是运维 master / operator 凭证：以该值作为 Bearer token 可通过任意会话的 owner 校验（管理工具 / e2e harness 用），并且是 hosted（`demo` / `commercial`）层级创建/列出会话、世界写入与维度导入、AI 世界生成、模型探测/刷新以及 community server-code 激活的必需凭证。`DEPLOYMENT_TIER=demo|commercial` 启动时若未配置该 token，`validateSecurityPosture` 会直接拒绝启动（fail-closed）。`self` / 桌面 / dev 层级不要求也不校验它。这是当前单运维方信任模型，不提供多租户身份或代码沙箱（见 [`docs/reference/api.md`](../reference/api.md) 鉴权章节）。
 - `COVEL_BIND_HOST` 默认 `127.0.0.1`（audit S-02）：本地 / 桌面部署只监听回环接口，网络上不可达。容器或多 pod 部署需显式设置 `COVEL_BIND_HOST=0.0.0.0`（`docker/docker-compose.yml` 已内置）——这是一次显式的部署决策，公开监听前请确认 `DEPLOYMENT_TIER` 与鉴权配置。
-- `TRUSTED_PROXY_IPS`、`COVEL_LLM_REPLAY`、`COVEL_LLM_REPLAY_DIR` 目前标记为 `documented`，后续实现可以直接提升为 `active`。（`COVEL_ALLOWED_LLM_HOSTS` 已移除：SSRF guard 设计上即 open-by-default，从未读取该变量，也无实现计划。）
+- `COVEL_LLM_REPLAY`、`COVEL_LLM_REPLAY_DIR` 目前标记为 `documented`（replay cache 的旧实现已删除，源码中无任何读取方），后续重新实现时可提升为 `active`。`TRUSTED_PROXY_IPS` 已是 `active`（由 `middleware/rate-limit.ts` 的 X-Forwarded-For 信任检查消费）。（`COVEL_ALLOWED_LLM_HOSTS` 已移除：SSRF guard 设计上即 open-by-default，从未读取该变量，也无实现计划。）
 - `COVEL_TRACE_TRUNCATE` 标记为 `planned`，对应 debug trace 设计文档中的未来开关。
 - `COVEL_COMPACTOR_CONTEXT_WINDOW` 为**可选的显式覆盖**：未设置时，压缩阈值与 prompt 硬裁剪预算按当前叙事 slot（`default`，缺省为 llm.toml 首个 slot）的模型 capability `contextWindow` 动态解析（llm.toml 热重载即时生效），capability 也缺失时回退 `32768`。设置后固定使用该值，不再查 capability。
 - `COVEL_SNAPSHOT_INTERVAL_TURNS` 默认 `5`，控制 `kind=auto` 快照的 checkpoint 节奏：`turnCount <= 1`（pre-game 与首个正式回合）总是写入，其后每 N 回合写一份；`1` 表示每回合。resume 路径无视该节流强制写入。构建快照 payload 需要全量读取消息历史与全部 session-scoped 集合，逐回合写入会导致 O(T²) 成本与存储膨胀（audit 2026-07-11 R-04）。
 - `COVEL_MEDIA_CLEANUP_ENABLED` 默认 `false`，控制 `POST /api/media/cleanup` 的可用性。即使设为 `true`，`DEPLOYMENT_TIER=commercial` 时该端点仍强制 503，等待管理员鉴权中间件接入。详见 [`docs/reference/api.md`](../reference/api.md) 媒体管理章节。
 - `COVEL_PG_LOCK_POOL_MAX` 默认 `16`，控制 PG advisory session-lock 专用连接池的 `max`。每个进行中的 turn 占用一条 reserved 连接；多并发 pod 可按峰值并发会话数调大。锁获取超时（30s）覆盖连接池排队 + advisory lock 轮询全程。
-- `COVEL_SUSPENSION_TTL_MS` 默认 `604800000`（7 天），控制未解决（unresolved）挂起项的过期清理（TODO S4-T4.c）。清理无独立调度器：服务启动时执行一次性 force sweep，之后由 `GET /api/sessions/:id/suspensions` 与 `POST /api/sessions/:id/resume` 机会式触发、最多每小时一次的时间门控 sweep。设为 `0`（或负数）关闭清理。**claimed（恢复进行中）/ 已成功解决的记录永不清理**。属于框架基础设施开关（非插件 per-session 设置）。详见 [`docs/reference/api.md`](../reference/api.md) Suspend / Resume 章节。
+- `COVEL_SUSPENSION_TTL_MS` 默认 `604800000`（7 天），控制未解决（unresolved）挂起项的过期清理（spec S4-T4.c）。清理无独立调度器：服务启动时执行一次性 force sweep，之后由 `GET /api/sessions/:id/suspensions` 与 `POST /api/sessions/:id/resume` 机会式触发、最多每小时一次的时间门控 sweep。设为 `0`（或负数）关闭清理。**claimed（恢复进行中）/ 已成功解决的记录永不清理**。属于框架基础设施开关（非插件 per-session 设置）。详见 [`docs/reference/api.md`](../reference/api.md) Suspend / Resume 章节。
 - 插件自带的运行期开关——如 story-guard 的 `STORY_GUARD_REDACT_TERMS` / `STORY_GUARD_REDACT_MARK` / `STORY_GUARD_BLOCKED_TOOLS`——由插件自身经 `process.env` 读取，并在各自 `PLUGIN.md` / `README.md` 文档化。它们不经框架 env helper，也不在本 registry 的分组表内：这是「插件作者可读自己 env」的既定边界，与框架运行期开关分离管理。
 - cost-gate 的 `COST_GATE_SOFT_TOKENS` / `COST_GATE_HARD_TOKENS` 现已降级为**兜底**：阈值优先取 per-session `userSettings`（hook 经 `HookContext.getOwnSettings()` 读取本插件解析后的设置），回退链为 **per-session `userSettings` → env → 硬编码默认（150000 / 200000）**。只设 env 的旧部署照常工作；详见 `plugins/cost-gate/PLUGIN.md`。
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index a7cc2574..1c3090b5 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -5,13 +5,6 @@ export { shouldTrigger } from "./trigger/trigger.js";
 export { scheduleByPriority } from "./schedule/scheduler.js";
 export { scheduleByDag } from "./schedule/dag-scheduler.js";
 
-// ── Context Builder (re-exported from @covel/context) ───────────
-export {
-  interpolateTemplate,
-  buildInjectBlocks,
-  buildContext,
-} from "@covel/context";
-
 // ── Parallel Executor ────────────────────────────────────────────
 export { executeParallel } from "./schedule/parallel-executor.js";
 export type { RuntimeExecuteFn } from "./schedule/parallel-executor.js";
diff --git a/packages/runtime/src/turn-executor/post-turn-memory.ts b/packages/runtime/src/turn-executor/post-turn-memory.ts
index 53c7c139..ce60f55c 100644
--- a/packages/runtime/src/turn-executor/post-turn-memory.ts
+++ b/packages/runtime/src/turn-executor/post-turn-memory.ts
@@ -44,7 +44,7 @@ export function schedulePostTurnMemoryUpdate(args: {
     .catch((err) => {
       console.warn(
         `[turn-executor] memory update failed for ${input.sessionId}:`,
-        err instanceof Error ? err.message : String(err),
+        err,
       );
     });
 }
diff --git a/packages/runtime/src/turn-executor/session-context.ts b/packages/runtime/src/turn-executor/session-context.ts
index 9c45b5cb..47c07de6 100644
--- a/packages/runtime/src/turn-executor/session-context.ts
+++ b/packages/runtime/src/turn-executor/session-context.ts
@@ -98,10 +98,7 @@ export async function refreshSessionContextSnapshot(args: {
       playerMessage: input.playerMessage,
     });
   } catch (err) {
-    console.warn(
-      "[turn-executor] SessionContextSnapshot build failed:",
-      err instanceof Error ? err.message : String(err),
-    );
+    console.warn("[turn-executor] SessionContextSnapshot build failed:", err);
     return undefined;
   }
 }
diff --git a/packages/runtime/src/turn-executor/turn-result-finalizer.ts b/packages/runtime/src/turn-executor/turn-result-finalizer.ts
index c0ccb9a7..82eb6a84 100644
--- a/packages/runtime/src/turn-executor/turn-result-finalizer.ts
+++ b/packages/runtime/src/turn-executor/turn-result-finalizer.ts
@@ -84,7 +84,7 @@ async function persistTurnResult(
     } catch (err) {
       console.warn(
         `[turn-executor] saveRuntimeOutput failed for ${rr.runtimeId}:`,
-        err instanceof Error ? err.message : String(err),
+        err,
       );
     }
   }
diff --git a/packages/runtime/tests/scene-stage-integration.test.ts b/packages/runtime/tests/scene-stage-integration.test.ts
index cdc470c1..02b2a383 100644
--- a/packages/runtime/tests/scene-stage-integration.test.ts
+++ b/packages/runtime/tests/scene-stage-integration.test.ts
@@ -4,12 +4,12 @@
  * same-turn event fan-out (`runEventChain`) triggers the real scene-stage
  * resolver, and its `plugin.data` proposal commits `stage/current`.
  *
- * `@covel/plugin-test-utils`'s `createTestHarness` was tried first (per
- * docs/guide/plugin-testing.md) and found insufficient for this scenario:
- * it only discovers runtimes from a filesystem `pluginsDir` with no way to
+ * `@covel/plugin-test-utils`'s `createTestHarness` (since removed from the
+ * package) was tried first and found insufficient for this scenario:
+ * it only discovered runtimes from a filesystem `pluginsDir` with no way to
  * inject a synthetic MockLLM-driven "emitter" runtime alongside the real
- * scene-stage plugin, and it never calls `processRuntimeResult`, so a turn
- * it runs never lands anything in the store. Falls back to the
+ * scene-stage plugin, and it never called `processRuntimeResult`, so a turn
+ * it ran never landed anything in the store. Uses the
  * turn-executor direct-construction pattern from
  * emit-event-integration.test.ts, loading the real scene-stage handler via
  * `@covel/plugin-loader` instead of a hand-written stand-in.
diff --git a/packages/settings/src/backends/json-file.ts b/packages/settings/src/backends/json-file.ts
index 742124fb..8dcfbf43 100644
--- a/packages/settings/src/backends/json-file.ts
+++ b/packages/settings/src/backends/json-file.ts
@@ -68,11 +68,14 @@ export function createJsonFileBackend(
         await ipc.invoke("covel:settings:save", entries);
         return;
       }
-      await fetchImpl(endpoint, {
+      const res = await fetchImpl(endpoint, {
         method: "PUT",
         headers: { "Content-Type": "application/json", ...authHeaders() },
         body: JSON.stringify({ entries }),
       });
+      if (!res.ok) {
+        throw new Error(`[settings] save failed: HTTP ${res.status}`);
+      }
     },
     async loadSecrets(): Promise<Record<string, string>> {
       const ipc = getIpc();
@@ -100,11 +103,14 @@ export function createJsonFileBackend(
         await ipc.invoke("covel:keys:save", keys);
         return;
       }
-      await fetchImpl(secretsEndpoint, {
+      const res = await fetchImpl(secretsEndpoint, {
         method: "PUT",
         headers: { "Content-Type": "application/json", ...authHeaders() },
         body: JSON.stringify(keys),
       });
+      if (!res.ok) {
+        throw new Error(`[settings] secrets save failed: HTTP ${res.status}`);
+      }
     },
   };
 }
diff --git a/packages/shared/src/env/groups/server.ts b/packages/shared/src/env/groups/server.ts
index e0256c1c..dc19e254 100644
--- a/packages/shared/src/env/groups/server.ts
+++ b/packages/shared/src/env/groups/server.ts
@@ -117,7 +117,7 @@ export const SERVER_ENV_VARS = [
     status: "active",
     defaultValue: "604800000",
     description:
-      "TTL (ms) after which an UNRESOLVED suspension is swept by the startup + opportunistic cleanup (TODO S4-T4.c). Default 604800000 (7 days). Set to 0 (or negative) to disable sweeping. Claimed (in-flight) and successfully-resolved suspensions are never swept.",
+      "TTL (ms) after which an UNRESOLVED suspension is swept by the startup + opportunistic cleanup (spec S4-T4.c). Default 604800000 (7 days). Set to 0 (or negative) to disable sweeping. Claimed (in-flight) and successfully-resolved suspensions are never swept.",
   },
   {
     name: "APP_PORT",
diff --git a/packages/store/src/memory/vector-methods.ts b/packages/store/src/memory/vector-methods.ts
index 1138ba3d..563d9032 100644
--- a/packages/store/src/memory/vector-methods.ts
+++ b/packages/store/src/memory/vector-methods.ts
@@ -22,24 +22,6 @@ function squaredL2(a: Float32Array, b: Float32Array): number {
   return sum;
 }
 
-export function cloneVectorRows(
-  src: Map<string, MemoryVectorRow>,
-): Map<string, MemoryVectorRow> {
-  const out = new Map<string, MemoryVectorRow>();
-  for (const [key, row] of src) {
-    out.set(key, {
-      sessionId: row.sessionId,
-      pluginId: row.pluginId,
-      namespace: row.namespace,
-      key: row.key,
-      dim: row.dim,
-      embedding: new Float32Array(row.embedding),
-      payload: row.payload,
-    });
-  }
-  return out;
-}
-
 export function createVectorMethods(state: MemoryState): MemoryStoreMethods {
   return {
     async upsertVector(input: UpsertVectorInput) {
diff --git a/packages/store/src/types.ts b/packages/store/src/types.ts
index 1c87f0b7..79c31132 100644
--- a/packages/store/src/types.ts
+++ b/packages/store/src/types.ts
@@ -478,7 +478,7 @@ export interface SuspensionStore {
    */
   claimSuspension(id: string): Promise<boolean>;
   /**
-   * Global maintenance sweep of stale suspensions (TODO S4-T4.c).
+   * Global maintenance sweep of stale suspensions (spec S4-T4.c).
    *
    * Deletes ONLY records that are still unresolved (`resolvedAt` unset) AND
    * whose `createdAt` is strictly older than `olderThanIso`. Claimed

From f07bedeca3e79b4012403eb1da64c764142d0fde Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 14:26:02 +0800
Subject: [PATCH 07/10] perf(store,runtime): bound per-turn history reads;
 derive IDB cascade from registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two verified high-impact items from the six-dimension audit:

1. Bounded per-turn message reads. loadTurnSessionState no longer
   full-reads listTurnMessages every turn (the log only ever grows —
   compaction tags rows but never deletes). New DataStore surface:
   - listUncompactedTurnMessages(sessionId): the raw suffix the
     compactor and prompt builder actually operate on (the compacted
     prefix is represented by session summaries)
   - getTurnMessageStats(sessionId): grouped-count aggregate for
     turnNumber / per-runtime trigger counts (GROUP BY on SQL backends
     via a new SelectOpts.groupBy; shared JS fallback for memory/idb)
   buildMessageHistoryWithSummaries now emits summaries not referenced
   by any history row up front (chronological), so uncompacted-suffix
   histories keep their compacted context; maybeCompact counts ALL
   session summaries for its token estimate for the same reason.
   Full-history callers are byte-identical in both cases.

2. IDB deleteSession cascade is now derived from SESSION_SCOPED_TABLES
   (new explicit idbStore field), matching the SQL/Memory backends —
   a newly registered session table can no longer silently leak rows
   on the browser backend. Index-vs-filter deletion is auto-detected
   from the store's own indexNames; the IDB-only
   state_snapshot_metadata sidecar stays as one explicit residual.

Validation: store contract suite extended for both new methods and run
against memory/sqlite/idb plus a real PostgreSQL container (152/152 —
covers PG's string count(*) normalisation); runtime read-dedup test
updated to pin the new two-read pattern; full turbo lint 21/21.
---
 packages/context/src/compactor.ts             |  13 +-
 packages/context/src/message-insertion.ts     |  35 +++--
 .../runtime/src/turn-executor/scheduling.ts   |   8 ++
 .../src/turn-executor/session-state.ts        |  40 +++---
 .../tests/session-state-read-dedup.test.ts    |  89 ++++++++++---
 packages/store/src/common/sql-runner.ts       |   5 +
 .../src/common/sql-session-journal-records.ts |  51 +++++++-
 .../store/src/common/turn-message-stats.ts    |  23 ++++
 .../contract/suites/runtime-record-suites.ts  | 121 +++++++++++++++++
 packages/store/src/index.ts                   |   1 +
 .../store/src/indexeddb/idb-runtime-store.ts  |  22 ++++
 .../store/src/indexeddb/idb-session-store.ts  |  79 +++++-------
 packages/store/src/memory/runtime-methods.ts  |  13 ++
 packages/store/src/postgres/pg-sql-runner.ts  |   3 +
 .../store/src/sqlite/sqlite-sql-runner.ts     |   3 +
 packages/store/src/table-registry.ts          | 122 +++++++++++++++---
 packages/store/src/types.ts                   |  30 +++++
 .../tests/table-registry-consistency.test.ts  |  14 ++
 18 files changed, 560 insertions(+), 112 deletions(-)
 create mode 100644 packages/store/src/common/turn-message-stats.ts

diff --git a/packages/context/src/compactor.ts b/packages/context/src/compactor.ts
index 559e2361..420a455c 100644
--- a/packages/context/src/compactor.ts
+++ b/packages/context/src/compactor.ts
@@ -238,25 +238,26 @@ export async function maybeCompact(
   //    message-insertion.ts), so counting their raw content would permanently
   //    inflate the estimate and re-trigger compaction after the first round.
   const systemTokens = deps.estimator(systemPrompt);
-  const compactedSummaryIds = new Set<string>();
   let lastCompactedIndex = -1;
   let messageTokens = 0;
   for (let i = 0; i < messages.length; i++) {
     const m = messages[i]!;
     if (m.compactedAtTurnId != null) {
-      compactedSummaryIds.add(m.compactedAtTurnId);
       lastCompactedIndex = i;
     } else {
       messageTokens += deps.estimator(m.content);
     }
   }
+  // Count ALL session summaries, not just those referenced by `messages`:
+  // callers now pass the uncompacted suffix (listUncompactedTurnMessages),
+  // where compacted rows — and thus their summary references — are absent.
+  // Every summary is part of the effective prompt view either way (see
+  // message-insertion.ts), so a full history yields the identical total.
   let summaryTokens = 0;
-  if (compactedSummaryIds.size > 0 && deps.store.listSessionSummaries) {
+  if (deps.store.listSessionSummaries) {
     const summaries = await deps.store.listSessionSummaries(sessionId);
     for (const s of summaries) {
-      if (compactedSummaryIds.has(s.id)) {
-        summaryTokens += deps.estimator(s.content);
-      }
+      summaryTokens += deps.estimator(s.content);
     }
   }
   const totalTokens = systemTokens + messageTokens + summaryTokens;
diff --git a/packages/context/src/message-insertion.ts b/packages/context/src/message-insertion.ts
index 57d779ef..10d4e4c3 100644
--- a/packages/context/src/message-insertion.ts
+++ b/packages/context/src/message-insertion.ts
@@ -39,6 +39,13 @@ export function toLLMMessage(msg: MessageHistoryRecord): LLMMessage {
  * Segment 7 — history with optional compaction substitution. When a message
  * carries `compactedAtTurnId`, the first such message is replaced by its
  * summary and subsequent compacted messages are dropped.
+ *
+ * Histories read via `listUncompactedTurnMessages` contain no compacted rows
+ * at all, so summaries they reference would never be emitted by substitution.
+ * Because compaction always tags a contiguous PREFIX of the timeline, any
+ * summary not referenced by a row in `messageHistory` is emitted up front (in
+ * the given, chronological order) — for a full history this set is empty and
+ * the output is unchanged.
  */
 export function buildMessageHistoryWithSummaries(
   messageHistory: readonly MessageHistoryRecord[],
@@ -48,24 +55,36 @@ export function buildMessageHistoryWithSummaries(
     return messageHistory.map(toLLMMessage);
   }
 
+  const compactedIdOf = (msg: MessageHistoryRecord): string | undefined =>
+    (msg as MessageHistoryRecord & { compactedAtTurnId?: string })
+      .compactedAtTurnId;
+
+  const referencedIds = new Set<string>();
+  for (const msg of messageHistory) {
+    const compactedId = compactedIdOf(msg);
+    if (compactedId) referencedIds.add(compactedId);
+  }
+
+  const toSummaryMessage = (summary: SummaryRecord): LLMMessage => ({
+    role: "system",
+    content: `[Compacted history: sections=${JSON.stringify(summary.focusSections)}]\n\n${summary.content}`,
+  });
+
   const summaryById = new Map(summaries.map((s) => [s.id, s]));
   const emittedSummaryIds = new Set<string>();
-  const result: LLMMessage[] = [];
+  const result: LLMMessage[] = summaries
+    .filter((s) => !referencedIds.has(s.id))
+    .map(toSummaryMessage);
 
   for (const msg of messageHistory) {
-    const compactedId = (
-      msg as MessageHistoryRecord & { compactedAtTurnId?: string }
-    ).compactedAtTurnId;
+    const compactedId = compactedIdOf(msg);
 
     if (compactedId) {
       if (!emittedSummaryIds.has(compactedId)) {
         const summary = summaryById.get(compactedId);
         if (summary) {
           emittedSummaryIds.add(compactedId);
-          result.push({
-            role: "system",
-            content: `[Compacted history: sections=${JSON.stringify(summary.focusSections)}]\n\n${summary.content}`,
-          });
+          result.push(toSummaryMessage(summary));
         }
       }
       continue;
diff --git a/packages/runtime/src/turn-executor/scheduling.ts b/packages/runtime/src/turn-executor/scheduling.ts
index d554639b..d6bf018f 100644
--- a/packages/runtime/src/turn-executor/scheduling.ts
+++ b/packages/runtime/src/turn-executor/scheduling.ts
@@ -117,6 +117,14 @@ export function scheduleMainLoopFollowups(args: {
   return dag.error ? scheduleByPriority(mainLoop, args.turnNumber) : dag.groups;
 }
 
+/**
+ * `messageHistory` is the uncompacted suffix of the session timeline. If a
+ * runtime's last trigger was compacted away, the backward scan misses it and
+ * returns the not-found sentinel (999) — erring toward triggering, which is
+ * safe: the compactor's protect window keeps recent turns raw, so any message
+ * old enough to be compacted is at least a protect-window's worth of player
+ * turns in the past.
+ */
 function countPlayerMessagesSinceRuntime(
   messageHistory: readonly TurnMessageRecord[],
   runtimeId: string,
diff --git a/packages/runtime/src/turn-executor/session-state.ts b/packages/runtime/src/turn-executor/session-state.ts
index 6747277f..b17b6046 100644
--- a/packages/runtime/src/turn-executor/session-state.ts
+++ b/packages/runtime/src/turn-executor/session-state.ts
@@ -57,15 +57,23 @@ export async function loadTurnSessionState(args: {
     await deps.memorySystem.updater.awaitPending(input.sessionId);
   }
 
+  // Bounded per-turn reads: counts come from a store-side aggregate over the
+  // FULL log, while the in-memory history is only the uncompacted suffix —
+  // the compacted prefix is represented by session summaries at prompt-build
+  // time, so a long session never re-loads its whole history every turn.
   let messageHistory: readonly TurnMessageRecord[] = [];
+  let turnNumber = 0;
+  let runtimeTriggerCounts: ReadonlyMap<string, number> = new Map();
   if (deps.store) {
-    messageHistory = await deps.store.listTurnMessages(input.sessionId);
+    const [uncompacted, stats] = await Promise.all([
+      deps.store.listUncompactedTurnMessages(input.sessionId),
+      deps.store.getTurnMessageStats(input.sessionId),
+    ]);
+    messageHistory = uncompacted;
+    turnNumber = stats.playerMessageCount;
+    runtimeTriggerCounts = new Map(Object.entries(stats.runtimeMessageCounts));
   }
 
-  const turnNumber = messageHistory.filter(
-    (m) => m.sourceType === "player",
-  ).length;
-
   if (deps.store && shouldAppendPlayerMessage) {
     const playerMessage: TurnMessageRecord = {
       id: crypto.randomUUID(),
@@ -113,11 +121,14 @@ export async function loadTurnSessionState(args: {
         compacted: result.compacted,
         ...(result.summaryId ? { summaryId: result.summaryId } : {}),
       });
-      messageHistory = await deps.store.listTurnMessages(input.sessionId);
+      messageHistory = await deps.store.listUncompactedTurnMessages(
+        input.sessionId,
+      );
     }
   }
 
-  const runtimeTriggerCounts = buildRuntimeTriggerCounts(messageHistory);
+  // triggerCounts already came from getTurnMessageStats above; the player
+  // message appended this turn is a "player" row, so no runtime count moved.
   let sessionStatus: "active" | "paused" | "ended" = "active";
   let preGameCompleted: readonly string[] = [];
   let sessionCharacters: TurnSessionCharacter[] = [];
@@ -212,18 +223,3 @@ export function getPreGameRuntimeState(
     ),
   };
 }
-
-export function buildRuntimeTriggerCounts(
-  messageHistory: readonly TurnMessageRecord[],
-): ReadonlyMap<string, number> {
-  const counts = new Map<string, number>();
-  for (const msg of messageHistory) {
-    if (msg.sourceType === "runtime" && msg.sourceRuntimeId) {
-      counts.set(
-        msg.sourceRuntimeId,
-        (counts.get(msg.sourceRuntimeId) ?? 0) + 1,
-      );
-    }
-  }
-  return counts;
-}
diff --git a/packages/runtime/tests/session-state-read-dedup.test.ts b/packages/runtime/tests/session-state-read-dedup.test.ts
index 7c4889a5..1efd076c 100644
--- a/packages/runtime/tests/session-state-read-dedup.test.ts
+++ b/packages/runtime/tests/session-state-read-dedup.test.ts
@@ -5,11 +5,13 @@ import { loadTurnSessionState } from "../src/turn-executor/session-state.js";
 import type { TurnExecutorDeps } from "../src/turn-executor/turn-executor-types.js";
 
 /**
- * Audit 2026-07-11 R-13: loadTurnSessionState used to full-read
- * listTurnMessages twice per turn (before and after appending the player
- * message). The appended record is now concatenated locally; these tests pin
- * the single read and that the returned history still includes the player
- * message.
+ * Audit 2026-07-11 R-13 + 2026-07-17 bounded-history follow-up:
+ * loadTurnSessionState used to full-read listTurnMessages twice per turn.
+ * Today the per-turn reads are (a) one listUncompactedTurnMessages for the
+ * raw suffix, (b) one getTurnMessageStats aggregate for turnNumber / trigger
+ * counts — never a full listTurnMessages. The appended player record is
+ * concatenated locally; these tests pin the read pattern and that the
+ * returned history still includes the player message.
  */
 
 async function makeStore(): Promise<DataStore> {
@@ -41,26 +43,35 @@ async function makeStore(): Promise<DataStore> {
 
 function countingStore(store: DataStore): {
   store: DataStore;
-  counts: () => number;
+  counts: () => Record<string, number>;
 } {
-  let listTurnMessagesCalls = 0;
+  const calls: Record<string, number> = {};
+  const counted = new Set([
+    "listTurnMessages",
+    "listUncompactedTurnMessages",
+    "getTurnMessageStats",
+  ]);
   const wrapped = new Proxy(store, {
     get(target, prop, receiver) {
       const value = Reflect.get(target, prop, receiver);
-      if (prop === "listTurnMessages" && typeof value === "function") {
+      if (
+        typeof prop === "string" &&
+        counted.has(prop) &&
+        typeof value === "function"
+      ) {
         return (...args: unknown[]) => {
-          listTurnMessagesCalls += 1;
+          calls[prop] = (calls[prop] ?? 0) + 1;
           return (value as (...a: unknown[]) => unknown).apply(target, args);
         };
       }
       return typeof value === "function" ? value.bind(target) : value;
     },
   });
-  return { store: wrapped, counts: () => listTurnMessagesCalls };
+  return { store: wrapped, counts: () => calls };
 }
 
 describe("loadTurnSessionState read dedup (audit R-13)", () => {
-  it("reads listTurnMessages once when appending the player message (no compactor)", async () => {
+  it("reads the uncompacted suffix once + one stats aggregate, never the full log", async () => {
     const { store, counts } = countingStore(await makeStore());
     const deps = { store } as unknown as TurnExecutorDeps;
 
@@ -74,7 +85,10 @@ describe("loadTurnSessionState read dedup (audit R-13)", () => {
       shouldAppendPlayerMessage: true,
     });
 
-    expect(counts()).toBe(1);
+    expect(counts()).toEqual({
+      listUncompactedTurnMessages: 1,
+      getTurnMessageStats: 1,
+    });
     // History includes both the pre-existing message and the appended one.
     expect(state.messageHistory).toHaveLength(2);
     const appended = state.messageHistory[1]!;
@@ -87,7 +101,7 @@ describe("loadTurnSessionState read dedup (audit R-13)", () => {
     expect(state.turnNumber).toBe(1);
   });
 
-  it("re-reads after compaction actually runs", async () => {
+  it("re-reads the uncompacted suffix after compaction actually runs", async () => {
     const base = await makeStore();
     const { store, counts } = countingStore(base);
     const deps = {
@@ -107,8 +121,51 @@ describe("loadTurnSessionState read dedup (audit R-13)", () => {
       shouldAppendPlayerMessage: true,
     });
 
-    // One initial read + the post-compaction reload; the pre-append second
-    // full read is gone.
-    expect(counts()).toBe(2);
+    // One initial read + the post-compaction reload; the stats aggregate
+    // still runs exactly once and the full log is never read.
+    expect(counts()).toEqual({
+      listUncompactedTurnMessages: 2,
+      getTurnMessageStats: 1,
+    });
+  });
+
+  it("excludes compacted rows from the loaded history while counts still cover the full log", async () => {
+    const base = await makeStore();
+    const now = new Date().toISOString();
+    await base.appendTurnMessage({
+      id: "tm-runtime-old",
+      sessionId: "sess-dedup",
+      turnId: "turn-0",
+      sourceType: "runtime",
+      sourceRuntimeId: "demo/narrator",
+      role: "assistant",
+      content: "old narrative",
+      order: 1,
+      createdAt: now,
+    });
+    await base.tagTurnMessagesCompacted(
+      "sess-dedup",
+      ["tm-0", "tm-runtime-old"],
+      "summary-1",
+    );
+
+    const state = await loadTurnSessionState({
+      input: {
+        sessionId: "sess-dedup",
+        turnId: "turn-1",
+        playerMessage: "hello",
+      },
+      deps: { store: base } as unknown as TurnExecutorDeps,
+      shouldAppendPlayerMessage: true,
+    });
+
+    // Compacted rows are absent from the in-memory history…
+    expect(state.messageHistory.map((m) => m.id)).toEqual(
+      state.messageHistory.map((m) => m.id).filter((id) => id !== "tm-0"),
+    );
+    expect(state.messageHistory).toHaveLength(1);
+    // …but turnNumber / trigger counts still see the whole log.
+    expect(state.turnNumber).toBe(1);
+    expect(state.runtimeTriggerCounts.get("demo/narrator")).toBe(1);
   });
 });
diff --git a/packages/store/src/common/sql-runner.ts b/packages/store/src/common/sql-runner.ts
index 8d553ab1..06623a4b 100644
--- a/packages/store/src/common/sql-runner.ts
+++ b/packages/store/src/common/sql-runner.ts
@@ -54,6 +54,11 @@ export interface SelectOpts {
    * a table without transferring a large JSON column (snapshot metadata).
    */
   readonly columns?: Record<string, Column | SQL>;
+  /**
+   * GROUP BY clause — pair with an aggregate expression in `columns` (e.g.
+   * `sql\`count(*)\``) to resolve counts store-side instead of streaming rows.
+   */
+  readonly groupBy?: readonly (Column | SQL)[];
 }
 
 /** One row of an atomic batch upsert: insert payload + optional conflict. */
diff --git a/packages/store/src/common/sql-session-journal-records.ts b/packages/store/src/common/sql-session-journal-records.ts
index 560a71aa..c356e538 100644
--- a/packages/store/src/common/sql-session-journal-records.ts
+++ b/packages/store/src/common/sql-session-journal-records.ts
@@ -20,7 +20,7 @@
  *    return unified across both backends.
  */
 
-import { and, asc, desc, eq, inArray } from "drizzle-orm";
+import { and, asc, desc, eq, inArray, isNull, sql } from "drizzle-orm";
 import type { Column, Table } from "drizzle-orm";
 
 import { cursorPageOrder, cursorPageWhere } from "./cursor.js";
@@ -47,6 +47,7 @@ import type {
   SessionSummaryRecord,
   TraceEventRecord,
   TurnMessageRecord,
+  TurnMessageStats,
 } from "../types.js";
 
 type TraceEventsTable = Table & {
@@ -58,6 +59,9 @@ type TurnMessagesTable = Table & {
   sessionId: Column;
   createdAt: Column;
   id: Column;
+  sourceType: Column;
+  sourceRuntimeId: Column;
+  compactedAtTurnId: Column;
 };
 type PlayerInputsTable = Table & { sessionId: Column; formId: Column };
 type SessionSummariesTable = Table & { sessionId: Column };
@@ -89,6 +93,8 @@ export type SqlSessionJournalRecords = Pick<
   | "listTraceEventsPage"
   | "appendTurnMessage"
   | "listTurnMessages"
+  | "listUncompactedTurnMessages"
+  | "getTurnMessageStats"
   | "listRecentTurnMessages"
   | "tagTurnMessagesCompacted"
   | "savePlayerInput"
@@ -152,6 +158,49 @@ export function createSqlSessionJournalRecords(
       return rows.map((row) => toTurnMessageRecord(row, json));
     },
 
+    async listUncompactedTurnMessages(
+      sessionId: string,
+    ): Promise<TurnMessageRecord[]> {
+      const rows = await runner.select<TurnMessageRow>(turnMessages, {
+        where: and(
+          eq(turnMessages.sessionId, sessionId),
+          isNull(turnMessages.compactedAtTurnId),
+        ),
+        orderBy: [asc(turnMessages.createdAt)],
+      });
+      return rows.map((row) => toTurnMessageRecord(row, json));
+    },
+
+    async getTurnMessageStats(sessionId: string): Promise<TurnMessageStats> {
+      // Single grouped count over (sourceType, sourceRuntimeId); COUNT(*)
+      // arrives as number on SQLite and string on PG, so normalise via Number.
+      const rows = await runner.select<{
+        sourceType: string;
+        sourceRuntimeId: string | null;
+        count: number | string;
+      }>(turnMessages, {
+        columns: {
+          sourceType: turnMessages.sourceType,
+          sourceRuntimeId: turnMessages.sourceRuntimeId,
+          count: sql`count(*)`,
+        },
+        where: eq(turnMessages.sessionId, sessionId),
+        groupBy: [turnMessages.sourceType, turnMessages.sourceRuntimeId],
+      });
+      let playerMessageCount = 0;
+      const runtimeMessageCounts: Record<string, number> = {};
+      for (const row of rows) {
+        const count = Number(row.count);
+        if (row.sourceType === "player") {
+          playerMessageCount += count;
+        } else if (row.sourceType === "runtime" && row.sourceRuntimeId) {
+          runtimeMessageCounts[row.sourceRuntimeId] =
+            (runtimeMessageCounts[row.sourceRuntimeId] ?? 0) + count;
+        }
+      }
+      return { playerMessageCount, runtimeMessageCounts };
+    },
+
     async listRecentTurnMessages(
       sessionId: string,
       limit: number,
diff --git a/packages/store/src/common/turn-message-stats.ts b/packages/store/src/common/turn-message-stats.ts
new file mode 100644
index 00000000..e1e7642e
--- /dev/null
+++ b/packages/store/src/common/turn-message-stats.ts
@@ -0,0 +1,23 @@
+/**
+ * In-memory fallback for {@link TurnMessageStats}, shared by the Memory and
+ * IndexedDB backends (the SQL backends resolve the same aggregate as a grouped
+ * COUNT query in `sql-session-journal-records.ts`).
+ */
+
+import type { TurnMessageRecord, TurnMessageStats } from "../types.js";
+
+export function computeTurnMessageStats(
+  records: readonly TurnMessageRecord[],
+): TurnMessageStats {
+  let playerMessageCount = 0;
+  const runtimeMessageCounts: Record<string, number> = {};
+  for (const record of records) {
+    if (record.sourceType === "player") {
+      playerMessageCount += 1;
+    } else if (record.sourceType === "runtime" && record.sourceRuntimeId) {
+      runtimeMessageCounts[record.sourceRuntimeId] =
+        (runtimeMessageCounts[record.sourceRuntimeId] ?? 0) + 1;
+    }
+  }
+  return { playerMessageCount, runtimeMessageCounts };
+}
diff --git a/packages/store/src/contract/suites/runtime-record-suites.ts b/packages/store/src/contract/suites/runtime-record-suites.ts
index 0fa25418..09520b36 100644
--- a/packages/store/src/contract/suites/runtime-record-suites.ts
+++ b/packages/store/src/contract/suites/runtime-record-suites.ts
@@ -423,6 +423,127 @@ export function registerRuntimeRecordStoreSuites(
       expect(list[0].compactedAtTurnId).toBe("summary-preexisting");
     });
 
+    it("listUncompactedTurnMessages returns only the raw suffix, oldest-first", async () => {
+      const compacted1 = makeTurnMessage({
+        sessionId: "sess-unc",
+        createdAt: ts(10),
+        compactedAtTurnId: "summary-1",
+      });
+      const compacted2 = makeTurnMessage({
+        sessionId: "sess-unc",
+        createdAt: ts(20),
+        compactedAtTurnId: "summary-1",
+      });
+      const raw1 = makeTurnMessage({
+        sessionId: "sess-unc",
+        createdAt: ts(40),
+      });
+      const raw2 = makeTurnMessage({
+        sessionId: "sess-unc",
+        createdAt: ts(30),
+      });
+      const otherSession = makeTurnMessage({
+        sessionId: "sess-other",
+        createdAt: ts(50),
+      });
+      await store.appendTurnMessage(compacted1);
+      await store.appendTurnMessage(compacted2);
+      await store.appendTurnMessage(raw1);
+      await store.appendTurnMessage(raw2);
+      await store.appendTurnMessage(otherSession);
+
+      const list = await store.listUncompactedTurnMessages("sess-unc");
+      expect(list.map((m) => m.id)).toEqual([raw2.id, raw1.id]);
+    });
+
+    it("listUncompactedTurnMessages reflects tagTurnMessagesCompacted", async () => {
+      const m1 = makeTurnMessage({
+        sessionId: "sess-unc-tag",
+        createdAt: ts(10),
+      });
+      const m2 = makeTurnMessage({
+        sessionId: "sess-unc-tag",
+        createdAt: ts(20),
+      });
+      await store.appendTurnMessage(m1);
+      await store.appendTurnMessage(m2);
+      await store.tagTurnMessagesCompacted(
+        "sess-unc-tag",
+        [m1.id],
+        "summary-x",
+      );
+
+      const list = await store.listUncompactedTurnMessages("sess-unc-tag");
+      expect(list.map((m) => m.id)).toEqual([m2.id]);
+    });
+
+    it("getTurnMessageStats aggregates player and per-runtime counts over the full log", async () => {
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-stats",
+          sourceType: "player",
+          role: "user",
+          createdAt: ts(10),
+        }),
+      );
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-stats",
+          sourceType: "player",
+          role: "user",
+          createdAt: ts(20),
+          // Compacted rows still count toward the aggregates.
+          compactedAtTurnId: "summary-1",
+        }),
+      );
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-stats",
+          sourceRuntimeId: "demo/narrator",
+          createdAt: ts(30),
+        }),
+      );
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-stats",
+          sourceRuntimeId: "demo/narrator",
+          createdAt: ts(40),
+        }),
+      );
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-stats",
+          sourceRuntimeId: "demo/codex",
+          createdAt: ts(50),
+        }),
+      );
+      // Runtime rows without a sourceRuntimeId and other sessions are ignored.
+      await store.appendTurnMessage(
+        makeTurnMessage({ sessionId: "sess-stats", createdAt: ts(60) }),
+      );
+      await store.appendTurnMessage(
+        makeTurnMessage({
+          sessionId: "sess-other",
+          sourceType: "player",
+          role: "user",
+          createdAt: ts(70),
+        }),
+      );
+
+      const stats = await store.getTurnMessageStats("sess-stats");
+      expect(stats.playerMessageCount).toBe(2);
+      expect(stats.runtimeMessageCounts).toEqual({
+        "demo/narrator": 2,
+        "demo/codex": 1,
+      });
+    });
+
+    it("getTurnMessageStats returns zeroed stats for an empty session", async () => {
+      const stats = await store.getTurnMessageStats("sess-none");
+      expect(stats.playerMessageCount).toBe(0);
+      expect(stats.runtimeMessageCounts).toEqual({});
+    });
+
     it("should support pagination with limit and offset", async () => {
       const m1 = makeTurnMessage({ sessionId: "sess-pg", createdAt: ts(10) });
       const m2 = makeTurnMessage({ sessionId: "sess-pg", createdAt: ts(20) });
diff --git a/packages/store/src/index.ts b/packages/store/src/index.ts
index f5ec2469..cbffd92c 100644
--- a/packages/store/src/index.ts
+++ b/packages/store/src/index.ts
@@ -79,6 +79,7 @@ export type {
   RuntimeOutputFilters,
   InteractionRecordFilters,
   TurnMessageRecord,
+  TurnMessageStats,
   PlayerInputRecord,
   WorkingMemoryRecord,
   WorldDataImportLedgerRecord,
diff --git a/packages/store/src/indexeddb/idb-runtime-store.ts b/packages/store/src/indexeddb/idb-runtime-store.ts
index dbf6dcf8..65c02bbc 100644
--- a/packages/store/src/indexeddb/idb-runtime-store.ts
+++ b/packages/store/src/indexeddb/idb-runtime-store.ts
@@ -15,9 +15,11 @@ import type {
   ToolCallRecordRow,
   TraceEventRecord,
   TurnMessageRecord,
+  TurnMessageStats,
   TurnResultRecord,
 } from "../types.js";
 import { applyCursorPage, sortByCursorAsc } from "../common/pagination.js";
+import { computeTurnMessageStats } from "../common/turn-message-stats.js";
 import type { IdbStoreContext, IdbStoreSlice } from "./idb-context.js";
 import {
   filterInteractionRecords,
@@ -305,6 +307,26 @@ export function createIdbRuntimeStore(ctx: IdbStoreContext): IdbStoreSlice {
       return paginateRows(sortByCreatedAtAsc(all), pagination);
     },
 
+    async listUncompactedTurnMessages(
+      sessionId: string,
+    ): Promise<TurnMessageRecord[]> {
+      const all = await listBySession<TurnMessageRecord>(
+        db,
+        "turnMessages",
+        sessionId,
+      );
+      return sortByCreatedAtAsc(all.filter((r) => r.compactedAtTurnId == null));
+    },
+
+    async getTurnMessageStats(sessionId: string): Promise<TurnMessageStats> {
+      const all = await listBySession<TurnMessageRecord>(
+        db,
+        "turnMessages",
+        sessionId,
+      );
+      return computeTurnMessageStats(all);
+    },
+
     async listRecentTurnMessages(
       sessionId: string,
       limit: number,
diff --git a/packages/store/src/indexeddb/idb-session-store.ts b/packages/store/src/indexeddb/idb-session-store.ts
index bd63eb14..911ecb53 100644
--- a/packages/store/src/indexeddb/idb-session-store.ts
+++ b/packages/store/src/indexeddb/idb-session-store.ts
@@ -1,3 +1,4 @@
+import { SESSION_SCOPED_TABLES } from "../table-registry.js";
 import {
   mergeSessionPatch,
   normalizeSessionRecord,
@@ -10,35 +11,38 @@ import type { IdbStoreContext, IdbStoreSlice } from "./idb-context.js";
 export function createIdbSessionStore(ctx: IdbStoreContext): IdbStoreSlice {
   const { db, mutations } = ctx;
 
-  async function cascadeByIndex(
+  /**
+   * Delete every row of `storeName` owned by `sessionId`. Uses the store's
+   * `sessionId` index when it has one; otherwise falls back to a full scan
+   * filtered on the `sessionId` property (composite-index stores such as
+   * `runtimeResults` and `plugin_data` have no standalone `sessionId` index).
+   */
+  async function cascadeSession(
     storeName: IdbStoreName,
     sessionId: string,
   ): Promise<void> {
-    const rows = (await db.getAllFromIndex(
-      storeName,
-      "sessionId",
-      sessionId,
-    )) as Array<{ id: string }>;
+    const hasSessionIdIndex = db
+      .transaction(storeName)
+      .store.indexNames.contains("sessionId");
+    const rows = hasSessionIdIndex
+      ? ((await db.getAllFromIndex(
+          storeName,
+          "sessionId",
+          sessionId,
+        )) as Array<{
+          id: string;
+        }>)
+      : (
+          (await db.getAll(storeName)) as Array<{
+            id: string;
+            sessionId: string;
+          }>
+        ).filter((row) => row.sessionId === sessionId);
     for (const row of rows) {
       await mutations.deleteAndTrack(storeName, row.id);
     }
   }
 
-  async function cascadeByFilter(
-    storeName: IdbStoreName,
-    sessionId: string,
-  ): Promise<void> {
-    const all = (await db.getAll(storeName)) as Array<{
-      id: string;
-      sessionId: string;
-    }>;
-    for (const row of all) {
-      if (row.sessionId === sessionId) {
-        await mutations.deleteAndTrack(storeName, row.id);
-      }
-    }
-  }
-
   return {
     async createSession(session: SessionRecord): Promise<void> {
       await mutations.putAndTrack(
@@ -66,29 +70,16 @@ export function createIdbSessionStore(ctx: IdbStoreContext): IdbStoreSlice {
     },
 
     async deleteSession(id: string): Promise<void> {
-      await cascadeByIndex("turnResults", id);
-      await cascadeByFilter("runtimeResults", id);
-      await cascadeByIndex("toolCalls", id);
-      await cascadeByIndex("stateSchemas", id);
-      await cascadeByIndex("stateEntries", id);
-      await cascadeByIndex("stateChanges", id);
-      await cascadeByIndex("events", id);
-      await cascadeByIndex("approvals", id);
-      await cascadeByIndex("messages", id);
-      await cascadeByIndex("characters", id);
-      await cascadeByIndex("traceEvents", id);
-      await cascadeByIndex("turnMessages", id);
-      await cascadeByIndex("playerInputs", id);
-      await cascadeByIndex("working_memory", id);
-      await cascadeByIndex("sessionSummaries", id);
-      await cascadeByIndex("suspensions", id);
-      await cascadeByIndex("state_snapshots", id);
-      await cascadeByIndex("state_snapshot_metadata", id);
-      await cascadeByIndex("lorebook_entries", id);
-      await cascadeByIndex("runtime_outputs", id);
-      await cascadeByIndex("interaction_records", id);
-      await cascadeByFilter("plugin_data", id);
-      await cascadeByIndex("world_data_import_ledger", id);
+      // Cascade is derived from the registry — adding a session-scoped table
+      // there extends this delete automatically, matching the SQL/Memory
+      // backends and closing the historical IDB drift gap.
+      for (const { idbStore } of SESSION_SCOPED_TABLES) {
+        await cascadeSession(idbStore, id);
+      }
+      // `state_snapshot_metadata` is an IDB-only pagination sidecar (no SQL
+      // table, so it is intentionally absent from SESSION_SCOPED_TABLES);
+      // clean it explicitly.
+      await cascadeSession("state_snapshot_metadata", id);
       await mutations.deleteAndTrack("sessions", id);
     },
 
diff --git a/packages/store/src/memory/runtime-methods.ts b/packages/store/src/memory/runtime-methods.ts
index 97e65b2c..74e0c13b 100644
--- a/packages/store/src/memory/runtime-methods.ts
+++ b/packages/store/src/memory/runtime-methods.ts
@@ -4,6 +4,7 @@ import {
   sortByCursorAsc,
 } from "../common/pagination.js";
 import { stateEntryKey } from "../common/keys.js";
+import { computeTurnMessageStats } from "../common/turn-message-stats.js";
 import type { SessionSummaryRecord } from "../types.js";
 import type { MemoryState, MemoryStoreMethods } from "./memory-types.js";
 
@@ -244,6 +245,18 @@ export function createRuntimeMethods(state: MemoryState): MemoryStoreMethods {
       return applyPagination(filtered, pagination);
     },
 
+    async listUncompactedTurnMessages(sessionId) {
+      return state.turnMessages
+        .filter((r) => r.sessionId === sessionId && r.compactedAtTurnId == null)
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    },
+
+    async getTurnMessageStats(sessionId) {
+      return computeTurnMessageStats(
+        state.turnMessages.filter((r) => r.sessionId === sessionId),
+      );
+    },
+
     async listRecentTurnMessages(sessionId, limit) {
       if (limit <= 0) return [];
       const sorted = sortByCursorAsc(
diff --git a/packages/store/src/postgres/pg-sql-runner.ts b/packages/store/src/postgres/pg-sql-runner.ts
index c5ef72f1..cbf0fa00 100644
--- a/packages/store/src/postgres/pg-sql-runner.ts
+++ b/packages/store/src/postgres/pg-sql-runner.ts
@@ -44,6 +44,9 @@ export function createPgSqlRunner(getDb: () => PgDb): SqlRunner {
         .from(table as PgTable)
         .$dynamic();
       if (opts?.where) query = query.where(opts.where);
+      if (opts?.groupBy && opts.groupBy.length > 0) {
+        query = query.groupBy(...(opts.groupBy as SQL[]));
+      }
       if (opts?.orderBy && opts.orderBy.length > 0) {
         query = query.orderBy(...opts.orderBy);
       }
diff --git a/packages/store/src/sqlite/sqlite-sql-runner.ts b/packages/store/src/sqlite/sqlite-sql-runner.ts
index 5f8468a2..015e0fa9 100644
--- a/packages/store/src/sqlite/sqlite-sql-runner.ts
+++ b/packages/store/src/sqlite/sqlite-sql-runner.ts
@@ -51,6 +51,9 @@ export function createSqliteSqlRunner(db: SqliteDb): SqlRunner {
         .from(table as SQLiteTable)
         .$dynamic();
       if (opts?.where) query = query.where(opts.where);
+      if (opts?.groupBy && opts.groupBy.length > 0) {
+        query = query.groupBy(...(opts.groupBy as SQL[]));
+      }
       if (opts?.orderBy && opts.orderBy.length > 0) {
         query = query.orderBy(...opts.orderBy);
       }
diff --git a/packages/store/src/table-registry.ts b/packages/store/src/table-registry.ts
index b42c7121..89bd68f6 100644
--- a/packages/store/src/table-registry.ts
+++ b/packages/store/src/table-registry.ts
@@ -11,6 +11,7 @@
  *
  *   - PG cascade delete         → postgres/pg-session-cascade.ts
  *   - SQLite cascade delete      → sqlite/sqlite-session-cascade.ts
+ *   - IDB cascade delete         → indexeddb/idb-session-store.ts
  *   - MemoryStore cascade        → memory/session-methods.ts
  *   - MemoryStore tx snapshot    → memory/transaction-methods.ts
  *   - DROP list / ALL_TABLE_NAMES → postgres/pg-schema-ddl.ts
@@ -36,6 +37,7 @@
  */
 
 import type { MemoryState } from "./memory/memory-types.js";
+import type { IdbStoreName } from "./indexeddb/idb-db.js";
 
 /**
  * Keys of {@link MemoryState} that back a session-scoped collection — a `Map`
@@ -77,6 +79,14 @@ export interface SessionScopedTable {
   readonly memoryKey: SessionScopedMemoryKey;
   /** Whether the MemoryState collection is a `Map` or an array. */
   readonly memoryKind: MemoryCollectionKind;
+  /**
+   * Browser IDB object-store name. IDB names are historically inconsistent
+   * (some camelCase like `turnResults`, some snake_case like `plugin_data`) and
+   * match neither {@link table} nor {@link memoryKey} reliably, so the mapping
+   * is declared explicitly. The IDB cascade auto-picks index vs full-scan
+   * deletion by whether the store carries a `sessionId` index.
+   */
+  readonly idbStore: IdbStoreName;
 }
 
 /**
@@ -86,56 +96,138 @@ export interface SessionScopedTable {
  * and delete ordering.
  */
 export const SESSION_SCOPED_TABLES: readonly SessionScopedTable[] = [
-  { table: "turn_results", memoryKey: "turnResults", memoryKind: "array" },
+  {
+    table: "turn_results",
+    memoryKey: "turnResults",
+    memoryKind: "array",
+    idbStore: "turnResults",
+  },
   {
     table: "runtime_results",
     memoryKey: "runtimeResults",
     memoryKind: "array",
+    idbStore: "runtimeResults",
+  },
+  {
+    table: "tool_calls",
+    memoryKey: "toolCalls",
+    memoryKind: "array",
+    idbStore: "toolCalls",
+  },
+  {
+    table: "state_schemas",
+    memoryKey: "stateSchemas",
+    memoryKind: "array",
+    idbStore: "stateSchemas",
+  },
+  {
+    table: "state_entries",
+    memoryKey: "stateEntries",
+    memoryKind: "map",
+    idbStore: "stateEntries",
+  },
+  {
+    table: "state_changes",
+    memoryKey: "stateChanges",
+    memoryKind: "array",
+    idbStore: "stateChanges",
+  },
+  {
+    table: "events",
+    memoryKey: "events",
+    memoryKind: "array",
+    idbStore: "events",
+  },
+  {
+    table: "approvals",
+    memoryKey: "approvals",
+    memoryKind: "array",
+    idbStore: "approvals",
+  },
+  {
+    table: "messages",
+    memoryKey: "messages",
+    memoryKind: "array",
+    idbStore: "messages",
+  },
+  {
+    table: "characters",
+    memoryKey: "characters",
+    memoryKind: "map",
+    idbStore: "characters",
+  },
+  {
+    table: "plugin_data",
+    memoryKey: "pluginData",
+    memoryKind: "map",
+    idbStore: "plugin_data",
   },
-  { table: "tool_calls", memoryKey: "toolCalls", memoryKind: "array" },
-  { table: "state_schemas", memoryKey: "stateSchemas", memoryKind: "array" },
-  { table: "state_entries", memoryKey: "stateEntries", memoryKind: "map" },
-  { table: "state_changes", memoryKey: "stateChanges", memoryKind: "array" },
-  { table: "events", memoryKey: "events", memoryKind: "array" },
-  { table: "approvals", memoryKey: "approvals", memoryKind: "array" },
-  { table: "messages", memoryKey: "messages", memoryKind: "array" },
-  { table: "characters", memoryKey: "characters", memoryKind: "map" },
-  { table: "plugin_data", memoryKey: "pluginData", memoryKind: "map" },
   {
     table: "world_data_import_ledger",
     memoryKey: "worldDataImportLedger",
     memoryKind: "map",
+    idbStore: "world_data_import_ledger",
+  },
+  {
+    table: "trace_events",
+    memoryKey: "traceEvents",
+    memoryKind: "array",
+    idbStore: "traceEvents",
   },
-  { table: "trace_events", memoryKey: "traceEvents", memoryKind: "array" },
   {
     table: "runtime_outputs",
     memoryKey: "runtimeOutputs",
     memoryKind: "array",
+    idbStore: "runtime_outputs",
   },
   {
     table: "interaction_records",
     memoryKey: "interactionRecords",
     memoryKind: "array",
+    idbStore: "interaction_records",
+  },
+  {
+    table: "turn_messages",
+    memoryKey: "turnMessages",
+    memoryKind: "array",
+    idbStore: "turnMessages",
+  },
+  {
+    table: "player_inputs",
+    memoryKey: "playerInputs",
+    memoryKind: "array",
+    idbStore: "playerInputs",
   },
-  { table: "turn_messages", memoryKey: "turnMessages", memoryKind: "array" },
-  { table: "player_inputs", memoryKey: "playerInputs", memoryKind: "array" },
   {
     table: "working_memory",
     memoryKey: "workingMemoryEntries",
     memoryKind: "map",
+    idbStore: "working_memory",
   },
   {
     table: "lorebook_entries",
     memoryKey: "lorebookEntries",
     memoryKind: "map",
+    idbStore: "lorebook_entries",
   },
   {
     table: "session_summaries",
     memoryKey: "sessionSummaries",
     memoryKind: "array",
+    idbStore: "sessionSummaries",
+  },
+  {
+    table: "suspensions",
+    memoryKey: "suspensions",
+    memoryKind: "map",
+    idbStore: "suspensions",
+  },
+  {
+    table: "state_snapshots",
+    memoryKey: "snapshots",
+    memoryKind: "map",
+    idbStore: "state_snapshots",
   },
-  { table: "suspensions", memoryKey: "suspensions", memoryKind: "map" },
-  { table: "state_snapshots", memoryKey: "snapshots", memoryKind: "map" },
 ];
 
 /** SQL names of the session-scoped child tables, in cascade order. */
diff --git a/packages/store/src/types.ts b/packages/store/src/types.ts
index 79c31132..041300fe 100644
--- a/packages/store/src/types.ts
+++ b/packages/store/src/types.ts
@@ -352,6 +352,20 @@ export interface TraceStore {
   ): Promise<TraceEventRecord[]>;
 }
 
+/**
+ * Whole-session turn-message aggregates, computed store-side so the per-turn
+ * pipeline never has to load the full message history just to count it.
+ */
+export interface TurnMessageStats {
+  /** Total messages with `sourceType === "player"` (the turn number). */
+  readonly playerMessageCount: number;
+  /**
+   * Total messages per `sourceRuntimeId` for `sourceType === "runtime"` rows
+   * (the per-runtime trigger counts used by `maxTriggerCount`).
+   */
+  readonly runtimeMessageCounts: Readonly<Record<string, number>>;
+}
+
 /** Append-only turn-message log. Part of `sql-session-journal-records`. */
 export interface TurnMessageStore {
   appendTurnMessage(record: TurnMessageRecord): Promise<void>;
@@ -359,6 +373,22 @@ export interface TurnMessageStore {
     sessionId: string,
     pagination?: PaginationOpts,
   ): Promise<TurnMessageRecord[]>;
+  /**
+   * List only messages NOT yet folded into a compaction summary
+   * (`compactedAtTurnId` unset), oldest-first. Because the compactor always
+   * tags a contiguous prefix of the timeline, this is exactly the raw suffix
+   * the prompt builder and the compactor itself operate on — the compacted
+   * prefix is represented by `listSessionSummaries` instead. With compaction
+   * enabled this read stays bounded for the life of a session, unlike
+   * {@link listTurnMessages}.
+   */
+  listUncompactedTurnMessages(sessionId: string): Promise<TurnMessageRecord[]>;
+  /**
+   * Aggregate counts over the FULL message log (compacted rows included),
+   * resolved as a grouped count query on SQL backends. Replaces the per-turn
+   * "load every row and count in JS" scan.
+   */
+  getTurnMessageStats(sessionId: string): Promise<TurnMessageStats>;
   /**
    * Return the **most recent** `limit` turn messages, ordered oldest-first
    * (the tail of {@link listTurnMessages}).
diff --git a/packages/store/tests/table-registry-consistency.test.ts b/packages/store/tests/table-registry-consistency.test.ts
index 2399542f..3db82c59 100644
--- a/packages/store/tests/table-registry-consistency.test.ts
+++ b/packages/store/tests/table-registry-consistency.test.ts
@@ -23,6 +23,7 @@ import {
 } from "../src/table-registry.js";
 import { createTables } from "../src/sqlite/sqlite-schema-ddl.js";
 import { ALL_TABLE_NAMES } from "../src/postgres/pg-schema-ddl.js";
+import { IDB_OBJECT_STORES } from "../src/indexeddb/idb-db.js";
 import { MEMORY_SNAPSHOT_COLLECTIONS } from "../src/memory/transaction-methods.js";
 import { createMemoryState } from "../src/memory/memory-state.js";
 import * as sqliteSchema from "../src/sqlite/schema.js";
@@ -136,6 +137,19 @@ describe("table registry consistency", () => {
     }
   });
 
+  it("maps every registry table to a declared IDB object store", () => {
+    // Guards the IDB cascade: the browser backend derives deleteSession from
+    // `idbStore`, so a registry entry pointing at a non-existent object store
+    // would silently leak orphaned rows. A typo fails here instead of in prod.
+    const idbStores = new Set<string>(IDB_OBJECT_STORES);
+    for (const { table, idbStore } of SESSION_SCOPED_TABLES) {
+      expect(
+        idbStores.has(idbStore),
+        `registry table "${table}" points at IDB store "${idbStore}" which is not in IDB_OBJECT_STORES`,
+      ).toBe(true);
+    }
+  });
+
   it("maps every registry table to a MemoryState collection of the right kind", () => {
     const state = createMemoryState() as unknown as Record<string, unknown>;
     for (const { table, memoryKey, memoryKind } of SESSION_SCOPED_TABLES) {

From 39289eda2c2bf49fb8e104cf2bf891210f6853ee Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 15:15:50 +0800
Subject: [PATCH 08/10] refactor: land second audit-backlog batch (bounded
 ingest, seam removal, settings probe, chat window cap)

Four verified backlog items, per owner triage:

- perf(memory): recall ingestion no longer full-reads + sorts the whole
  turn-message log every turn. New DataStore.listTurnMessagesAfter
  (forward keyset on (createdAt, id), SQL tuple predicate + shared JS
  fallback, contract-tested incl. same-createdAt tie-break) reads just
  the batch window past the persisted cursor. Also fixes a latent
  stall: a run of empty-content rows now advances the cursor instead
  of pinning it forever, and cursor ordering now matches the store's
  byte-order keyset exactly.

- refactor(runtime,server,context): remove two zero-caller extension
  seams. findToolClient (structurally broken for any non-InMemory
  client) is gone from ToolExecutorConfig; tool resolution is the
  plain findTool path. The getConfigFn / ctx.config / {{ config.* }}
  chain (always {} in production, undocumented) is deleted end to end,
  plus stale comment references ({{ config.worldEntries }} et al).

- fix(web): settings backend selection now honours the REST-desktop
  tier. probeDesktopMode() runs BEFORE initSettings() and the backend
  picks via isDesktopApp(), so self-host setups without the Electron
  IPC bridge persist settings to ~/.covel/settings.json instead of
  silently falling back to localStorage.

- feat(web): live chat messages are capped in memory (configurable
  ui.chatMessageWindow setting, default 2000, min 200). The cap drops
  oldest rows on live append only and advances olderMessagesCursor to
  the new window edge so scroll-up re-fetches exactly the dropped
  range; streaming placeholders are never dropped and explicit
  history loads never cap.

Validation: full workspace tests 40/40 tasks, turbo lint 21/21,
prettier + oxlint clean; new contract tests ran on memory/sqlite/idb.
---
 apps/server/src/env.d.ts                      |   5 -
 apps/server/src/routes/api/actions.ts         |  11 --
 apps/server/src/routes/api/bootstrap.ts       |  14 ---
 apps/server/src/routes/api/plugin-rpc.ts      |   4 -
 apps/server/src/routes/api/resume.ts          |   6 -
 apps/server/src/routes/api/snapshots.ts       |   5 +-
 .../tests/api/actions-commit-barrier.test.ts  |   1 -
 .../api/actions-deferred-followers.test.ts    |   1 -
 .../tests/api/actions-phase-emit.test.ts      |   1 -
 .../actions-turn-control-concurrency.test.ts  |   1 -
 .../api/hook-pipeline-integration.test.ts     |   1 -
 apps/server/tests/api/resume.test.ts          |   4 -
 apps/server/tests/api/snapshot.test.ts        |   2 -
 .../api/start-game-flow-scenario.test.ts      |   1 -
 apps/web/src/main.tsx                         |  21 ++--
 apps/web/src/settings/registry/core.ts        |  12 ++
 apps/web/src/settings/store.ts                |  15 +--
 .../session-store-message-window.test.ts      | 103 ++++++++++++++++++
 apps/web/src/stores/session-store/reducer.ts  |  79 ++++++++++++--
 docs/reference/prompt-structure.md            |   1 -
 docs/reference/tools.md                       |  19 +---
 packages/context/src/context-builder.ts       |   6 +-
 packages/context/src/prompt-internals.ts      |   3 +-
 packages/context/src/types.ts                 |   6 +-
 .../tests/context-builder-async.test.ts       |   6 -
 .../tests/context-builder-budget.test.ts      |   1 -
 .../context/tests/context-builder.test.ts     |  36 +-----
 .../context/tests/llm-content-parts.test.ts   |   1 -
 .../context/tests/prompt-assembler.test.ts    |   1 -
 .../tests/working-memory-injection.test.ts    |   1 -
 packages/memory/src/vector-ingest.ts          |  78 ++++++-------
 packages/plugin-loader/src/types.ts           |   1 -
 .../plugin-test-utils/src/manual-context.ts   |   3 -
 .../tests/plugin-test-utils.test.ts           |   3 -
 .../runtime/src/agent-loop/tool-executor.ts   |  19 +---
 .../src/agent-loop/turn-agent-guard.ts        |   2 -
 .../src/agent-loop/turn-agent-runtime.ts      |   4 -
 .../function-runtime/turn-function-runtime.ts |   2 -
 .../src/turn-executor/turn-executor-types.ts  |   5 -
 .../src/turn-executor/turn-executor.ts        |   2 +-
 .../runtime/tests/agent-guard-timeout.test.ts |   1 -
 .../core-plugin-char-creator-bridge.test.ts   |   1 -
 .../core-plugin-npc-graph-inject.test.ts      |   1 -
 .../tests/emit-event-integration.test.ts      |   3 -
 .../tests/function-runtime-trace.test.ts      |   1 -
 .../runtime/tests/hook-own-settings.test.ts   |   1 -
 .../tests/hook-wire-turn-executor.test.ts     |   6 -
 .../pre-game-completion-contract.test.ts      |   4 -
 .../runtime/tests/require-tool-use.test.ts    |   4 -
 .../tests/runtime-images-wiring.test.ts       |   1 -
 .../tests/runtime-speech-wiring.test.ts       |   1 -
 .../tests/scene-stage-integration.test.ts     |   1 -
 .../tests/start-game-flow-scenario.test.ts    |   1 -
 .../tests/tool-executor-text-result.test.ts   |  39 +------
 .../runtime/tests/turn-executor-abort.test.ts |   3 -
 .../tests/turn-executor-budget-wiring.test.ts |   1 -
 .../tests/turn-executor-dag-scheduler.test.ts |   1 -
 .../tests/turn-executor-events.test.ts        |   5 -
 .../turn-executor-manual-trigger.test.ts      |   1 -
 .../tests/turn-executor-output-schema.test.ts |   5 -
 .../turn-executor-recursive-call.test.ts      |   2 -
 .../tests/turn-executor-resilience.test.ts    |   3 -
 .../turn-executor-session-context.test.ts     |   8 +-
 .../turn-executor-stream-recovery.test.ts     |   3 -
 .../tests/turn-executor-suspend.test.ts       |  17 ---
 .../runtime/tests/turn-executor-trace.test.ts |   3 -
 ...-executor-turn-result-always-saved.test.ts |   4 -
 .../turn-executor-upstream-required.test.ts   |   2 -
 ...-executor-working-memory-injection.test.ts |   2 -
 packages/runtime/tests/turn-executor.test.ts  |  15 ---
 packages/shared/src/types/plugin.ts           |   2 +-
 packages/store/src/common/cursor.ts           |  27 ++++-
 packages/store/src/common/pagination.ts       |  22 ++++
 .../src/common/sql-session-journal-records.ts |  22 +++-
 .../contract/suites/runtime-record-suites.ts  |  58 ++++++++++
 .../store/src/indexeddb/idb-runtime-store.ts  |  19 +++-
 packages/store/src/memory/runtime-methods.ts  |   8 ++
 packages/store/src/types.ts                   |  15 ++-
 packages/test-runtime/src/cases.test.ts       |   2 -
 packages/test-runtime/src/cases.ts            |   2 -
 packages/test-runtime/src/cli.ts              |   5 -
 packages/test-runtime/src/execution.test.ts   |   7 --
 packages/test-runtime/src/execution.ts        |   2 -
 packages/test-runtime/src/runner.ts           |   2 -
 packages/test-runtime/src/types.ts            |   1 -
 plugins/world-init/tests/guard.test.ts        |   2 -
 86 files changed, 422 insertions(+), 401 deletions(-)
 create mode 100644 apps/web/src/stores/__tests__/session-store-message-window.test.ts

diff --git a/apps/server/src/env.d.ts b/apps/server/src/env.d.ts
index 0c65a0b2..97fed8eb 100644
--- a/apps/server/src/env.d.ts
+++ b/apps/server/src/env.d.ts
@@ -26,10 +26,6 @@ type LoadRuntimeFn = (
   locale?: string,
   sessionId?: string,
 ) => Promise<LoadedRuntime | undefined>;
-type GetConfigFn = (
-  pluginId: string,
-  runtimeId: string,
-) => Readonly<Record<string, unknown>>;
 type ResolveModelFn = (
   manifest: RuntimeManifest,
   apiOverride?: string,
@@ -75,7 +71,6 @@ declare module "hono" {
     pluginUtils?: PluginRuntimeUtils;
     loadRuntimeFn: LoadRuntimeFn;
     toolExecutor: ToolExecutor;
-    getConfigFn: GetConfigFn;
     resolveModel: ResolveModelFn;
     compactorRunner: CompactorRunner;
     /**
diff --git a/apps/server/src/routes/api/actions.ts b/apps/server/src/routes/api/actions.ts
index c6fe6b3b..1eae4306 100644
--- a/apps/server/src/routes/api/actions.ts
+++ b/apps/server/src/routes/api/actions.ts
@@ -83,10 +83,6 @@ type Env = {
       locale?: string,
     ) => Promise<LoadedRuntime | undefined>;
     toolExecutor: ToolExecutor;
-    getConfigFn: (
-      pluginId: string,
-      runtimeId: string,
-    ) => Readonly<Record<string, unknown>>;
     resolveModel: (
       manifest: RuntimeManifest,
       apiOverride?: string,
@@ -127,7 +123,6 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
   const getPluginSource = c.get("getPluginSource");
   const loadRuntimeFn = c.get("loadRuntimeFn");
   const toolExecutor = c.get("toolExecutor");
-  const getConfigFn = c.get("getConfigFn");
   const resolveModel = c.get("resolveModel");
   const eventBus = c.get("eventBus");
   const compactorRunner = c.get("compactorRunner");
@@ -446,11 +441,6 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
               ...(pluginGateway ? { gateway: pluginGateway } : {}),
               ...(pluginUtils ? { utils: pluginUtils } : {}),
               ...(getPluginSource ? { getPluginSource } : {}),
-              // bootstrapApi always supplies getConfigFn; default to a no-op so a
-              // minimal harness (or any caller that omits it) can't crash the turn
-              // executor's `deps.getConfig(...)` call. Preserves the defensiveness
-              // the removed /:id/turn route carried.
-              getConfig: getConfigFn ?? (() => ({})),
               store,
               ...(mediaStore ? { mediaStore } : {}),
               toolExecutor,
@@ -625,7 +615,6 @@ actionRoutes.post("/", rateLimiter({ max: 30 }), async (c) => {
             ...(pluginGateway ? { gateway: pluginGateway } : {}),
             ...(pluginUtils ? { utils: pluginUtils } : {}),
             ...(getPluginSource ? { getPluginSource } : {}),
-            getConfig: getConfigFn ?? (() => ({})),
             ...(mediaStore ? { mediaStore } : {}),
             toolExecutor,
             resolveModel,
diff --git a/apps/server/src/routes/api/bootstrap.ts b/apps/server/src/routes/api/bootstrap.ts
index 3e5c90b9..0f68441e 100644
--- a/apps/server/src/routes/api/bootstrap.ts
+++ b/apps/server/src/routes/api/bootstrap.ts
@@ -148,11 +148,6 @@ export interface ApiBootstrapConfig {
    * player-facing settings (`memory` → `plugin` → `story` → first text slot).
    */
   readonly preferredMemorySlot?: string;
-  /** Optional config provider for injecting world context etc. into runtime execution. */
-  readonly getConfigFn?: (
-    pluginId: string,
-    runtimeId: string,
-  ) => Readonly<Record<string, unknown>>;
   /**
    * Optional per-request middleware inserted AFTER the default dependency
    * injection middleware but BEFORE route handlers execute. Intended for
@@ -442,14 +437,6 @@ export async function bootstrapApi(
     }
   }
 
-  // 7. getConfigFn — per-runtime config injection seam. No production caller
-  //    passes it today, so ctx.config / {{ config.* }} always resolve to {}.
-  const getConfigFn =
-    config.getConfigFn ??
-    ((
-      _pluginId: string,
-      _runtimeId: string,
-    ): Readonly<Record<string, unknown>> => ({}));
   const getPluginSource = (pluginId: string) => registry.get(pluginId)?.source;
 
   const { rpcRegistry, rpcExecutor, rpcApprovalGate } =
@@ -561,7 +548,6 @@ export async function bootstrapApi(
     }
     c.set("loadRuntimeFn", loadRuntimeFn);
     c.set("toolExecutor", toolExecutor);
-    c.set("getConfigFn", getConfigFn);
     c.set("resolveModel", resolveModel);
     c.set("compactorRunner", compactorRunner);
     c.set("turnContextBudget", turnContextBudget);
diff --git a/apps/server/src/routes/api/plugin-rpc.ts b/apps/server/src/routes/api/plugin-rpc.ts
index 411d76de..66c60ebc 100644
--- a/apps/server/src/routes/api/plugin-rpc.ts
+++ b/apps/server/src/routes/api/plugin-rpc.ts
@@ -206,9 +206,6 @@ pluginRpcRoutes.post("/:id/plugin-rpc", rateLimiter({ max: 30 }), async (c) => {
       pluginRegistry,
       sessionId,
     );
-    const turnGetConfig =
-      c.get("getConfigFn") ?? ((_pluginId: string, _runtimeId: string) => ({}));
-
     // Audit F7: player-authored plugin settings travel with the request
     // as a base64-encoded JSON header (`X-Plugin-User-Settings`) sourced
     // from the unified SettingsStore. The body map keys on pluginId so
@@ -251,7 +248,6 @@ pluginRpcRoutes.post("/:id/plugin-rpc", rateLimiter({ max: 30 }), async (c) => {
         ...(pluginGateway ? { gateway: pluginGateway } : {}),
         ...(pluginUtils ? { utils: pluginUtils } : {}),
         ...(getPluginSource ? { getPluginSource } : {}),
-        getConfig: turnGetConfig,
         ...(mediaStore ? { mediaStore } : {}),
         toolExecutor,
         resolveModel,
diff --git a/apps/server/src/routes/api/resume.ts b/apps/server/src/routes/api/resume.ts
index feb1bdee..d3078efe 100644
--- a/apps/server/src/routes/api/resume.ts
+++ b/apps/server/src/routes/api/resume.ts
@@ -55,10 +55,6 @@ type Env = {
       locale?: string,
     ) => Promise<LoadedRuntime | undefined>;
     toolExecutor: ToolExecutor;
-    getConfigFn: (
-      pluginId: string,
-      runtimeId: string,
-    ) => Readonly<Record<string, unknown>>;
     resolveModel: (
       manifest: RuntimeManifest,
       apiOverride?: string,
@@ -288,8 +284,6 @@ resumeRoutes.post("/:id/resume", async (c) => {
             llm: llmAdapter,
             ...(pluginGateway ? { gateway: pluginGateway } : {}),
             ...(pluginUtils ? { utils: pluginUtils } : {}),
-            getConfig:
-              c.get("getConfigFn") ?? ((_p: string, _r: string) => ({})),
             store,
             toolExecutor,
             resolveModel,
diff --git a/apps/server/src/routes/api/snapshots.ts b/apps/server/src/routes/api/snapshots.ts
index eece3d7a..0c92d4b4 100644
--- a/apps/server/src/routes/api/snapshots.ts
+++ b/apps/server/src/routes/api/snapshots.ts
@@ -422,8 +422,9 @@ snapshotRoutes.post("/:id/fork", async (c) => {
 
           // Copy session-scoped lorebook entries. Missing before, so a fork lost
           // every lore/world entry the parent accumulated during play, and the
-          // child's `{{ config.worldEntries }}` came back empty. (sessionId, id) is
-          // the composite key, so keeping the original id is safe.
+          // child's world-entries prompt injection came back empty.
+          // (sessionId, id) is the composite key, so keeping the original id
+          // is safe.
           if (snapshot.payload.lorebookEntries.length > 0) {
             await tx.upsertLorebookEntries(
               snapshot.payload.lorebookEntries.map((lb) => ({
diff --git a/apps/server/tests/api/actions-commit-barrier.test.ts b/apps/server/tests/api/actions-commit-barrier.test.ts
index 3eb6eeb5..bff5fdc0 100644
--- a/apps/server/tests/api/actions-commit-barrier.test.ts
+++ b/apps/server/tests/api/actions-commit-barrier.test.ts
@@ -156,7 +156,6 @@ describe("POST /api/actions — turn commit barrier", () => {
       c.set("loadRuntimeFn", async () => loaded);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       c.set("toolExecutor", undefined as any);
-      c.set("getConfigFn", () => ({}));
       c.set("resolveModel", () => undefined);
       c.set("eventBus", eventBus);
       c.set("sessionLock", sessionLock);
diff --git a/apps/server/tests/api/actions-deferred-followers.test.ts b/apps/server/tests/api/actions-deferred-followers.test.ts
index ad1f74a4..d028996e 100644
--- a/apps/server/tests/api/actions-deferred-followers.test.ts
+++ b/apps/server/tests/api/actions-deferred-followers.test.ts
@@ -160,7 +160,6 @@ describe("POST /api/actions — deferred background followers (Audit F1, main pa
       c.set("loadRuntimeFn", loadRuntimeFn);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       c.set("toolExecutor", undefined as any);
-      c.set("getConfigFn", () => ({}));
       c.set("resolveModel", () => undefined);
       c.set("eventBus", eventBus);
       c.set("sessionLock", sessionLock);
diff --git a/apps/server/tests/api/actions-phase-emit.test.ts b/apps/server/tests/api/actions-phase-emit.test.ts
index 6356a6fb..6081a6eb 100644
--- a/apps/server/tests/api/actions-phase-emit.test.ts
+++ b/apps/server/tests/api/actions-phase-emit.test.ts
@@ -137,7 +137,6 @@ describe("POST /api/actions — phase.changed hygiene (Finding 4 regression)", (
       c.set("loadRuntimeFn", async (m) => loadedByName.get(m.name));
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       c.set("toolExecutor", undefined as any);
-      c.set("getConfigFn", () => ({}));
       c.set("resolveModel", () => undefined);
       c.set("eventBus", eventBus);
       c.set("sessionLock", sessionLock);
diff --git a/apps/server/tests/api/actions-turn-control-concurrency.test.ts b/apps/server/tests/api/actions-turn-control-concurrency.test.ts
index 97007e9d..2643211f 100644
--- a/apps/server/tests/api/actions-turn-control-concurrency.test.ts
+++ b/apps/server/tests/api/actions-turn-control-concurrency.test.ts
@@ -127,7 +127,6 @@ describe("POST /api/actions — steer/abort targets the executing turn, not a qu
       c.set("loadRuntimeFn", async () => loaded);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       c.set("toolExecutor", undefined as any);
-      c.set("getConfigFn", () => ({}));
       c.set("resolveModel", () => undefined);
       c.set("eventBus", eventBus);
       c.set("sessionLock", sessionLock);
diff --git a/apps/server/tests/api/hook-pipeline-integration.test.ts b/apps/server/tests/api/hook-pipeline-integration.test.ts
index e75e70da..abda13b1 100644
--- a/apps/server/tests/api/hook-pipeline-integration.test.ts
+++ b/apps/server/tests/api/hook-pipeline-integration.test.ts
@@ -151,7 +151,6 @@ describe("POST /api/actions — hook pipeline wired through commit chain", () =>
       );
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       c.set("toolExecutor", undefined as any);
-      c.set("getConfigFn", () => ({}));
       c.set("resolveModel", () => undefined);
       c.set("eventBus", eventBus);
       c.set("hookPipeline", hookPipeline);
diff --git a/apps/server/tests/api/resume.test.ts b/apps/server/tests/api/resume.test.ts
index 3444b5da..b7be9b1c 100644
--- a/apps/server/tests/api/resume.test.ts
+++ b/apps/server/tests/api/resume.test.ts
@@ -30,7 +30,6 @@ type Deps = {
     execute: () => Promise<unknown>;
     getToolInfo: () => undefined;
   };
-  getConfigFn: () => Record<string, unknown>;
   resolveModel: () => undefined;
   hookPipeline?: HookPipeline;
 };
@@ -43,7 +42,6 @@ function createTestApp(deps: Deps) {
       llmAdapter: Deps["llmAdapter"];
       loadRuntimeFn: Deps["loadRuntimeFn"];
       toolExecutor: Deps["toolExecutor"];
-      getConfigFn: Deps["getConfigFn"];
       resolveModel: Deps["resolveModel"];
     };
   }>();
@@ -58,7 +56,6 @@ function createTestApp(deps: Deps) {
     c.set("loadRuntimeFn", deps.loadRuntimeFn as any);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     c.set("toolExecutor", deps.toolExecutor as any);
-    c.set("getConfigFn", deps.getConfigFn);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     c.set("resolveModel", deps.resolveModel as any);
     c.set("sessionLock", sessionLock);
@@ -187,7 +184,6 @@ function makeDefaultDeps(store: DataStore, overrides?: Partial<Deps>): Deps {
       }),
       getToolInfo: () => undefined,
     },
-    getConfigFn: () => ({}),
     resolveModel: () => undefined,
     ...overrides,
   };
diff --git a/apps/server/tests/api/snapshot.test.ts b/apps/server/tests/api/snapshot.test.ts
index fb5b3b28..8f81e850 100644
--- a/apps/server/tests/api/snapshot.test.ts
+++ b/apps/server/tests/api/snapshot.test.ts
@@ -1079,7 +1079,6 @@ describe("Auto snapshot", () => {
             usage: { inputTokens: 0, outputTokens: 0 },
           }),
         } as any,
-        getConfig: () => ({}),
         store,
       },
     );
@@ -1115,7 +1114,6 @@ describe("Auto snapshot", () => {
             usage: { inputTokens: 0, outputTokens: 0 },
           }),
         } as any,
-        getConfig: () => ({}),
         store,
         eventBus,
       },
diff --git a/apps/server/tests/api/start-game-flow-scenario.test.ts b/apps/server/tests/api/start-game-flow-scenario.test.ts
index 28e2e3f0..a140a266 100644
--- a/apps/server/tests/api/start-game-flow-scenario.test.ts
+++ b/apps/server/tests/api/start-game-flow-scenario.test.ts
@@ -216,7 +216,6 @@ function makeApp(
       loaded.get(manifest.name),
     );
     c.set("toolExecutor", undefined);
-    c.set("getConfigFn", () => ({}));
     c.set("resolveModel", () => undefined);
     c.set("eventBus", eventBus);
     c.set("sessionLock", sessionLock);
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 0cf593cc..3a851123 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -18,6 +18,7 @@ import {
   type ColorScheme,
 } from "@/lib/appearance";
 import { getSettings, initSettings } from "@/settings/store";
+import { configureMessagesWindowCap } from "@/stores/session-store/reducer";
 import { CUSTOM_THEMES_KEY } from "@/theme-system/storage.js";
 import {
   syncThemeRegistry,
@@ -76,9 +77,13 @@ function syncNextThemesStorage(scheme: ColorScheme): void {
   window.localStorage.setItem("covel:scheme", scheme);
 }
 
-// Boot order: hydrate settings store first so appearance / locale apply
-// without a flash, then run the rest of the bootstrap in parallel.
-initSettings()
+// Boot order: probe desktop mode FIRST — the settings backend choice
+// (localStorage vs ~/.covel via IPC/REST) depends on its result — then
+// hydrate the settings store so appearance / locale apply without a flash,
+// then run the rest of the bootstrap in parallel. The probe is one same-origin
+// fetch (skipped entirely under Electron IPC) and non-fatal on failure.
+probeDesktopMode()
+  .then(() => initSettings())
   .then(async () => {
     const store = getSettings();
     await migrateLegacyThemeScheme(store);
@@ -114,11 +119,11 @@ initSettings()
         document.documentElement.lang = next;
       }
     });
-    return Promise.all([
-      syncStorageMode(),
-      probeDesktopMode(),
-      loadProviderKeysFromStorage(),
-    ]);
+    configureMessagesWindowCap(store.get<number>("ui.chatMessageWindow"));
+    store.subscribe<number>("ui.chatMessageWindow", (next) => {
+      configureMessagesWindowCap(next);
+    });
+    return Promise.all([syncStorageMode(), loadProviderKeysFromStorage()]);
   })
   .then(() => {
     createRoot(document.getElementById("root")!).render(
diff --git a/apps/web/src/settings/registry/core.ts b/apps/web/src/settings/registry/core.ts
index 685e3563..fca8e9b8 100644
--- a/apps/web/src/settings/registry/core.ts
+++ b/apps/web/src/settings/registry/core.ts
@@ -27,6 +27,18 @@ export function registerCoreSettings(store: SettingsStoreApi): void {
 
   registerThemeSettings(store);
 
+  store.register({
+    key: "ui.chatMessageWindow",
+    schema: z.number().int().min(200).max(20000),
+    default: 2000,
+    group: "general",
+    widget: "number",
+    label: {
+      "zh-CN": "聊天窗口消息上限",
+      "en-US": "Chat window message limit",
+    },
+  });
+
   store.register({
     key: "ui.onboardedVersion",
     schema: z.number().int(),
diff --git a/apps/web/src/settings/store.ts b/apps/web/src/settings/store.ts
index 157ecd28..41625e18 100644
--- a/apps/web/src/settings/store.ts
+++ b/apps/web/src/settings/store.ts
@@ -10,18 +10,19 @@ import {
   registerProviderKeys,
 } from "./registry/index.js";
 import { cleanupLegacyLocalStorage } from "./legacy-cleanup.js";
-import { getDesktopRestAuthHeaders } from "@/lib/desktop-bridge";
-
-function isDesktopBridge(): boolean {
-  if (typeof window === "undefined") return false;
-  return Boolean((window as unknown as { covelIpc?: unknown }).covelIpc);
-}
+import { getDesktopRestAuthHeaders, isDesktopApp } from "@/lib/desktop-bridge";
 
 let singleton: SettingsStore | null = null;
 let readyPromise: Promise<void> | null = null;
 
 function createStore(): SettingsStore {
-  const adapter = isDesktopBridge()
+  // isDesktopApp() covers BOTH desktop signals: the Electron IPC bridge and
+  // the REST-desktop probe (`/api/config/info` → isDesktop, self-host setups
+  // where the sidecar owns ~/.covel). The boot sequence in main.tsx runs
+  // probeDesktopMode() BEFORE initSettings() so this decision sees the probe
+  // result; without that ordering REST-desktop silently fell back to
+  // localStorage and settings never reached ~/.covel/settings.json.
+  const adapter = isDesktopApp()
     ? createJsonFileBackend({ getAuthHeaders: getDesktopRestAuthHeaders })
     : createLocalStorageBackend();
   const store = new SettingsStore(adapter);
diff --git a/apps/web/src/stores/__tests__/session-store-message-window.test.ts b/apps/web/src/stores/__tests__/session-store-message-window.test.ts
new file mode 100644
index 00000000..0dd80607
--- /dev/null
+++ b/apps/web/src/stores/__tests__/session-store-message-window.test.ts
@@ -0,0 +1,103 @@
+/**
+ * Live-append message window cap (`ui.chatMessageWindow`).
+ *
+ * A marathon tab must not grow `messages` without bound: once a live append
+ * exceeds the configured cap, the OLDEST rows are dropped and
+ * `olderMessagesCursor` advances to the new window edge, so the existing
+ * scroll-up path re-fetches exactly the dropped range (no unreachable gap).
+ * Streaming placeholders are never dropped, and PREPEND_MESSAGES (the user
+ * explicitly loading history) never caps.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  configureMessagesWindowCap,
+  initialState,
+  reducer,
+} from "../session-store/reducer.js";
+import type { SessionState, StreamMessage } from "../session-store/types.js";
+
+const CAP_MIN = 200;
+
+function msg(i: number, over?: Partial<StreamMessage>): StreamMessage {
+  return {
+    id: `m-${String(i).padStart(4, "0")}`,
+    role: "assistant",
+    content: `msg ${i}`,
+    timestamp: `2026-01-01T00:00:${String(i % 60).padStart(2, "0")}.${String(i).padStart(3, "0")}Z`,
+    ...over,
+  };
+}
+
+function stateWith(messages: StreamMessage[]): SessionState {
+  return { ...initialState, messages };
+}
+
+function addMessage(state: SessionState, message: StreamMessage): SessionState {
+  return reducer(state, { type: "ADD_MESSAGE", message });
+}
+
+afterEach(() => {
+  // Restore the default so this file cannot leak a tiny cap into other tests.
+  configureMessagesWindowCap(Number.NaN);
+});
+
+describe("live message window cap", () => {
+  it("drops the oldest rows past the cap and advances the scroll-up cursor", () => {
+    configureMessagesWindowCap(CAP_MIN);
+    const full = stateWith(Array.from({ length: CAP_MIN }, (_, i) => msg(i)));
+
+    const next = addMessage(full, msg(CAP_MIN));
+
+    expect(next.messages).toHaveLength(CAP_MIN);
+    expect(next.messages[0]!.id).toBe(msg(1).id);
+    expect(next.messages.at(-1)!.id).toBe(msg(CAP_MIN).id);
+    // Cursor points at the new window edge so scroll-up re-fetches the
+    // dropped row (listMessagesPage fetches strictly BEFORE the cursor).
+    expect(next.olderMessagesCursor).toEqual({
+      createdAt: msg(1).timestamp,
+      id: msg(1).id,
+    });
+  });
+
+  it("does not cap below the cap and keeps the cursor untouched", () => {
+    configureMessagesWindowCap(CAP_MIN);
+    const small = stateWith([msg(0)]);
+    const next = addMessage(small, msg(1));
+    expect(next.messages).toHaveLength(2);
+    expect(next.olderMessagesCursor).toBeNull();
+  });
+
+  it("skips capping when a streaming placeholder would be dropped", () => {
+    configureMessagesWindowCap(CAP_MIN);
+    const withPlaceholder = stateWith([
+      msg(0, { id: "stream_t1_narrator" }),
+      ...Array.from({ length: CAP_MIN - 1 }, (_, i) => msg(i + 1)),
+    ]);
+    const next = addMessage(withPlaceholder, msg(CAP_MIN));
+    expect(next.messages).toHaveLength(CAP_MIN + 1);
+    expect(next.messages[0]!.id).toBe("stream_t1_narrator");
+  });
+
+  it("PREPEND_MESSAGES never caps (explicit history load)", () => {
+    configureMessagesWindowCap(CAP_MIN);
+    const full = stateWith(
+      Array.from({ length: CAP_MIN }, (_, i) => msg(i + 100)),
+    );
+    const older = Array.from({ length: 50 }, (_, i) => msg(i));
+    const next = reducer(full, {
+      type: "PREPEND_MESSAGES",
+      messages: older,
+      cursor: null,
+    });
+    expect(next.messages).toHaveLength(CAP_MIN + 50);
+    expect(next.messages[0]!.id).toBe(msg(0).id);
+  });
+
+  it("configureMessagesWindowCap falls back to the default on invalid input", () => {
+    configureMessagesWindowCap(1); // below MESSAGES_WINDOW_MIN → default (2000)
+    const full = stateWith(Array.from({ length: 300 }, (_, i) => msg(i)));
+    const next = addMessage(full, msg(300));
+    expect(next.messages).toHaveLength(301);
+  });
+});
diff --git a/apps/web/src/stores/session-store/reducer.ts b/apps/web/src/stores/session-store/reducer.ts
index d56eb047..93836a86 100644
--- a/apps/web/src/stores/session-store/reducer.ts
+++ b/apps/web/src/stores/session-store/reducer.ts
@@ -9,6 +9,7 @@ import type {
   AssetProgressEvent,
   SessionAction,
   SessionState,
+  StreamMessage,
 } from "./types.js";
 
 const EXEC_STEPS_MAX = 500;
@@ -16,6 +17,53 @@ const EXEC_STEPS_MAX = 500;
 /** Streaming-placeholder id convention shared with the renderer. */
 const STREAM_ID_PREFIX = "stream_";
 
+/**
+ * In-memory chat window: live appends past this cap drop the OLDEST loaded
+ * messages (a marathon tab otherwise grows without bound). Dropped rows stay
+ * re-fetchable — the cap also advances `olderMessagesCursor` to the new window
+ * edge, so the existing scroll-up path reloads them on demand. Configurable
+ * via the `ui.chatMessageWindow` setting (wired in main.tsx).
+ */
+const MESSAGES_WINDOW_DEFAULT = 2000;
+const MESSAGES_WINDOW_MIN = 200;
+let messagesWindowCap = MESSAGES_WINDOW_DEFAULT;
+
+export function configureMessagesWindowCap(cap: number): void {
+  messagesWindowCap =
+    Number.isFinite(cap) && cap >= MESSAGES_WINDOW_MIN
+      ? Math.floor(cap)
+      : MESSAGES_WINDOW_DEFAULT;
+}
+
+/**
+ * Cap a grown `messages` array. Only live-append paths call this —
+ * PREPEND_MESSAGES (the user explicitly loading history) never caps, and
+ * streaming placeholders are never dropped (they only live at the tail; a
+ * placeholder inside the drop range means assumptions broke, so skip capping).
+ */
+function capLiveMessages(
+  state: SessionState,
+  messages: StreamMessage[],
+): Pick<SessionState, "messages"> & Partial<SessionState> {
+  if (messages.length <= messagesWindowCap) return { messages };
+  const dropCount = messages.length - messagesWindowCap;
+  const dropped = messages.slice(0, dropCount);
+  if (dropped.some((m) => m.id.startsWith(STREAM_ID_PREFIX))) {
+    return { messages };
+  }
+  const kept = messages.slice(dropCount);
+  const edge = kept[0];
+  return {
+    messages: kept,
+    // Boundary rows this deep in the window are server-authoritative
+    // (timestamp = server createdAt); stream placeholders with client wall
+    // clocks never reach the front of a full window.
+    olderMessagesCursor: edge
+      ? { createdAt: edge.timestamp, id: edge.id }
+      : state.olderMessagesCursor,
+  };
+}
+
 export const initialState: SessionState = {
   presets: [],
   packages: [],
@@ -141,7 +189,10 @@ export function reducer(
         next[existingIdx] = { ...next[existingIdx], ...action.message };
         return { ...state, messages: next };
       }
-      return { ...state, messages: [...state.messages, action.message] };
+      return {
+        ...state,
+        ...capLiveMessages(state, [...state.messages, action.message]),
+      };
     }
     case "COMPLETE_MESSAGE": {
       // Replace the streaming placeholder with the final message content and
@@ -170,7 +221,10 @@ export function reducer(
       }
       return {
         ...state,
-        messages: [...state.messages, { ...action.message, kind: "story" }],
+        ...capLiveMessages(state, [
+          ...state.messages,
+          { ...action.message, kind: "story" },
+        ]),
       };
     }
     case "APPEND_DELTA": {
@@ -187,15 +241,18 @@ export function reducer(
         return state;
       return {
         ...state,
-        messages: state.messages.concat({
-          id: streamId,
-          role: "assistant",
-          content: "",
-          timestamp: new Date().toISOString(),
-          turnId: action.turnId,
-          runtimeId: action.runtimeId,
-          kind: "story",
-        }),
+        ...capLiveMessages(
+          state,
+          state.messages.concat({
+            id: streamId,
+            role: "assistant",
+            content: "",
+            timestamp: new Date().toISOString(),
+            turnId: action.turnId,
+            runtimeId: action.runtimeId,
+            kind: "story",
+          }),
+        ),
       };
     }
     case "SET_EXECUTING":
diff --git a/docs/reference/prompt-structure.md b/docs/reference/prompt-structure.md
index 42bf1c09..4477e9aa 100644
--- a/docs/reference/prompt-structure.md
+++ b/docs/reference/prompt-structure.md
@@ -86,7 +86,6 @@ summaryFocus:
 - `{{ player.lastFormValues }}`：最近一次 player 表单提交，JSON 字符串。
 - `{{ session.id }}` / `{{ session.turnNumber }}`。
 - `{{ inputs.<pluginId>.<runtimeId>.<field> }}`：上游 runtime 输出。
-- `{{ config.* }}`：当前 runtime 配置视图。
 - `{{ world.* }}`：由 session context snapshot 的 `world` 视图提供，例如 `world.schema`、`world.entries`、`world.dimensions`。
 - `{{ userSettings.* }}`：玩家配置的插件设置。
 
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 6dc54752..4dadcfba 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -632,15 +632,12 @@ export default function ({ tool, z, shortId, shortIdBatch }) {
 
 ## ToolClient
 
-工具执行统一经过 `ToolClient`。内置工具和插件本地工具使用 `InMemoryToolClient`，registry 记录每个 tool 对应的 client，runtime 执行时解析 client 后调用 `client.call(name, args, ctx)`。
+工具执行统一经过 `ToolClient`。`ToolExecutor` 通过注入的 `findTool(name, context)` 解析出 `ToolModule`，再用 `InMemoryToolClient` 包裹后调用 `client.call(name, args, ctx)` —— 内置工具和插件本地工具都走这条内存内路径，审批、trace、结果 envelope 由 `ToolExecutor` 统一处理。
 
 接口位于 `@covel/tools`：
 
 ```typescript
-type ToolTransport = "in-memory" | "stdio" | "http" | "sse";
-
 interface ToolClient {
-  readonly transport: ToolTransport;
   readonly id: string;
   list(): Promise<readonly ToolDefinition[]>;
   call(
@@ -652,20 +649,6 @@ interface ToolClient {
 }
 ```
 
-兼容入口继续可用：
-
-- `registry.register(resolvedTool)`
-- `registry.getByFullName(fullName)`
-- `registry.getToolsForRuntime(pluginId, runtimeId, manifest)`
-
-新增入口用于统一执行路径：
-
-- `registry.registerClient(client, tools)`
-- `registry.getClientEntry(fullName)`
-- `registry.getClientForTool(fullName)`
-
-未来的 `stdio` / `http` / `sse` 工具传输只需要实现同一个 `ToolClient` 协议，审批、trace、结果 envelope 继续由 runtime 的 `ToolExecutor` 统一处理。
-
 ---
 
 ## 审批策略
diff --git a/packages/context/src/context-builder.ts b/packages/context/src/context-builder.ts
index 411c8f07..76a82bf2 100644
--- a/packages/context/src/context-builder.ts
+++ b/packages/context/src/context-builder.ts
@@ -2,7 +2,7 @@
  * Context Builder — public entrypoint for runtime prompt assembly.
  *
  * Responsibilities:
- * - Template variable interpolation (`{{ inputs.xxx }}`, `{{ config.xxx }}`, etc.)
+ * - Template variable interpolation (`{{ inputs.xxx }}`, `{{ player.xxx }}`, etc.)
  * - Inject block assembly (XML-wrapped data from other runtime outputs)
  * - Full context assembly (system prompt + message history)
  *
@@ -26,7 +26,6 @@ import type { AssembledContext, ContextBuildParams } from "./types.js";
  *
  * Supported variable paths:
  * - `{{ inputs.pluginId.runtimeId.fieldName }}` -- other runtime's output field
- * - `{{ config.fieldName }}` -- current runtime's config value
  * - `{{ session.id }}` -- session info
  * - `{{ player.message }}` -- player's current message
  *
@@ -67,7 +66,7 @@ export const buildInjectBlocks = _buildInjectBlocks;
  * This delegates to the segment-based assembler. Budget pruning runs whenever
  * the caller supplies both an estimator and context budget.
  *
- * @param params - Context build parameters: prompt template, manifest, turn input, completed results, config, and message history.
+ * @param params - Context build parameters: prompt template, manifest, turn input, completed results, and message history.
  * @returns An `AssembledContext` containing the interpolated system prompt and ordered messages.
  *
  * @example
@@ -79,7 +78,6 @@ export const buildInjectBlocks = _buildInjectBlocks;
  *   manifest,
  *   turnInput: { sessionId: 'sess-1', turnId: 'turn-1', playerMessage: 'Enter the dungeon' },
  *   completedResults: new Map(),
- *   config: {},
  * });
  *
  * console.log(ctx.systemPrompt); // Interpolated system prompt
diff --git a/packages/context/src/prompt-internals.ts b/packages/context/src/prompt-internals.ts
index 2f1d732f..99d81e86 100644
--- a/packages/context/src/prompt-internals.ts
+++ b/packages/context/src/prompt-internals.ts
@@ -6,7 +6,7 @@
  * - template-variable interpolation
  * - inject-block construction
  * - variable-object assembly (the big `variables` record fed to the
- *   interpolator, including `inputs`, `config`, `world`, `session`, `player`)
+ *   interpolator, including `inputs`, `world`, `session`, `player`)
  * - locale → language-name resolution
  *
  * This module is `@internal` — exports are imported by sibling modules only
@@ -377,7 +377,6 @@ export function assemblePromptVariables(
 
   return {
     inputs: inputsMap,
-    config: params.config,
     world,
     session: {
       id: turnInput.sessionId,
diff --git a/packages/context/src/types.ts b/packages/context/src/types.ts
index f53889e7..19ecbe29 100644
--- a/packages/context/src/types.ts
+++ b/packages/context/src/types.ts
@@ -117,8 +117,6 @@ export interface ContextBuildParams {
   readonly turnInput: TurnInput;
   /** Completed results from other runtimes (for inject). */
   readonly completedResults: ReadonlyMap<string, RuntimeResult>;
-  /** Runtime's effective config values. */
-  readonly config: Readonly<Record<string, unknown>>;
   /** Previous turn messages (append-only history from DataStore). */
   readonly messageHistory?: readonly MessageHistoryRecord[];
   /** Session-level metadata (turnNumber, characters, lastFormValues). */
@@ -186,8 +184,8 @@ export interface ContextBuildParams {
   }[];
   /**
    * Pre-assembled session context. When provided, prompt assembly reads
-   * session-level data from here instead of the scattered `config` /
-   * `sessionMeta` / `workingMemory` / `coreMemoryBlocks` fields.
+   * session-level data from here instead of the scattered `sessionMeta` /
+   * `workingMemory` / `coreMemoryBlocks` fields.
    */
   readonly sessionContext?: SessionContextSnapshot;
   /**
diff --git a/packages/context/tests/context-builder-async.test.ts b/packages/context/tests/context-builder-async.test.ts
index a769168e..b61bb003 100644
--- a/packages/context/tests/context-builder-async.test.ts
+++ b/packages/context/tests/context-builder-async.test.ts
@@ -173,7 +173,6 @@ describe("buildContextAsync — runtime inject regression", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: results,
-      config: {},
     };
 
     const sync = buildContext(params);
@@ -205,7 +204,6 @@ describe("buildContextAsync — runtime inject regression", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
     };
     const result = buildContext(params);
     expect(result.systemPrompt).toBe(`body${PROMPT_CACHE_BREAKPOINT_MARKER}`);
@@ -241,7 +239,6 @@ describe("buildContextAsync — plugin-data inject", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
       store,
     };
   }
@@ -343,7 +340,6 @@ describe("buildContextAsync — two-pass truncation", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
       store,
     });
 
@@ -393,7 +389,6 @@ describe("buildContextAsync — two-pass truncation", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
       store,
     });
     expect(result.systemPrompt).toContain("- codex-a");
@@ -432,7 +427,6 @@ describe("buildContextAsync — format variants", () => {
       manifest,
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
       store,
     });
   }
diff --git a/packages/context/tests/context-builder-budget.test.ts b/packages/context/tests/context-builder-budget.test.ts
index f3f545d2..3dbe4d68 100644
--- a/packages/context/tests/context-builder-budget.test.ts
+++ b/packages/context/tests/context-builder-budget.test.ts
@@ -39,7 +39,6 @@ const baseParams = (): ContextBuildParams => ({
   manifest: makeManifest(),
   turnInput: makeTurnInput(),
   completedResults: new Map(),
-  config: {},
   messageHistory: makeHistory(),
 });
 
diff --git a/packages/context/tests/context-builder.test.ts b/packages/context/tests/context-builder.test.ts
index ffef7f5a..a6715ecb 100644
--- a/packages/context/tests/context-builder.test.ts
+++ b/packages/context/tests/context-builder.test.ts
@@ -60,11 +60,11 @@ describe("interpolateTemplate", () => {
     expect(result).toBe("story");
   });
 
-  it("should replace a config variable", () => {
-    const result = interpolateTemplate("Length: {{ config.outputLength }}", {
-      config: { outputLength: 150 },
+  it("should replace a nested variable", () => {
+    const result = interpolateTemplate("World: {{ world.name }}", {
+      world: { name: "Cloudmere" },
     });
-    expect(result).toBe("Length: 150");
+    expect(result).toBe("World: Cloudmere");
   });
 
   it("should replace a missing variable with empty string", () => {
@@ -121,7 +121,6 @@ describe("buildInjectBlocks", () => {
           makeRuntimeResult({ output: { narrativeOutput: "the story" } }),
         ],
       ]),
-      config: {},
     };
 
     const result = buildInjectBlocks(params);
@@ -160,7 +159,6 @@ describe("buildInjectBlocks", () => {
           makeRuntimeResult({ output: { combatLog: "hit for 10 damage" } }),
         ],
       ]),
-      config: {},
     };
 
     const result = buildInjectBlocks(params);
@@ -186,7 +184,6 @@ describe("buildInjectBlocks", () => {
       }),
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
     };
 
     expect(buildInjectBlocks(params)).toBe("");
@@ -198,7 +195,6 @@ describe("buildInjectBlocks", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput(),
       completedResults: new Map(),
-      config: {},
     };
 
     expect(buildInjectBlocks(params)).toBe("");
@@ -230,7 +226,6 @@ describe("buildContext", () => {
           makeRuntimeResult({ output: { narrativeOutput: "the story" } }),
         ],
       ]),
-      config: {},
     };
 
     const ctx = buildContext(params);
@@ -250,7 +245,6 @@ describe("buildContext", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "hello" }),
       completedResults: new Map(),
-      config: {},
     };
 
     const ctx = buildContext(params);
@@ -261,28 +255,12 @@ describe("buildContext", () => {
     expect(ctx.messages).toEqual([{ role: "user", content: "hello" }]);
   });
 
-  it("should interpolate config variables in the system prompt", () => {
-    const params: ContextBuildParams = {
-      promptTemplate: "Write in {{ config.style }} style.",
-      manifest: makeManifest(),
-      turnInput: makeTurnInput({ playerMessage: "go" }),
-      completedResults: new Map(),
-      config: { style: "dramatic" },
-    };
-
-    const ctx = buildContext(params);
-    expect(ctx.systemPrompt).toBe(
-      `Write in dramatic style.${PROMPT_CACHE_BREAKPOINT_MARKER}`,
-    );
-  });
-
   it("uses a runtime execution cue when the current player message is empty", () => {
     const params: ContextBuildParams = {
       promptTemplate: "Plain instructions.",
       manifest: makeManifest(),
       turnInput: makeTurnInput({ locale: "zh-CN", playerMessage: "" }),
       completedResults: new Map(),
-      config: {},
     };
 
     const ctx = buildContext(params);
@@ -305,7 +283,6 @@ describe("buildContext", () => {
         manualTrigger: { runtimeId: "dashscope-image-gen/prompt-generator" },
       }),
       completedResults: new Map(),
-      config: {},
     };
 
     const ctx = buildContext(params);
@@ -334,7 +311,6 @@ describe("buildContext", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "I look around" }),
       completedResults: new Map(),
-      config: {},
       messageHistory: history,
     };
 
@@ -363,7 +339,6 @@ describe("buildContext", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "continue" }),
       completedResults: new Map(),
-      config: {},
       messageHistory: history,
     };
 
@@ -381,7 +356,6 @@ describe("buildContext", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "hello" }),
       completedResults: new Map(),
-      config: {},
     };
 
     const ctx = buildContext(params);
@@ -408,7 +382,6 @@ describe("buildContext — summary substitution", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "current" }),
       completedResults: new Map(),
-      config: {},
       messageHistory: history,
       summaries: [
         {
@@ -444,7 +417,6 @@ describe("buildContext — summary substitution", () => {
       manifest: makeManifest(),
       turnInput: makeTurnInput({ playerMessage: "now" }),
       completedResults: new Map(),
-      config: {},
       messageHistory: history,
       summaries: [
         { id: "sum-1", content: "All summarized.", focusSections: [] },
diff --git a/packages/context/tests/llm-content-parts.test.ts b/packages/context/tests/llm-content-parts.test.ts
index bff9ff65..da5fc10a 100644
--- a/packages/context/tests/llm-content-parts.test.ts
+++ b/packages/context/tests/llm-content-parts.test.ts
@@ -71,7 +71,6 @@ function makeBaseParams(
     manifest: makeManifest(),
     turnInput: makeTurnInput(),
     completedResults: new Map(),
-    config: {},
     messageHistory: history,
   };
 }
diff --git a/packages/context/tests/prompt-assembler.test.ts b/packages/context/tests/prompt-assembler.test.ts
index 9b144b6a..3676f21c 100644
--- a/packages/context/tests/prompt-assembler.test.ts
+++ b/packages/context/tests/prompt-assembler.test.ts
@@ -56,7 +56,6 @@ function baselineParams(
     manifest: makeManifest(),
     turnInput: makeTurnInput(),
     completedResults: new Map(),
-    config: {},
     ...overrides,
   };
 }
diff --git a/packages/context/tests/working-memory-injection.test.ts b/packages/context/tests/working-memory-injection.test.ts
index 0f8e3ad3..39df41fc 100644
--- a/packages/context/tests/working-memory-injection.test.ts
+++ b/packages/context/tests/working-memory-injection.test.ts
@@ -40,7 +40,6 @@ function makeParams(
       locale: undefined,
     },
     completedResults: new Map(),
-    config: {},
     ...overrides,
   };
 }
diff --git a/packages/memory/src/vector-ingest.ts b/packages/memory/src/vector-ingest.ts
index f82971ef..12264308 100644
--- a/packages/memory/src/vector-ingest.ts
+++ b/packages/memory/src/vector-ingest.ts
@@ -111,17 +111,6 @@ async function ingestRecall(
   embed: EmbedFn,
   sessionId: string,
 ): Promise<number> {
-  const messages = (await store.listTurnMessages(sessionId)).filter((m) =>
-    String(m.content ?? "").trim(),
-  );
-  if (messages.length === 0) return 0;
-
-  // Deterministic order (createdAt, id) so a same-millisecond tie cannot make
-  // the cursor skip a message across backends with different secondary sorts.
-  // Uses the SAME comparator as `isAfterCursor` so sort order and cursor
-  // advancement can never disagree.
-  const sorted = [...messages].sort(compareByCursor);
-
   const cursor = await readPluginJson<RecallCursor>(
     store,
     sessionId,
@@ -129,21 +118,39 @@ async function ingestRecall(
     CURSOR_KEY,
   );
 
-  const pending = sorted.filter((m) => isAfterCursor(m, cursor));
-  if (pending.length === 0) return 0;
+  // Keyset read of just the batch window past the cursor — the store orders by
+  // the same `(createdAt, id)` total order the cursor is written in, so a long
+  // session never streams its whole history through this per-turn sweep.
+  const batch = await store.listTurnMessagesAfter(
+    sessionId,
+    cursor,
+    MAX_INGEST_BATCH,
+  );
+  if (batch.length === 0) return 0;
 
-  const batch = pending.slice(0, MAX_INGEST_BATCH);
-  const vectors = await embed(batch.map((m) => String(m.content)));
+  const isEmbeddable = (m: { content?: unknown }): boolean =>
+    Boolean(String(m.content ?? "").trim());
+  const embeddable = batch.filter(isEmbeddable);
+  const vectors = embeddable.length
+    ? await embed(embeddable.map((m) => String(m.content)))
+    : [];
 
   let written = 0;
-  // Only advance the cursor past messages we actually persisted. If `embed`
-  // returns an empty/short array for some entry, we skip it WITHOUT moving the
-  // cursor beyond it, so the next sweep retries it — otherwise a transient empty
+  // Advance the cursor only past messages we handled: persisted embeddings and
+  // empty-content rows (which are never embeddable, so skipping them forward is
+  // what keeps a run of blank rows from stalling the cursor forever). If
+  // `embed` returns an empty/short array for some entry, stop WITHOUT moving
+  // past it, so the next sweep retries it — otherwise a transient empty
   // embedding would silently drop that message from recall forever.
-  let lastWritten: { createdAt: string; id: string } | null = null;
-  for (let i = 0; i < batch.length; i += 1) {
-    const msg = batch[i];
-    const embedding = vectors[i];
+  let lastHandled: RecallCursor | null = null;
+  let vectorIndex = 0;
+  for (const msg of batch) {
+    if (!isEmbeddable(msg)) {
+      lastHandled = { createdAt: msg.createdAt, id: msg.id };
+      continue;
+    }
+    const embedding = vectors[vectorIndex];
+    vectorIndex += 1;
     if (!embedding || embedding.length === 0) break;
     await store.upsertVector({
       sessionId,
@@ -159,42 +166,21 @@ async function ingestRecall(
       }),
     });
     written += 1;
-    lastWritten = { createdAt: msg.createdAt, id: msg.id };
+    lastHandled = { createdAt: msg.createdAt, id: msg.id };
   }
 
-  if (lastWritten) {
+  if (lastHandled) {
     await writePluginJson<RecallCursor>(
       store,
       sessionId,
       CURSOR_NS,
       CURSOR_KEY,
-      lastWritten,
+      lastHandled,
     );
   }
   return written;
 }
 
-/**
- * Total order on `(createdAt, id)` — the single comparator used for both the
- * ingest sort and the cursor "is this after the cursor?" check, so the two can
- * never disagree. `localeCompare` (not raw `<`/`>`) keeps the ordering stable
- * regardless of field contents.
- */
-function compareByCursor(
-  a: { createdAt: string; id: string },
-  b: { createdAt: string; id: string },
-): number {
-  return a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id);
-}
-
-function isAfterCursor(
-  msg: { createdAt: string; id: string },
-  cursor: RecallCursor | null,
-): boolean {
-  if (!cursor) return true;
-  return compareByCursor(msg, cursor) > 0;
-}
-
 // ── Archival (lorebook + characters, hash-incremental) ───────────
 
 interface ArchivalItem {
diff --git a/packages/plugin-loader/src/types.ts b/packages/plugin-loader/src/types.ts
index c1400bb1..92e319af 100644
--- a/packages/plugin-loader/src/types.ts
+++ b/packages/plugin-loader/src/types.ts
@@ -401,7 +401,6 @@ export interface FunctionHandlerContext {
    */
   readonly store: FunctionStoreView | unknown;
   readonly completedResults: ReadonlyMap<string, unknown>;
-  readonly config: Readonly<Record<string, unknown>>;
   /**
    * Optional gateway facade for function runtimes that need LLM / image /
    * structured-object generation. Absent when the executor was constructed
diff --git a/packages/plugin-test-utils/src/manual-context.ts b/packages/plugin-test-utils/src/manual-context.ts
index cafd305d..f9e2144e 100644
--- a/packages/plugin-test-utils/src/manual-context.ts
+++ b/packages/plugin-test-utils/src/manual-context.ts
@@ -13,7 +13,6 @@ export interface ManualFunctionContextOptions {
   readonly locale?: string;
   readonly store?: unknown;
   readonly completedResults?: ReadonlyMap<string, unknown>;
-  readonly config?: Readonly<Record<string, unknown>>;
   readonly manualPayload?: Readonly<Record<string, unknown>>;
 }
 
@@ -26,7 +25,6 @@ export function makeManualFunctionContext({
   locale,
   store = {},
   completedResults = new Map(),
-  config = {},
   manualPayload = {},
 }: ManualFunctionContextOptions): FunctionHandlerContext {
   return {
@@ -38,7 +36,6 @@ export function makeManualFunctionContext({
     ...(locale ? { locale } : {}),
     store,
     completedResults,
-    config,
     recursiveCall: async () => {
       throw new Error("recursiveCall is not configured for this test context");
     },
diff --git a/packages/plugin-test-utils/tests/plugin-test-utils.test.ts b/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
index 9866dbe7..668ce244 100644
--- a/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
+++ b/packages/plugin-test-utils/tests/plugin-test-utils.test.ts
@@ -75,7 +75,6 @@ describe("makeManualFunctionContext", () => {
     expect(ctx.runtimeId).toBe("character-blueprint/import");
     expect(ctx.playerMessage).toBe("");
     expect(ctx.completedResults).toBeInstanceOf(Map);
-    expect(ctx.config).toEqual({});
     expect(ctx.manualPayload).toEqual({ blueprint: { id: "mentor-lin" } });
   });
 
@@ -88,14 +87,12 @@ describe("makeManualFunctionContext", () => {
       turnId: "turn-custom",
       store,
       completedResults,
-      config: { tone: "quiet" },
     });
 
     expect(ctx.sessionId).toBe("sess-custom");
     expect(ctx.turnId).toBe("turn-custom");
     expect(ctx.store).toBe(store);
     expect(ctx.completedResults).toBe(completedResults);
-    expect(ctx.config).toEqual({ tone: "quiet" });
   });
 });
 
diff --git a/packages/runtime/src/agent-loop/tool-executor.ts b/packages/runtime/src/agent-loop/tool-executor.ts
index 028f94c0..91b4477d 100644
--- a/packages/runtime/src/agent-loop/tool-executor.ts
+++ b/packages/runtime/src/agent-loop/tool-executor.ts
@@ -17,7 +17,6 @@ import {
   getPendingProposals,
   getToolContent,
   type EmittedEvent,
-  type ToolClient,
   type ToolModule,
 } from "@covel/tools";
 import type { DataStore } from "@covel/store";
@@ -107,11 +106,6 @@ export interface ToolExecutorConfig {
     name: string,
     context?: ToolCallContext,
   ) => ToolModule | undefined;
-  /** Tool client lookup function — returns the execution client by name. */
-  readonly findToolClient?: (
-    name: string,
-    context?: ToolCallContext,
-  ) => ToolClient | undefined;
   /** Optional DataStore for recording tool calls. */
   readonly store?: DataStore;
   /** Optional approval pipeline for permission checking. */
@@ -205,23 +199,14 @@ function resolveToolModule(
   name: string,
   context?: ToolCallContext,
 ): ToolModule | undefined {
-  const direct = config.findTool?.(name, context);
-  if (direct) return direct;
-  const client = config.findToolClient?.(name, context);
-  if (client instanceof InMemoryToolClient) {
-    return client.get(name)?.module;
-  }
-  return undefined;
+  return config.findTool?.(name, context);
 }
 
 function resolveToolClient(
   config: ToolExecutorConfig,
   name: string,
   context: ToolCallContext,
-): ToolClient | undefined {
-  const client = config.findToolClient?.(name, context);
-  if (client) return client;
-
+): InMemoryToolClient | undefined {
   const tool = config.findTool?.(name, context);
   if (!tool) return undefined;
 
diff --git a/packages/runtime/src/agent-loop/turn-agent-guard.ts b/packages/runtime/src/agent-loop/turn-agent-guard.ts
index ddf90aa6..d0b9fc58 100644
--- a/packages/runtime/src/agent-loop/turn-agent-guard.ts
+++ b/packages/runtime/src/agent-loop/turn-agent-guard.ts
@@ -67,7 +67,6 @@ export async function executeAgentGuard({
 }: ExecuteAgentGuardOptions): Promise<RuntimeResult | undefined> {
   // ── Guard: pre-execution gate for agent runtimes ────────────
   if (loaded.guard) {
-    const guardConfig = deps.getConfig(manifest.pluginId, manifest.name);
     const guardManualPayload =
       input.manualTrigger?.runtimeId === manifest.name
         ? input.manualTrigger.payload
@@ -209,7 +208,6 @@ export async function executeAgentGuard({
       locale: input.locale,
       store: guardStore,
       completedResults,
-      config: guardConfig,
       recursiveCall: guardRecursiveCall,
       recursionDepth,
       ...(deps.gateway && trustedGuard
diff --git a/packages/runtime/src/agent-loop/turn-agent-runtime.ts b/packages/runtime/src/agent-loop/turn-agent-runtime.ts
index 1b159d71..13428129 100644
--- a/packages/runtime/src/agent-loop/turn-agent-runtime.ts
+++ b/packages/runtime/src/agent-loop/turn-agent-runtime.ts
@@ -131,9 +131,6 @@ export async function executeAgentRuntime({
     }
   }
 
-  // Build context
-  const config = deps.getConfig(manifest.pluginId, manifest.name);
-
   // TODO(S2): Tool-pair pruning safety — budget pruning does not understand
   // assistant↔tool message pairing (see T2 review I1). Skip budget injection
   // whenever this runtime declares tools via any of the four tool-declaration
@@ -203,7 +200,6 @@ export async function executeAgentRuntime({
     activeManifests: [loaded.manifest],
     turnInput: input,
     completedResults,
-    config,
     messageHistory: filteredHistory,
     sessionMeta,
     summaries: sessionSummaries ?? [],
diff --git a/packages/runtime/src/function-runtime/turn-function-runtime.ts b/packages/runtime/src/function-runtime/turn-function-runtime.ts
index 67498924..77312a45 100644
--- a/packages/runtime/src/function-runtime/turn-function-runtime.ts
+++ b/packages/runtime/src/function-runtime/turn-function-runtime.ts
@@ -137,7 +137,6 @@ export async function executeFunctionRuntime({
       failed,
     );
   }
-  const config = deps.getConfig(manifest.pluginId, manifest.name);
   const manualPayloadForRuntime =
     input.manualTrigger?.runtimeId === manifest.name
       ? input.manualTrigger.payload
@@ -240,7 +239,6 @@ export async function executeFunctionRuntime({
       locale: input.locale,
       store: handlerStore,
       completedResults,
-      config,
       recursiveCall: createRecursiveCall(),
       recursionDepth,
       ...(tracedGateway ? { gateway: tracedGateway } : {}),
diff --git a/packages/runtime/src/turn-executor/turn-executor-types.ts b/packages/runtime/src/turn-executor/turn-executor-types.ts
index 7ecb5d13..dd0aacd3 100644
--- a/packages/runtime/src/turn-executor/turn-executor-types.ts
+++ b/packages/runtime/src/turn-executor/turn-executor-types.ts
@@ -117,11 +117,6 @@ export interface TurnExecutorDeps extends AgentLoopDeps {
    * author-supplied `pluginType` manifest field.
    */
   readonly getPluginSource?: (pluginId: string) => PluginSource | undefined;
-  /** Get effective config for a plugin/runtime. */
-  readonly getConfig: (
-    pluginId: string,
-    runtimeId: string,
-  ) => Readonly<Record<string, unknown>>;
 
   /** Called when a runtime starts execution. */
   readonly onRuntimeStart?: (info: {
diff --git a/packages/runtime/src/turn-executor/turn-executor.ts b/packages/runtime/src/turn-executor/turn-executor.ts
index fd21343e..2238a1ec 100644
--- a/packages/runtime/src/turn-executor/turn-executor.ts
+++ b/packages/runtime/src/turn-executor/turn-executor.ts
@@ -97,7 +97,7 @@ export {
  * const result = await executeTurn(
  *   { sessionId: 'sess-1', turnId: 'turn-1', playerMessage: 'Go north' },
  *   activeManifests,
- *   { loadRuntime, llm, getConfig: () => ({}), store, toolExecutor },
+ *   { loadRuntime, llm, store, toolExecutor },
  * );
  *
  * for (const rr of result.runtimeResults) {
diff --git a/packages/runtime/tests/agent-guard-timeout.test.ts b/packages/runtime/tests/agent-guard-timeout.test.ts
index 8a925526..65b8cd73 100644
--- a/packages/runtime/tests/agent-guard-timeout.test.ts
+++ b/packages/runtime/tests/agent-guard-timeout.test.ts
@@ -57,7 +57,6 @@ function makeDeps(
   return {
     loadRuntime: async () => loaded,
     llm: baseLLM,
-    getConfig: () => ({}),
     ...extra,
   } as TurnExecutorDeps;
 }
diff --git a/packages/runtime/tests/core-plugin-char-creator-bridge.test.ts b/packages/runtime/tests/core-plugin-char-creator-bridge.test.ts
index 5b67f36e..2b0db625 100644
--- a/packages/runtime/tests/core-plugin-char-creator-bridge.test.ts
+++ b/packages/runtime/tests/core-plugin-char-creator-bridge.test.ts
@@ -119,7 +119,6 @@ describe("char-creator core plugin guard bridge", () => {
         };
       },
       llm,
-      getConfig: () => ({}),
       getPluginSource: (pluginId) =>
         pluginId === "char-creator" || pluginId === "narrator"
           ? "builtin"
diff --git a/packages/runtime/tests/core-plugin-npc-graph-inject.test.ts b/packages/runtime/tests/core-plugin-npc-graph-inject.test.ts
index 6ef84a17..e62a4fc4 100644
--- a/packages/runtime/tests/core-plugin-npc-graph-inject.test.ts
+++ b/packages/runtime/tests/core-plugin-npc-graph-inject.test.ts
@@ -169,7 +169,6 @@ describe("npc-graph core plugin write-read-inject path", () => {
         };
       },
       llm,
-      getConfig: () => ({}),
       store,
     };
 
diff --git a/packages/runtime/tests/emit-event-integration.test.ts b/packages/runtime/tests/emit-event-integration.test.ts
index ea3cbe86..92e39b79 100644
--- a/packages/runtime/tests/emit-event-integration.test.ts
+++ b/packages/runtime/tests/emit-event-integration.test.ts
@@ -130,7 +130,6 @@ describe("emit-event: tool-loop accumulation + finalize merge into output.events
         };
       },
       llm: new ScriptedLLM(),
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -226,7 +225,6 @@ describe("emit-event: segment 5 directory injection (plan task 5)", () => {
         promptTemplate: "You are a domain-event emitter.",
       }),
       llm: new CapturingLLM(),
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -307,7 +305,6 @@ describe("emit-event: same-turn duplicate topic no-op (plan task 1)", () => {
         promptTemplate: "Emit test.ping via emit-event.",
       }),
       llm: new RepeatingLLM(),
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
diff --git a/packages/runtime/tests/function-runtime-trace.test.ts b/packages/runtime/tests/function-runtime-trace.test.ts
index 444f2a1f..313f1c56 100644
--- a/packages/runtime/tests/function-runtime-trace.test.ts
+++ b/packages/runtime/tests/function-runtime-trace.test.ts
@@ -110,7 +110,6 @@ describe("function-runtime trace (A2-P1-5)", () => {
     return {
       loadRuntime: async () => loaded,
       llm: baseLLM,
-      getConfig: () => ({}),
       store,
       eventBus,
       ...extra,
diff --git a/packages/runtime/tests/hook-own-settings.test.ts b/packages/runtime/tests/hook-own-settings.test.ts
index 7757b089..ea04866e 100644
--- a/packages/runtime/tests/hook-own-settings.test.ts
+++ b/packages/runtime/tests/hook-own-settings.test.ts
@@ -259,7 +259,6 @@ describe("executeTurn → hook getOwnSettings end-to-end", () => {
         promptTemplate: "Say something.",
       }),
       llm: new SimpleMockLLM(),
-      getConfig: () => ({}),
       hookPipeline: pipeline,
       store: await createMainLoopStore(sessionId),
     };
diff --git a/packages/runtime/tests/hook-wire-turn-executor.test.ts b/packages/runtime/tests/hook-wire-turn-executor.test.ts
index a152f2b2..b672955d 100644
--- a/packages/runtime/tests/hook-wire-turn-executor.test.ts
+++ b/packages/runtime/tests/hook-wire-turn-executor.test.ts
@@ -94,7 +94,6 @@ async function makeDeps(
       promptTemplate: "Say something.",
     }),
     llm,
-    getConfig: () => ({}),
     hookPipeline,
     store: store ?? (await createMainLoopStore("sess-hook-wire")),
   };
@@ -229,7 +228,6 @@ describe("Turn executor hook wire-in", () => {
           promptTemplate: "Use tools.",
         }),
         llm,
-        getConfig: () => ({}),
         toolExecutor,
         hookPipeline: pipeline,
         store: await createMainLoopStore("sess-hook-wire"),
@@ -369,7 +367,6 @@ describe("Turn executor hook wire-in", () => {
           promptTemplate: "Use tools.",
         }),
         llm,
-        getConfig: () => ({}),
         toolExecutor,
         hookPipeline: pipeline,
         store: await createMainLoopStore("sess-hook-wire"),
@@ -454,7 +451,6 @@ describe("Turn executor hook wire-in", () => {
           promptTemplate: "Say something.",
         }),
         llm,
-        getConfig: () => ({}),
         hookPipeline: pipeline,
         store: await createMainLoopStore("sess-hook-wire"),
       };
@@ -661,7 +657,6 @@ describe("Turn executor hook wire-in", () => {
           promptTemplate: "Use tools.",
         }),
         llm,
-        getConfig: () => ({}),
         toolExecutor,
         hookPipeline: pipeline,
         store: await createMainLoopStore("sess-hook-wire"),
@@ -735,7 +730,6 @@ describe("Turn executor hook wire-in", () => {
           promptTemplate: "Use tools.",
         }),
         llm,
-        getConfig: () => ({}),
         toolExecutor,
         hookPipeline: pipeline,
         store: await createMainLoopStore("sess-hook-wire"),
diff --git a/packages/runtime/tests/pre-game-completion-contract.test.ts b/packages/runtime/tests/pre-game-completion-contract.test.ts
index 498a0ef5..41df5eac 100644
--- a/packages/runtime/tests/pre-game-completion-contract.test.ts
+++ b/packages/runtime/tests/pre-game-completion-contract.test.ts
@@ -83,7 +83,6 @@ async function runPregameTurn(
       guard: options?.guards?.[m.name],
     }),
     llm: new NoopLLM(),
-    getConfig: () => ({}),
     store,
   };
   const result = await executeTurn(input, manifests, deps);
@@ -177,7 +176,6 @@ describe("Pre-Game completion contract", () => {
             : { form: { formId: "character-form" } },
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
 
@@ -226,7 +224,6 @@ describe("Pre-Game completion contract", () => {
         },
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
 
@@ -363,7 +360,6 @@ describe("Pre-Game completion contract", () => {
         },
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
     await executeTurn(
diff --git a/packages/runtime/tests/require-tool-use.test.ts b/packages/runtime/tests/require-tool-use.test.ts
index 53a98a16..2d9731c9 100644
--- a/packages/runtime/tests/require-tool-use.test.ts
+++ b/packages/runtime/tests/require-tool-use.test.ts
@@ -116,7 +116,6 @@ describe("requireToolUse gate", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: toolExecutor(store),
     };
@@ -153,7 +152,6 @@ describe("requireToolUse gate", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: toolExecutor(store),
     };
@@ -181,7 +179,6 @@ describe("requireToolUse gate", () => {
       const deps: TurnExecutorDeps = {
         loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
         llm,
-        getConfig: () => ({}),
         store,
         toolExecutor: toolExecutor(store),
       };
@@ -215,7 +212,6 @@ describe("requireToolUse gate", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: toolExecutor(store),
     };
diff --git a/packages/runtime/tests/runtime-images-wiring.test.ts b/packages/runtime/tests/runtime-images-wiring.test.ts
index 8a1f4066..a1aefe8a 100644
--- a/packages/runtime/tests/runtime-images-wiring.test.ts
+++ b/packages/runtime/tests/runtime-images-wiring.test.ts
@@ -88,7 +88,6 @@ async function runWithHandler(
         usage: { inputTokens: 0, outputTokens: 0 },
       }),
     },
-    getConfig: () => ({}),
     store,
     ...extraDeps,
   };
diff --git a/packages/runtime/tests/runtime-speech-wiring.test.ts b/packages/runtime/tests/runtime-speech-wiring.test.ts
index cabc7191..2e46fc6a 100644
--- a/packages/runtime/tests/runtime-speech-wiring.test.ts
+++ b/packages/runtime/tests/runtime-speech-wiring.test.ts
@@ -88,7 +88,6 @@ async function runWithHandler(
         usage: { inputTokens: 0, outputTokens: 0 },
       }),
     },
-    getConfig: () => ({}),
     store,
     ...extraDeps,
   };
diff --git a/packages/runtime/tests/scene-stage-integration.test.ts b/packages/runtime/tests/scene-stage-integration.test.ts
index 02b2a383..3b8f319c 100644
--- a/packages/runtime/tests/scene-stage-integration.test.ts
+++ b/packages/runtime/tests/scene-stage-integration.test.ts
@@ -150,7 +150,6 @@ describe("scene-stage: scene.set → resolver → stage/current (E → B integra
             ? { manifest: m, promptTemplate: "Emit scene.set via emit-event." }
             : resolverLoaded,
         llm: new SceneSetLLM(data),
-        getConfig: () => ({}),
         store,
         toolExecutor: createToolExecutor({
           findTool: (name) =>
diff --git a/packages/runtime/tests/start-game-flow-scenario.test.ts b/packages/runtime/tests/start-game-flow-scenario.test.ts
index 75232581..5e9de6c8 100644
--- a/packages/runtime/tests/start-game-flow-scenario.test.ts
+++ b/packages/runtime/tests/start-game-flow-scenario.test.ts
@@ -142,7 +142,6 @@ function makeRuntimeHarness(store: DataStore): {
     deps: {
       loadRuntime: async (manifest) => loaded.get(manifest.name),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     },
   };
diff --git a/packages/runtime/tests/tool-executor-text-result.test.ts b/packages/runtime/tests/tool-executor-text-result.test.ts
index a8bbd3ed..71d9a726 100644
--- a/packages/runtime/tests/tool-executor-text-result.test.ts
+++ b/packages/runtime/tests/tool-executor-text-result.test.ts
@@ -18,8 +18,7 @@ import type {
 } from "../src/agent-loop/tool-executor.js";
 import { createMemoryStore } from "@covel/store";
 import type { DataStore } from "@covel/store";
-import { InMemoryToolClient, tool, withPendingProposals } from "@covel/tools";
-import type { ResolvedTool } from "@covel/tools";
+import { tool, withPendingProposals } from "@covel/tools";
 import { z } from "zod";
 
 const textFirstTool = tool({
@@ -69,16 +68,6 @@ const queuedTool = tool({
     ),
 });
 
-const clientResolvedTextTool: ResolvedTool = {
-  fullName: "text-first",
-  localName: "text-first",
-  pluginId: "test-plugin",
-  runtimeId: "test-rt",
-  module: textFirstTool,
-  source: "local",
-  requiresApproval: false,
-};
-
 function makeCall(name: string, args: Record<string, unknown>): ToolCall {
   return { toolCallId: `call-${name}`, name, arguments: JSON.stringify(args) };
 }
@@ -181,30 +170,4 @@ describe("ToolExecutor text-result convention", () => {
       }),
     ]);
   });
-
-  it("executes through an InMemoryToolClient when a client resolver is configured", async () => {
-    const client = new InMemoryToolClient({
-      id: "test-plugin:test-rt",
-      tools: [clientResolvedTextTool],
-    });
-    const executor = createToolExecutor({
-      findToolClient: (name) => (name === "text-first" ? client : undefined),
-      store,
-    });
-
-    const info = executor.getToolInfo("text-first", ctx);
-    expect(info?.name).toBe("text-first");
-
-    const result = await executor.execute(
-      makeCall("text-first", { name: "Client Path" }),
-      ctx,
-    );
-
-    expect(result.success).toBe(true);
-    expect(result.result).toBe("Character Client Path created successfully");
-    expect(result.parsedResult).toMatchObject({
-      characterId: "char-123",
-      name: "Client Path",
-    });
-  });
 });
diff --git a/packages/runtime/tests/turn-executor-abort.test.ts b/packages/runtime/tests/turn-executor-abort.test.ts
index 9bceda38..181fee2b 100644
--- a/packages/runtime/tests/turn-executor-abort.test.ts
+++ b/packages/runtime/tests/turn-executor-abort.test.ts
@@ -63,7 +63,6 @@ describe("executeTurn player abort", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
       llm,
-      getConfig: () => ({}),
       store,
       turnControl: { signal: controller.signal },
     };
@@ -119,7 +118,6 @@ describe("executeTurn player abort", () => {
         },
       }),
       llm: { generate: async () => prose("unused") } as LLMAdapter,
-      getConfig: () => ({}),
       store,
       turnControl: { signal: controller.signal },
     };
@@ -147,7 +145,6 @@ describe("executeTurn player abort", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (m) => ({ manifest: m, promptTemplate: "prompt" }),
       llm,
-      getConfig: () => ({}),
       store,
     };
 
diff --git a/packages/runtime/tests/turn-executor-budget-wiring.test.ts b/packages/runtime/tests/turn-executor-budget-wiring.test.ts
index 3340ec8f..89237c4e 100644
--- a/packages/runtime/tests/turn-executor-budget-wiring.test.ts
+++ b/packages/runtime/tests/turn-executor-budget-wiring.test.ts
@@ -85,7 +85,6 @@ async function makeBaseDeps(
   return {
     loadRuntime: async () => makeLoaded(manifest),
     llm,
-    getConfig: () => ({}),
     store: await createMainLoopStore("sess-budget-wire"),
   };
 }
diff --git a/packages/runtime/tests/turn-executor-dag-scheduler.test.ts b/packages/runtime/tests/turn-executor-dag-scheduler.test.ts
index 97b32b7f..d953abc8 100644
--- a/packages/runtime/tests/turn-executor-dag-scheduler.test.ts
+++ b/packages/runtime/tests/turn-executor-dag-scheduler.test.ts
@@ -135,7 +135,6 @@ describe("executeTurn main-loop DAG scheduler", () => {
         handler: makeHandler(m.name),
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store: await mainLoopStore("sess-dag"),
     };
 
diff --git a/packages/runtime/tests/turn-executor-events.test.ts b/packages/runtime/tests/turn-executor-events.test.ts
index 4630cac8..20dc0e56 100644
--- a/packages/runtime/tests/turn-executor-events.test.ts
+++ b/packages/runtime/tests/turn-executor-events.test.ts
@@ -95,7 +95,6 @@ describe("TurnExecutor EventBus Bridge", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       eventBus,
       store: await createMainLoopStore("sess-1"),
     };
@@ -144,7 +143,6 @@ describe("TurnExecutor EventBus Bridge", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       eventBus,
       store: await createMainLoopStore("sess-1"),
       memorySystem,
@@ -170,7 +168,6 @@ describe("TurnExecutor EventBus Bridge", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       eventBus,
       store: await createMainLoopStore("sess-1"),
     };
@@ -208,7 +205,6 @@ describe("TurnExecutor EventBus Bridge", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: failingLLM,
-      getConfig: () => ({}),
       eventBus,
       store: await createMainLoopStore("sess-1"),
     };
@@ -227,7 +223,6 @@ describe("TurnExecutor EventBus Bridge", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       // No eventBus
       store: await createMainLoopStore("sess-1"),
     };
diff --git a/packages/runtime/tests/turn-executor-manual-trigger.test.ts b/packages/runtime/tests/turn-executor-manual-trigger.test.ts
index 93bbd3a9..5ee55d3d 100644
--- a/packages/runtime/tests/turn-executor-manual-trigger.test.ts
+++ b/packages/runtime/tests/turn-executor-manual-trigger.test.ts
@@ -105,7 +105,6 @@ async function runTurn(
       },
     }),
     llm: new NoopLLM(),
-    getConfig: () => ({}),
     store,
     ...extraDeps,
   };
diff --git a/packages/runtime/tests/turn-executor-output-schema.test.ts b/packages/runtime/tests/turn-executor-output-schema.test.ts
index a8f52ec1..bc55efd4 100644
--- a/packages/runtime/tests/turn-executor-output-schema.test.ts
+++ b/packages/runtime/tests/turn-executor-output-schema.test.ts
@@ -62,7 +62,6 @@ describe("executeTurn: output.schema.json", () => {
         outputSchema: schema,
       }),
       llm,
-      getConfig: () => ({}),
       store: createMemoryStore(),
     };
 
@@ -109,7 +108,6 @@ describe("executeTurn: output.schema.json", () => {
         outputSchema: schema,
       }),
       llm,
-      getConfig: () => ({}),
       store: createMemoryStore(),
       toolExecutor,
     };
@@ -149,7 +147,6 @@ describe("executeTurn: output.schema.json", () => {
         outputSchema: schema,
       }),
       llm,
-      getConfig: () => ({}),
       store: createMemoryStore(),
     };
 
@@ -202,7 +199,6 @@ describe("executeTurn: output.schema.json", () => {
         outputSchema: schema,
       }),
       llm,
-      getConfig: () => ({}),
       store: createMemoryStore(),
     };
 
@@ -264,7 +260,6 @@ describe("executeTurn: output.schema.json", () => {
         outputSchema: schema,
       }),
       llm,
-      getConfig: () => ({}),
       store: createMemoryStore(),
     };
 
diff --git a/packages/runtime/tests/turn-executor-recursive-call.test.ts b/packages/runtime/tests/turn-executor-recursive-call.test.ts
index 0dbbdb70..3a7c36ab 100644
--- a/packages/runtime/tests/turn-executor-recursive-call.test.ts
+++ b/packages/runtime/tests/turn-executor-recursive-call.test.ts
@@ -71,7 +71,6 @@ describe("executeTurn recursiveCall", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (rt) => loaded.get(rt.name),
       llm: { generate: vi.fn() },
-      getConfig: () => ({}),
       emitter,
     };
 
@@ -129,7 +128,6 @@ describe("executeTurn recursiveCall", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async (rt) => loaded.get(rt.name),
       llm: { generate: vi.fn() },
-      getConfig: () => ({}),
       emitter,
     };
 
diff --git a/packages/runtime/tests/turn-executor-resilience.test.ts b/packages/runtime/tests/turn-executor-resilience.test.ts
index 4a3ae591..f11e599e 100644
--- a/packages/runtime/tests/turn-executor-resilience.test.ts
+++ b/packages/runtime/tests/turn-executor-resilience.test.ts
@@ -111,7 +111,6 @@ describe("TurnExecutor Resilience", () => {
       const deps: TurnExecutorDeps = {
         loadRuntime: async () => narratorLoaded,
         llm: mockLLM,
-        getConfig: () => ({}),
         onRuntimeStart: async () => {
           throw new Error("SSE write failed");
         },
@@ -133,7 +132,6 @@ describe("TurnExecutor Resilience", () => {
       const deps: TurnExecutorDeps = {
         loadRuntime: async () => narratorLoaded,
         llm: mockLLM,
-        getConfig: () => ({}),
         onRuntimeStart: () => Promise.reject(new Error("Connection closed")),
         store: await createMainLoopStore("sess-1"),
       };
@@ -157,7 +155,6 @@ describe("TurnExecutor Resilience", () => {
       const deps: TurnExecutorDeps = {
         loadRuntime: async () => narratorLoaded,
         llm: streamingLLM,
-        getConfig: () => ({}),
         onDelta: async () => {
           deltaCallCount++;
           throw new Error("Client disconnected");
diff --git a/packages/runtime/tests/turn-executor-session-context.test.ts b/packages/runtime/tests/turn-executor-session-context.test.ts
index de0359c2..192d9977 100644
--- a/packages/runtime/tests/turn-executor-session-context.test.ts
+++ b/packages/runtime/tests/turn-executor-session-context.test.ts
@@ -5,8 +5,7 @@
  * memory, summary, and character data to prompt-variable resolution.
  *
  * These tests verify:
- *   1. No `config` passed via `getConfig` + world data seeded via store → the
- *      prompt still receives `{{ world.lore }}` etc.
+ *   1. World data seeded via store → the prompt receives `{{ world.lore }}` etc.
  *   2. Snapshot build failure does not crash the turn.
  */
 
@@ -142,7 +141,7 @@ describe("turn-executor → SessionContextSnapshot wiring", () => {
     vi.restoreAllMocks();
   });
 
-  it("empty getConfig → snapshot world view populates prompt", async () => {
+  it("snapshot world view populates prompt", async () => {
     const store = createMemoryStore();
     const sessionId = "sess-sc-on";
     const worldId = "w-sc-on";
@@ -156,7 +155,6 @@ describe("turn-executor → SessionContextSnapshot wiring", () => {
       llm,
       // Deliberately empty: world variables must come from
       // SessionContextSnapshot, not from runtime config.
-      getConfig: () => ({}),
       store,
       // No worldDataPluginId — world.lore / world.tone come from WorldRecord
       // metadata alone, so the snapshot does not need plugin data for this.
@@ -213,7 +211,6 @@ describe("turn-executor → SessionContextSnapshot wiring", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => makeLoaded(manifest),
       llm,
-      getConfig: () => ({}),
       store: breakingStore,
       // No worldDataPluginId → listPluginData in snapshot loader is not
       // invoked. The snapshot build itself therefore succeeds using the
@@ -311,7 +308,6 @@ describe("turn-executor → SessionContextSnapshot wiring", () => {
         };
       },
       llm,
-      getConfig: () => ({}),
       store,
     };
 
diff --git a/packages/runtime/tests/turn-executor-stream-recovery.test.ts b/packages/runtime/tests/turn-executor-stream-recovery.test.ts
index 0c5a82ac..80abceaf 100644
--- a/packages/runtime/tests/turn-executor-stream-recovery.test.ts
+++ b/packages/runtime/tests/turn-executor-stream-recovery.test.ts
@@ -144,7 +144,6 @@ describe("TurnExecutor stream recovery (S1-T3)", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
       onDelta: async () => {
         /* consume deltas */
@@ -171,7 +170,6 @@ describe("TurnExecutor stream recovery (S1-T3)", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
       onDelta: async () => {
         /* no deltas expected */
@@ -197,7 +195,6 @@ describe("TurnExecutor stream recovery (S1-T3)", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
       onDelta: async () => {
         /* no deltas expected */
diff --git a/packages/runtime/tests/turn-executor-suspend.test.ts b/packages/runtime/tests/turn-executor-suspend.test.ts
index 9e9dabcc..cd59aa89 100644
--- a/packages/runtime/tests/turn-executor-suspend.test.ts
+++ b/packages/runtime/tests/turn-executor-suspend.test.ts
@@ -200,7 +200,6 @@ describe("TurnExecutor — agent runtime suspend", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => agentLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -258,7 +257,6 @@ describe("TurnExecutor — agent runtime suspend", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => agentLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -329,7 +327,6 @@ describe("TurnExecutor — agent runtime suspend", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => agentLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -421,7 +418,6 @@ describe("TurnExecutor — agent runtime suspend", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => agentLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -481,7 +477,6 @@ describe("TurnExecutor — agent runtime suspend", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => agentLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -547,7 +542,6 @@ describe("TurnExecutor — function runtime suspend", () => {
           usage: { inputTokens: 0, outputTokens: 0 },
         }),
       },
-      getConfig: () => ({}),
       store,
       eventBus,
     };
@@ -598,7 +592,6 @@ describe("TurnExecutor — function runtime suspend", () => {
           usage: { inputTokens: 0, outputTokens: 0 },
         }),
       },
-      getConfig: () => ({}),
       getPluginSource: () => "community",
       store,
       eventBus,
@@ -642,7 +635,6 @@ describe("TurnExecutor — function runtime suspend", () => {
           usage: { inputTokens: 0, outputTokens: 0 },
         }),
       },
-      getConfig: () => ({}),
       getPluginSource: () => "community",
       store,
       eventBus,
@@ -739,7 +731,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -794,7 +785,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -865,7 +855,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -937,7 +926,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -984,7 +972,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -1022,7 +1009,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: mockToolExecutor,
       eventBus,
@@ -1068,7 +1054,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       eventBus,
     };
@@ -1130,7 +1115,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       eventBus,
     };
@@ -1160,7 +1144,6 @@ describe("resumeSuspendedRuntime", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => undefined,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
       eventBus,
     };
diff --git a/packages/runtime/tests/turn-executor-trace.test.ts b/packages/runtime/tests/turn-executor-trace.test.ts
index 8c89a7d6..0e5c1dc2 100644
--- a/packages/runtime/tests/turn-executor-trace.test.ts
+++ b/packages/runtime/tests/turn-executor-trace.test.ts
@@ -82,7 +82,6 @@ describe("turn-executor message.completed trace emission", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       emitter,
     };
@@ -131,7 +130,6 @@ describe("turn-executor message.completed trace emission", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       emitter,
     };
@@ -189,7 +187,6 @@ describe("turn-executor direct-generate error trace pairing (Q1)", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       emitter,
       toolExecutor: createToolExecutor({
diff --git a/packages/runtime/tests/turn-executor-turn-result-always-saved.test.ts b/packages/runtime/tests/turn-executor-turn-result-always-saved.test.ts
index c37b8757..ac3b289d 100644
--- a/packages/runtime/tests/turn-executor-turn-result-always-saved.test.ts
+++ b/packages/runtime/tests/turn-executor-turn-result-always-saved.test.ts
@@ -67,7 +67,6 @@ describe("executeTurn: saveTurnResult invariant", () => {
         handler: async () => ({ preGameDone: true }),
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
     await executeTurn(
@@ -89,7 +88,6 @@ describe("executeTurn: saveTurnResult invariant", () => {
         },
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
     await executeTurn(
@@ -115,7 +113,6 @@ describe("executeTurn: saveTurnResult invariant", () => {
         promptTemplate: "",
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
     await executeTurn(
@@ -137,7 +134,6 @@ describe("executeTurn: saveTurnResult invariant", () => {
         promptTemplate: "",
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store,
     };
     await executeTurn(
diff --git a/packages/runtime/tests/turn-executor-upstream-required.test.ts b/packages/runtime/tests/turn-executor-upstream-required.test.ts
index d092fdfe..37a9b13b 100644
--- a/packages/runtime/tests/turn-executor-upstream-required.test.ts
+++ b/packages/runtime/tests/turn-executor-upstream-required.test.ts
@@ -77,7 +77,6 @@ async function runTurn(
       handler: handlers[m.name],
     }),
     llm: new NoopLLM(),
-    getConfig: () => ({}),
     store: await mainLoopStore("sess-1"),
   };
   return executeTurn(input, manifests, deps);
@@ -174,7 +173,6 @@ describe("executeTurn: manifest.upstreamRequired", () => {
           : {}),
       }),
       llm: new NoopLLM(),
-      getConfig: () => ({}),
       store: await mainLoopStore("sess-1"),
     };
 
diff --git a/packages/runtime/tests/turn-executor-working-memory-injection.test.ts b/packages/runtime/tests/turn-executor-working-memory-injection.test.ts
index 19a38629..c0e8a554 100644
--- a/packages/runtime/tests/turn-executor-working-memory-injection.test.ts
+++ b/packages/runtime/tests/turn-executor-working-memory-injection.test.ts
@@ -146,7 +146,6 @@ describe("turn-executor → working memory injection", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => makeLoaded(manifest),
       llm,
-      getConfig: () => ({}),
       store,
     };
 
@@ -181,7 +180,6 @@ describe("turn-executor → working memory injection", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => makeLoaded(manifest),
       llm,
-      getConfig: () => ({}),
       store,
     };
 
diff --git a/packages/runtime/tests/turn-executor.test.ts b/packages/runtime/tests/turn-executor.test.ts
index 1d5c63ed..e110f2a0 100644
--- a/packages/runtime/tests/turn-executor.test.ts
+++ b/packages/runtime/tests/turn-executor.test.ts
@@ -110,7 +110,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -141,7 +140,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -156,7 +154,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -203,7 +200,6 @@ describe("TurnExecutor E2E", () => {
         return undefined;
       },
       llm: mockLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -258,7 +254,6 @@ describe("TurnExecutor E2E", () => {
       loadRuntime: async (manifest) =>
         manifest.name === "story-runtime" ? storyLoaded : helperLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       resolveModel,
       store: await createMainLoopStore("sess-1"),
     };
@@ -356,7 +351,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -382,7 +376,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: failingLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -405,7 +398,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store: await createMainLoopStore("sess-1"),
     };
 
@@ -426,7 +418,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
     };
 
@@ -525,7 +516,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => guideLoaded,
       llm: guideLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -605,7 +595,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -674,7 +663,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => lookupLoaded,
       llm: loopingLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -756,7 +744,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => loaded,
       llm: invalidGuideLLM,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) =>
@@ -806,7 +793,6 @@ describe("TurnExecutor E2E", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => narratorLoaded,
       llm: mockLLM,
-      getConfig: () => ({}),
       store,
     };
 
@@ -909,7 +895,6 @@ describe("TurnExecutor _interaction protocol", () => {
     const deps: TurnExecutorDeps = {
       loadRuntime: async () => charLoaded,
       llm: mockLLM as LLMAdapter,
-      getConfig: () => ({}),
       store,
       toolExecutor: createToolExecutor({
         findTool: (n) => toolMap.get(n),
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
index 864ca891..7e07ebfa 100644
--- a/packages/shared/src/types/plugin.ts
+++ b/packages/shared/src/types/plugin.ts
@@ -637,7 +637,7 @@ export interface RuntimeManifest {
    * inserted near the end of the message history, just before the Nth-from-last
    * message. Modeled after SillyTavern / NovelAI author's-note semantics.
    *
-   * The content supports template interpolation (`{{ config.xxx }}`, etc.)
+   * The content supports template interpolation (`{{ player.xxx }}`, etc.)
    * identical to the plugin body. Multiple active plugins' notes are merged
    * in priority order.
    */
diff --git a/packages/store/src/common/cursor.ts b/packages/store/src/common/cursor.ts
index 4b24b87f..aa90591d 100644
--- a/packages/store/src/common/cursor.ts
+++ b/packages/store/src/common/cursor.ts
@@ -20,7 +20,7 @@
  * model column collation, so it would be a codegen/migration change).
  */
 
-import { and, desc, eq, lt, or } from "drizzle-orm";
+import { and, asc, desc, eq, gt, lt, or } from "drizzle-orm";
 import type { Column, SQL } from "drizzle-orm";
 
 import type { CursorPageOpts } from "../records/pagination-records.js";
@@ -57,3 +57,28 @@ export function cursorPageWhere(
 export function cursorPageOrder(cols: CursorColumns): SQL[] {
   return [desc(cols.createdAt), desc(cols.id)];
 }
+
+/**
+ * WHERE for a forward keyset read: `sessionId = ?` plus, when a cursor is
+ * supplied, the strict `(createdAt, id) > (after.createdAt, after.id)` tuple
+ * predicate — the mirror of {@link cursorPageWhere} for oldest-first
+ * consumers that walk the log incrementally (vector-ingest's recall cursor).
+ */
+export function cursorAfterWhere(
+  cols: CursorColumns,
+  sessionId: string,
+  after?: { readonly createdAt: string; readonly id: string } | null,
+): SQL | undefined {
+  const base = eq(cols.sessionId, sessionId);
+  if (!after) return base;
+  const newer = or(
+    gt(cols.createdAt, after.createdAt),
+    and(eq(cols.createdAt, after.createdAt), gt(cols.id, after.id)),
+  );
+  return and(base, newer);
+}
+
+/** ORDER BY for a forward keyset read — oldest-first, no reverse needed. */
+export function cursorAfterOrder(cols: CursorColumns): SQL[] {
+  return [asc(cols.createdAt), asc(cols.id)];
+}
diff --git a/packages/store/src/common/pagination.ts b/packages/store/src/common/pagination.ts
index 0a6e03c2..f9fc5d2a 100644
--- a/packages/store/src/common/pagination.ts
+++ b/packages/store/src/common/pagination.ts
@@ -53,3 +53,25 @@ export function applyCursorPage<T extends Keyed>(
     : rowsAscending;
   return older.slice(-opts.limit);
 }
+
+/**
+ * Forward keyset read over rows already sorted ascending by `(createdAt, id)`:
+ * the first `limit` rows strictly after `after` (all rows from the start when
+ * `after` is null). The memory/idb counterpart to `cursorAfterWhere`.
+ * `limit <= 0` ⇒ `[]`.
+ */
+export function applyCursorAfter<T extends Keyed>(
+  rowsAscending: readonly T[],
+  after: { readonly createdAt: string; readonly id: string } | null,
+  limit: number,
+): T[] {
+  if (limit <= 0) return [];
+  const newer = after
+    ? rowsAscending.filter(
+        (r) =>
+          r.createdAt > after.createdAt ||
+          (r.createdAt === after.createdAt && r.id > after.id),
+      )
+    : rowsAscending;
+  return newer.slice(0, limit);
+}
diff --git a/packages/store/src/common/sql-session-journal-records.ts b/packages/store/src/common/sql-session-journal-records.ts
index c356e538..ee5b21b9 100644
--- a/packages/store/src/common/sql-session-journal-records.ts
+++ b/packages/store/src/common/sql-session-journal-records.ts
@@ -23,7 +23,12 @@
 import { and, asc, desc, eq, inArray, isNull, sql } from "drizzle-orm";
 import type { Column, Table } from "drizzle-orm";
 
-import { cursorPageOrder, cursorPageWhere } from "./cursor.js";
+import {
+  cursorAfterOrder,
+  cursorAfterWhere,
+  cursorPageOrder,
+  cursorPageWhere,
+} from "./cursor.js";
 import type { InsertValueBuilders } from "./insert-values.js";
 import type { JsonReader } from "./mappers.js";
 import {
@@ -94,6 +99,7 @@ export type SqlSessionJournalRecords = Pick<
   | "appendTurnMessage"
   | "listTurnMessages"
   | "listUncompactedTurnMessages"
+  | "listTurnMessagesAfter"
   | "getTurnMessageStats"
   | "listRecentTurnMessages"
   | "tagTurnMessagesCompacted"
@@ -171,6 +177,20 @@ export function createSqlSessionJournalRecords(
       return rows.map((row) => toTurnMessageRecord(row, json));
     },
 
+    async listTurnMessagesAfter(
+      sessionId: string,
+      after: { readonly createdAt: string; readonly id: string } | null,
+      limit: number,
+    ): Promise<TurnMessageRecord[]> {
+      if (limit <= 0) return [];
+      const rows = await runner.select<TurnMessageRow>(turnMessages, {
+        where: cursorAfterWhere(turnMessages, sessionId, after),
+        orderBy: cursorAfterOrder(turnMessages),
+        limit,
+      });
+      return rows.map((row) => toTurnMessageRecord(row, json));
+    },
+
     async getTurnMessageStats(sessionId: string): Promise<TurnMessageStats> {
       // Single grouped count over (sourceType, sourceRuntimeId); COUNT(*)
       // arrives as number on SQLite and string on PG, so normalise via Number.
diff --git a/packages/store/src/contract/suites/runtime-record-suites.ts b/packages/store/src/contract/suites/runtime-record-suites.ts
index 09520b36..a496f16c 100644
--- a/packages/store/src/contract/suites/runtime-record-suites.ts
+++ b/packages/store/src/contract/suites/runtime-record-suites.ts
@@ -538,6 +538,64 @@ export function registerRuntimeRecordStoreSuites(
       });
     });
 
+    it("listTurnMessagesAfter walks the log forward from a (createdAt, id) cursor", async () => {
+      // ts() is Date.now()-relative, so capture each timestamp once — the
+      // cursor must equal the stored createdAt byte-for-byte.
+      const t10 = ts(10);
+      const t20 = ts(20);
+      const t30 = ts(30);
+      // Two rows share a createdAt so the id tie-break is exercised — the
+      // cursor must pick the same boundary rows on every backend.
+      const m1 = makeTurnMessage({
+        id: "after-a",
+        sessionId: "sess-after",
+        createdAt: t10,
+      });
+      const m2 = makeTurnMessage({
+        id: "after-b",
+        sessionId: "sess-after",
+        createdAt: t10,
+      });
+      const m3 = makeTurnMessage({
+        id: "after-c",
+        sessionId: "sess-after",
+        createdAt: t20,
+      });
+      const m4 = makeTurnMessage({
+        id: "after-d",
+        sessionId: "sess-after",
+        createdAt: t30,
+      });
+      await store.appendTurnMessage(m3);
+      await store.appendTurnMessage(m1);
+      await store.appendTurnMessage(m4);
+      await store.appendTurnMessage(m2);
+
+      // Null cursor ⇒ from the start, capped at limit.
+      const first = await store.listTurnMessagesAfter("sess-after", null, 2);
+      expect(first.map((m) => m.id)).toEqual(["after-a", "after-b"]);
+
+      // Resume strictly after the same-createdAt boundary row.
+      const rest = await store.listTurnMessagesAfter(
+        "sess-after",
+        { createdAt: t10, id: "after-a" },
+        10,
+      );
+      expect(rest.map((m) => m.id)).toEqual(["after-b", "after-c", "after-d"]);
+
+      // Cursor at the tail ⇒ empty; limit <= 0 ⇒ empty.
+      expect(
+        await store.listTurnMessagesAfter(
+          "sess-after",
+          { createdAt: t30, id: "after-d" },
+          10,
+        ),
+      ).toEqual([]);
+      expect(await store.listTurnMessagesAfter("sess-after", null, 0)).toEqual(
+        [],
+      );
+    });
+
     it("getTurnMessageStats returns zeroed stats for an empty session", async () => {
       const stats = await store.getTurnMessageStats("sess-none");
       expect(stats.playerMessageCount).toBe(0);
diff --git a/packages/store/src/indexeddb/idb-runtime-store.ts b/packages/store/src/indexeddb/idb-runtime-store.ts
index 65c02bbc..cd78f674 100644
--- a/packages/store/src/indexeddb/idb-runtime-store.ts
+++ b/packages/store/src/indexeddb/idb-runtime-store.ts
@@ -18,7 +18,11 @@ import type {
   TurnMessageStats,
   TurnResultRecord,
 } from "../types.js";
-import { applyCursorPage, sortByCursorAsc } from "../common/pagination.js";
+import {
+  applyCursorAfter,
+  applyCursorPage,
+  sortByCursorAsc,
+} from "../common/pagination.js";
 import { computeTurnMessageStats } from "../common/turn-message-stats.js";
 import type { IdbStoreContext, IdbStoreSlice } from "./idb-context.js";
 import {
@@ -327,6 +331,19 @@ export function createIdbRuntimeStore(ctx: IdbStoreContext): IdbStoreSlice {
       return computeTurnMessageStats(all);
     },
 
+    async listTurnMessagesAfter(
+      sessionId: string,
+      after: { readonly createdAt: string; readonly id: string } | null,
+      limit: number,
+    ): Promise<TurnMessageRecord[]> {
+      const all = await listBySession<TurnMessageRecord>(
+        db,
+        "turnMessages",
+        sessionId,
+      );
+      return applyCursorAfter(sortByCursorAsc(all), after, limit);
+    },
+
     async listRecentTurnMessages(
       sessionId: string,
       limit: number,
diff --git a/packages/store/src/memory/runtime-methods.ts b/packages/store/src/memory/runtime-methods.ts
index 74e0c13b..7c4c3c7f 100644
--- a/packages/store/src/memory/runtime-methods.ts
+++ b/packages/store/src/memory/runtime-methods.ts
@@ -1,4 +1,5 @@
 import {
+  applyCursorAfter,
   applyCursorPage,
   applyPagination,
   sortByCursorAsc,
@@ -257,6 +258,13 @@ export function createRuntimeMethods(state: MemoryState): MemoryStoreMethods {
       );
     },
 
+    async listTurnMessagesAfter(sessionId, after, limit) {
+      const sorted = sortByCursorAsc(
+        state.turnMessages.filter((r) => r.sessionId === sessionId),
+      );
+      return applyCursorAfter(sorted, after, limit);
+    },
+
     async listRecentTurnMessages(sessionId, limit) {
       if (limit <= 0) return [];
       const sorted = sortByCursorAsc(
diff --git a/packages/store/src/types.ts b/packages/store/src/types.ts
index 041300fe..0d4dc1fa 100644
--- a/packages/store/src/types.ts
+++ b/packages/store/src/types.ts
@@ -383,6 +383,17 @@ export interface TurnMessageStore {
    * {@link listTurnMessages}.
    */
   listUncompactedTurnMessages(sessionId: string): Promise<TurnMessageRecord[]>;
+  /**
+   * Forward keyset read: the first `limit` messages strictly after the
+   * `(createdAt, id)` cursor position, oldest-first (all messages from the
+   * start when `after` is null). Lets incremental consumers (vector-ingest's
+   * recall cursor) walk the log without loading it whole. `limit <= 0` ⇒ `[]`.
+   */
+  listTurnMessagesAfter(
+    sessionId: string,
+    after: { readonly createdAt: string; readonly id: string } | null,
+    limit: number,
+  ): Promise<TurnMessageRecord[]>;
   /**
    * Aggregate counts over the FULL message log (compacted rows included),
    * resolved as a grouped count query on SQL backends. Replaces the per-turn
@@ -462,8 +473,8 @@ export interface LorebookStore {
   /**
    * List all session-scoped lorebook entries for the given session, sorted
    * by `insertionOrder` ascending then `id` ascending for deterministic
-   * output. Used by snapshot payload builder (FU-4) and by the context
-   * loader to populate `{{ config.worldEntries }}` for backward compatibility.
+   * output. Used by the snapshot payload builder (FU-4) and by the
+   * session-context loader's world-entries injection.
    */
   listSessionLorebookEntries(
     sessionId: string,
diff --git a/packages/test-runtime/src/cases.test.ts b/packages/test-runtime/src/cases.test.ts
index 18f039a5..27d53d9c 100644
--- a/packages/test-runtime/src/cases.test.ts
+++ b/packages/test-runtime/src/cases.test.ts
@@ -74,7 +74,6 @@ describe("runtime case helpers", () => {
           pluginId: "base-plugin",
           message: "base message",
           payload: { from: "base" },
-          config: { a: 1 },
           userSettings: { theme: "dark" },
           llmContent: "base",
           mockPresetId: "base-slot",
@@ -98,7 +97,6 @@ describe("runtime case helpers", () => {
       caseName: "case",
       message: "case message",
       payload: { from: "base" },
-      config: { a: 1 },
       userSettings: { theme: "dark" },
       llmContent: "base",
       mockPresetId: "case-slot",
diff --git a/packages/test-runtime/src/cases.ts b/packages/test-runtime/src/cases.ts
index 15859897..fbf70b13 100644
--- a/packages/test-runtime/src/cases.ts
+++ b/packages/test-runtime/src/cases.ts
@@ -15,7 +15,6 @@ export interface RuntimeCase {
   readonly pluginId?: string;
   readonly message?: string;
   readonly payload?: Record<string, unknown>;
-  readonly config?: Record<string, unknown>;
   readonly userSettings?: Record<string, unknown>;
   readonly llmResponse?: Record<string, unknown>;
   readonly llmResponses?: readonly Record<string, unknown>[];
@@ -77,7 +76,6 @@ export function buildCaseDebugOptions(args: {
     caseName: testCase.name,
     message: testCase.message ?? base.message,
     payload: testCase.payload ?? base.payload,
-    config: testCase.config ?? base.config,
     userSettings: testCase.userSettings ?? base.userSettings,
     llmResponse: testCase.llmResponse ?? base.llmResponse,
     llmResponses: testCase.llmResponses ?? base.llmResponses,
diff --git a/packages/test-runtime/src/cli.ts b/packages/test-runtime/src/cli.ts
index 8e65b247..797f58af 100755
--- a/packages/test-runtime/src/cli.ts
+++ b/packages/test-runtime/src/cli.ts
@@ -11,7 +11,6 @@ interface CliOptions {
   locale?: string;
   message?: string;
   payload?: Record<string, unknown>;
-  config?: Record<string, unknown>;
   userSettings?: Record<string, unknown>;
   llmResponse?: Record<string, unknown>;
   llmResponses?: readonly Record<string, unknown>[];
@@ -40,7 +39,6 @@ Options:
   --locale <locale>          Locale. Defaults to zh-CN.
   --message <text>           Player message for context. Defaults to empty.
   --payload <json>           manualTrigger payload JSON.
-  --config <json>            Config object returned by getConfig().
   --user-settings <json>     Plugin userSettings bucket for this plugin.
   --llm-content <text>       Mock LLM content for agent runtimes.
   --llm-object <json>        Mock LLM JSON object content (auto stringified — easier than --llm-content for JSON envelopes).
@@ -120,9 +118,6 @@ function parseArgs(argv: readonly string[]): CliOptions {
       case "--payload":
         options.payload = parseJsonObject(next(), "--payload");
         break;
-      case "--config":
-        options.config = parseJsonObject(next(), "--config");
-        break;
       case "--user-settings":
         options.userSettings = parseJsonObject(next(), "--user-settings");
         break;
diff --git a/packages/test-runtime/src/execution.test.ts b/packages/test-runtime/src/execution.test.ts
index 7ff6665d..00445d7d 100644
--- a/packages/test-runtime/src/execution.test.ts
+++ b/packages/test-runtime/src/execution.test.ts
@@ -208,7 +208,6 @@ describe("test-runtime execution helpers", () => {
       gateway,
       mediaStore: createMemoryMediaStore(),
       utils,
-      config: { temperature: 0.1 },
       userSettings: { enabled: true },
     });
 
@@ -232,7 +231,6 @@ describe("test-runtime execution helpers", () => {
       sessionId: SESSION_ID,
       pluginId: PLUGIN_ID,
       locale: "zh-CN",
-      config: { temperature: 0.1 },
       userSettings: { enabled: true },
       triggerEvent: { topic: "test.ready", data: { ok: true } },
     });
@@ -287,7 +285,6 @@ describe("test-runtime execution helpers", () => {
       gateway,
       mediaStore: createMemoryMediaStore(),
       utils,
-      config: {},
     });
 
     expect(job.status).toBe("failed");
@@ -334,7 +331,6 @@ describe("test-runtime execution helpers", () => {
       gateway,
       mediaStore: createMemoryMediaStore(),
       utils,
-      config: {},
     });
 
     expect(job.status).toBe("failed");
@@ -378,7 +374,6 @@ describe("test-runtime execution helpers", () => {
       gateway,
       mediaStore: createMemoryMediaStore(),
       utils,
-      config: {},
     });
 
     expect(job.status).toBe("failed");
@@ -405,7 +400,6 @@ describe("test-runtime execution helpers", () => {
         gateway,
         mediaStore: createMemoryMediaStore(),
         utils,
-        config: {},
       }),
     ).rejects.toThrow("deferred follower not found: plugin/follower");
 
@@ -424,7 +418,6 @@ describe("test-runtime execution helpers", () => {
         gateway,
         mediaStore: createMemoryMediaStore(),
         utils,
-        config: {},
       }),
     ).rejects.toThrow("deferred follower has no handler: plugin/follower");
   });
diff --git a/packages/test-runtime/src/execution.ts b/packages/test-runtime/src/execution.ts
index 3153acaf..3a11e304 100644
--- a/packages/test-runtime/src/execution.ts
+++ b/packages/test-runtime/src/execution.ts
@@ -91,7 +91,6 @@ export async function runDeferredFollower(args: {
   readonly gateway: PluginRuntimeGateway;
   readonly mediaStore: MediaStore;
   readonly utils: PluginRuntimeUtils;
-  readonly config: Record<string, unknown>;
   readonly userSettings?: Record<string, unknown>;
 }): Promise<DeferredFollowerJobResult> {
   const manifest = args.manifests.find(
@@ -145,7 +144,6 @@ export async function runDeferredFollower(args: {
       locale: args.locale,
       store: createFunctionStoreView(args.store, helperCtx),
       completedResults: new Map(),
-      config: args.config,
       recursiveCall: async () => {
         throw new Error(
           "recursiveCall is unavailable for test-runtime deferred followers",
diff --git a/packages/test-runtime/src/runner.ts b/packages/test-runtime/src/runner.ts
index 9f90d48a..7f258838 100644
--- a/packages/test-runtime/src/runner.ts
+++ b/packages/test-runtime/src/runner.ts
@@ -172,7 +172,6 @@ export async function runRuntimeDebug(
       utils: PLUGIN_UTILS,
       mediaStore,
       getPluginSource: () => discovery.source,
-      getConfig: () => options.config ?? {},
       store,
       toolExecutor: createToolExecutor({
         findTool: (name) => toolMap.get(name),
@@ -221,7 +220,6 @@ export async function runRuntimeDebug(
       gateway: liveAdapters?.gateway ?? makeGateway(options),
       mediaStore,
       utils: PLUGIN_UTILS,
-      config: options.config ?? {},
       ...(options.userSettings ? { userSettings: options.userSettings } : {}),
     });
     jobs.push({
diff --git a/packages/test-runtime/src/types.ts b/packages/test-runtime/src/types.ts
index 62a06b1d..b7f27bd2 100644
--- a/packages/test-runtime/src/types.ts
+++ b/packages/test-runtime/src/types.ts
@@ -15,7 +15,6 @@ export interface RunRuntimeDebugOptions {
   readonly locale?: string;
   readonly message?: string;
   readonly payload?: Record<string, unknown>;
-  readonly config?: Record<string, unknown>;
   readonly userSettings?: Record<string, unknown>;
   readonly llmResponse?: Record<string, unknown>;
   readonly llmResponses?: readonly Record<string, unknown>[];
diff --git a/plugins/world-init/tests/guard.test.ts b/plugins/world-init/tests/guard.test.ts
index f0066298..d293dca4 100644
--- a/plugins/world-init/tests/guard.test.ts
+++ b/plugins/world-init/tests/guard.test.ts
@@ -66,7 +66,6 @@ describe("world-init guard", () => {
       locale: "zh-CN",
       store,
       completedResults: new Map(),
-      config: {},
     });
 
     expect(result.skip).toBe(true);
@@ -168,7 +167,6 @@ describe("world-init guard", () => {
       locale: "zh-CN",
       store,
       completedResults: new Map(),
-      config: {},
     });
 
     expect(result.skip).toBe(true);

From 8b250b047f0d8dbe8aaf32dc0793353d3d77c89c Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 15:59:38 +0800
Subject: [PATCH 09/10] feat(runtime,tools): deferred tool loading via
 search-tools (BM25 tool discovery)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Runtimes with large tool whitelists can now declare tools.defer
(true = whole whitelist, string[] = listed names). Deferred tools stay
registered and authorized but are withheld from the initial LLM tool
list; the framework injects a search-tools definition instead, whose
description advertises the pool size and owner. When the LLM calls it,
the agent loop intercepts the call (suspend/runtime-done sentinel
pattern — never dispatched to the ToolExecutor), ranks the deferred
pool with BM25, and grows the working tool surface so matches are
directly callable from the next step for the rest of the turn.

Design follows openai/codex's tool_search (ToolExposure::Deferred +
BM25 over name/description/parameter-schema text, default limit 8):

- zero-dep BM25 (k1=1.2, b=0.75) in @covel/tools; CJK text tokenizes
  into character bigrams so Chinese queries match non-adjacent words
  ('解锁图鉴' → '解锁…图鉴条目'), with substring fallback
- corpus per tool = name + description + parameter-schema field
  names/descriptions (parameterSchemaSearchText)
- search-tools is framework-injected only: not registered in the tool
  map, not declarable in tools.builtin; searchable pool is exactly the
  runtime's own declared whitelist resolved through getToolInfo, so
  the builtin/local access boundary is inherited unchanged
- defer entries outside the whitelist are ignored — deferring can
  never grant access to an undeclared tool
- searches are traced as normal toolCalls records

No-defer runtimes are byte-identical to before (regression-pinned).

Docs: tools.md (registry row + search-tools contract), plugins.md
(tools.defer field), plugin-authoring-advanced.md (usage guidance).

Validation: 14 new tests (BM25 ranking/CJK/limits ×9, agent-loop
integration ×5); full workspace tests 40/40 tasks, lint 21/21,
prettier + oxlint clean.
---
 docs/guide/plugin-authoring-advanced.md       |  12 +
 docs/reference/plugins.md                     |  12 +
 docs/reference/tools.md                       |  72 ++++--
 .../src/agent-loop/agent-loop-policy.ts       |  17 +-
 .../runtime/src/agent-loop/tool-search.ts     | 176 ++++++++++++++
 .../src/agent-loop/turn-agent-tool-loop.ts    |  63 +++++-
 .../turn-executor/turn-executor-helpers.ts    |  33 +--
 .../runtime/tests/tool-search-loop.test.ts    | 214 ++++++++++++++++++
 packages/shared/src/types/plugin.ts           |  12 +
 packages/tools/src/builtin/tool-search.ts     | 208 +++++++++++++++++
 packages/tools/src/index.ts                   |  11 +
 packages/tools/tests/tool-search.test.ts      | 110 +++++++++
 12 files changed, 897 insertions(+), 43 deletions(-)
 create mode 100644 packages/runtime/src/agent-loop/tool-search.ts
 create mode 100644 packages/runtime/tests/tool-search-loop.test.ts
 create mode 100644 packages/tools/src/builtin/tool-search.ts
 create mode 100644 packages/tools/tests/tool-search.test.ts

diff --git a/docs/guide/plugin-authoring-advanced.md b/docs/guide/plugin-authoring-advanced.md
index 53057166..10290c2c 100644
--- a/docs/guide/plugin-authoring-advanced.md
+++ b/docs/guide/plugin-authoring-advanced.md
@@ -245,6 +245,18 @@ interface PluginManifest {
 }
 ```
 
+### 大工具集：延迟加载（`tools.defer`）
+
+如果一个 runtime 的工具白名单很大（经验阈值 ~10 个以上），每次 LLM 调用都全量携带所有工具的 JSON schema 会持续挤占 prompt 预算。声明 `tools.defer` 可以把部分或全部工具改为**按需检索**：
+
+```yaml
+tools:
+  plugin: [attack, defend, cast-spell, brew-potion, forge-item, ...]
+  defer: true # 或 defer: [brew-potion, forge-item] 只延迟低频工具
+```
+
+行为：被延迟的工具不进初始工具清单，框架注入 `search-tools`；LLM 用能力关键词（中英文均可）检索，命中的工具**下一步起**直接可调用，激活持续到本 turn 结束。工具注册、信任门控、审批策略完全不变——只是 schema 广播时机变了。高频工具建议留在 `defer` 之外（省一步检索往返）。详细契约见 [tools.md 的 search-tools 小节](../reference/tools.md#search-tools框架注入延迟工具加载)。
+
 ## 6. 函数 Runtime、手动触发与后台执行
 
 `runtimeType: function` 表示"跳过 LLM,直接执行 JS 模块"。用于调用外部 API、做纯计算、写 plugin-data 等不需要 LLM 推理的场景。
diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md
index 1fa4abbc..a1c13948 100644
--- a/docs/reference/plugins.md
+++ b/docs/reference/plugins.md
@@ -1453,6 +1453,18 @@ Covel 的核心设计原则是**插件承载游戏逻辑，框架提供原语和
 
 当框架需要区分插件行为时，应在 `RuntimeManifest` 中添加通用字段（如 `outputKind`、`capabilities`），而非在框架代码中添加条件分支。
 
+### 延迟工具加载：`tools.defer`
+
+工具白名单较大（>~10 个）的 runtime 可以声明延迟加载，避免每次 LLM 调用都全量预载所有工具 schema：
+
+```yaml
+tools:
+  plugin: [tool-a, tool-b, tool-c, ...] # entry 注册的工具名
+  defer: true # true = 延迟整个白名单；或 [tool-a, tool-b] 精确列出
+```
+
+被延迟的工具**照常注册、照常鉴权**，只是不进初始 LLM 工具清单；框架自动注入 `search-tools`（BM25 检索，中英文均可），LLM 检索命中的工具自下一步起可直接调用，激活状态持续到本 turn 结束。`defer` 数组中不在白名单内的名字会被忽略——延迟声明永远不能授予未声明的工具。详见 [docs/reference/tools.md](./tools.md#search-tools框架注入延迟工具加载)。
+
 ### Runtime 输出字段：`preGameDone`
 
 Pre-Game 段 runtime（priority `0-99`）可在 `RuntimeOutput` 中声明：
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 4dadcfba..5fa4e9c3 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -6,31 +6,32 @@
 
 ## 概览
 
-| 工具名                  | 来源    | 所属插件   | 审批策略   | 描述                                                                             |
-| ----------------------- | ------- | ---------- | ---------- | -------------------------------------------------------------------------------- |
-| create-form             | builtin | —          | auto-allow | 创建玩家表单                                                                     |
-| create-choices          | builtin | —          | auto-allow | 创建选项列表                                                                     |
-| create-notification     | builtin | —          | auto-allow | 显示通知消息                                                                     |
-| render-ui               | builtin | —          | auto-allow | 渲染带独立 part 状态的 UI 块                                                     |
-| plugin-data-set         | builtin | —          | auto-allow | 写入插件持久化数据（单条）                                                       |
-| plugin-data-set-batch   | builtin | —          | auto-allow | 批量写入插件持久化数据                                                           |
-| plugin-data-get         | builtin | —          | auto-allow | 读取当前插件持久化数据                                                           |
-| plugin-data-list        | builtin | —          | auto-allow | 列出当前插件持久化数据                                                           |
-| **create-character**    | builtin | —          | auto-allow | 创建角色（player/npc/companion），写 characters 表 + 镜像到 plugin-data          |
-| **update-character**    | builtin | —          | auto-allow | 按 id 更新角色描述/字段（shallow merge），自动 version++                         |
-| **list-characters**     | builtin | —          | auto-allow | 列出本 session 所有角色（session 作用域，跨插件可见）                            |
-| **get-character**       | builtin | —          | auto-allow | 按 id 或 name 查找单个角色                                                       |
-| **world-dimension-get** | builtin | —          | auto-allow | 按需读取当前 session 世界的结构化维度字段                                        |
-| **emit-event**          | builtin | —          | auto-allow | 发射当前 session 已声明的领域事件（一次一个 topic），校验 topic + payload schema |
-| **suspend**             | builtin | —          | auto-allow | 挂起当前 runtime 等待玩家输入，写 `suspensions` 表，可通过 resume API 恢复       |
-| **runtime-done**        | builtin | —          | auto-allow | Agent 工具循环的结束信号——业务工具调用完毕后调用以结束本 runtime                 |
-| **memory-search**       | builtin | —          | auto-allow | 搜索记忆：对话历史(recall) + 长期知识库(archival，含 codex/lorebook/角色)        |
-| **memory-get-block**    | builtin | —          | auto-allow | 读取一个核心记忆块的当前内容                                                     |
-| **memory-update-block** | builtin | —          | auto-allow | 更新（完整替换）一个核心记忆块。无 capability 门控——列入 tools.builtin 即可用    |
-| set-world-schema        | local   | world-init | auto-allow | 定义世界角色属性 Schema                                                          |
-| set-world-entries-batch | local   | world-init | auto-allow | 批量写入世界词条                                                                 |
-| unlock-codex-entries    | local   | codex      | auto-allow | 批量解锁图鉴条目                                                                 |
-| update-codex-entry      | local   | codex      | auto-allow | 更新已有图鉴条目                                                                 |
+| 工具名                  | 来源    | 所属插件   | 审批策略   | 描述                                                                                |
+| ----------------------- | ------- | ---------- | ---------- | ----------------------------------------------------------------------------------- |
+| create-form             | builtin | —          | auto-allow | 创建玩家表单                                                                        |
+| create-choices          | builtin | —          | auto-allow | 创建选项列表                                                                        |
+| create-notification     | builtin | —          | auto-allow | 显示通知消息                                                                        |
+| render-ui               | builtin | —          | auto-allow | 渲染带独立 part 状态的 UI 块                                                        |
+| plugin-data-set         | builtin | —          | auto-allow | 写入插件持久化数据（单条）                                                          |
+| plugin-data-set-batch   | builtin | —          | auto-allow | 批量写入插件持久化数据                                                              |
+| plugin-data-get         | builtin | —          | auto-allow | 读取当前插件持久化数据                                                              |
+| plugin-data-list        | builtin | —          | auto-allow | 列出当前插件持久化数据                                                              |
+| **create-character**    | builtin | —          | auto-allow | 创建角色（player/npc/companion），写 characters 表 + 镜像到 plugin-data             |
+| **update-character**    | builtin | —          | auto-allow | 按 id 更新角色描述/字段（shallow merge），自动 version++                            |
+| **list-characters**     | builtin | —          | auto-allow | 列出本 session 所有角色（session 作用域，跨插件可见）                               |
+| **get-character**       | builtin | —          | auto-allow | 按 id 或 name 查找单个角色                                                          |
+| **world-dimension-get** | builtin | —          | auto-allow | 按需读取当前 session 世界的结构化维度字段                                           |
+| **emit-event**          | builtin | —          | auto-allow | 发射当前 session 已声明的领域事件（一次一个 topic），校验 topic + payload schema    |
+| **suspend**             | builtin | —          | auto-allow | 挂起当前 runtime 等待玩家输入，写 `suspensions` 表，可通过 resume API 恢复          |
+| **runtime-done**        | builtin | —          | auto-allow | Agent 工具循环的结束信号——业务工具调用完毕后调用以结束本 runtime                    |
+| **search-tools**        | 注入    | —          | auto-allow | 延迟工具搜索——manifest 声明 `tools.defer` 时框架自动注入，BM25 检索并激活未预载工具 |
+| **memory-search**       | builtin | —          | auto-allow | 搜索记忆：对话历史(recall) + 长期知识库(archival，含 codex/lorebook/角色)           |
+| **memory-get-block**    | builtin | —          | auto-allow | 读取一个核心记忆块的当前内容                                                        |
+| **memory-update-block** | builtin | —          | auto-allow | 更新（完整替换）一个核心记忆块。无 capability 门控——列入 tools.builtin 即可用       |
+| set-world-schema        | local   | world-init | auto-allow | 定义世界角色属性 Schema                                                             |
+| set-world-entries-batch | local   | world-init | auto-allow | 批量写入世界词条                                                                    |
+| unlock-codex-entries    | local   | codex      | auto-allow | 批量解锁图鉴条目                                                                    |
+| update-codex-entry      | local   | codex      | auto-allow | 更新已有图鉴条目                                                                    |
 
 ---
 
@@ -343,6 +344,27 @@ interface UIRenderPart {
 
 ---
 
+### search-tools（框架注入，延迟工具加载）
+
+契约声明在 `packages/tools/src/builtin/tool-search.ts`，执行逻辑在 `packages/runtime/src/agent-loop/tool-search.ts`。**不可在 `tools.builtin` 中手动声明**——当某个 agent runtime 的 manifest 声明了 `tools.defer`（`true` = 延迟整个白名单；`string[]` = 延迟指定工具名）时，框架把被延迟工具的 schema 从初始 LLM 工具清单中移除，并自动注入本工具。设计对齐 openai/codex 的 `tool_search`（`ToolExposure::Deferred` + BM25）。
+
+| 参数  | 类型   | 必需 | 描述                                        |
+| ----- | ------ | ---- | ------------------------------------------- |
+| query | string | ✓    | 能力关键词（中英文均可），如 `切换场景背景` |
+| limit | number | —    | 最多激活的工具数（默认 8，上限 20）         |
+
+**输出**: 文本列出命中工具的名字与描述；命中工具的完整 schema 自下一次 LLM 调用起加入工具清单，并在本 turn 的 agent loop 内持续有效（跨 turn 重置为精简清单）。
+
+**注意事项**：
+
+- 与 `suspend` / `runtime-done` 同为 loop 层 sentinel：调用被 agent loop 拦截，**永不进入 ToolExecutor**，也不注册在全局 toolMap
+- 检索池严格限定为该 runtime 自己声明且被延迟的白名单，schema 通过 `getToolInfo(name, context)` 获取——沿用 builtin/local 访问边界，无权工具既搜不到也不会泄露
+- 打分为零依赖 BM25（k1=1.2 / b=0.75），CJK 文本按字符二元组切分，语料 = 工具名 + 描述 + 参数 schema 的字段名/字段描述
+- description 会向 LLM 通告延迟池的数量与来源插件，模型据此知道有未预载工具可搜
+- 适用场景：单 runtime 白名单超过 ~10 个工具、每次调用全量预载 schema 开始挤占 prompt 预算时
+
+---
+
 ## Character 管理工具
 
 框架级角色管理工具，定义在 `packages/tools/src/builtin/character-tools.ts`。写入 `characters` 表（session 作用域，跨插件可见），同时镜像到调用插件的 `plugin_data[pluginId][namespace="characters"][key=charId]`，让右侧面板通过现成的 `plugin-data.changed` SSE 通道实时更新。
diff --git a/packages/runtime/src/agent-loop/agent-loop-policy.ts b/packages/runtime/src/agent-loop/agent-loop-policy.ts
index e88d78a6..deee65e8 100644
--- a/packages/runtime/src/agent-loop/agent-loop-policy.ts
+++ b/packages/runtime/src/agent-loop/agent-loop-policy.ts
@@ -19,12 +19,24 @@ import type {
   LLMToolDefinition,
 } from "../llm/llm-adapter.js";
 import { buildToolDefinitions } from "../turn-executor/turn-executor-helpers.js";
+import { resolveDeferredToolNames } from "./tool-search.js";
 import { buildRetryPolicy, type RetryPolicy } from "../retry/llm-retry.js";
 import type { AgentLoopDeps } from "../turn-executor/turn-executor-types.js";
 
 export interface AgentLoopPolicy {
-  /** LLM tool definitions built from manifest declarations (once per run). */
+  /**
+   * LLM tool definitions built from manifest declarations (once per run).
+   * When `deferredToolNames` is non-empty this is the REDUCED surface
+   * (deferred schemas withheld, `search-tools` appended); the loop grows its
+   * own working copy as searches activate tools mid-run.
+   */
   readonly toolDefs: readonly LLMToolDefinition[] | undefined;
+  /**
+   * Tool names withheld from the initial advertisement (`tools.defer`).
+   * Non-empty ⇒ the loop intercepts `search-tools` calls and activates
+   * matches from this pool for the rest of the run.
+   */
+  readonly deferredToolNames: ReadonlySet<string>;
   /** JSON-schema response format when the runtime declares an output schema. */
   readonly responseFormat: LLMResponseFormat | undefined;
   /**
@@ -98,6 +110,9 @@ export function buildAgentLoopPolicy({
 
   return {
     toolDefs,
+    deferredToolNames: deps.toolExecutor
+      ? resolveDeferredToolNames(manifest)
+      : new Set<string>(),
     responseFormat: loaded.outputSchema
       ? { type: "json_schema" as const, schema: loaded.outputSchema }
       : undefined,
diff --git a/packages/runtime/src/agent-loop/tool-search.ts b/packages/runtime/src/agent-loop/tool-search.ts
new file mode 100644
index 00000000..1fd4d692
--- /dev/null
+++ b/packages/runtime/src/agent-loop/tool-search.ts
@@ -0,0 +1,176 @@
+/**
+ * Deferred tool loading (tool-search) — runtime side.
+ *
+ * The manifest half (`tools.defer`) and the ranking half (BM25) live in
+ * `@covel/shared` / `@covel/tools`; this module derives the deferred name
+ * set, builds the LLM-facing `search-tools` definition, and executes a
+ * search when the agent loop intercepts the sentinel call (see
+ * turn-agent-tool-loop.ts — same interception pattern as `suspend` /
+ * `runtime-done`; the executor tool map never sees `search-tools`).
+ *
+ * Authorization is inherited: the searchable pool is exactly the runtime's
+ * own declared whitelist, and every schema is fetched through
+ * `ToolExecutor.getToolInfo(name, context)`, which enforces the same
+ * builtin/local access rules as advertisement — an unauthorized tool can
+ * neither be found nor activated.
+ */
+
+import type { RuntimeManifest } from "@covel/shared";
+import {
+  buildSearchToolsDescription,
+  parameterSchemaSearchText,
+  rankToolSearchDocs,
+  SEARCH_TOOLS_DEFAULT_LIMIT,
+  SEARCH_TOOLS_JSON_SCHEMA,
+  SEARCH_TOOLS_MAX_LIMIT,
+  SEARCH_TOOLS_TOOL_NAME,
+  type ToolSearchDoc,
+} from "@covel/tools";
+import type { LLMToolDefinition } from "../llm/llm-adapter.js";
+import type { ToolCallContext, ToolExecutor } from "./tool-executor.js";
+
+export { SEARCH_TOOLS_TOOL_NAME };
+
+/**
+ * The runtime's declared tool names, in advertisement form (local paths
+ * reduced to their file basename). Single source for both the initial
+ * advertisement list and the deferred-pool derivation, so the two can never
+ * disagree on a name.
+ */
+export function declaredToolNames(manifest: RuntimeManifest): string[] {
+  const names: string[] = [
+    ...(manifest.tools?.builtin ?? []),
+    ...(manifest.tools?.plugin ?? []),
+  ];
+  for (const p of manifest.tools?.local ?? []) {
+    names.push(
+      p
+        .split("/")
+        .pop()
+        ?.replace(/\.[^.]+$/, "") ?? p,
+    );
+  }
+  return names;
+}
+
+/**
+ * Resolve `tools.defer` into a concrete name set. `true` defers the whole
+ * declared whitelist; an array defers just those names (entries not present
+ * in the whitelist are ignored — deferring can never grant access to a tool
+ * the runtime did not declare).
+ */
+export function resolveDeferredToolNames(
+  manifest: RuntimeManifest,
+): ReadonlySet<string> {
+  const defer = manifest.tools?.defer;
+  if (!defer) return new Set();
+  const all = declaredToolNames(manifest);
+  if (defer === true) return new Set(all);
+  const allSet = new Set(all);
+  return new Set(defer.filter((name) => allSet.has(name)));
+}
+
+/** The injected `search-tools` LLM definition, advertising the pool size. */
+export function buildSearchToolsDefinition(
+  deferredCount: number,
+  pluginId: string,
+): LLMToolDefinition {
+  return {
+    name: SEARCH_TOOLS_TOOL_NAME,
+    description: buildSearchToolsDescription(deferredCount, pluginId),
+    parameters: SEARCH_TOOLS_JSON_SCHEMA as Record<string, unknown>,
+  };
+}
+
+export interface ToolSearchExecution {
+  /** Tool-result text fed back to the LLM. */
+  readonly resultText: string;
+  /** Structured result recorded in the runtime's toolCalls trace. */
+  readonly parsedResult: {
+    readonly activated: readonly string[];
+    readonly query: string;
+  };
+  /** Newly activated definitions to append to the loop's tool list. */
+  readonly activated: readonly LLMToolDefinition[];
+}
+
+/**
+ * Execute a `search-tools` call: rank the still-deferred pool with BM25 and
+ * activate up to `limit` matches. Idempotent per name — tools already
+ * advertised or previously activated are excluded from the pool.
+ */
+export function executeToolSearch(args: {
+  readonly argumentsJson: string;
+  readonly deferredNames: ReadonlySet<string>;
+  readonly activeNames: ReadonlySet<string>;
+  readonly toolExecutor: ToolExecutor;
+  readonly context: ToolCallContext;
+}): ToolSearchExecution {
+  const { deferredNames, activeNames, toolExecutor, context } = args;
+
+  let query = "";
+  let limit = SEARCH_TOOLS_DEFAULT_LIMIT;
+  try {
+    const parsed = JSON.parse(args.argumentsJson) as {
+      query?: unknown;
+      limit?: unknown;
+    };
+    if (typeof parsed.query === "string") query = parsed.query.trim();
+    if (typeof parsed.limit === "number" && Number.isFinite(parsed.limit)) {
+      limit = Math.max(1, Math.min(SEARCH_TOOLS_MAX_LIMIT, parsed.limit));
+    }
+  } catch {
+    // Fall through with empty query → error text below.
+  }
+  if (!query) {
+    return {
+      resultText:
+        "search-tools requires a non-empty `query` string describing the capability you need.",
+      parsedResult: { activated: [], query: "" },
+      activated: [],
+    };
+  }
+
+  const pool: { doc: ToolSearchDoc; def: LLMToolDefinition }[] = [];
+  for (const name of deferredNames) {
+    if (activeNames.has(name)) continue;
+    const info = toolExecutor.getToolInfo(name, context);
+    if (!info) continue;
+    const parameters = info.jsonSchema as Record<string, unknown>;
+    pool.push({
+      doc: {
+        key: info.name,
+        text: `${info.name} ${info.description} ${parameterSchemaSearchText(parameters)}`,
+      },
+      def: { name: info.name, description: info.description, parameters },
+    });
+  }
+
+  const ranked = rankToolSearchDocs(
+    query,
+    pool.map((p) => p.doc),
+    limit,
+  );
+  if (ranked.length === 0) {
+    return {
+      resultText:
+        `No matching tools among ${pool.length} deferred tool(s) for "${query}". ` +
+        `Try different capability keywords.`,
+      parsedResult: { activated: [], query },
+      activated: [],
+    };
+  }
+
+  const byName = new Map(pool.map((p) => [p.def.name, p.def]));
+  const activated = ranked
+    .map((name) => byName.get(name))
+    .filter((def): def is LLMToolDefinition => def !== undefined);
+  const lines = activated.map((d) => `- ${d.name}: ${d.description}`);
+  return {
+    resultText:
+      `Activated ${activated.length} tool(s) — directly callable from your next step:\n` +
+      lines.join("\n"),
+    parsedResult: { activated: activated.map((d) => d.name), query },
+    activated,
+  };
+}
diff --git a/packages/runtime/src/agent-loop/turn-agent-tool-loop.ts b/packages/runtime/src/agent-loop/turn-agent-tool-loop.ts
index f51e2a2c..55cad641 100644
--- a/packages/runtime/src/agent-loop/turn-agent-tool-loop.ts
+++ b/packages/runtime/src/agent-loop/turn-agent-tool-loop.ts
@@ -16,6 +16,7 @@ import type { HookPipeline } from "../hooks/pipeline.js";
 import type { RetryInfo } from "../retry/llm-retry.js";
 import { buildAgentLoopPolicy } from "./agent-loop-policy.js";
 import { createDeltaForwarder } from "./delta-forwarder.js";
+import { executeToolSearch, SEARCH_TOOLS_TOOL_NAME } from "./tool-search.js";
 import { requestLLMResponse } from "./tool-loop-handler.js";
 import { handleSuspension } from "../resume/suspend-resume-handler.js";
 import { guardAgainstToolLoop, type LoopGuardState } from "./loop-detection.js";
@@ -129,6 +130,7 @@ export async function runAgentToolLoop({
   // below is control flow only.
   const {
     toolDefs,
+    deferredToolNames,
     responseFormat,
     runtimeModelOverride,
     useStreaming,
@@ -145,6 +147,11 @@ export async function runAgentToolLoop({
     timeoutMs,
   });
 
+  // Working tool surface for this run. Starts as the policy's (possibly
+  // reduced) advertisement and grows when an intercepted `search-tools` call
+  // activates deferred tools — every subsequent LLM step sees the grown list.
+  let activeToolDefs = toolDefs;
+
   // The loop's single narrative outlet — counts chunks for `message.completed`.
   const delta = createDeltaForwarder({
     onDelta: deps.onDelta,
@@ -220,7 +227,7 @@ export async function runAgentToolLoop({
     const llmRequest = await runPreLLMCallHook(hookOpts, {
       messages,
       model: effectiveModel,
-      tools: toolDefs,
+      tools: activeToolDefs,
     });
 
     let response = await requestLLMResponse({
@@ -279,6 +286,60 @@ export async function runAgentToolLoop({
           // Use the (possibly replaced) toolCall from the hook outcome
           const effectiveTc = preToolOutcome.toolCall;
 
+          // ── search-tools interception (deferred tool loading) ─
+          // Framework-injected sentinel, same pattern as suspend /
+          // runtime-done: never dispatched to the executor. Ranks the
+          // still-deferred pool (BM25) and grows the working tool surface so
+          // the NEXT LLM step can call the activated tools directly.
+          if (
+            effectiveTc.name === SEARCH_TOOLS_TOOL_NAME &&
+            deferredToolNames.size > 0
+          ) {
+            const activeNames = new Set(
+              (activeToolDefs ?? []).map((d) => d.name),
+            );
+            const search = executeToolSearch({
+              argumentsJson: effectiveTc.arguments,
+              deferredNames: deferredToolNames,
+              activeNames,
+              toolExecutor: deps.toolExecutor,
+              context: {
+                sessionId: input.sessionId,
+                turnId: input.turnId,
+                pluginId: manifest.pluginId,
+                runtimeId: manifest.name,
+              },
+            });
+            if (search.activated.length > 0) {
+              activeToolDefs = [...(activeToolDefs ?? []), ...search.activated];
+            }
+            messages.push(
+              buildToolResultMessage({
+                toolCallId: effectiveTc.id,
+                content: search.resultText,
+              }),
+            );
+            executedToolCalls.push({
+              name: effectiveTc.name,
+              arguments: effectiveTc.arguments,
+              result: search.parsedResult,
+              success: true,
+            });
+            collectedToolCalls.push({
+              toolCallId: effectiveTc.id,
+              toolName: effectiveTc.name,
+              pluginId: manifest.pluginId,
+              runtimeId: manifest.name,
+              turnId: input.turnId,
+              input: { query: search.parsedResult.query },
+              output: search.parsedResult,
+              durationMs: Date.now() - tcStart,
+              approvalStatus: "auto-allowed",
+              timestamp: new Date().toISOString(),
+            });
+            continue;
+          }
+
           const result = await deps.toolExecutor.execute(
             {
               toolCallId: effectiveTc.id,
diff --git a/packages/runtime/src/turn-executor/turn-executor-helpers.ts b/packages/runtime/src/turn-executor/turn-executor-helpers.ts
index 44b6fa5c..055d1806 100644
--- a/packages/runtime/src/turn-executor/turn-executor-helpers.ts
+++ b/packages/runtime/src/turn-executor/turn-executor-helpers.ts
@@ -13,6 +13,11 @@ import type {
   ToolExecutor,
 } from "../agent-loop/tool-executor.js";
 import type { LLMToolDefinition } from "../llm/llm-adapter.js";
+import {
+  buildSearchToolsDefinition,
+  declaredToolNames,
+  resolveDeferredToolNames,
+} from "../agent-loop/tool-search.js";
 import { isPreGamePriority } from "../schedule/scheduler.js";
 
 /**
@@ -63,21 +68,13 @@ export function buildToolDefinitions(
   toolExecutor: ToolExecutor,
   context?: ToolCallContext,
 ): LLMToolDefinition[] | undefined {
-  const names: string[] = [
-    ...(manifest.tools?.builtin ?? []),
-    // Entry-registered plugin tools are declared by name.
-    ...(manifest.tools?.plugin ?? []),
-  ];
-
-  // For local tools, extract name from path (e.g., ./tools/unlock-codex-entries.ts → unlock-codex-entries)
-  for (const p of manifest.tools?.local ?? []) {
-    names.push(
-      p
-        .split("/")
-        .pop()
-        ?.replace(/\.[^.]+$/, "") ?? p,
-    );
-  }
+  // Deferred tools (tools.defer) are registered and authorized but withheld
+  // from the initial advertisement — the LLM discovers them through the
+  // injected `search-tools` tool (see agent-loop/tool-search.ts).
+  const deferred = resolveDeferredToolNames(manifest);
+  const names = declaredToolNames(manifest).filter(
+    (name) => !deferred.has(name),
+  );
 
   // Framework-contracted tool: `runtime-done` is auto-available to tool-using
   // agent runtimes so the LLM can exit immediately after completing business
@@ -88,7 +85,7 @@ export function buildToolDefinitions(
     names.push("runtime-done");
   }
 
-  if (names.length === 0) {
+  if (names.length === 0 && deferred.size === 0) {
     return undefined;
   }
 
@@ -112,6 +109,10 @@ export function buildToolDefinitions(
     }
   }
 
+  if (deferred.size > 0) {
+    defs.push(buildSearchToolsDefinition(deferred.size, manifest.pluginId));
+  }
+
   return defs.length > 0 ? defs : undefined;
 }
 
diff --git a/packages/runtime/tests/tool-search-loop.test.ts b/packages/runtime/tests/tool-search-loop.test.ts
new file mode 100644
index 00000000..546bb2bc
--- /dev/null
+++ b/packages/runtime/tests/tool-search-loop.test.ts
@@ -0,0 +1,214 @@
+/**
+ * Deferred tool loading (tool-search) — end-to-end agent-loop behaviour.
+ *
+ * A manifest with `tools.defer` advertises a REDUCED tool list (search-tools
+ * instead of the deferred schemas); when the LLM calls `search-tools`, the
+ * loop intercepts it (never reaching the ToolExecutor), ranks the deferred
+ * pool with BM25, and grows the working tool surface so the NEXT step can
+ * call the activated tool directly. These tests script the LLM and capture
+ * the `tools` array of every request to pin that contract, plus the
+ * `defer: [subset]` and no-defer shapes of buildToolDefinitions.
+ */
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import type { RuntimeManifest, TurnInput } from "@covel/shared";
+import { SEARCH_TOOLS_TOOL_NAME, tool } from "@covel/tools";
+import type { ToolModule } from "@covel/tools";
+import { executeTurn } from "../src/turn-executor/turn-executor.js";
+import type { TurnExecutorDeps } from "../src/turn-executor/turn-executor.js";
+import { createToolExecutor } from "../src/agent-loop/tool-executor.js";
+import { buildToolDefinitions } from "../src/turn-executor/turn-executor-helpers.js";
+import { resolveDeferredToolNames } from "../src/agent-loop/tool-search.js";
+import type {
+  LLMAdapter,
+  LLMResponse,
+  LLMToolDefinition,
+} from "../src/llm/llm-adapter.js";
+
+const SESSION_ID = "sess-tool-search";
+
+function echoTool(name: string, description: string): ToolModule {
+  return tool({
+    name,
+    description,
+    parameters: z.object({ value: z.string() }),
+    execute: async (params: { value: string }) => ({ echoed: params.value }),
+  });
+}
+
+const TOOL_POOL: ToolModule[] = [
+  echoTool(
+    "set-scene-background",
+    "Switch the scene background image to a registered variant.",
+  ),
+  echoTool("roll-dice", "Roll dice with an expression like 2d6+3."),
+  echoTool("grant-item", "Give the player an inventory item."),
+];
+
+/** Scripted adapter: replays canned responses, recording each request's tools. */
+class ScriptedLLM implements LLMAdapter {
+  readonly requestTools: (readonly LLMToolDefinition[] | undefined)[] = [];
+  private step = 0;
+  constructor(private readonly script: LLMResponse[]) {}
+  async generate(params: {
+    tools?: readonly LLMToolDefinition[];
+  }): Promise<LLMResponse> {
+    this.requestTools.push(params.tools);
+    const response = this.script[this.step];
+    this.step += 1;
+    if (!response) throw new Error("ScriptedLLM: script exhausted");
+    return response;
+  }
+}
+
+function toolCallResponse(name: string, args: object): LLMResponse {
+  return {
+    content: null,
+    toolCalls: [{ id: `tc-${name}`, name, arguments: JSON.stringify(args) }],
+    finishReason: "tool_calls",
+    usage: { inputTokens: 10, outputTokens: 5 },
+  };
+}
+
+const DONE: LLMResponse = {
+  content: "done.",
+  toolCalls: [],
+  finishReason: "stop",
+  usage: { inputTokens: 10, outputTokens: 5 },
+};
+
+function makeManifest(over?: Partial<RuntimeManifest>): RuntimeManifest {
+  return {
+    name: "mega/worker",
+    pluginId: "mega",
+    description: "test runtime with a deferred tool pool",
+    priority: 500,
+    outputKind: "plugin",
+    tools: {
+      builtin: TOOL_POOL.map((t) => t.name),
+      defer: true,
+    },
+    trigger: { type: "auto" },
+    ...over,
+  } as RuntimeManifest;
+}
+
+function makeDeps(llm: LLMAdapter): TurnExecutorDeps {
+  return {
+    loadRuntime: async (m) => ({
+      manifest: m,
+      promptTemplate: "Do the task using your tools.",
+    }),
+    llm,
+    toolExecutor: createToolExecutor({
+      findTool: (name) => TOOL_POOL.find((t) => t.name === name),
+    }),
+  };
+}
+
+const TURN_INPUT: TurnInput = {
+  sessionId: SESSION_ID,
+  turnId: "turn-1",
+  playerMessage: "roll for initiative",
+};
+
+describe("tool-search: deferred loading in the agent loop", () => {
+  it("advertises only search-tools initially, activates matches for the next step", async () => {
+    const llm = new ScriptedLLM([
+      toolCallResponse(SEARCH_TOOLS_TOOL_NAME, { query: "roll dice" }),
+      toolCallResponse("roll-dice", { value: "2d6" }),
+      DONE,
+    ]);
+    const manifest = makeManifest();
+
+    const result = await executeTurn(TURN_INPUT, [manifest], makeDeps(llm), {
+      maxSteps: 5,
+    });
+    const rr = result.runtimeResults.find((r) => r.runtimeId === manifest.name);
+    expect(rr?.status).toBe("success");
+
+    // Step 1: reduced surface — search-tools + runtime-done, no pool schemas.
+    const firstTools = (llm.requestTools[0] ?? []).map((d) => d.name);
+    expect(firstTools).toContain(SEARCH_TOOLS_TOOL_NAME);
+    expect(firstTools).toContain("runtime-done");
+    for (const t of TOOL_POOL) expect(firstTools).not.toContain(t.name);
+
+    // Step 2: the activated tool joined the surface and stays for step 3.
+    const secondTools = (llm.requestTools[1] ?? []).map((d) => d.name);
+    expect(secondTools).toContain("roll-dice");
+    const thirdTools = (llm.requestTools[2] ?? []).map((d) => d.name);
+    expect(thirdTools).toContain("roll-dice");
+
+    // The activated tool actually executed through the normal executor path.
+    const rollCall = rr?.toolCalls?.find((tc) => tc.toolName === "roll-dice");
+    expect(rollCall?.output).toEqual({ echoed: "2d6" });
+    // And the search itself is traced.
+    const searchCall = rr?.toolCalls?.find(
+      (tc) => tc.toolName === SEARCH_TOOLS_TOOL_NAME,
+    );
+    expect(searchCall?.output).toMatchObject({
+      activated: ["roll-dice"],
+      query: "roll dice",
+    });
+  });
+
+  it("feeds a no-match result back without activating anything", async () => {
+    const llm = new ScriptedLLM([
+      toolCallResponse(SEARCH_TOOLS_TOOL_NAME, { query: "teleport wormhole" }),
+      DONE,
+    ]);
+    const result = await executeTurn(
+      TURN_INPUT,
+      [makeManifest()],
+      makeDeps(llm),
+      { maxSteps: 4 },
+    );
+    expect(result.runtimeResults[0]?.status).toBe("success");
+    const secondTools = (llm.requestTools[1] ?? []).map((d) => d.name);
+    for (const t of TOOL_POOL) expect(secondTools).not.toContain(t.name);
+  });
+});
+
+describe("buildToolDefinitions defer shapes", () => {
+  const toolExecutor = createToolExecutor({
+    findTool: (name) => TOOL_POOL.find((t) => t.name === name),
+  });
+
+  it("defer: [subset] withholds only the listed names", () => {
+    const manifest = makeManifest({
+      tools: {
+        builtin: TOOL_POOL.map((t) => t.name),
+        defer: ["set-scene-background", "grant-item"],
+      },
+    });
+    const names = (buildToolDefinitions(manifest, toolExecutor) ?? []).map(
+      (d) => d.name,
+    );
+    expect(names).toContain("roll-dice");
+    expect(names).toContain(SEARCH_TOOLS_TOOL_NAME);
+    expect(names).not.toContain("set-scene-background");
+    expect(names).not.toContain("grant-item");
+  });
+
+  it("defer entries outside the whitelist are ignored", () => {
+    const manifest = makeManifest({
+      tools: {
+        builtin: ["roll-dice"],
+        defer: ["roll-dice", "not-declared-tool"],
+      },
+    });
+    expect(resolveDeferredToolNames(manifest)).toEqual(new Set(["roll-dice"]));
+  });
+
+  it("no defer ⇒ byte-identical full advertisement, no search-tools", () => {
+    const manifest = makeManifest({
+      tools: { builtin: TOOL_POOL.map((t) => t.name) },
+    });
+    const names = (buildToolDefinitions(manifest, toolExecutor) ?? []).map(
+      (d) => d.name,
+    );
+    for (const t of TOOL_POOL) expect(names).toContain(t.name);
+    expect(names).not.toContain(SEARCH_TOOLS_TOOL_NAME);
+  });
+});
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
index 7e07ebfa..e491e788 100644
--- a/packages/shared/src/types/plugin.ts
+++ b/packages/shared/src/types/plugin.ts
@@ -342,6 +342,18 @@ export interface ToolsConfig {
    * (registration itself happens in the plugin's `entry` module).
    */
   readonly plugin?: readonly string[];
+  /**
+   * Deferred tool loading (tool-search). `true` defers the runtime's entire
+   * whitelist; a string array defers just those tool names (for `local`
+   * entries, the name is the file basename without extension — same rule as
+   * LLM advertisement). Deferred tools stay registered and authorized but
+   * are omitted from the initial LLM tool list; the framework injects a
+   * `search-tools` tool instead, and tools the LLM discovers through it are
+   * activated for the rest of the current turn's agent loop. Use when the
+   * whitelist is large (>~10 tools) and per-call schema preloading would
+   * dominate the prompt budget.
+   */
+  readonly defer?: true | readonly string[];
 }
 
 // ── User-declared plugin settings ────────────────────────────────
diff --git a/packages/tools/src/builtin/tool-search.ts b/packages/tools/src/builtin/tool-search.ts
new file mode 100644
index 00000000..a832ffd2
--- /dev/null
+++ b/packages/tools/src/builtin/tool-search.ts
@@ -0,0 +1,208 @@
+/**
+ * search-tools — framework-injected tool discovery (deferred tool loading).
+ *
+ * When a runtime's manifest defers part of its tool whitelist
+ * (`tools.defer: true | string[]`), the deferred tools' schemas are omitted
+ * from the initial LLM tool list and this tool is injected instead. The LLM
+ * searches by capability keywords; matching tools are activated for the NEXT
+ * model call and stay active for the rest of the current turn's agent loop.
+ *
+ * Modeled after openai/codex's `tool_search` (ToolExposure::Deferred + BM25
+ * over name/description/parameter-schema text, default limit 8). Like
+ * `suspend` / `runtime-done`, execution is intercepted in the agent loop —
+ * this module only carries the LLM-facing contract and the ranking function;
+ * it is never registered in the executor tool map and never declarable in a
+ * plugin's own whitelist.
+ *
+ * Scoring is a self-contained BM25 (k1=1.2, b=0.75). CJK text is tokenized
+ * into character bigrams (segmenter-free standard), and query terms that
+ * still don't match a whole token earn substring credit — Chinese queries
+ * and descriptions match without a dictionary. Zero dependencies by design —
+ * a per-runtime pool is tens of documents, not thousands.
+ */
+
+export const SEARCH_TOOLS_TOOL_NAME = "search-tools";
+
+export const SEARCH_TOOLS_DEFAULT_LIMIT = 8;
+export const SEARCH_TOOLS_MAX_LIMIT = 20;
+
+/** JSON schema for the LLM-facing `search-tools` definition. */
+export const SEARCH_TOOLS_JSON_SCHEMA: Readonly<Record<string, unknown>> = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      description:
+        "Capability keywords describing the tool you need (English or Chinese), e.g. 'change scene background' / '切换场景背景'.",
+    },
+    limit: {
+      type: "number",
+      description: `Maximum number of tools to activate (default ${SEARCH_TOOLS_DEFAULT_LIMIT}, max ${SEARCH_TOOLS_MAX_LIMIT}).`,
+    },
+  },
+  required: ["query"],
+};
+
+/**
+ * LLM-facing description. Advertises the deferred pool (count + owner) so the
+ * model knows undeclared tools exist at all — without this hint a deferred
+ * pool is effectively invisible (codex does the same in its tool_search
+ * description).
+ */
+export function buildSearchToolsDescription(
+  deferredCount: number,
+  pluginId: string,
+): string {
+  return (
+    `This runtime has ${deferredCount} additional tool(s) from plugin "${pluginId}" ` +
+    `that were NOT preloaded into your tool list (deferred to save context). ` +
+    `Search them by describing the capability you need; matching tools are ` +
+    `activated and become directly callable from your next step onward. ` +
+    `Call this first whenever none of your current tools fits the task.`
+  );
+}
+
+// ── BM25 ranking ─────────────────────────────────────────────────
+
+export interface ToolSearchDoc {
+  /** Stable key returned by {@link rankToolSearchDocs} (the tool name). */
+  readonly key: string;
+  /** Indexed text: tool name + description + parameter-schema text. */
+  readonly text: string;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+/** Substring (CJK) match counts as a fractional term occurrence. */
+const SUBSTRING_TF = 0.5;
+
+const CJK_CHAR = /[぀-ヿ一-鿿]/;
+const CJK_RUN_SPLIT = /([぀-ヿ一-鿿]+)/;
+
+/**
+ * Tokenizer: whitespace/punctuation split for Latin text, character BIGRAMS
+ * for CJK runs (the standard segmenter-free approach — "解锁图鉴" → 解锁/锁图/
+ * 图鉴 matches a description phrased "解锁…图鉴条目" even when the words are
+ * not adjacent). NOT deduplicated: BM25 needs term frequencies. Query-side
+ * callers dedupe themselves.
+ */
+export function tokenizeForToolSearch(text: string): string[] {
+  const rough = text
+    .toLowerCase()
+    .split(/[\s,.:;!?，。：；！？、\-—""''()（）【】[\]{}"/\\_]+/)
+    .filter(Boolean);
+  const out: string[] = [];
+  for (const token of rough) {
+    if (!CJK_CHAR.test(token)) {
+      if (token.length >= 2) out.push(token);
+      continue;
+    }
+    for (const segment of token.split(CJK_RUN_SPLIT).filter(Boolean)) {
+      if (!CJK_CHAR.test(segment)) {
+        if (segment.length >= 2) out.push(segment);
+      } else if (segment.length === 1) {
+        out.push(segment);
+      } else {
+        for (let i = 0; i < segment.length - 1; i += 1) {
+          out.push(segment.slice(i, i + 2));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Rank documents against a query with BM25, returning up to `limit` keys,
+ * best first. Documents with zero overlap (token or substring) are dropped.
+ */
+export function rankToolSearchDocs(
+  query: string,
+  docs: readonly ToolSearchDoc[],
+  limit: number,
+): string[] {
+  if (limit <= 0 || docs.length === 0) return [];
+  const queryTerms = [...new Set(tokenizeForToolSearch(query))];
+  if (queryTerms.length === 0) return [];
+
+  const prepared = docs.map((doc) => {
+    const tokens = tokenizeForToolSearch(doc.text);
+    const tf = new Map<string, number>();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+    return {
+      key: doc.key,
+      lowerText: doc.text.toLowerCase(),
+      tf,
+      len: Math.max(tokens.length, 1),
+    };
+  });
+  const avgLen = prepared.reduce((sum, d) => sum + d.len, 0) / prepared.length;
+
+  // Term frequency with CJK substring fallback — a Chinese description
+  // tokenizes into long runs, so `包含` matching inside a token still counts.
+  const termFrequency = (
+    doc: (typeof prepared)[number],
+    term: string,
+  ): number =>
+    doc.tf.get(term) ?? (doc.lowerText.includes(term) ? SUBSTRING_TF : 0);
+
+  const docFrequency = new Map<string, number>();
+  for (const term of queryTerms) {
+    docFrequency.set(
+      term,
+      prepared.filter((d) => termFrequency(d, term) > 0).length,
+    );
+  }
+
+  const n = prepared.length;
+  const scored = prepared
+    .map((doc) => {
+      let score = 0;
+      for (const term of queryTerms) {
+        const tf = termFrequency(doc, term);
+        if (tf === 0) continue;
+        const df = docFrequency.get(term) ?? 0;
+        const idf = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+        const norm = 1 - BM25_B + BM25_B * (doc.len / avgLen);
+        score += idf * ((tf * (BM25_K1 + 1)) / (tf + BM25_K1 * norm));
+      }
+      return { key: doc.key, score };
+    })
+    .filter((d) => d.score > 0);
+
+  scored.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
+  return scored.slice(0, limit).map((d) => d.key);
+}
+
+/**
+ * Flatten a JSON-schema parameters object into searchable text: property
+ * names + `description` strings, recursively. Field names and descriptions
+ * carry the capability signal (codex indexes the schema for the same
+ * reason); structural keywords (`type: object`) are uniform noise and
+ * excluded.
+ */
+export function parameterSchemaSearchText(
+  schema: Readonly<Record<string, unknown>> | undefined,
+): string {
+  if (!schema) return "";
+  const parts: string[] = [];
+  const walk = (node: unknown): void => {
+    if (!node || typeof node !== "object") return;
+    const obj = node as Record<string, unknown>;
+    if (typeof obj["description"] === "string") {
+      parts.push(obj["description"]);
+    }
+    const props = obj["properties"];
+    if (props && typeof props === "object") {
+      for (const [name, child] of Object.entries(
+        props as Record<string, unknown>,
+      )) {
+        parts.push(name);
+        walk(child);
+      }
+    }
+    if (obj["items"]) walk(obj["items"]);
+  };
+  walk(schema);
+  return parts.join(" ");
+}
diff --git a/packages/tools/src/index.ts b/packages/tools/src/index.ts
index c516b8cf..831a96a6 100644
--- a/packages/tools/src/index.ts
+++ b/packages/tools/src/index.ts
@@ -58,6 +58,17 @@ export {
   isRuntimeDoneSentinel,
 } from "./builtin/runtime-done.js";
 export type { RuntimeDoneSentinel } from "./builtin/runtime-done.js";
+export {
+  SEARCH_TOOLS_TOOL_NAME,
+  SEARCH_TOOLS_DEFAULT_LIMIT,
+  SEARCH_TOOLS_MAX_LIMIT,
+  SEARCH_TOOLS_JSON_SCHEMA,
+  buildSearchToolsDescription,
+  rankToolSearchDocs,
+  tokenizeForToolSearch,
+  parameterSchemaSearchText,
+} from "./builtin/tool-search.js";
+export type { ToolSearchDoc } from "./builtin/tool-search.js";
 export { createMemoryTools } from "./builtin/memory-tools.js";
 export type { MemoryToolDeps } from "./builtin/memory-tools.js";
 export { createEmitEventTool } from "./builtin/emit-event.js";
diff --git a/packages/tools/tests/tool-search.test.ts b/packages/tools/tests/tool-search.test.ts
new file mode 100644
index 00000000..87c70fc8
--- /dev/null
+++ b/packages/tools/tests/tool-search.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildSearchToolsDescription,
+  parameterSchemaSearchText,
+  rankToolSearchDocs,
+  SEARCH_TOOLS_JSON_SCHEMA,
+  tokenizeForToolSearch,
+  type ToolSearchDoc,
+} from "../src/builtin/tool-search.js";
+
+const DOCS: ToolSearchDoc[] = [
+  {
+    key: "set-scene-background",
+    text: "set-scene-background Switch the current scene background image to a registered scene variant (day/night). sceneId variant",
+  },
+  {
+    key: "roll-dice",
+    text: "roll-dice Roll dice with an expression like 2d6+3 and return the total. expression",
+  },
+  {
+    key: "unlock-codex-entry",
+    text: "unlock-codex-entry 解锁一条图鉴条目，包含条目 ID 与解锁原因。entryId reason",
+  },
+  {
+    key: "grant-item",
+    text: "grant-item Give the player an inventory item with quantity. itemId quantity",
+  },
+];
+
+describe("rankToolSearchDocs (BM25)", () => {
+  it("ranks the capability-matching tool first for an English query", () => {
+    const ranked = rankToolSearchDocs("change scene background image", DOCS, 3);
+    expect(ranked[0]).toBe("set-scene-background");
+  });
+
+  it("matches Chinese queries via the CJK substring path", () => {
+    const ranked = rankToolSearchDocs("解锁图鉴", DOCS, 3);
+    expect(ranked[0]).toBe("unlock-codex-entry");
+  });
+
+  it("drops zero-overlap documents and respects the limit", () => {
+    const ranked = rankToolSearchDocs("dice roll", DOCS, 1);
+    expect(ranked).toEqual(["roll-dice"]);
+  });
+
+  it("returns empty for an empty/stop-word query or empty corpus", () => {
+    expect(rankToolSearchDocs("", DOCS, 5)).toEqual([]);
+    expect(rankToolSearchDocs("a", DOCS, 5)).toEqual([]); // <2 chars filtered
+    expect(rankToolSearchDocs("dice", [], 5)).toEqual([]);
+    expect(rankToolSearchDocs("dice", DOCS, 0)).toEqual([]);
+  });
+
+  it("is deterministic on ties (name tie-break)", () => {
+    const twins: ToolSearchDoc[] = [
+      { key: "b-tool", text: "shared capability words" },
+      { key: "a-tool", text: "shared capability words" },
+    ];
+    expect(rankToolSearchDocs("capability", twins, 2)).toEqual([
+      "a-tool",
+      "b-tool",
+    ]);
+  });
+});
+
+describe("tokenizeForToolSearch", () => {
+  it("keeps term frequencies (no dedupe) and lowercases", () => {
+    expect(tokenizeForToolSearch("Scene scene BACKGROUND")).toEqual([
+      "scene",
+      "scene",
+      "background",
+    ]);
+  });
+});
+
+describe("parameterSchemaSearchText", () => {
+  it("extracts property names and descriptions recursively", () => {
+    const text = parameterSchemaSearchText({
+      type: "object",
+      properties: {
+        sceneId: { type: "string", description: "Registered scene id" },
+        options: {
+          type: "object",
+          properties: {
+            variant: { type: "string", description: "day or night" },
+          },
+        },
+        tags: { type: "array", items: { description: "tag text" } },
+      },
+    });
+    expect(text).toContain("sceneId");
+    expect(text).toContain("Registered scene id");
+    expect(text).toContain("variant");
+    expect(text).toContain("day or night");
+    expect(text).toContain("tag text");
+    expect(text).not.toContain("object");
+  });
+
+  it("returns empty for undefined", () => {
+    expect(parameterSchemaSearchText(undefined)).toBe("");
+  });
+});
+
+describe("search-tools contract", () => {
+  it("schema requires query and description advertises the pool", () => {
+    expect(SEARCH_TOOLS_JSON_SCHEMA["required"]).toEqual(["query"]);
+    const desc = buildSearchToolsDescription(12, "mega-plugin");
+    expect(desc).toContain("12");
+    expect(desc).toContain("mega-plugin");
+  });
+});

From 2ab06b2aef831a1354c01e9dc9db529679f2554d Mon Sep 17 00:00:00 2001
From: ackness <ackness8@gmail.com>
Date: Fri, 17 Jul 2026 16:21:03 +0800
Subject: [PATCH 10/10] fix(ai-provider): accept private DNS answers on self
 tier core provider path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Provider connectivity test (and every real LLM call) failed with
"SSRF policy rejected ...198.18.x.x" on machines running a TUN proxy:
Clash/mihomo/sing-box/Surge fake-IP mode maps every external hostname
into 198.18.0.0/15 and routes by SNI, and the DNS-pinning guard
rejected those answers as non-public. LAN endpoints (Ollama at
192.168.x.x) hit the same wall.

The self tier is already single-user local play (loopback-bound,
owner/operator tokens no-op), so the core provider path (the user's
own configured baseUrl via postJson/getJson) now accepts any resolver
answer for a hostname; the socket stays pinned to it, preserving the
anti-rebinding guarantee. The exemption is deliberately narrow:

- plugin ctx.http (third-party code) stays strict — no local-network
  probing even on desktop
- IP-literal URLs get no exemption (url-safety blocks private literals)
- hosted tiers (demo/commercial) keep the strict public-only policy

Verified end-to-end against api.deepseek.com through the real
connect-pinned dispatcher (reaches the host, 401 on the dummy key).

Tests: request-dns-safety split into hosted-tier-strict and
self-tier-core-accept + ctx.http-still-strict cases; ai-provider 239
pass; turbo lint 21/21.
---
 CLAUDE.md                                     |  2 +-
 .../src/adapters/http/dns-safety.ts           | 54 ++++++++++++++++-
 .../tests/request-dns-safety.test.ts          | 59 ++++++++++++++++++-
 3 files changed, 108 insertions(+), 7 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ee9d8f19..9770bd5e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -295,7 +295,7 @@ Each SQL backend keeps a thin public factory plus focused method modules:
 
 ## Security & Operations
 
-- **SSRF guard**: `validateBaseUrl()` in `ai-provider/adapters/http.ts` is **open by default** — any public https host is allowed. Blocks: RFC1918 / link-local IPs (`10.x` / `172.16-31.x` / `192.168.x` / `169.254.x` / `fc00::` / `fe80::`), cloud metadata hostnames (`metadata.google.internal`, `metadata.internal`), non-https on remote hosts, non-http(s) protocols. Loopback (`localhost` / `127.0.0.1` / `::1`) bypasses the https requirement for Ollama-style local dev. Additionally, core provider requests (`postJson` / `getJson` / `postFormData`) and the plugin `ctx.http` helper resolve DNS through a pinning dispatcher (`adapters/http/dns-safety.ts`): every A/AAAA answer must be publicly routable (loopback hostnames must resolve to loopback), closing the string-check-to-connect DNS-rebinding gap. There is **no host allowlist env** — the guard is open by design; third-party plugin authors targeting custom provider hosts do not need any env shim (the never-read `COVEL_ALLOWED_LLM_HOSTS` registry entry was removed).
+- **SSRF guard**: `validateBaseUrl()` in `ai-provider/adapters/http.ts` is **open by default** — any public https host is allowed. Blocks: RFC1918 / link-local IPs (`10.x` / `172.16-31.x` / `192.168.x` / `169.254.x` / `fc00::` / `fe80::`), cloud metadata hostnames (`metadata.google.internal`, `metadata.internal`), non-https on remote hosts, non-http(s) protocols. Loopback (`localhost` / `127.0.0.1` / `::1`) bypasses the https requirement for Ollama-style local dev. Additionally, core provider requests (`postJson` / `getJson` / `postFormData`) and the plugin `ctx.http` helper resolve DNS through a pinning dispatcher (`adapters/http/dns-safety.ts`): every A/AAAA answer must be publicly routable (loopback hostnames must resolve to loopback), closing the string-check-to-connect DNS-rebinding gap. **Self-tier exemption (core provider path only)**: on the `self` tier (desktop/self-deploy default — already loopback-bound with owner/operator tokens as no-ops), the core provider path (the user's own configured LLM `baseUrl`) accepts any resolver answer for a hostname (the socket is still pinned to it). Single-user local machines run TUN proxies (Clash/mihomo/sing-box/Surge map every domain into a private/benchmark range and route by SNI) and LAN endpoints (Ollama at `192.168.x.x`) that the public-only rule wrongly rejected. The exemption is NOT granted to the plugin `ctx.http` path (third-party plugin code stays strict — no probing the local network even on a desktop install), to IP-literal URLs (url-safety's string check still blocks private literals), or to hosted tiers (`demo`/`commercial` may run inside a cloud network where private answers reach real internal services). There is **no host allowlist env** — the guard is open by design; third-party plugin authors targeting custom provider hosts do not need any env shim (the never-read `COVEL_ALLOWED_LLM_HOSTS` registry entry was removed).
 - **Env-key origin binding (S-01)**: server-env / platform API keys flow to the gateway as `envApiKeys`, separate from request-supplied `X-Provider-Keys` (`apiKeys`). The provider registry only attaches an env key when the resolved target's baseUrl origin matches trusted config (llm.toml / registered provider defaults) — a request-scoped custom preset (`X-Slot-Config` overlay) that redirects a provider to another origin gets no env key and no trusted default headers; it must supply its own key.
 - **Hosted auth (S-02/C-01/C-02)**: `demo` / `commercial` tiers enforce a per-session **owner token** (minted at session create, hash-persisted in `SessionRecord.metadata`, returned once) on every session-scoped route, and an **operator token** (`COVEL_DESKTOP_REST_TOKEN`, also a master key that passes any owner check) on global/admin routes (session create/list, world writes, AI/model, community server-code activation). `validateSecurityPosture` fails boot on a hosted tier missing the operator token / media secret / CORS origin. The server binds `127.0.0.1` by default (`COVEL_BIND_HOST` opts into `0.0.0.0`). `self` / desktop / dev are a strict no-op (single-user local play unchanged). Community server code (`entry` / handler / hook / wire / runtime JS) is import-gated behind two-phase approval (a `covel:plugin-server-code` grant, then the action grant). Full model: [docs/reference/api.md](./docs/reference/api.md) 鉴权 section.
 - **Signed media URLs**: `middleware/media-token.ts` signs `MediaRef` URLs with `COVEL_MEDIA_TOKEN_SECRET`. Desktop shells must provision it or generated images/portraits fail to load; web uses an ephemeral per-boot secret.
diff --git a/packages/ai-provider/src/adapters/http/dns-safety.ts b/packages/ai-provider/src/adapters/http/dns-safety.ts
index dbaed343..8a8b3689 100644
--- a/packages/ai-provider/src/adapters/http/dns-safety.ts
+++ b/packages/ai-provider/src/adapters/http/dns-safety.ts
@@ -1,6 +1,7 @@
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import { Agent } from "undici";
+import { readRuntimeEnv } from "@covel/shared";
 
 interface ResolvedAddress {
   readonly address: string;
@@ -9,14 +10,52 @@ interface ResolvedAddress {
 
 const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
 
+/**
+ * Whether a resolver answer in a private/benchmark range may be accepted.
+ *
+ * True only for the CORE PROVIDER path (`trustedProviderPath` — the user's own
+ * configured LLM baseUrl via postJson/getJson) on the `self` tier
+ * (desktop / self-deploy, the default when DEPLOYMENT_TIER is unset — already
+ * loopback-bound with owner/operator tokens as no-ops). There, DNS-answer
+ * filtering does more harm than good: local TUN proxies (Clash / mihomo /
+ * sing-box / Surge) map every hostname into a private/benchmark range and
+ * route by SNI, and a LAN Ollama endpoint legitimately resolves to
+ * 192.168.x.x — both were wrongly rejected as "SSRF". The socket is still
+ * pinned to the exact answer, preserving the anti-rebinding guarantee.
+ *
+ * NEVER granted to:
+ *  - the plugin `ctx.http` path (`trustedProviderPath: false`) — third-party
+ *    plugin code must not reach internal services even on a local machine;
+ *  - IP-LITERAL URLs — a raw `https://10.0.0.1` stays subject to the
+ *    public-only rule (url-safety's string check also blocks it upstream);
+ *  - hosted tiers (demo / commercial) — they may run inside a cloud network
+ *    where private answers reach real internal services.
+ */
+function allowResolvedPrivateAddresses(
+  isLiteral: boolean,
+  trustedProviderPath: boolean,
+): boolean {
+  return (
+    trustedProviderPath &&
+    !isLiteral &&
+    readRuntimeEnv().deploymentTier === "self"
+  );
+}
+
 /**
  * Resolve one request target, reject every non-public answer, and return a
  * dispatcher whose socket lookup is pinned to those exact answers. Resolving
  * before creating the dispatcher makes the policy easy to audit; overriding
  * the connector lookup closes the validation-to-connect DNS-rebinding gap.
  */
-export async function createPinnedDispatcher(url: URL): Promise<Agent> {
-  const addresses = await resolveAllowedAddresses(url.hostname);
+export async function createPinnedDispatcher(
+  url: URL,
+  trustedProviderPath = false,
+): Promise<Agent> {
+  const addresses = await resolveAllowedAddresses(
+    url.hostname,
+    trustedProviderPath,
+  );
 
   let nextAddress = 0;
   return new Agent({
@@ -45,7 +84,8 @@ export function createConnectPinnedDispatcher(): Agent {
   return new Agent({
     connect: {
       lookup(hostname, options, callback) {
-        resolveAllowedAddresses(hostname).then(
+        // Core provider path — the user's own configured baseUrl.
+        resolveAllowedAddresses(hostname, true).then(
           (addresses) => {
             if (options.all) {
               callback(null, [...addresses]);
@@ -74,6 +114,7 @@ export function createConnectPinnedDispatcher(): Agent {
  */
 async function resolveAllowedAddresses(
   rawHostname: string,
+  trustedProviderPath = false,
 ): Promise<readonly ResolvedAddress[]> {
   const hostname = normalizeHost(rawHostname);
   const literalFamily = isIP(hostname);
@@ -93,6 +134,13 @@ async function resolveAllowedAddresses(
     );
   }
 
+  // Core provider path on the self tier: accept any resolver answer (see the
+  // helper's rationale) — local proxies and LAN endpoints resolve to private
+  // ranges, and the socket stays pinned to these exact addresses regardless.
+  if (allowResolvedPrivateAddresses(literalFamily !== 0, trustedProviderPath)) {
+    return addresses;
+  }
+
   const allowLoopback = LOOPBACK_HOSTNAMES.has(hostname);
   for (const result of addresses) {
     const allowed = allowLoopback
diff --git a/packages/ai-provider/tests/request-dns-safety.test.ts b/packages/ai-provider/tests/request-dns-safety.test.ts
index 66dc15ca..5a46f076 100644
--- a/packages/ai-provider/tests/request-dns-safety.test.ts
+++ b/packages/ai-provider/tests/request-dns-safety.test.ts
@@ -15,6 +15,7 @@ import type { AddressInfo } from "node:net";
 import { lookup } from "node:dns/promises";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { getJson, postJson } from "../src/adapters/http.js";
+import { createPinnedDispatcher } from "../src/adapters/http/dns-safety.js";
 
 vi.mock("node:dns/promises", () => ({ lookup: vi.fn() }));
 
@@ -22,10 +23,13 @@ const lookupMock = vi.mocked(lookup);
 
 afterEach(() => {
   lookupMock.mockReset();
+  vi.unstubAllEnvs();
 });
 
 describe("core request DNS SSRF safety (S-05)", () => {
-  it("rejects a POST to a hostname resolving to a private IP", async () => {
+  // Hosted tiers keep the strict public-only policy on the core provider path.
+  it("rejects a POST to a hostname resolving to a private IP (hosted tier)", async () => {
+    vi.stubEnv("DEPLOYMENT_TIER", "demo");
     lookupMock.mockResolvedValue([{ address: "10.0.0.8", family: 4 }] as never);
 
     await expect(
@@ -37,7 +41,8 @@ describe("core request DNS SSRF safety (S-05)", () => {
     ).rejects.toThrow(/SSRF policy rejected internal\.example/);
   });
 
-  it("rejects a GET to a hostname resolving to cloud metadata", async () => {
+  it("rejects a GET to a hostname resolving to cloud metadata (hosted tier)", async () => {
+    vi.stubEnv("DEPLOYMENT_TIER", "commercial");
     lookupMock.mockResolvedValue([
       { address: "169.254.169.254", family: 4 },
     ] as never);
@@ -47,7 +52,8 @@ describe("core request DNS SSRF safety (S-05)", () => {
     ).rejects.toThrow(/disallowed address 169\.254\.169\.254/);
   });
 
-  it("rejects localhost when it does not actually resolve to loopback", async () => {
+  it("rejects localhost when it does not actually resolve to loopback (hosted tier)", async () => {
+    vi.stubEnv("DEPLOYMENT_TIER", "demo");
     lookupMock.mockResolvedValue([
       { address: "192.168.1.50", family: 4 },
     ] as never);
@@ -57,6 +63,53 @@ describe("core request DNS SSRF safety (S-05)", () => {
     ).rejects.toThrow(/disallowed address 192\.168\.1\.50/);
   });
 
+  it("self tier accepts private resolver answers on the trusted provider path", async () => {
+    // self tier (default) = single-user local play: a TUN proxy fake-IP
+    // (198.18/15) and a LAN Ollama (192.168.x.x) both resolve to private
+    // ranges and must not be rejected on the user's own configured baseUrl,
+    // or provider calls fail on those machines. Socket stays pinned regardless.
+    for (const address of ["198.18.2.176", "192.168.1.50"]) {
+      lookupMock.mockResolvedValue([{ address, family: 4 }] as never);
+      const dispatcher = await createPinnedDispatcher(
+        new URL("https://api.deepseek.com"),
+        true, // trustedProviderPath — core provider request
+      );
+      expect(dispatcher).toBeDefined();
+      await dispatcher.close();
+    }
+  });
+
+  it("self tier still rejects private answers on the ctx.http (plugin) path", async () => {
+    // Third-party plugin code never gets the self-tier exemption, so it can
+    // not probe the local network even on a desktop install.
+    lookupMock.mockResolvedValue([
+      { address: "198.18.2.176", family: 4 },
+    ] as never);
+
+    await expect(
+      createPinnedDispatcher(new URL("https://api.deepseek.com")),
+    ).rejects.toThrow(/disallowed address 198\.18\.2\.176/);
+  });
+
+  it("rejects private answers on the trusted path on hosted tiers", async () => {
+    vi.stubEnv("DEPLOYMENT_TIER", "demo");
+    lookupMock.mockResolvedValue([
+      { address: "198.18.2.176", family: 4 },
+    ] as never);
+
+    await expect(
+      createPinnedDispatcher(new URL("https://api.deepseek.com"), true),
+    ).rejects.toThrow(/disallowed address 198\.18\.2\.176/);
+  });
+
+  it("rejects a literal private-range URL even on the self trusted path", async () => {
+    // IP-literal URLs never get the self-tier exemption (url-safety's string
+    // check also blocks these upstream).
+    await expect(
+      createPinnedDispatcher(new URL("https://198.18.1.1"), true),
+    ).rejects.toThrow(/disallowed address 198\.18\.1\.1/);
+  });
+
   it("still serves loopback (local Ollama-style) endpoints", async () => {
     const server = createServer((_req, res) => {
       res.writeHead(200, { "content-type": "application/json" });