@sema-agent/server 2.0.0 → 2.0.1

package/dist/boot/runner-deps.d.ts

@@ -0,0 +1,101 @@
+/**
+ * design/158 A10:composition root 分段 —— `RunnerDeps` 装配(含 self-orchestration 成组段)。
+ *
+ * 纯搬运:两个字面量逐字来自 `main.ts`(原 1579-1881 行),缩进不变(顶层键仍在 4 空格,
+ * `deps-literal-shape-gate` 的顶层条件展开门覆盖面不变);新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:必须晚于 stores/exec-env/coordinators/workflow 段(所有键都是它们的产物),
+ * 且早于 `new Runner(runnerDeps)` —— Runner 构造会冻结 tier 展开后的私有目录副本
+ * (`runnerTierFrozen` 判据就取自构造那一刻的 `config.tiers`)。
+ * `getRunStore()` 是唯一的晚绑取值(runStore 在本段之后才构造),原文靠同作用域前向引用。
+ */
+import { type RunnerDeps, type WorkflowRunStore } from "@sema-agent/core";
+import type { createBrain } from "../brain.js";
+import type { buildPricing, createTracer } from "../budget.js";
+import type { ServiceConfig } from "../config.js";
+import type { ElicitationCoordinator } from "../elicitation.js";
+import { FleetEventBus } from "../fleet/fleet-bus.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
+import { type WorkflowCompletionInbox } from "../orchestration/workflow-completion-inbox.js";
+import { WorkflowNotifyGate, type WorkflowCompletionPayload } from "../orchestration/workflow-notify-journal.js";
+import type { ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+import type { QuestionCoordinator } from "../question.js";
+import type { ToolApprovalCoordinator } from "../tool-approval.js";
+import type { MemoryBackend } from "@sema-agent/core";
+import type { MemorySyncRunner } from "../memory-sync-client.js";
+export interface RunnerDepsCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    localRoot: string;
+    promptSource: RunnerDeps["promptSource"];
+    rosterStore: RunnerDeps["rosterStore"];
+    backgroundAgentStore: RunnerDeps["backgroundAgentStore"];
+    mailboxStore: RunnerDeps["mailboxStore"];
+    brain: ReturnType<typeof createBrain>;
+    pricing: ReturnType<typeof buildPricing>;
+    tracer: ReturnType<typeof createTracer>;
+    outcomeSink: ReturnType<StoreBackend["outcomeSink"]> | undefined;
+    elicitation: ElicitationCoordinator | undefined;
+    question: QuestionCoordinator | undefined;
+    toolApproval: ToolApprovalCoordinator | undefined;
+    sessionStore: ReturnType<StoreBackend["session"]>;
+    memoryEngine: {
+        backend: MemoryBackend;
+        root: string;
+    } | undefined;
+    memorySyncRunner: MemorySyncRunner | undefined;
+    toolResultStore: ToolResultStoreFull | undefined;
+    sessionPolicyStore: ReturnType<StoreBackend["sessionPolicy"]> | undefined;
+    runtimeCapsResolver: RunnerDeps["runtimeCapsResolver"];
+    fileSnapshotStore: ReturnType<StoreBackend["fileSnapshot"]> | undefined;
+    executionEnvFactory: RunnerDeps["executionEnvFactory"];
+    lspManager: RunnerDeps["lspManager"];
+    fleetBus: FleetEventBus;
+    deploymentHooks: NonNullable<RunnerDeps["hooks"]>;
+    workflowRunStore: WorkflowRunStore | undefined;
+    workflowJournalStore: ServiceWorkflowJournalStore | undefined;
+    workflowAgentRegistry: WorkflowAgentRegistry | undefined;
+    workflowNotifyGate: WorkflowNotifyGate | undefined;
+    workflowCompletionInbox: WorkflowCompletionInbox | undefined;
+    deliverWorkflowCompletion: (p: WorkflowCompletionPayload) => Promise<void>;
+    /** 晚绑(runStore 在本段之后构造)——见文件头「位置即契约」。 */
+    getRunStore: () => ReturnType<StoreBackend["run"]> | undefined;
+}
+/** design/158 A10 留档发现②:main runner `RunnerDeps` 与 main.ts subRunner 字面量之间此前手工重复
+ * 的 ~15 个键,类型标注见 {@link createSharedRunnerDeps} 头注。 */
+export type SharedRunnerDeps = Pick<RunnerDeps, "brain" | "models" | "roles" | "tiers" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "hooks" | "toolResultStore" | "sessionPolicyStore">;
+/**
+ * design/158 A10 留档发现②(review 2026-07-29,[1543]§三族A 同源修补的延续):main runner 的
+ * `RunnerDeps` 字面量(下方 `createRunnerDeps`)与 `main.ts` 里 subRunner 的 `new Runner({...})`
+ * 字面量之间,以下 ~15 个键此前是**各自手写、独立展开**的同源值(同一 ctx 变量,两处分别拼字面量,
+ * 不是同一引用)——正是 [1543]§三族A 那次「主 runner 挂了、subRunner 漏挂」漏配事故的键族(当时的
+ * 修法是把 onBackgroundChildEvent/loadProjectMemory/probeInstructionSources/onError 四键改成直引
+ * `runnerDeps.X`「同一实例」;这里补的是**剩下未被那次改法覆盖**的 15 个键——两处字面量各自独立
+ * 取值,漏配一个不会有任何编译期或运行期信号)。
+ *
+ * 抽成本函数 + `Pick<RunnerDeps, …>` 类型标注(`SharedRunnerDeps`),把「新增/改名一个键、两处忘
+ * 同步」从「肉眼比对两份手写字面量」变成**编译期护栏**:调用方漏写一个必需键 ⇒ 返回值类型当场
+ * 红;`RunnerDeps` 改名/删键 ⇒ 这里的联合类型当场红。
+ *
+ * 消费点(复审 2026-07-30 F1 更新,过期「尚未接上」段已删):**两处都已展开**——下方
+ * `createRunnerDeps()`(全量 ctx)与 main.ts 的 subRunner `new Runner({...createSharedRunnerDeps(...)})`
+ * (窄面 {@link SharedRunnerDepsCtx})。新增共享键只需加进本函数返回体,两 Runner 自动同源;
+ * **不要**再在任一调用点手写同名键(那会 override 展开,回到 [1543] 漏配病)。
+ *
+ * 差异键(为何不在本共享基座、逐一注明):
+ *  - `sessionStore`:main runner 用宿主 durable 会话店;subRunner 用私有短 TTL 的
+ *    `ForkRoutingSessionStore`(main.ts 现场构造,子代转录生命周期与主会话不同)。
+ *  - `checkpointStore`:main runner 走 `spec.checkpointStore` 分支(不进 `RunnerDeps`,本 ctx 根本
+ *    没有这个字段);subRunner 单独携带(子代执行面的 park 设施,[1584])。
+ *  - `onBackgroundChildEvent` / `loadProjectMemory` / `probeInstructionSources` / `onError`:
+ *    [1543]§三族A 已用「直引 `runnerDeps.X`」修过(main.ts 两处引用同一个 `runnerDeps` 实例的同一
+ *    属性,比再抽一层共享基座更强的同源保证),不重复收纳进这里。
+ */
+/** 基座真实消费的窄面(Pick)——subRunner 调用点(main.ts)只需凑这 13 个字段,不必造全量 ctx。 */
+export type SharedRunnerDepsCtx = Pick<RunnerDepsCtx, "config" | "brain" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "deploymentHooks" | "toolResultStore" | "sessionPolicyStore">;
+export declare function createSharedRunnerDeps(ctx: SharedRunnerDepsCtx): SharedRunnerDeps;
+export declare function createRunnerDeps(ctx: RunnerDepsCtx): RunnerDeps;
+//# sourceMappingURL=runner-deps.d.ts.map

