@sema-agent/server 2.0.0 → 3.0.0

package/dist/boot/stores.js

@@ -0,0 +1,361 @@
+/**
+ * design/158 A10:composition root 分段 —— 持久层装配(StoreBackend / memory engine / roster /
+ * background-agent / attachment / mailbox / memory sync / session store + 姿势断言 / breaker)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 627-932 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:
+ *  1. 本段**就地改写 `config.sessionBackend`**(`auto` → `tidb|memory`,local backend 再归一为 `tidb`)。
+ *     这两行是后续所有消费点(createSessionStore / ensureChildSessionDurable 的 tidb 门 / /health 标签)
+ *     的前置条件,必须留在本段这个位置,不能上移(backend 还没开)也不能下移(消费点已读)。
+ *  2. `assertCloudSnapshotBlobPosture` 与两条 REQUIRE_PRINCIPAL 拒启断言必须在 sessionStore 造出来之后、
+ *     任何路由装配之前 —— fail-loud 拒启的意义就在于"还没开始服务"。
+ *  3. `breakerState` 放在段尾:brain(下一段)要它,而它要 backend。
+ */
+import { join } from "node:path";
+import { FileBackgroundAgentStore, FileMailboxStore, FileRosterStore } from "@sema-agent/core";
+import { createMemorySyncRunner, createMemorySyncTransport } from "../memory-sync-client.js";
+import { PgMemoryEngineBackend, ensurePgMemoryEngineSchema } from "../plugins/memory-engine-pg.js";
+import { TiDBMemoryEngineBackend, ensureTiDBMemoryEngineSchema } from "../plugins/memory-engine-tidb.js";
+import { PgMemoryHistoryStore, PgMemorySyncStore, ensurePgMemoryHistorySchema, ensurePgMemorySyncSchema } from "../plugins/memory-sync-store-pg.js";
+import { TiDBMemoryHistoryStore, TiDBMemorySyncStore, ensureTiDBMemoryHistorySchema, ensureTiDBMemorySyncSchema } from "../plugins/memory-sync-store-tidb.js";
+import { MinioBlobBackend } from "../plugins/blob-backend.js";
+import { PgBackgroundAgentStore, TiDBBackgroundAgentStore, ensurePgBackgroundAgentSchema, ensureTiDBBackgroundAgentSchema } from "../plugins/background-agent-store-sql.js";
+import { PgMailboxStore, TiDBMailboxStore, ensurePgMailboxSchema, ensureTiDBMailboxSchema } from "../plugins/mailbox-store-sql.js";
+import { PgRosterStore, TiDBRosterStore, ensurePgRosterSchema, ensureTiDBRosterSchema } from "../plugins/roster-store-sql.js";
+import { LocalTaskAttachmentStore } from "../plugins/local-task-attachment-store.js";
+import { PgTaskAttachmentStore, TiDBTaskAttachmentStore, ensurePgTaskAttachmentSchema, ensureTiDBTaskAttachmentSchema } from "../plugins/task-attachment-store.js";
+import { createSessionStore } from "../plugins/session-store.js";
+import { assertCloudSnapshotBlobPosture, openStoreBackendWithFallback } from "../plugins/store-backend.js";
+import { memoryEngineBackendFor, memoryEngineRemoteLanePosture } from "../security.js";
+export async function openStores(ctx) {
+    const { config, logger, metrics, localRoot } = ctx;
+    // One shared SQL store backend for L1 + L2 (TiDB/MySQL or PostgreSQL per DB_BACKEND). Owned here.
+    let backend;
+    let storeBackendDegraded = false; // S5: auto-probe degraded this replica to in-memory (surfaced via gauge + /health)
+    // `auto` probes a configured DB and degrades to in-memory if it's unreachable (local/intranet binaries:
+    // "use my DB if I can reach it, else memory"). Explicit `tidb` fails fast instead — silently dropping
+    // persistence the operator asked for would lose runs. (`tidb` here = "the SQL DB"; DB_BACKEND picks the engine.)
+    const wantDb = config.sessionBackend === "tidb" ||
+        config.dbBackend === "local" || // local (clay 2026-06-25): always build the DB-less in-memory/file StoreBackend
+        (config.sessionBackend === "auto" && !!(config.tidb || config.pg));
+    if (wantDb) {
+        // 构造 + ensureSchema 同罩一层降级臂(2026-07-28 修):原先 try 只罩 ensureSchema,而 local 形真正
+        // 会抛的是构造里的 mkdir + 数据根 BootLock ——「裸 boot 不得拒启」那条口径对 local 从未生效过。
+        // 降级/fail-loud 的判据与理由见 openStoreBackendWithFallback 顶注。
+        const opened = await openStoreBackendWithFallback(config, logger);
+        backend = opened.backend;
+        storeBackendDegraded = opened.degraded;
+    }
+    // S5 review LOW-1: always render the series (0 = healthy) — gauge absence is indistinguishable from
+    // "old build without this metric", which breaks `== 0`-style alert rules.
+    metrics.setGauge("store_backend_degraded", storeBackendDegraded ? 1 : 0);
+    // S21 (SILENT-FALLBACK P1): MINIO_* partially set silently falls back to SQL-blob snapshots. Warn on the
+    // partial config and always render which backend blobs actually use.
+    {
+        const minioReq = ["MINIO_ENDPOINT", "MINIO_ACCESS_KEY", "MINIO_SECRET_KEY"];
+        const present = minioReq.filter((v) => (process.env[v] ?? "") !== "");
+        if (present.length > 0 && !config.snapshotBlobStore) {
+            logger.warn("snapshot_blob_store_partial_config_fallback_sql", { present, missing: minioReq.filter((v) => !present.includes(v)) });
+        }
+        metrics.setGauge("snapshot_blob_backend", 1, { backend: config.snapshotBlobStore ? "minio" : "sql" });
+    }
+    // Resolve `auto` to the concrete backend the rest of the wiring understands (createSessionStore,
+    // runStore, the startup summary). A DB-backed L2 with no backend degrades to in-memory the same way.
+    if (config.sessionBackend === "auto")
+        config.sessionBackend = backend ? "tidb" : "memory";
+    // local backend: route the session store through backend.session() (LocalSessionStore — the §0.5 OwnerAware twin),
+    // NOT the bare TtlSessionStore the "memory" path returns; "tidb" here means "the backend's durable store" generically.
+    if (config.dbBackend === "local" && backend)
+        config.sessionBackend = "tidb";
+    // Long-term memory (design/138 S1, clay 2026-07-08): the injection-first file-based memory ENGINE is the
+    // only memory plane — `RunnerDeps.memoryBackend` is core's switch (materialize → session file ops →
+    // harvest; no remember/recall tools). SINGLE-USER TURNKEY ONLY: the file basement has no tenant
+    // isolation, so a multi-tenant deployment (requirePrincipal) gets `undefined` = memory dark, fail-closed
+    // (memoryEngineBackendFor + memoryScopeFor enforce the same gate). The legacy MemoryStore plane
+    // (MEMORY_BACKEND/EMBEDDING_*) was dropped without migration; `scripts/drop-memory-tables.sql` drops the table.
+    // S3-TOB(设计 §1.3,后经改判与边界重切):backend 选择器——file=现状(单用户/host);pg|tidb=
+    // DB durable 真身(零卷主档:memory/ 文件面=materialize 的 ephemeral 工作副本,harvest 回 DB=持久化
+    // 时点)。DB backend 是多租户点亮的唯一门(显式 opt-in);选了 DB 但池不可用/方言不匹配=fail-loud 拒启
+    // (no-stopgap:绝不静默降 File/dark)。
+    let memoryEngine;
+    // 142-S2.5:per-(scope,peer) 同步游标面(sync_cursors)——POST /v1/memory/sync/:scope 的持久化半场。
+    // 只在 DB memory plane 上点亮(file 形态路由 501,不接);与 entry plane 同池同方言。
+    let memorySyncCursors;
+    if (config.memoryEngineBackend !== "file" && config.memoryEngineEnabled) {
+        const dialect = config.memoryEngineBackend;
+        // 142-S5.1 production history sink: every applied patch appends one
+        // agent_memory_engine_history row via the backend's optional history opts. The wrapper's ONLY
+        // job is the metrics leg — count lost rows BEFORE rethrowing (the backend swallows + warns with
+        // its own cumulative count; the audit line's breakage must itself be auditable).
+        const countedHistorySink = (store) => ({
+            appendHistory: async (rows) => {
+                try {
+                    await store.appendHistory(rows);
+                }
+                catch (err) {
+                    metrics.inc("memory_history_append_failed_total", { backend: dialect }, rows.length);
+                    throw err;
+                }
+            },
+        });
+        if (dialect === "pg") {
+            const pool = backend?.pgPool();
+            if (!pool)
+                throw new Error("MEMORY_ENGINE_BACKEND=pg requires DB_BACKEND=pg (the memory engine binds the same PG pool) — refusing to start half-configured");
+            const q = async (text, params) => { const r = await pool.query(text, params); return { rows: r.rows }; };
+            await ensurePgMemoryEngineSchema(q);
+            await ensurePgMemoryHistorySchema(q);
+            await ensurePgMemorySyncSchema(q); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
+            memorySyncCursors = new PgMemorySyncStore(q);
+            const pgMem = new PgMemoryEngineBackend(q, { history: countedHistorySink(new PgMemoryHistoryStore(q)) });
+            // 工作面根:DB 形态下 memory/ 目录=per-worker ephemeral 物化区(丢了重建,控制面同);
+            // 复用 localDataRoot 下独立子树,绝不与 File backend 的持久 memory/ 混写。
+            memoryEngine = { backend: pgMem, root: join(config.localDataRoot ?? localRoot, "memory-work") };
+        }
+        else {
+            const pool = backend?.mysqlPool();
+            if (!pool)
+                throw new Error("MEMORY_ENGINE_BACKEND=tidb requires DB_BACKEND=mysql/tidb — refusing to start half-configured");
+            await ensureTiDBMemoryEngineSchema(pool);
+            await ensureTiDBMemoryHistorySchema(pool);
+            await ensureTiDBMemorySyncSchema(pool); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
+            memorySyncCursors = new TiDBMemorySyncStore(pool);
+            memoryEngine = { backend: new TiDBMemoryEngineBackend(pool, { history: countedHistorySink(new TiDBMemoryHistoryStore(pool)) }), root: join(config.localDataRoot ?? localRoot, "memory-work") };
+        }
+        logger.info("memory_engine_enabled", { enabled: true, backend: dialect, multiTenant: config.requirePrincipal === true, workRoot: memoryEngine.root });
+    }
+    else {
+        memoryEngine = memoryEngineBackendFor(config);
+        // [1845]②(cli 桌面撞坑;壳侧此前同坑已各自修过——两个宿主都踩=第三个宿主还会踩):操作员用
+        // LOCAL_DATA_ROOT 明确要了隔离数据根,MEMORY_ENGINE_DIR 却缺省 ⇒ file 形 memory engine 落 core
+        // 默认链(AGENT_DATA_DIR → ~/.ai-agent)= **静默共享全机 memory 库**。不改行为(单机用户可能就要
+        // 共享),只把「你现在在共享」说出来。
+        if (memoryEngine && process.env.LOCAL_DATA_ROOT && !config.memoryEngineDir) {
+            logger.warn("memory_engine_dir_defaulted", {
+                root: memoryEngine.root,
+                hint: "LOCAL_DATA_ROOT is set but MEMORY_ENGINE_DIR is not — the memory engine is sharing the machine-wide default; set MEMORY_ENGINE_DIR to isolate it under your data root",
+            });
+        }
+    }
+    // RosterStore(agent-team S1 server 半场,[1070]① 提货单;core 1.316 `RunnerDeps.rosterStore`):
+    // 具名子 agent 持久名册。形态跟 StoreBackend:tidb/pg=SQL twins(语义三条+真双库验证,
+    // roster-store-sql.ts 顶注);local=core FileRosterStore(dataRoot 下 roster.json,core 自带原子写/
+    // 损坏安全);无 backend(纯内存 dev)=不挂(core 用活注册表,跨 run 指针面自然缺席——诚实)。
+    let rosterStore;
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool) {
+            const q = async (text, params) => { const r = await pgPool.query(text, params); return { rows: r.rows }; };
+            await ensurePgRosterSchema(q);
+            rosterStore = new PgRosterStore(q);
+        }
+        else if (mysqlPool) {
+            await ensureTiDBRosterSchema(mysqlPool);
+            rosterStore = new TiDBRosterStore(mysqlPool);
+        }
+        else if (backend?.kind === "local") {
+            rosterStore = new FileRosterStore(join(config.localDataRoot ?? localRoot, "roster.json"));
+        }
+        if (rosterStore)
+            logger.info("roster_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
+    }
+    // BackgroundAgentStore(design/151 S1 server 半场,[1503] 提货单;core 1.364 durable background agents):
+    // 后台子代 `a*` 行的 durable 执行记录——settle 后转录 session 不再 eager release(TaskOutput/
+    // AgentTranscript 完成后照读全程),清理移交 reapDurableAgents(reaper 区)。形态跟 roster:
+    // tidb/pg=SQL twins(真双库验证,background-agent-store-sql.ts 顶注);local=core
+    // FileBackgroundAgentStore(dataRoot 下 background-agents/,core 自带 ledger+snapshot 原子写);
+    // 无 backend(纯内存 dev)=不挂(core 契约:store 不接线=pre-151 逐字节等价——单进程 live 注册表
+    // 已覆盖读面,诚实缺席)。⚠️ 同实例双点挂载:RunnerDeps.backgroundAgentStore(读半场)+
+    // ScenarioDeps→SubagentToolOptions.background.agentStore(写半场)都用这一个引用——engine 无法核对
+    // 配对,半接=静默死特性(RB-37①)。
+    let backgroundAgentStore;
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool) {
+            const q = async (text, params) => { const r = await pgPool.query(text, params); return { rows: r.rows }; };
+            await ensurePgBackgroundAgentSchema(q);
+            backgroundAgentStore = new PgBackgroundAgentStore(q);
+        }
+        else if (mysqlPool) {
+            await ensureTiDBBackgroundAgentSchema(mysqlPool);
+            backgroundAgentStore = new TiDBBackgroundAgentStore(mysqlPool);
+        }
+        else if (backend?.kind === "local") {
+            // core 1.368([1516]②)listScopes 落地:file 实现自带枚举——1.248 拍的「local+多租户 reap 缺口」
+            // warn-once 已撤(reaper 腿现在真枚举,不再假设单 scope)。
+            backgroundAgentStore = new FileBackgroundAgentStore(config.localDataRoot ?? localRoot);
+        }
+        if (backgroundAgentStore)
+            logger.info("background_agent_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
+    }
+    // D-1 通用文件上传(clay 拍 2026-07-27):独立附件 store(不骑 snapshot blob 面——那套的 orphan GC
+    // 会把非 manifest 引用的 bytes 误收;生命周期也不同:附件跟 task/session 绑定)。形态跟 StoreBackend
+    // 三态:tidb/pg=SQL twins(真双库验证)、local=文件店;无 backend(纯内存 dev)=不挂 ⇒ 路由 501。
+    // 四半场:①上传/取回/删除(http/server.ts 路由)②提交时绑定+objective 告知+host lane 物化
+    // (resolveSpec 内,下方)③远程 lane env 建立时物化(executionEnvFactory 包装,下方)④生命周期
+    // (E21 purge 级联 + 未绑定 TTL reaper)。
+    let taskAttachmentStore;
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool || mysqlPool) {
+            // clay 裁(2026-07-27):**云形态对象存储必配**——附件字节本体进 MinIO(SQL 只存 meta/门/生命周期)。
+            // 复用快照 lane 的同一 MinIO 部署配置(MINIO_ENDPOINT/ACCESS/SECRET,零重映射),但**附件专属
+            // keyPrefix**:对象键=sha256,与快照 blob 同 sha 不同生命周期,同名字空间会互删。未配 ⇒ 附件面
+            // 不接线(路由 501)+ error 级日志——这是部署配置错误,不静默降级回「字节进 DB」(该形已被裁掉)。
+            const minio = config.snapshotBlobStore;
+            if (!minio) {
+                logger.error("attachments_disabled_object_store_required", {
+                    hint: "cloud deployments must configure object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) — attachment routes will 501 until it is set",
+                });
+            }
+            else {
+                const bytes = new MinioBlobBackend({ ...minio, keyPrefix: `${minio.keyPrefix ?? ""}attachments/` });
+                if (pgPool) {
+                    const q = async (text, params) => { const r = await pgPool.query(text, params); return { rows: r.rows }; };
+                    await ensurePgTaskAttachmentSchema(q);
+                    taskAttachmentStore = new PgTaskAttachmentStore(q, bytes);
+                }
+                else {
+                    await ensureTiDBTaskAttachmentSchema(mysqlPool);
+                    taskAttachmentStore = new TiDBTaskAttachmentStore(mysqlPool, bytes);
+                }
+            }
+        }
+        else if (backend?.kind === "local") {
+            taskAttachmentStore = new LocalTaskAttachmentStore(config.localDataRoot ?? localRoot);
+        }
+        if (taskAttachmentStore)
+            logger.info("task_attachment_store_enabled", { backend: pgPool ? "pg+minio" : mysqlPool ? "tidb+minio" : "file", maxBytes: config.attachmentMaxBytes });
+    }
+    // S3c(core 1.374 行为车,[1531]):teammate 信箱——SendMessage 对 SETTLED named teammate 的 tier-3
+    // 懒复活链(durable 行解析→claim-CAS→mailbox append→reviveSpawn→attach 屏障后 ack)。激活三件套=
+    // RunnerDeps.mailboxStore + backgroundAgentStore 同挂 + delegation 工具在场,三缺一=1.373 文本字节
+    // 不变(诚实拒)。形态同上:tidb/pg=SQL twins(mailbox-store-sql.ts,发车复审八修顶注);local=
+    // core FileMailboxStore;纯内存 dev=不挂。回执句族(details.error 枚举)wire 透传零改动。
+    let mailboxStore;
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool) {
+            await ensurePgMailboxSchema(async (text, params) => pgPool.query(text, params));
+            mailboxStore = new PgMailboxStore(pgPool);
+        }
+        else if (mysqlPool) {
+            await ensureTiDBMailboxSchema(mysqlPool);
+            mailboxStore = new TiDBMailboxStore(mysqlPool);
+        }
+        else if (backend?.kind === "local") {
+            mailboxStore = new FileMailboxStore(config.localDataRoot ?? localRoot);
+        }
+        if (mailboxStore)
+            logger.info("mailbox_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
+    }
+    // 142-S5 §1.4: the per-scope export READ face lights up only on the DB memory plane (the multi-tenant
+    // truth lives in the scope-partitioned tables; the file posture exports by copying the memory dir, so
+    // the route 501s honestly there). History-table WRITE wiring: inside the backend construction above
+    // (S5.1, opts.history — the write point lives in the handed-over backend code).
+    const memoryExportBackend = config.memoryEngineBackend !== "file" ? memoryEngine?.backend : undefined;
+    const memoryLane = memoryEngineRemoteLanePosture(config); // N0: worker/sandbox file-plane split posture
+    if (config.memoryEngineBackend === "file" || !config.memoryEngineEnabled) {
+        logger.info("memory_engine_enabled", memoryEngine
+            ? { enabled: true, backend: "file", dir: memoryEngine.root }
+            : {
+                enabled: false,
+                // 复审 F-11:按最终门结果报因,多租户 file=隔离判据,其余照旧。
+                reason: config.requirePrincipal === true ? "multi-tenant on the FILE backend (no tenant isolation; set MEMORY_ENGINE_BACKEND=pg|tidb to light up)"
+                    : !config.memoryEngineEnabled ? "MEMORY_ENGINE=off"
+                        : `remote exec lane "${memoryLane?.lane}" (worker/sandbox file planes split; MEMORY_ENGINE_REMOTE_LANE=allow overrides)`,
+            });
+    }
+    // N0 boot warn: loud in BOTH postures — "dark" so an upgrade that silently turns memory off is visible,
+    // "forced" so an operator override states what it depends on (harvest only sees the WORKER fs).
+    if (memoryLane && config.memoryEngineEnabled && config.requirePrincipal !== true) {
+        logger.warn("memory_engine_remote_lane", memoryLane.posture === "dark"
+            ? { lane: memoryLane.lane, effect: "memory dark (fail-closed): the file engine works the worker's local fs while this lane routes model file tools to the sandbox fs — sandbox writes are never harvested. Set MEMORY_ENGINE_REMOTE_LANE=allow ONLY if both are one fs." }
+            : { lane: memoryLane.lane, effect: "MEMORY_ENGINE_REMOTE_LANE=allow: memory engine ON over a remote lane — harvest only sees files landing on the WORKER fs; verify the lane really shares it." });
+    }
+    // 142-S2.5-W1: TOC 同步 client 腿——只在 file memory 形态接线(loadConfig 已拒 DB backend
+    // 上的 MEMORY_SYNC_*,这条分支到不了)。boot 后 fire-and-forget 一轮(失败 warn 不阻断——纯本地现状
+    // 是安全降级面);之后 harvest 真有 patch 落地时再触发(onMemoryHarvestReport 站点,inflight 节流)。
+    // 引擎 dark(多租户/MEMORY_ENGINE=off/remote lane)⇒ 无本地盘可同步:warn 不 throw(dark 的三个成因
+    // 各有自己的 loud 日志在上方,这里补“sync 因此没跑”这半句,operator 可见不半配)。
+    let memorySyncRunner;
+    if (config.memorySync) {
+        if (memoryEngine) {
+            memorySyncRunner = createMemorySyncRunner({
+                backend: memoryEngine.backend,
+                scope: config.memorySync.scope,
+                memoryRoot: memoryEngine.root,
+                transport: createMemorySyncTransport({ url: config.memorySync.url, token: config.memorySync.token }),
+                log: logger,
+                // S2.5 分批(core 1.284):未设=不分批 wire 字节不变;设了=续轮 loop 至收敛(MAX_SYNC_ROUNDS 警戒)。
+                ...(config.memorySync.maxPushEntries !== undefined ? { maxPushEntries: config.memorySync.maxPushEntries } : {}),
+                ...(config.memorySync.maxPullEntries !== undefined ? { maxPullEntries: config.memorySync.maxPullEntries } : {}),
+            });
+            logger.info("memory_sync_enabled", { url: config.memorySync.url, scope: config.memorySync.scope, cursorPath: memorySyncRunner.cursorPath });
+            memorySyncRunner.trigger("boot");
+        }
+        else {
+            logger.warn("memory_sync_configured_but_memory_dark", { note: "MEMORY_SYNC_URL is set but the file memory engine is dark (multi-tenant / MEMORY_ENGINE=off / remote exec lane) — no sync rounds will run" });
+        }
+    }
+    const sessionStore = createSessionStore(config, backend, metrics); // S25: stale-affinity evict fingerprint
+    // S6 startup guard: multi-tenant isolation needs an owner-aware (TiDB) store. Refuse to start with
+    // REQUIRE_PRINCIPAL on an in-memory store that can't enforce session ownership.
+    if (config.requirePrincipal && !sessionStore.ownerOf) {
+        throw new Error("REQUIRE_PRINCIPAL=true needs an owner-aware session store (SESSION_BACKEND=tidb); " +
+            "the in-memory store cannot enforce session ownership.");
+    }
+    // The local in-memory backend HAS an ownerOf (LocalSessionStore), so the guard above passes — but its owner map is
+    // process-local + lost on restart, so it cannot DURABLY enforce multi-tenant ownership (post-restart a session id is
+    // re-claimable by whoever attaches first). Refuse REQUIRE_PRINCIPAL on it: a real multi-tenant
+    // boundary needs the durable DB backend; single-user local runs with REQUIRE_PRINCIPAL=false (the principal may
+    // still ride for memory-scoping). The file-backed follow-on (durable owners) can revisit this.
+    if (config.requirePrincipal && backend?.kind === "local") {
+        throw new Error("REQUIRE_PRINCIPAL=true is not supported on the local file backend (DB_BACKEND=local): session/run CONTENT is " +
+            "durable there, but OWNER attribution is process-local and lost on restart (store-backend.ts §0.5 — durable " +
+            "owners = P1), so it cannot durably enforce multi-tenant session ownership. Use a SQL backend " +
+            "(DB_BACKEND=mysql|pg) for multi-tenant, or run local single-user with REQUIRE_PRINCIPAL=false (a BFF may " +
+            "still inject x-agent-principal per request for memory scoping and audit attribution).");
+    }
+    // (c)(clay 拍 a+c,2026-07-27)云形快照 blob 姿势门:mysql|pg 后端缺 MinIO ⇒ fail-loud(bytes-in-DB
+    // 撞包墙已两役实证);SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true 显式逃生(单机/测试台,吃 (a) 的 per-blob 帽)。
+    if (backend)
+        assertCloudSnapshotBlobPosture(backend.kind, config);
+    // Posture warning (audit B, security.ts): an owner-aware store without REQUIRE_PRINCIPAL means the
+    // principal layer is optional per request. Owned sessions are still protected (the authorizer rejects
+    // anonymous/mismatched attach), but new headerless submissions create anonymous sessions any token
+    // holder can attach to — a multi-tenant deployment should set REQUIRE_PRINCIPAL=true.
+    if (!config.requirePrincipal && sessionStore.ownerOf) {
+        logger.warn("principal_optional", {
+            note: "owner-aware session store with REQUIRE_PRINCIPAL=false — owned sessions are protected, but headerless callers can create/share anonymous sessions; set REQUIRE_PRINCIPAL=true for multi-tenant",
+        });
+    }
+    metrics.dynamicGauge("sessions_warm", "Sessions held in the warm cache", () => sessionStore.size);
+    // 1.38 cross-replica circuit-breaker state: shared via TiDB when a pool exists AND the breaker is
+    // enabled; otherwise core's per-process Map (single replica / no DB / breaker off). Refresh loop is
+    // unref'd so it never holds the process open.
+    const breakerState = backend?.breaker && config.resilience.circuitBreaker
+        ? backend
+            .breaker((streak) => {
+            // LOW (SILENT-FALLBACK P1): cross-replica breaker write-through failures were a bare swallow.
+            metrics.setGauge("counter_flush_fail_streak", streak, { table: "circuit_breaker", kind: "write_through" });
+            if (streak > 0)
+                metrics.inc("breaker_writethrough_failed_total", { backend: backend.kind });
+            if (streak === 3)
+                logger.warn("breaker_writethrough_degraded", { streak });
+            else if (streak === 0)
+                logger.info("breaker_writethrough_recovered", {});
+        })
+            .startRefresh()
+        : undefined; // local omits breaker() → core's per-process Map
+    return {
+        backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore,
+        taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState,
+    };
+}
+//# sourceMappingURL=stores.js.map

package/dist/boot/workflow-orchestration.d.ts

@@ -0,0 +1,46 @@
+/**
+ * design/158 A10:composition root 分段 —— workflow 编排面(run store / notify 门 / completion inbox /
+ * fleet 总线 / 可 steer 句柄注册表)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 1315-1441 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:
+ *  1. `fleetBus` 必须**先于** `workflowRunStore` 构造 —— `JournalingWorkflowRunStore` 要把 workflow 行
+ *     发布到它上面(原文逐字注释即此)。
+ *  2. `baseWorkflowRunStore` → `workflowNotifyJournal` → `workflowCompletionInbox` → `workflowNotifyGate`
+ *     → `workflowRunStore`(包装体)的顺序是数据依赖链,不可重排。
+ *  3. `getRunStore()` 是晚绑取值(runStore 在本段之后构造),原文靠同作用域前向引用。
+ */
+import { type WorkflowRunStore } from "@sema-agent/core";
+import type { ServiceConfig } from "../config.js";
+import { FleetEventBus } from "../fleet/fleet-bus.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { type WorkflowCompletionInbox } from "../orchestration/workflow-completion-inbox.js";
+import { WorkflowNotifyGate, type WorkflowCompletionPayload } from "../orchestration/workflow-notify-journal.js";
+import { SubagentSteerRegistry } from "../orchestration/subagent-steer.js";
+import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
+import type { StoreBackend } from "../plugins/store-backend.js";
+export interface WorkflowOrchestrationCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    localRoot: string;
+    backend: StoreBackend | undefined;
+    /** 晚绑(runStore 在本段之后构造)——见文件头「位置即契约」③。 */
+    getRunStore: () => ReturnType<StoreBackend["run"]> | undefined;
+}
+export declare function createWorkflowOrchestration(ctx: WorkflowOrchestrationCtx): {
+    sqlWorkflowRunStore: WorkflowRunStore | undefined;
+    workflowNotifyJournal: import("../orchestration/workflow-notify-journal.js").WorkflowNotifyJournalStore | undefined;
+    workflowCompletionInbox: WorkflowCompletionInbox | undefined;
+    deliverWorkflowCompletion: (p: WorkflowCompletionPayload) => Promise<void>;
+    workflowNotifyGate: WorkflowNotifyGate | undefined;
+    fleetBus: FleetEventBus;
+    workflowRunStore: WorkflowRunStore | undefined;
+    workflowJournalStore: import("../plugins/store-backend.js").ServiceWorkflowJournalStore | undefined;
+    outcomeSink: import("../plugins/file-outcome-sink.js").OutcomeSink | undefined;
+    workflowAgentRegistry: WorkflowAgentRegistry | undefined;
+    subagentSteerRegistry: SubagentSteerRegistry;
+};
+//# sourceMappingURL=workflow-orchestration.d.ts.map