package/dist/boot/runner-deps.js

@@ -0,0 +1,343 @@
+/**
+ * design/158 A10:composition root 分段 —— `RunnerDeps` 装配(含 self-orchestration 成组段)。
+ *
+ * 纯搬运:两个字面量逐字来自 `main.ts`(原 1579-1881 行),缩进不变(顶层键仍在 4 空格,
+ * `deps-literal-shape-gate` 的顶层条件展开门覆盖面不变);新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:必须晚于 stores/exec-env/coordinators/workflow 段(所有键都是它们的产物),
+ * 且早于 `new Runner(runnerDeps)` —— Runner 构造会冻结 tier 展开后的私有目录副本
+ * (`runnerTierFrozen` 判据就取自构造那一刻的 `config.tiers`)。
+ * `getRunStore()` 是唯一的晚绑取值(runStore 在本段之后才构造),原文靠同作用域前向引用。
+ */
+import { createFileWorkflowScriptStore } from "@sema-agent/core";
+import { join } from "node:path";
+import { listCollabWorkflows, resolveCollabWorkflow } from "../capabilities/collab-workflows.js";
+import { fleetBackgroundChildPublisher, FleetEventBus } from "../fleet/fleet-bus.js";
+import { createHardenedVmRunner } from "../orchestration/hardened-vm-runner.js";
+import { createWorkerHardenedVmRunner } from "../orchestration/hardened-vm-worker-runner.js";
+import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
+import { resolveServedSession } from "../orchestration/workflow-completion-inbox.js";
+import { WorkflowNotifyGate } from "../orchestration/workflow-notify-journal.js";
+import { makeLoadProjectMemory, makeProbeInstructionSources } from "../project-memory.js";
+import { workflowModelAllowlistFor } from "../task-workflow.js";
+export function createSharedRunnerDeps(ctx) {
+    // 具名带类型的字面量(非裸 return)——deps-literal-shape-gate 的 POINTS 按 `const X: T = {` 咬装配
+    // 字面量,裸 return 形在它的覆盖外(复审 2026-07-30 F5):conditional-spread 病在这里就会失检。
+    const shared = {
+        brain: ctx.brain,
+        // core 1.265: the active tier table (tier words + CC aliases → catalog keys, expandTiers at Runner
+        // construction; empty = INERT by core contract). Same mutateInPlace reference applyEffective fills — a
+        // refresh-time tier change is restart-to-apply, same tier as models.
+        tiers: ctx.config.tiers,
+        models: ctx.config.models,
+        roles: ctx.config.roles,
+        pricing: ctx.pricing,
+        tracer: ctx.tracer,
+        // e/b([985]):center catalog 轴的 core 消费面——candidate/pinned-digest 解析走这里(prepare-task
+        // dist:session_start 优先 candidate、resume 按 digest 解析、miss=fail-loud prompt_snapshot_unavailable)。
+        promptSource: ctx.promptSource,
+        executionEnvFactory: ctx.executionEnvFactory ? ctx.executionEnvFactory : undefined,
+        lspManager: ctx.lspManager ? ctx.lspManager : undefined,
+        // core 1.364 durable bg agents 读半场(写半场=scenarioDeps.backgroundAgentStore 同实例,组装区注释)。
+        backgroundAgentStore: ctx.backgroundAgentStore ? ctx.backgroundAgentStore : undefined,
+        // S3c tier-3 懒复活(core 1.374):SendMessage 链内消费,与 backgroundAgentStore 同实例配套挂载。
+        mailboxStore: ctx.mailboxStore ? ctx.mailboxStore : undefined,
+        // [1070]① agent-team S1:持久名册 seam(具名 spawn advisory 写入;SendMessage 活注册表 miss 后咨询)。
+        rosterStore: ctx.rosterStore ? ctx.rosterStore : undefined,
+        hooks: ctx.deploymentHooks,
+        toolResultStore: ctx.toolResultStore,
+        // E6: operator-tightened session tool rules — core folds them into the ToolPolicy FIRST (subtract-only) for tasks
+        // carrying a sessionId (a delegated subagent has none → inherits no rules). Opt-in: undefined ⇒ no rules read.
+        sessionPolicyStore: ctx.sessionPolicyStore ? ctx.sessionPolicyStore : undefined,
+    };
+    return shared;
+}
+export function createRunnerDeps(ctx) {
+    const { config, logger, metrics, localRoot, outcomeSink, elicitation, question, toolApproval, sessionStore, memoryEngine, memorySyncRunner, runtimeCapsResolver, fileSnapshotStore, fleetBus, workflowRunStore, workflowJournalStore, workflowAgentRegistry, workflowNotifyGate, workflowCompletionInbox, deliverWorkflowCompletion, getRunStore, } = ctx;
+    // design/158 A10 留档发现②:共享基座——见 createSharedRunnerDeps 头注(main.ts 的第二处展开是
+    // 并行车道待办,未在本次改动内接线)。
+    const sharedRunnerDeps = createSharedRunnerDeps(ctx);
+    // S8 (design/98) + SVC-1: mount core's `run_workflow` under the hardened-vm sandbox when
+    // enabled (default OFF → core fail-closed, tool not mounted, zero impact). The tool STARTS a workflow and
+    // returns its runId IMMEDIATELY (the background-run half — the caller never blocks); the workflow runs to
+    // terminal in the background and fires core's in-process completion notify. Workflow-spawned children inherit
+    // a CONSERVATIVE baseline (handsReadOnly — read-only by default; loosen deliberately); the script may pick
+    // ONLY allow-listed model names (empty ⇒ it cannot pick → the workflow's default role).
+    //
+    // design/158 S4:三处装配点里**唯一**一组多键条件段 —— 提成带类型标注的中间 const 再整体展开进
+    // runnerDeps。标注位 `Pick<RunnerDeps, …>` 本身触发 TS 多余属性检查(键名写错 / 键根本不属于
+    // RunnerDeps ⇒ 编译期红),所以这不是把旁路挪个地方;组内可选键一律写成显式
+    // `k: cond ? expr : undefined`,不再用 `...(cond ? { k } : {})`。
+    const workflowModelAllowlist = workflowModelAllowlistFor(config);
+    const selfOrchestrationDeps = config.selfOrchestrationEnabled
+        ? {
+            // worker_thread isolation (heap cap + terminate) when opted in (multi-tenant DoS hardening), else
+            // the faster in-process runner. Both run the same conformance-validated + probe-hardened membrane.
+            workflowScriptRunner: config.selfOrchestrationWorkerIsolation
+                ? createWorkerHardenedVmRunner()
+                : createHardenedVmRunner(),
+            workflowRunStore: workflowRunStore ? workflowRunStore : undefined,
+            // SVC-2 (CORE-9 Part A): durable resume journal — core auto-wires it into the tool's startWorkflow, the
+            // `resumeFromRunId` tool input then replays the unchanged prefix (cross-replica when tidb/pg-backed). The
+            // store enforces scope in its WHERE (CORE-9 audit BLOCKER: a cross-tenant resumeFromRunId → empty → live).
+            workflowJournalStore: workflowJournalStore ? workflowJournalStore : undefined,
+            // 切片 1.5 / design/140 §6: the named-workflow registry seam — a COMPOSITE store.
+            // persist/load = core's file store under `<localDataRoot>/workflow-scripts` (the CC scriptPath-iterate
+            // face: every invocation's script lands on disk, the model edits + re-invokes with {scriptPath};
+            // containment is the file store's contract). resolveName consults the collab projection FIRST (center
+            // collab templates as `{TEAM_DISCUSSION_SCRIPT, defaultArgs}` entries; a collab id equal to a built-in
+            // name SHADOWS it — §6 1c) and falls back to the file store's `<name>.js` face (an operator-saved
+            // script is a named workflow too). list() = collab entries only (the file store deliberately doesn't
+            // enumerate — its dir mixes per-run scripts with saved names, core contract note); sync, so the
+            // entries reach the statically-built Workflow tool card.
+            workflowScriptStore: (() => {
+                const fileStore = createFileWorkflowScriptStore(join(config.localDataRoot ?? localRoot, "workflow-scripts"));
+                return {
+                    // core 1.366 (B-4) scope 分区一致性标:persist/load 直转 core file 实现(per-scope 子目录,
+                    // 真分区)——标是诚实声明;缺标=core 工具读侧拒/写侧跳(编译期必填字面量即为此设计)。
+                    scopePartitioned: true,
+                    persist: fileStore.persist.bind(fileStore),
+                    load: fileStore.load.bind(fileStore),
+                    resolveName: (name) => resolveCollabWorkflow(name) ?? fileStore.resolveName?.(name),
+                    list: () => listCollabWorkflows(),
+                };
+            })(),
+            // SVC-5 (CORE-9 Part B): the opt-in steer handle-sink. When set, the tool's `agent()` runs STEERABLE and
+            // emits the live handle HERE (never into the script/runner — the host-context membrane stays closed). We
+            // register it by runId+label so POST /v1/workflows/:id/agents/:label/steer can route a steer to it, and
+            // unregister when the agent settles (result() settles on stream completion; a stale handle would only
+            // 409 `steering.not_running` anyway — this just bounds the map). A steered agent is NOT journaled (CORE-9.1
+            // limitation: its resume re-runs live), which is correct + documented.
+            onWorkflowAgentSpawn: workflowAgentRegistry
+                ? (handle) => {
+                    const unregister = workflowAgentRegistry.register(handle);
+                    void Promise.resolve(handle.result()).then(unregister, unregister);
+                }
+                : undefined,
+            // workflowSizeGuideline: advisory size guidance injected into the
+            // Workflow tool card (core Wvs, CC 206 verbatim). Absent/unrestricted = byte-compat card.
+            workflowLimits: config.workflowSizeGuideline ? { sizeGuideline: config.workflowSizeGuideline } : undefined,
+            workflowGovernanceBaseline: {
+                // [824]① clay 拍 A 案(workflow 权限全面 CC parity):默认基线撤 handsReadOnly 钳 —— 主 LLM 与
+                // 子 agent 同 root 同信任域,主 LLM 本就能写这棵树([816] ask 门照管),单独钳子 agent 的安全增益≈0
+                // (只防绕路不防直路的门不是边界);实测产品代价=[814]A 死锁(写型 workflow agent 永远只读)。并发
+                // 写互踩按 CC 同姿用建议解决(worktree 契约话术+design/111 advisory),不用强制钳。要保守的 TOB
+                // 部署自己开 WORKFLOW_AGENTS_READONLY=true(config.workflowAgentsReadOnly)加回旧钳。
+                base: config.workflowAgentsReadOnly ? { handsReadOnly: true } : {},
+                // [824]②/[826]-core 1.291 worktree seam(TOB 旋钮回归腿):旋钮开启时 worktreeBase 配成
+                // overlay 形状 —— core 对 `agent({isolation:"worktree"})` 做 base 浅合并(非整体替换,
+                // workflow-primitives effectiveBaseline:{...base,...worktreeBase}),{handsReadOnly:false} 语义=
+                // 「只放写,其余基线全保留」。效果:保守部署里非隔离子 agent 仍只读,进了自有 worktree 的
+                // agent 恢复可写([814]A 写型 workflow 在 TOB 形态下不死锁)。A 案默认(旋钮 off)不配 worktreeBase。
+                worktreeBase: config.workflowAgentsReadOnly ? { handsReadOnly: false } : undefined,
+                // Model allowlist for the script's `agent({model})` picks: explicit
+                // SELF_ORCHESTRATION_MODELS wins; single-user defaults to the deployment's own catalog; multi-tenant
+                // keeps core's fail-closed empty default. Decision + rationale in workflowModelAllowlistFor.
+                workflowModelAllowlist: workflowModelAllowlist ? workflowModelAllowlist : undefined,
+            },
+            // SVC-1 at-least-once notify: route core's terminal notify THROUGH the gate (deliver-then-ack +
+            // journal dedup) instead of straight to log/meter, so a crash mid-delivery re-delivers on the next boot
+            // recovery sweep. When the gate is absent (memory backend / no journal) fall back to the bare
+            // log+meter delivery (at-most-once, the prior behavior — honest about the lost-on-crash window).
+            workflowCompletionNotifier: {
+                // ⚠️ design/158 S4 有意保留的展开:两臂**都非空**(要么 gate 造的 notifier,要么裸 notify 兜底),
+                // 不是「条件键」形——它合并的是同一必填键 `notify` 的两个来源,两来源都有类型,不构成
+                // 多余属性检查旁路(缺 notify 反而当场编译红)。
+                ...(workflowNotifyGate
+                    ? workflowNotifyGate.buildNotifier()
+                    : { notify: (input) => deliverWorkflowCompletion(input) }),
+                // core 1.232 (the CORE half of the poll-then-also-notify dedup): pollWorkflow fires this
+                // ONCE when the ORIGINATING session polls the run to a real terminal (timeout/cross-session polls
+                // don't) — drop that (session, runId)'s pending inbox entry + arm the served fence, so the push
+                // that would duplicate what the model just read is dead even across a shell restart. Session
+                // attribution mirrors resolveCompletionRoute's session half (payload id, else the run row).
+                ackServed: async (input) => {
+                    if (!workflowCompletionInbox)
+                        return;
+                    try {
+                        const sid = await resolveServedSession(input, getRunStore() ? (id) => getRunStore().getRun(id) : undefined); // A10 搬运改写:晚绑取值
+                        if (sid) {
+                            await workflowCompletionInbox.markTerminalServed(sid, input.runId);
+                            // The THIRD way an inbox entry disappears (besides the three stream-open drains
+                            // and the owner-mismatch drop) — the model itself polled the run to terminal, so the push is
+                            // suppressed. An "enqueue → ack within ms, but the shell showed nothing" report with THIS line
+                            // means the completion went to the MODEL in-process (core injected it), not onto any stream.
+                            logger.info("workflow_complete_ack_served", { route: "poll-served", sessionId: sid, runId: input.runId });
+                        }
+                    }
+                    catch (err) {
+                        logger.warn("workflow_ack_served_failed", { runId: input.runId, err: String(err) });
+                    }
+                },
+            },
+        }
+        : {};
+    const runnerDeps = {
+        // design/158 A10 留档发现②:brain/models/roles/tiers/pricing/tracer/promptSource/
+        // executionEnvFactory/lspManager/backgroundAgentStore/mailboxStore/rosterStore/hooks/
+        // toolResultStore/sessionPolicyStore —— 共享基座展开,见 createSharedRunnerDeps 头注
+        // (含每键各自的历史 rationale 注释,搬到了那个函数里,不在此重复)。
+        ...sharedRunnerDeps,
+        // [931]① clay 拍(core 1.300 BREAKING:缺省不署 Co-Authored-By,署名=产品身份资产归部署):
+        // branded 形态(local provider = Sema 产品线,scenarios brandIdentity 同判据)commit 尾注接 Sema 署名;
+        // 非 brand 部署维持 core 新缺省(不署)。seam=RunnerDeps.hands.commitCoAuthor。
+        hands: config.configProvider === "local" ? { commitCoAuthor: "Sema <noreply@vivi-ai.com>" } : undefined,
+        // design/73 §1 (core 1.226 seam, clay 拍 2026-07-04 接): consume mechanical TaskOutcome facts into the
+        // outcome ledger — tidb/pg = SQL rows (coreOutcomeToLedgerRow mapping + verbatim `core_outcome` JSON so
+        // red-line ② oracleHadRedRun survives lossless), local = owner-only JSONL. Read-only v1: records facts,
+        // drives NO policy (§7.4 backtest gate stands). Fire-and-forget — a sink failure logs and never touches
+        // the run (core's emitTaskOutcome swallow-guards too). Emitters today: core runGoal terminal + any
+        // harness with a REAL mechanical oracle calling runner.emitTaskOutcome; plain runTask never auto-emits.
+        onTaskOutcome: outcomeSink
+            ? (o) => {
+                metrics.inc("task_outcomes_total", { status: o.status, green: String(o.oracle?.green ?? "unknown") });
+                void outcomeSink.recordCore(o).catch((err) => logger.warn("task_outcome_record_failed", { runId: o.runId, err: String(err) }));
+            }
+            : undefined,
+        // E23: the live-only inbound-elicitation seam. core invokes it only for servers that opted in via
+        // McpServerSpec.elicitation (default OFF) AND only when this is wired — both must hold (doubly fail-closed).
+        onElicit: elicitation ? elicitation.elicit : undefined,
+        // §4④: the live AskUserQuestion seam. core mounts the tool when onQuestion is present + routes each ask here; the
+        // DURABLE leg's spec.onQuestion (QUESTION_AWAITS_RESUME) OVERRIDES this per-task so a disconnected-human ask suspends.
+        onQuestion: question ? question.question : undefined,
+        // [816]/[820]②: the live tool-approval seam (core `resolveAsk` — `spec.onAsk ?? deps.onAsk`). ALS-routed like
+        // onQuestion: a leg wrapped by the coordinator's runWithContext reaches the human.
+        //
+        // [879] G1 终态(core 1.295 OnAsk 三值化):恒 wire。回调逐 ask 时刻判活人——ALS 附着腿 ⇒ 同步三选卡;
+        // 无附着/卡送达失败 ⇒ 返 "unavailable",core 以 approverUnavailable 回路把该 ask 交回 suspendAsk 走
+        // durable park(prepare-task 分路带 `approverUnavailable !== true` 豁免位,dist 亲读)——park 与 live 卡
+        // 两全,1.199 的「durable 部署不 wire deps.onAsk」止血撤除。无 park 设施的部署 core 自己 fail-closed
+        // deny(resolveAsk 的 unavailable 文案),与旧姿势同向。
+        onAsk: toolApproval
+            ? (req, signal) => toolApproval.ask(req, signal)
+            : undefined,
+        // [822]② auto permission mode, deployment half: RunnerDeps.autoMode is the operator TRUST face of core's
+        // auto-mode classifier (1.276/1.277) — wiring it alone arms NOTHING (core requires the per-principal entitlement
+        // runtimeCaps.autoMode === true from center, fail-closed dark by default; see runtime-caps-resolver.ts). With
+        // both present, core screens every policy `ask` through the classifier (allow safe / deny hostile / leave the
+        // rest on the ask path → this bridge or durable park). Defaults-only config (core's rules/window); breaker-open
+        // is surfaced for observability.
+        autoMode: {
+            onBreakerOpen: (info) => {
+                metrics.inc("auto_mode_breaker_open_total");
+                logger.warn("auto_mode_breaker_open", { consecutiveFailures: info.consecutiveFailures, lastCause: info.lastCause });
+            },
+        },
+        sessionStore,
+        // design/138 S1: the memory-engine switch — when present (single-user + engine on), core replaces the
+        // legacy memory path WHOLESALE per task (materialize → session file ops → harvest; no remember/recall
+        // tools). `memoryEngineDir` = the resolved config root (core derives the B3 control plane beside the
+        // memory dir). Absent (multi-tenant / MEMORY_ENGINE=off) ⇒ no deps.memoryBackend ⇒ memory dark.
+        memoryBackend: memoryEngine ? memoryEngine.backend : undefined,
+        memoryEngineDir: memoryEngine ? memoryEngine.root : undefined,
+        // S3-TOB 复审 F-9(operator 可观测底座):harvest 报告 → metrics(拒收/incident/patch 计数从此可见;
+        // core swallow-guard 保证 throwing consumer 不伤边界)。
+        onMemoryHarvestReport: memoryEngine
+            ? (report, info) => {
+                metrics.inc("memory_harvest_total", { ok: String(report.ok), phase: info.phase, incident: report.incident?.kind ?? "none" });
+                if (report.patches)
+                    metrics.inc("memory_harvest_patches_total", { phase: info.phase }, (report.patches.add ?? 0) + (report.patches.update ?? 0));
+                if (report.incident)
+                    logger.warn("memory_harvest_incident", { kind: report.incident.kind, phase: info.phase });
+                // 142-S2.5-W1: 成功 harvest 真有 patch 落地 = 本地记忆变了 ⇒ fire-and-forget 一轮同步
+                // (trigger 自带 inflight 节流:上一轮在飞则跳过,漏掉的变更下一轮全量补上)。
+                if (memorySyncRunner && report.ok && (report.patches?.add ?? 0) + (report.patches?.update ?? 0) > 0)
+                    memorySyncRunner.trigger("harvest");
+            }
+            : undefined,
+        // (toolResultStore/sessionPolicyStore already carried by the shared-base spread above.)
+        // design/99 §K: per-principal runtime entitlements (allowWorkflows / forceDurableGate) resolved from center.
+        // Opt-in: undefined ⇒ NO per-principal restriction (tighten-only; deployment default governs). See above.
+        runtimeCapsResolver: runtimeCapsResolver ? runtimeCapsResolver : undefined,
+        // E19: working-tree snapshot/restore for rewind (+ the 2c artifact store). core snapshots each completed turn +
+        // restores on resumeAt when spec.rewindFiles is set, for ANY env when this store is wired (gate-split 1.134.0).
+        fileSnapshotStore: fileSnapshotStore ? fileSnapshotStore : undefined,
+        // (executionEnvFactory/lspManager already carried by the shared-base spread above.)
+        // design/129-B (core 1.240.0): the PROCESS-LEVEL background-child observer — spawn/tick/terminal
+        // for every bg delegation child, never dying with a leg. Feeds the fleet rows (launch 即有行, session-scoped
+        // children stay visible past the turn — the 缺口① fix) + the bg_notification frame on the
+        // always-open fleet stream (缺口②: idle completion delivery is immediate). Wired once per process.
+        onBackgroundChildEvent: fleetBackgroundChildPublisher(fleetBus, (msg, fields) => logger.info(msg, fields)),
+        // design/113 C4: inject CLAUDE.md + git narrative so a chat opens project-aware (like CC). The helper reads cwd via
+        // local fs/execFile — only meaningful when cwd is LOCAL (host/file lane); it stats the dir and returns null on a
+        // remote-sandbox cwd, so this is safe to wire generally, but we gate it to single-user (cwdHonored posture — the
+        // same lane where reading the local project for the caller isn't a confused-deputy hole) + the opt-out kill-switch.
+        loadProjectMemory: config.requirePrincipal !== true && config.projectMemoryEnabled ? makeLoadProjectMemory({ logger }) : undefined,
+        // core 1.302 instructions-change lane (板 [952]②): re-fingerprint the declared instruction file each turn so a
+        // mid-run edit surfaces as a tail attachment. STRICTLY host lane — on a remote-sandbox lane the instruction file
+        // lives in the container; a local re-read would fingerprint the wrong tree, so the probe is not wired there.
+        probeInstructionSources: config.remoteExec?.provider === "host" && config.requirePrincipal !== true && config.projectMemoryEnabled
+            ? makeProbeInstructionSources()
+            : undefined,
+        // (hooks already carried by the shared-base spread above.)
+        ...selfOrchestrationDeps, // S8 self-orchestration 全家桶(成组条件段;类型标注在上方 const)
+        // F8: surface best-effort compaction failures + the 1.22 prompt-cache low-hit warning (an
+        // unstable/poisoned prefix tanking cost) instead of silently swallowing them.
+        onError: (err, ctx) => {
+            // "degraded" (1.40) is an operational event, NOT a failure — the task still completes (on a cheaper
+            // model). Log it as a warning so it doesn't pollute error rates/alerts. The degraded_total metric
+            // comes from the tracer's task.degraded event.
+            if (ctx.phase === "degraded") {
+                logger.warn("task_degraded", { sessionId: ctx.sessionId, info: String(err) });
+                return;
+            }
+            // "prompt-constitution" (core 1.243): a stableSystem provider returned an ALREADY-
+            // assembled prompt (constitution anchor found); core passed it through un-doubled. The task is safe
+            // (guard un-doubles), but the provider is pre-1.243-shaped and should be upgraded to return only the
+            // role base. Warn — paired with the tracer's prompt_constitution_total{mode="provider-assembled"}.
+            if (ctx.phase === "prompt-constitution") {
+                logger.warn("prompt_provider_needs_upgrade", { sessionId: ctx.sessionId, info: String(err) });
+                return;
+            }
+            // "rewind" (E19 per-turn file snapshot): best-effort — a failed snapshot only makes that one turn
+            // non-rewindable; the task itself is unaffected. `too_large` is the EXPECTED shape on a big working
+            // tree (TOC user opening a 20G folder: enumerate hits the 256MB bound EVERY turn → an error-level
+            // line per turn reads like the run is broken). Downgrade to warn + count by code so a real store
+            // fault (enumerate_failed on a readable tree, blob-write errors) still stands out in the metric.
+            if (ctx.phase === "rewind") {
+                const code = /\((\w+)\)/.exec(String(err))?.[1] ?? "unknown";
+                logger.warn("rewind_snapshot_failed", { sessionId: ctx.sessionId, code, info: String(err) });
+                metrics.inc("rewind_snapshot_failed_total", { code });
+                return;
+            }
+            // "memory" (1.62, design/41): a best-effort post-task consolidation pass failed. The task already
+            // completed and its notes are safely appended (just not reconciled this round) — warn, fail-open,
+            // don't pollute error rates. (Consolidation cost still lands in model_cost_micro_usd via the tracer.)
+            if (ctx.phase === "memory") {
+                logger.warn("memory_consolidation_failed", { sessionId: ctx.sessionId, info: String(err) });
+                return;
+            }
+            // "mcp" (1.68): a broken MCP server was SKIPPED (fail-open) — the task still ran without
+            // that server's tools. Surface it as a warning + metric so a misconfigured server is observable, not silent.
+            if (ctx.phase === "mcp") {
+                logger.warn("mcp_server_unavailable", { sessionId: ctx.sessionId, info: String(err) });
+                metrics.inc("mcp_server_unavailable_total");
+                return;
+            }
+            // "prompt-cache" (1.22 low-hit + design/31 break detector): since core 1.89 the detector passes its
+            // root cause as ctx.classification — "server-or-ttl" is usually benign in agentic tasks (slow tools ⇒
+            // 5min+ request gaps expire provider caches) → warn; the prefix-bug causes
+            // (model-switch/tool-schema/tool-set/system-prefix) stay errors that warrant attention.
+            if (ctx.phase === "prompt-cache") {
+                metrics.inc("prompt_cache_low_hit_total");
+                const fields = { sessionId: ctx.sessionId, ...(ctx.classification ? { classification: ctx.classification } : {}), err: String(err) };
+                if (ctx.classification === "server-or-ttl")
+                    logger.warn("prompt_cache_break", fields);
+                else
+                    logger.error("prompt_cache_break", fields);
+                return;
+            }
+            // "config" (core 1.300 [931]②): assembly-time advisories — e.g. toolPolicy 名单池审计
+            // (config.toolpolicy.unmatched_names:名单里写了实挂宇宙不存在的工具名=typo 探测,enforcement
+            // 不变)。观测性提示,warn+metric,不进 error 告警面。
+            if (ctx.phase === "config") {
+                logger.warn("runner_config_advisory", { sessionId: ctx.sessionId, info: String(err) });
+                metrics.inc("runner_config_advisory_total");
+                return;
+            }
+            logger.error("runner_error", { phase: ctx.phase, sessionId: ctx.sessionId, err: String(err) });
+        },
+    };
+    return runnerDeps;
+}
+//# sourceMappingURL=runner-deps.js.map

package/dist/boot/runtime-caps.d.ts

@@ -0,0 +1,21 @@
+/**
+ * design/158 A10:composition root 分段 —— per-principal 运行期准入(design/99 §K caps 客户端)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 1520-1577 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:必须早于 `RunnerDeps` 装配(core 的 `runtimeCapsResolver` seam 从这里取)与
+ * `resolveSpec`(scenario/lane 两道 ruling 同一 caps 车)。boot 期那条 scoped-token 误配 warn 也必须
+ * 留在这里 —— 它是"一次性 boot 诊断",挪到别处会变成每任务噪声或干脆不打。
+ */
+import type { ServiceConfig } from "../config.js";
+import type { Logger } from "../observability/logger.js";
+export interface RuntimeCapsCtx {
+    config: ServiceConfig;
+    logger: Logger;
+}
+export declare function createRuntimeCaps(ctx: RuntimeCapsCtx): {
+    principalCaps: import("../runtime-caps-resolver.js").PrincipalEntitlementsClient | undefined;
+    centerRuntimeCapsResolver: ((principal: string | undefined) => Promise<import("@sema-agent/core").RuntimeCaps | undefined>) | undefined;
+    runtimeCapsResolver: import("../runtime-caps-resolver.js").EntitlementsResolverFn | undefined;
+};
+//# sourceMappingURL=runtime-caps.d.ts.map