package/dist/boot/workflow-orchestration.js

@@ -0,0 +1,150 @@
+/**
+ * design/158 A10:composition root 分段 —— workflow 编排面(run store / notify 门 / completion inbox /
+ * fleet 总线 / 可 steer 句柄注册表)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 1315-1441 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:
+ *  1. `fleetBus` 必须**先于** `workflowRunStore` 构造 —— `JournalingWorkflowRunStore` 要把 workflow 行
+ *     发布到它上面(原文逐字注释即此)。
+ *  2. `baseWorkflowRunStore` → `workflowNotifyJournal` → `workflowCompletionInbox` → `workflowNotifyGate`
+ *     → `workflowRunStore`(包装体)的顺序是数据依赖链,不可重排。
+ *  3. `getRunStore()` 是晚绑取值(runStore 在本段之后构造),原文靠同作用域前向引用。
+ */
+import { FileWorkflowRunStore, InMemoryWorkflowRunStore } from "@sema-agent/core";
+import { join } from "node:path";
+import { FleetEventBus } from "../fleet/fleet-bus.js";
+import { FileWorkflowCompletionInbox, InMemoryWorkflowCompletionInbox, resolveCompletionRoute } from "../orchestration/workflow-completion-inbox.js";
+import { FileWorkflowNotifyJournalStore, JournalingWorkflowRunStore, WorkflowNotifyGate } from "../orchestration/workflow-notify-journal.js";
+import { SubagentSteerRegistry } from "../orchestration/subagent-steer.js";
+import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
+export function createWorkflowOrchestration(ctx) {
+    const { config, logger, metrics, localRoot, backend, getRunStore } = ctx;
+    // S8 / SVC-1 workflow run store (design/97 S1b): records LLM-authored BACKGROUND workflow
+    // runs for the /v1/workflows list+detail view (live subscribe is in-process via subscribeWorkflow,
+    // store-independent). Only present when self-orchestration is enabled (else no runs to record).
+    //
+    // SVC-1: the DEFAULT is now `FileWorkflowRunStore` (durable, crash-safe ledger) — NOT InMemory — so a
+    // background workflow's record SURVIVES a replica restart, which is the prerequisite for the at-least-once
+    // completion notify below to re-derive a run's terminal state after a crash. InMemory stays available only for
+    // an explicit ephemeral opt-out (WORKFLOW_RUN_STORE=memory); a durable cross-replica TiDB/PG WorkflowRunStore
+    // is a clean follow-on port (the workflowRunStoreContract makes it a drop-in like the run-store).
+    // P1 (fleet failover, 2026-07-05): `auto` (the default) prefers the SQL backend's cross-replica twin when
+    // present — a failover-landed session sees the run's history + its pending completion push on ANY replica.
+    // Explicit WORKFLOW_RUN_STORE=file/memory still wins (single-box File posture unchanged: local backend has
+    // no workflowRun() so auto falls to File there).
+    const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.() : undefined;
+    const baseWorkflowRunStore = config.selfOrchestrationEnabled
+        ? config.workflowRunStoreBackend === "memory"
+            ? new InMemoryWorkflowRunStore()
+            : (sqlWorkflowRunStore ?? new FileWorkflowRunStore(join(config.localDataRoot ?? localRoot, "workflows")))
+        : undefined;
+    // SVC-1 at-least-once completion-notify TRUST GATE (the half that is service's, [[core-service-boundary]]):
+    // core's `run_workflow` fires an in-process at-MOST-once notify on terminal — a crash between terminal and the
+    // receiver loses it. The gate makes it at-LEAST-once: a durable notify-journal records every STARTED run
+    // (observed via the JournalingWorkflowRunStore decorator's `put`), the LIVE notify path delivers-then-acks, and
+    // a BOOT recovery sweep re-derives every un-acked run's terminal state from the run store + re-delivers (the
+    // receiver is idempotent on runId). The default journal is the zero-dependency crash-safe File ledger; with no
+    // run store (self-orchestration off) there's nothing to journal, so the gate is absent.
+    // 1.108 review fix (lens③ HIGH): the journal FOLLOWS the run-store axis like the inbox — a SQL run store +
+    // inbox with a replica-LOCAL File journal meant a replica that died holding an un-acked notify stranded it
+    // forever (no surviving replica could recover it: at-least-once silently degraded to at-most-once across
+    // replica death — the exact fleet-failover gap P1 exists to close).
+    const workflowNotifyJournal = config.selfOrchestrationEnabled && config.workflowRunStoreBackend !== "memory"
+        ? (sqlWorkflowRunStore ? backend.notifyJournal() : new FileWorkflowNotifyJournalStore(join(config.localDataRoot ?? localRoot, "workflows")))
+        : undefined;
+    // P1 ①②: the async-workflow COMPLETION INBOX — the push half. A finished background
+    // workflow's completion is enqueued here keyed by the ORIGINATING session, and drained + emitted as a
+    // `workflow_complete` out-of-band SSE frame when that session next opens a stream (see server.ts). File-backed
+    // (crash-safe) when self-orchestration is on with a durable store; the ephemeral opt-out uses in-memory.
+    // P1: the inbox FOLLOWS the run-store choice (one axis, no split-brain: a SQL run record with a File inbox
+    // would re-open the cross-replica double-push the fence rows exist to close).
+    const workflowCompletionInbox = config.selfOrchestrationEnabled
+        ? config.workflowRunStoreBackend === "memory"
+            ? new InMemoryWorkflowCompletionInbox((msg, meta) => logger.warn(msg, meta))
+            : (sqlWorkflowRunStore ? backend.completionInbox((msg, meta) => logger.warn(msg, meta)) : new FileWorkflowCompletionInbox(join(config.localDataRoot ?? localRoot, "workflows"), (msg, meta) => logger.warn(msg, meta)))
+        : undefined;
+    // The deployment's REAL completion delivery: log + meter, THEN push into the originating session's inbox so the
+    // model that launched the workflow learns it finished (the `WorkflowStatus` poll is the deterministic floor;
+    // this is the proactive push). The gate guards this so it fires at-least-once + at-most-once-per-run-steady.
+    // `runStore` (below) is resolved at CALL time (post-boot) — a forward reference into the same boot scope.
+    const deliverWorkflowCompletion = async (p) => {
+        logger.info("workflow_completed", {
+            runId: p.runId,
+            status: p.status,
+            ...(p.sourceTaskId ? { sourceTaskId: p.sourceTaskId } : {}),
+        });
+        metrics.inc("workflow_runs_total", { status: p.status });
+        // Routing (core 1.208): session = payload's `originatingSessionId` (lookup-free); owner = run-row
+        // owner → payload `principal` (= VERIFIED spec.principal, the 1.55 F-fix invariant — covers the sync/resume
+        // legs whose sourceTaskId is a sessionId and misses getRun) → multi-tenant fail-closed /
+        // single-user null. Full rationale on `resolveCompletionRoute` (tested there).
+        if (!workflowCompletionInbox)
+            return;
+        try {
+            const route = await resolveCompletionRoute(p, getRunStore() ? (id) => getRunStore().getRun(id) : undefined, config.requirePrincipal === true); // A10 搬运改写:晚绑取值
+            if (!route)
+                return; // no route / unverifiable owner → the WorkflowStatus poll floor covers it
+            // `p.summary` is HUMAN-READABLE at the source since core 1.232 (completed lane = bounded
+            // one-liner with name/elapsed/agents + a TaskOutput pointer; failed lane = the bounded redacted error)
+            // — pass through verbatim, single-sourced (the 1.101.0 service-side re-wrap was superseded by core's
+            // own half and removed to avoid two drifting formats).
+            await workflowCompletionInbox.enqueue({
+                sessionId: route.sessionId,
+                owner: route.owner,
+                runId: p.runId,
+                status: p.status,
+                summary: p.summary,
+                enqueuedAt: Date.now(),
+            });
+        }
+        catch (err) {
+            logger.warn("workflow_completion_enqueue_failed", { runId: p.runId, err: String(err) });
+        }
+    };
+    const workflowNotifyGate = baseWorkflowRunStore && workflowNotifyJournal
+        ? new WorkflowNotifyGate(workflowNotifyJournal, baseWorkflowRunStore, deliverWorkflowCompletion, {
+            onError: (stage, runId, err) => logger.warn("workflow_notify_failed", { stage, runId, err: String(err) }),
+        })
+        : undefined;
+    // MF-Fleet (data contract): the in-process fleet aggregation bus backing GET /v1/fleet/stream. Created HERE
+    // (before the workflow run store) so the JournalingWorkflowRunStore can publish workflow rows to it. Always
+    // present (lightweight); the run (POST /v1/runs) + workflow lifecycle publish per-row deltas. Replica-local.
+    const fleetBus = new FleetEventBus();
+    // The store handed to core (+ the /v1/workflows reader): ALWAYS wrapped when a run store exists ([1262]
+    // fleet decoupling) — the wrap publishes the workflow's MF-Fleet row on each put/update (the write-observation
+    // point the shell's /workflows panel lives on), and ADDITIONALLY journals the start-time `put` when the notify
+    // gate is active (durable backends). The old `baseWorkflowRunStore && workflowNotifyGate` guard silently
+    // dropped the FLEET half on the memory backend (gate needs a durable journal; fleet needs neither) — clay's
+    // workflow panel went empty on exactly that shape.
+    const workflowRunStore = baseWorkflowRunStore
+        ? new JournalingWorkflowRunStore(baseWorkflowRunStore, workflowNotifyGate, fleetBus)
+        : undefined;
+    // SVC-2 (core CORE-7/CORE-9 Part A): the durable resume journal. core 1.145.0 added `RunnerDeps.workflowJournalStore`
+    // (twin of workflowRunStore) + auto-wires it into the run_workflow tool's startWorkflow(RunWorkflowOptions.journalStore);
+    // the tool's `resumeFromRunId` input then replays the longest unchanged prefix. tidb/pg = durable cross-replica resume;
+    // local = core's InMemory (single-process — in-process resume only, not restart-durable). Only when self-orchestration
+    // is on AND a backend is present (the load-bearing journal needs a real store).
+    const workflowJournalStore = config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
+    // design/73 §1 consumption sink (see RunnerDeps.onTaskOutcome below). Present whenever a StoreBackend is —
+    // NOT gated on self-orchestration (goal-mode/harness emissions are orthogonal to workflows).
+    const outcomeSink = backend?.outcomeSink();
+    // SVC-5 (CORE-9 Part B): the process-local registry of STEERABLE workflow-agent handles live on THIS replica,
+    // backing POST /v1/workflows/:id/agents/:label/steer. core 1.145.0 added `RunnerDeps.onWorkflowAgentSpawn` (the
+    // opt-in deployment handle-sink): when set, the run_workflow tool's `agent()` runs steerable + emits the handle
+    // HERE (the handle is a core object handed only to the trusted deployment sink — it NEVER enters the script/runner,
+    // so the script-sandbox host-context membrane stays closed). We register by runId+label; the steer route looks it up + calls
+    // handle.steer (core fences via CORE-5) behind our steer-in redaction + owner gate.
+    const workflowAgentRegistry = config.selfOrchestrationEnabled ? new WorkflowAgentRegistry() : undefined;
+    // C2 (core 1.219): the replica-local registry of STEERABLE Task-subagent handles, backing
+    // POST /v1/runs/:runId/subagents/:target/steer. Core emits a handle to the per-run `onSubagentSpawn` sink
+    // (wired in each run leg) the moment a SYNC delegation spawns; the handle never reaches the model. Always
+    // present (lightweight Map) — the sink is only threaded where a durable runId exists to address it by.
+    const subagentSteerRegistry = new SubagentSteerRegistry();
+    return {
+        sqlWorkflowRunStore, workflowNotifyJournal, workflowCompletionInbox, deliverWorkflowCompletion,
+        workflowNotifyGate, fleetBus, workflowRunStore, workflowJournalStore, outcomeSink,
+        workflowAgentRegistry, subagentSteerRegistry,
+    };
+}
+//# sourceMappingURL=workflow-orchestration.js.map