package/dist/boot/runtime-caps.js

@@ -0,0 +1,62 @@
+import { applyObserverEnvOptIn, createPrincipalEntitlementsClient, scopedTokenNeedsWorker } from "../runtime-caps-resolver.js";
+export function createRuntimeCaps(ctx) {
+    const { config, logger } = ctx;
+    // design/99 §K (core 1.157 `RunnerDeps.runtimeCapsResolver`) — the ENFORCE last-link of the
+    // three-stage workflows gate. core calls it once per task at prepare time with `spec.principal`; we resolve the
+    // per-principal entitlement from center's `GET /api/config/effective?principal=` (cached + fail-closed). Wired
+    // ONLY when a center is configured AND not in dry-run: in dry-run the service pulls+logs but does NOT APPLY
+    // center config, so it must NOT ENFORCE center's per-principal caps either (enforcing would deny workflows = a
+    // real behavior change, contradicting observe-only). Absent ⇒ core sees `undefined` ⇒ no per-principal
+    // restriction (the deployment-level capability + toolPolicy gates still govern).
+    //
+    // 🔐 TRUST DEPENDENCY: the gate keys off `spec.principal` (= resolveSpec's `auth.principal`). F-fix (2026-07-01,
+    // core-steered; contract-compliance per core 1.187's hardened `TaskSpec.principal` doc — it MUST be the
+    // cryptographically VERIFIED identity, never a spoofable header): `auth.principal` now comes from
+    // `verifiedPrincipal` (security.ts). On a GATED door that's `principalFrom` (the BFF already verified the header;
+    // `gatedPrincipal === principalFrom` there); on a DIRECT door (`directDoorActive`) it's the verified
+    // `x-approval-principal-token` JWT `sub`, NEVER the spoofable header. So `spec.principal` is ALWAYS the verified
+    // identity — governance (this gate), cost, and isolation key off it safely on BOTH postures. The same verified
+    // identity also fans out to the non-authorizer owner/cost sites that don't run createAuthorizer
+    // (runOwnerOk / quotaExceeded / leader / idemKey — they call `gatedPrincipal` directly). The invariant:
+    // spec.principal AND every principal-keyed security decision are VERIFIED. (Was a real direct-door spoof hole
+    // before this fix; latent until a multi-tenant direct door ships, but it is the only wall against it.)
+    // wpt_ scoped-token: RESOLVED (center ruling, sema-registry `aeb4979`). The earlier 1.14.0 guard
+    // (skip the resolver on a `wpt_` token, because center 403'd it for `?principal=`) is GONE — center now lets a
+    // worker-scoped `wpt_<self>` resolve its OWN worker's principal caps when we pass `?worker=<self>` (caps-only,
+    // never others' config). So we ALWAYS wire the resolver (configCenter + !dryRun) and pass `worker` =
+    // `SEMA_REGISTRY_WORKER` — it authorizes the wpt_ path and is harmless on a full token (caps are worker-
+    // independent). Per-principal workflow gating now truly works on the scoped-token topology (no more silent
+    // fleet-wide deny). (A wpt_ with no worker still 403s → fail-closed deny, the correct degrade.)
+    // MISCONFIG diagnostic (review MEDIUM): a wpt_<self> token with NO SEMA_REGISTRY_WORKER will 403 every caps
+    // fetch → fail-closed DENY ALL workflows (correct degrade, but otherwise only per-task warns). One-shot BOOT
+    // warning so it's diagnosable. (The orchestrator normally injects the worker alongside a wpt_ — hand-misconfig.)
+    if (config.configCenter && !config.configCenter.dryRun && scopedTokenNeedsWorker(config.configCenter.token, config.configCenter.worker)) {
+        logger.warn("runtime_caps_scoped_token_no_worker", {
+            reason: "SEMA_REGISTRY_TOKEN is a worker-scoped wpt_ token but SEMA_REGISTRY_WORKER is unset → center 403s per-principal caps → ALL workflow self-orchestration will be fail-closed denied. Set SEMA_REGISTRY_WORKER (the orchestrator normally injects it) or use the full SERVICE_PULL_TOKEN.",
+        });
+    }
+    // ONE per-principal caps client serves two faces off the same fetch/cache — `resolveRuntimeCaps`
+    // (core's seam, fail-closed) and `scenarioRuling` (resolveSpec's scenario gate, fail-open; center attaches the
+    // resolved {scenario, allowlist} to the caps body, single semantic source in center resolve-scenario.ts).
+    const principalCaps = config.configCenter && !config.configCenter.dryRun
+        ? createPrincipalEntitlementsClient({
+            baseUrl: config.configCenter.baseUrl,
+            token: config.configCenter.token,
+            ...(config.configCenter.worker ? { worker: config.configCenter.worker } : {}),
+            onError: (err, principal) => logger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }),
+        })
+        : undefined;
+    // 「entitlement resolver wired」语义源(enableForkFromBody / selfOrchestrationFromBody 的多租户 fail-close
+    // 判别):只有 center 背书的 caps client 算数 —— 下面的 env observer 基线不是 entitlement 源,不得改变它。
+    const centerRuntimeCapsResolver = principalCaps?.resolveRuntimeCaps;
+    // observer 开闸线 env 半场:EXPERIMENTAL_OBSERVER_AGENTS=true → 单用户部署把
+    // allowObservers:true 作部署基线合成(center caps 带键则 center 赢);多租户不认 env(boot warn 一次,
+    // 行为零变)。center caps 的 allowObservers 键本身在 toCoreRuntimeCaps 宽读透传(缺键=core 默认 OFF)。
+    const runtimeCapsResolver = applyObserverEnvOptIn(centerRuntimeCapsResolver, {
+        experimentalObserverAgents: config.experimentalObserverAgents,
+        requirePrincipal: config.requirePrincipal,
+        warn: (msg, fields) => logger.warn(msg, fields),
+    });
+    return { principalCaps, centerRuntimeCapsResolver, runtimeCapsResolver };
+}
+//# sourceMappingURL=runtime-caps.js.map

package/dist/boot/session-faces.d.ts

@@ -0,0 +1,57 @@
+import type { ServiceConfig } from "../config.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 { PlanCacheProbe } from "../plan-cache-probe.js";
+import type { CheckpointStoreFull, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
+import type { OwnerAwareSessionStore } from "../security.js";
+import { SessionWatchRegistry } from "../session-watch.js";
+export interface SessionFacesCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    localRoot: string;
+    backend: StoreBackend | undefined;
+    sessionStore: ReturnType<StoreBackend["session"]>;
+    runStore: ReturnType<StoreBackend["run"]> | undefined;
+    checkpointStore: CheckpointStoreFull | undefined;
+    toolResultStore: ToolResultStoreFull | undefined;
+    resumeAnchorStore: ReturnType<StoreBackend["resumeAnchor"]> | undefined;
+    approvalExemptionStore: ReturnType<StoreBackend["approvalExemption"]> | undefined;
+    sessionPolicyStore: ReturnType<StoreBackend["sessionPolicy"]> | undefined;
+    taskAttachmentStore: TaskAttachmentStore | undefined;
+    fileSnapshotStore: ReturnType<StoreBackend["fileSnapshot"]> | undefined;
+    workflowCompletionInbox: WorkflowCompletionInbox | undefined;
+}
+export declare function createSessionFaces(ctx: SessionFacesCtx): {
+    ownerAware: OwnerAwareSessionStore;
+    sessionAudit: ((sessionId: string) => Promise<{
+        owner: string | null;
+        sessionId: string;
+        createdAt: string;
+        floorEntryId: string | null;
+        thinkingLevel: string;
+        model: {
+            provider: string;
+            modelId: string;
+        } | null;
+        messages: unknown[];
+        promptEpoch?: {
+            epoch: number;
+            artifactDigest: string;
+            packId: string;
+            assemblyApi: number;
+            activatedBy: "session_start" | "compaction" | "legacy_migration";
+        };
+    } | undefined>) | undefined;
+    sessionWatchRegistry: SessionWatchRegistry | undefined;
+    purgeSession: ((sessionId: string, owner: string | null) => Promise<{
+        deleted: boolean;
+    } | {
+        active: string;
+    }>) | undefined;
+    instrumentDegenerate: ((result: import("@sema-agent/core").TaskResult) => void) | undefined;
+    planCacheProbe: PlanCacheProbe;
+};
+//# sourceMappingURL=session-faces.d.ts.map