package/dist/capabilities/scenarios.d.ts

@@ -105,9 +105,11 @@ export interface ScenarioDeps {
  * the operator configured — not Claude/Anthropic), so the agent never inherits the model's training-time
  * "I am Claude" hallucination.
  *
- * Live-caught incident (a Qwen3.5 deployment self-described as "running on a DeepSeek model"):
- * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (Qwen/GLM/Kimi/self-hosted
- * vLLM…), so a baked maker name makes every non-DeepSeek deployment misstate its own substrate. Same for
+ * Live-caught incident (a deployment served by one model family described itself as running on a DIFFERENT
+ * vendor's model, because that vendor's name was baked into this text):
+ * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (any OpenAI-/Anthropic-
+ * compatible endpoint, self-hosted vLLM included), so a baked maker name makes every deployment that is not
+ * that maker's misstate its own substrate. Same for
  * the gateway protocol (the brain stack serves Anthropic-compatible routes too — routing brain +
  * createAnthropicBrain — so "OpenAI-compatible gateway" would be the same class of lie). Neutral wording
  * (zero core-seam need; interpolating the model id would need a `StablePromptContext.model`

package/dist/capabilities/scenarios.js

@@ -14,9 +14,11 @@ import { skillsForScenario } from "./skills.js";
  * the operator configured — not Claude/Anthropic), so the agent never inherits the model's training-time
  * "I am Claude" hallucination.
  *
- * Live-caught incident (a Qwen3.5 deployment self-described as "running on a DeepSeek model"):
- * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (Qwen/GLM/Kimi/self-hosted
- * vLLM…), so a baked maker name makes every non-DeepSeek deployment misstate its own substrate. Same for
+ * Live-caught incident (a deployment served by one model family described itself as running on a DIFFERENT
+ * vendor's model, because that vendor's name was baked into this text):
+ * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (any OpenAI-/Anthropic-
+ * compatible endpoint, self-hosted vLLM included), so a baked maker name makes every deployment that is not
+ * that maker's misstate its own substrate. Same for
  * the gateway protocol (the brain stack serves Anthropic-compatible routes too — routing brain +
  * createAnthropicBrain — so "OpenAI-compatible gateway" would be the same class of lie). Neutral wording
  * (zero core-seam need; interpolating the model id would need a `StablePromptContext.model`

package/dist/config-center/apply-effective.js

@@ -25,9 +25,10 @@ function toModel(m, envDefaults = {}) {
         name: m.name,
         provider: m.provider,
         api: m.api,
-        // 实机 /model 切 Kimi 404 定谳: a catalog model MAY carry its own gateway URL — the
+        // 实机 /model 切换 404 定谳: a catalog model MAY carry its own gateway URL — the
         // hardcoded "" made core's brain fall back to the boot-env endpoint, so cross-endpoint `body.model`
-        // selection hit the WRONG gateway (kimi id → Qwen vLLM → 404). Absent still = "" (brain env default;
+        // selection hit the WRONG gateway (a model id routed to a gateway that does not serve it → 404).
+        // Absent still = "" (brain env default;
         // byte-compat for single-gateway rosters). core brain honors model.baseUrl; keys stay per-model via apiKeyEnv.
         baseUrl: m.baseUrl ?? "",
         // BL-8 extended (systematic-audit): fall back to the ENV-derived model's reasoning, not Boolean(undefined)=false —
@@ -220,7 +221,7 @@ export function applyEffective(config, eff, logger, opts = {}) {
         // NOTE: the wire face (this module's EffectiveConfig) carries the JSON body verbatim, so tierGroups ride
         // eff.models even though CenterModel doesn't type them — resolveActiveTiers reads them structurally.
         const activeTiers = resolveActiveTiers(eff.models) ?? {};
-        // [865]①(clay 生产实锤:onboard 选 kimi 实跑 Qwen)显式默认解析——enabled[0] 会被任何改变 pool 顺序的写
+        // [865]①(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个)显式默认解析——enabled[0] 会被任何改变 pool 顺序的写
         // 静默翻转,default 必须消费 wire 里已有的显式意图。解析单源 = resolveDefaultModelName(dry-run 的
         // wouldDefaultModel 共用同一只,报数与真 apply 永不撕裂——codex M2)。
         const picked = resolveDefaultModelName(eff, (n) => models[n] !== undefined, enabled[0].name, (source, name) => logger?.warn("sema_registry_default_dangling", { source, name, hint: "explicit default names a model that is not in the enabled catalog — falling to the next source" }));