@sema-agent/server 3.0.0 → 3.1.0

package/USAGE.md

@@ -239,6 +239,10 @@ SEMA_REGISTRY_WORKER=<worker名>                # 可选:拉取 /effective?worke
 🪦 `LSP_ENABLED=false`(拆分前唯一的 host 腿逃生舱)自 3.0.0 起是墓碑:拒启并指路 `LSP_HOST_ENABLED`。
 `LSP_ENABLED=true` 不受影响——那是沙箱腿自己的 opt-in,语义没变。
 
+**`CONFIG_REQUIRE_ROSTER=true`(3.1.0,可选,缺省关)**:远程 registry 非 dryRun 车道的 fleet worker
+可布防「roster 落地前拒接计费提交(503)」——3.0.0 起 MODEL_ID 必填,每个 worker 都带 boot 模型起服,
+旧的「无 env 模型即等 roster」推断失效;要那个保护语义现在需显式声明。
+
 ---
 
 ## 1. 请求与响应的通用规则

package/dist/boot/config-center.d.ts

@@ -47,7 +47,8 @@ export interface ConfigCenterRuntime {
     } | undefined>) | undefined;
     /** 晚绑取值:center 提示词面(热采用,新任务边界生效)。 */
     getCenterPrompts(): PromptsDomainFaces | undefined;
-    /** boot ready 门:roster 未落地 = 计费提交 503 + /health ready:false。 */
+    /** boot ready 门:布防(`CONFIG_REQUIRE_ROSTER=true`,远程 registry 非 dryRun)且 roster 未落地 =
+     *  计费提交 503 + /health ready:false。缺省未布防 ⇒ 恒 true。 */
     modelReady(): boolean;
     /** /health.restart(orchestrator 自动重启信号)。 */
     restartState(): RestartSignal | undefined;

package/dist/boot/config-center.js

@@ -119,17 +119,24 @@ export async function createConfigCenterRuntime(ctx) {
             ...(config.configProvider === "local" ? { localDir: localRoot } : {}),
         })
         : undefined;
-    // boot ready 门 latch:仅「远程 registry 部署(非 dryRun)+ 无显式 env MODEL_ID」时等 roster——
-    // 首次 effective 落 ≥1 enabled 模型即翻 true(one-way)。其余姿势(env 模型在/local provider/dryRun/纯 env)
-    // 恒 ready=现有部署零影响。E3 废除 workers.model 后,fleet worker 的占位模型窗口由此门 fail-closed。
+    // boot ready 门 latch:布防时等中心 roster 落地——首次 effective 落 ≥1 enabled 模型即翻 true(one-way);
+    // 未布防则恒 ready。守的危险=**registry 部署的 fleet worker 在 roster 落地前拿占位模型跑计费任务**
+    // (E3 废除 workers.model 之后,占位模型正是 fleet worker 的常态起服姿势)。
     //
-    // ⚠️ 如实记账(复审 2026-07-29 C1):**server 3.0.0 起 `MODEL_ID` 是必填**(未设 = loadConfig throw,
-    // 见 config.ts parseModelDomain),所以走到这一行时 `process.env.MODEL_ID` 必非空 ⇒ 这个初值**当前恒为
-    // true**,「等 roster」那条臂在今天的配置面上不可达。保留原式不改行为,原因有二:① latch 与
-    // `markRosterLanded` 是同一套机制,删掉初值里的判据不会让代码变简单,只会让重新开门时无处可挂;
-    // ② registry 轴一旦允许「无 env MODEL_ID、模型全由中心 roster 下发」(E3 之后这正是 fleet worker 的目标
-    // 形态),这条臂就要重新活过来 —— 届时应连同 MODEL_ID 必填的口径一起重估,而不是各改各的。
-    const modelReadyState = { ready: !(cc && !cc.dryRun) || Boolean(process.env.MODEL_ID) };
+    // 🔧 复审 2026-07-29 P1-6 —— 布防判据从**推断**改成**运营者声明**。原式是
+    // `!(cc && !cc.dryRun) || Boolean(process.env.MODEL_ID)`,其中 `Boolean(process.env.MODEL_ID)` 是
+    // 3.0.0 前「运营者手上除了中心 roster 什么都没有」的代理判据。**server 3.0.0 起 `MODEL_ID` 必填**
+    // (未设 = loadConfig throw,见 config.ts parseModelDomain)⇒ 走到这一行时它必非空 ⇒ 初值恒 true ⇒
+    // 「等 roster」那条臂不可达、markRosterLanded 的门体是死码、/health 的 ready:false 与计费提交的 503
+    // 全不可能发生。注意这不是「危险消失了」:必填 MODEL_ID 恰恰让**每个** fleet worker 都带着占位模型
+    // 起服,危险比以前更常见——只是那个代理判据从此写不出来了。
+    //
+    // 于是改成显式声明:`CONFIG_REQUIRE_ROSTER=true`(与 CONFIG_LKG_* / CONFIG_BOOT_FETCH_BUDGET_MS 同族,
+    // 直读 env,不进 ServiceConfig——纯 boot 期姿势旋钮)。**缺省关 = 现有部署逐字节零变化**;开了才真的
+    // fail-closed 等 roster。仅远程 registry 且非 dryRun 车道可布防:dryRun 是 compare-only(中心 roster
+    // 从不被应用,拿它当就绪判据无意义),local provider / 纯 env 部署则没有「中心」可等。
+    const rosterGateArmed = cc !== undefined && !cc.dryRun && process.env.CONFIG_REQUIRE_ROSTER === "true";
+    const modelReadyState = { ready: !rosterGateArmed };
     const markRosterLanded = (eff) => {
         if (!modelReadyState.ready && (eff.models?.models ?? []).some((m) => m.enabled !== false)) {
             modelReadyState.ready = true;
@@ -463,12 +470,19 @@ export async function createConfigCenterRuntime(ctx) {
         }
     }
     if (!modelReadyState.ready)
-        logger.warn("model_roster_pending", { note: "registry deployment without an env model and no roster yet — billable submissions 503 until the first effective pull lands models" });
+        logger.warn("model_roster_pending", {
+            note: "CONFIG_REQUIRE_ROSTER=true and no center roster has landed yet — the env MODEL_ID is treated as a PLACEHOLDER, so billable submissions 503 (and /health reports ready:false) until the first effective pull lands ≥1 enabled model. Unset the knob if this worker's env model is authoritative.",
+        });
     // Per-model API key (sema-registry `apiKeyEnv`): resolve each model's own upstream key per brain call /
     // cascade rung. undefined when no per-model keys are configured → spec field stays unset (core default).
     // `let` (not const): rebuilt on a sema-registry refresh so per-model key ADDITIONS hot-apply too (the
     // resolver is undefined when no per-model keys exist, so in-place mutation alone wouldn't cover empty→non-empty).
     let keyResolver;
+    // 复审 2026-07-29 P1-11:restart 片里唯一一块 EffectiveConfig **看不见**的输入 —— 反应式降级车道由 env
+    // (MODEL_DEGRADE_TO / MODEL_DEGRADE_REACTIVE)开关,而它焊死的是 CENTER 目录里那条模型的路由面。读成
+    // 函数而非常量:`config.degrade` 今天由 env 独占(applyEffective 不写它),但若哪天中心接管这面,这里
+    // 自动跟着走,不会退化成 boot 期快照。车道关(默认)⇒ ctx 空 ⇒ 该片恒 null ⇒ 零行为变化。
+    const restartCtx = () => (config.degrade?.reactive ? { reactiveDegradeTo: config.degrade.to } : {});
     return {
         providerKind: configProvider?.kind,
         promptSource,
@@ -794,7 +808,7 @@ export async function createConfigCenterRuntime(ctx) {
                                 // 顺序=先持久化(含 skill 正文预热,F1)再发信号;持久化失败=warn+照发(不发=配置永不生效;
                                 // 「盘坏+中心挂」双故障下环重现,接受并点名)。
                                 const lkgPersisted = await persistLkgDurable(r.effective, r.etag);
-                                const reasons = restartReasons(effective, r.effective);
+                                const reasons = restartReasons(effective, r.effective, restartCtx());
                                 // codex R35: the sticky boot skill debt rides EVERY tick's reasons — change-detection vs boot is
                                 // blind to it (the stale table IS the boot baseline). Under a no-handoff deferral it folds into
                                 // blocked (promoted later); otherwise it keeps pendingRestart alive until the restart happens.
@@ -956,7 +970,7 @@ export async function createConfigCenterRuntime(ctx) {
                     latestEffective = r.effective;
                     ccEtag = r.etag;
                     const lkgPersistedLate = await persistLkgDurable(r.effective, r.etag); // F2 parity:信号可见前落盘+skill 正文预热
-                    const reasons = restartReasons(undefined, r.effective); // (prompts 不在 restart slices——热采用已在上方 adopt)
+                    const reasons = restartReasons(undefined, r.effective, restartCtx()); // (prompts 不在 restart slices——热采用已在上方 adopt)
                     // codex R15 (late-boot twin): tiered env boot + tier-less late candidate ⇒ deferral fires but BOTH slice
                     // fingerprints reduce to null (undefined baseline, tier-less candidate) — no models-tiers reason, plane
                     // deferred forever. Deferral is the ground truth; force the reason so the orchestrator restarts and the

package/dist/config-center/restart-signal.d.ts

@@ -1,5 +1,13 @@
 import type { EffectiveConfig } from "./types.js";
-export type RestartSlice = "skills" | "mcp" | "scenarios" | "runtime-gates" | "models-tiers";
+export type RestartSlice = "skills" | "mcp" | "scenarios" | "runtime-gates" | "models-tiers" | "degrade-route";
+/** What the CALLER must contribute about boot-baked catalog consumers that live OUTSIDE the Runner — the
+ *  slices cannot see them, because they are configured from env (`ServiceConfig`), not from the center's
+ *  EffectiveConfig. Absent/empty = that lane is off ⇒ its slice is inert (null on both sides). */
+export interface RestartSliceCtx {
+    /** `config.degrade.to` when REACTIVE degrade is on (env `MODEL_DEGRADE_TO` + `MODEL_DEGRADE_REACTIVE`);
+     *  undefined = the lane is off ⇒ no degrading brain was composed ⇒ nothing is boot-frozen. */
+    reactiveDegradeTo?: string;
+}
 /** Structured restart signal an orchestrator consumes (GET /health → `restart`). Change-detected against the
  *  process's BOOT config, NOT presence — so it stays absent when nothing baked-at-boot changed (presence would
  *  re-fire every refresh → a restart LOOP). `restartRequired` is always true when this object exists. */
@@ -16,7 +24,7 @@ export interface RestartSignal {
  *  nothing baked-at-boot changed (only hot-apply slices moved, or nothing) → no restart needed. An orchestrator
  *  can auto rolling-restart on a non-empty result WITHOUT a restart loop, because the comparison is always
  *  against boot (a refresh that re-fires the same diff is idempotent, not a fresh trigger). */
-export declare function restartReasons(boot: EffectiveConfig | undefined, current: EffectiveConfig): RestartSlice[];
+export declare function restartReasons(boot: EffectiveConfig | undefined, current: EffectiveConfig, ctx?: RestartSliceCtx): RestartSlice[];
 /** codex R10 (models-tiers 窗收口): TRUE when the MODEL PLANE (enabled models + active tier table + resolved
  *  default) of `next` differs from the last-APPLIED plane `prev`. Under a tier-frozen Runner (tiers non-empty at
  *  construction → private expanded copy) main.ts DEFERS the whole plane mutation until restart when this is true —

package/dist/config-center/restart-signal.js

@@ -7,7 +7,7 @@
  */
 import { resolveActiveTiers } from "@sema-agent/registry-core";
 import { RUNTIME_GATE_KEYS, runtimeGatePresent, resolveDefaultModelName } from "./apply-effective.js";
-const RESTART_SLICES = ["skills", "mcp", "scenarios", "runtime-gates", "models-tiers"];
+const RESTART_SLICES = ["skills", "mcp", "scenarios", "runtime-gates", "models-tiers", "degrade-route"];
 /** Canonical, key-sorted JSON (array order preserved) so two semantically-equal effective slices fingerprint
  *  identically regardless of object key order from the center serializer. */
 function stableStringify(v) {
@@ -31,7 +31,22 @@ function enabledOnly(rows) {
         return null;
     return rows.filter((r) => r.enabled !== false);
 }
-function restartSliceValue(eff, slice) {
+/** The degrade hop is built from the FULLY-DERIVED Model (`toModel`), so almost every catalog field on the
+ *  target reaches it (id → body.model, baseUrl → the endpoint, provider → which brain, maxTokens/compat/
+ *  extraBody/input → the request body, apiKeyEnv → the construction-time credential). We therefore fingerprint
+ *  the WHOLE entry minus the two fields that are provably HOT — `cost` (refreshed via
+ *  `mutateInPlace(pricing, buildPricing(config.models))`) and `quotaWeight` (via
+ *  `mutateInPlace(config.modelQuotaWeights, …)`) — so a pure re-pricing never restarts a worker. A DENY-list
+ *  (not an allow-list) on purpose: a catalog field added later rides the fingerprint automatically, so the
+ *  failure mode of drift is a spurious restart, never a silently missed one. */
+function degradeRouteFingerprint(entry) {
+    // `enabled` is dropped too, but for a different reason: `enabledOnly` already filtered on it, so among the
+    // entries that reach here it is `true`-or-absent — two encodings of ONE state. Keeping it would let a center
+    // serializer that starts/stops emitting the explicit `true` manufacture a restart out of nothing.
+    const { cost: _cost, quotaWeight: _quotaWeight, enabled: _enabled, ...route } = entry;
+    return route;
+}
+function restartSliceValue(eff, slice, ctx) {
     if (!eff)
         return null;
     switch (slice) {
@@ -69,14 +84,23 @@ function restartSliceValue(eff, slice) {
             const def = resolveDefaultModelName(eff, (n) => names.has(n), enabled?.[0]?.name ?? "");
             return { models: enabled, tiers: active, default: def.name };
         }
+        case "degrade-route": {
+            const to = ctx?.reactiveDegradeTo;
+            if (to === undefined)
+                return null; // lane off — no degrading brain exists to go stale
+            // Present↔absent is itself a change: with no enabled entry named `to`, createBrain composes NO
+            // degrading shell at all, so the flip only takes effect at the next boot.
+            const target = (enabledOnly(eff.models?.models) ?? []).find((m) => m.name === to);
+            return target ? degradeRouteFingerprint(target) : null;
+        }
     }
 }
 /** Restart-to-apply slices that DIFFER between this process's BOOT config and a freshly-pulled one. Empty =
  *  nothing baked-at-boot changed (only hot-apply slices moved, or nothing) → no restart needed. An orchestrator
  *  can auto rolling-restart on a non-empty result WITHOUT a restart loop, because the comparison is always
  *  against boot (a refresh that re-fires the same diff is idempotent, not a fresh trigger). */
-export function restartReasons(boot, current) {
-    return RESTART_SLICES.filter((s) => stableStringify(restartSliceValue(boot, s)) !== stableStringify(restartSliceValue(current, s)));
+export function restartReasons(boot, current, ctx) {
+    return RESTART_SLICES.filter((s) => stableStringify(restartSliceValue(boot, s, ctx)) !== stableStringify(restartSliceValue(current, s, ctx)));
 }
 /** codex R10 (models-tiers 窗收口): TRUE when the MODEL PLANE (enabled models + active tier table + resolved
  *  default) of `next` differs from the last-APPLIED plane `prev`. Under a tier-frozen Runner (tiers non-empty at

package/dist/plugins/remote-env-host.d.ts

@@ -280,22 +280,40 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
  * `ctx.sessionId` into the workspace dir id so two concurrent tasks never share a working directory.
  */
 export declare function hostExecutionEnvFactory(config?: HostEnvConfig): ExecutionEnvFactory;
-export { localDockerExecutionEnvFactory, type LocalDockerEnvConfig, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
-/** Config for the (not-yet-implemented) `remote-docker` provider: run each task in a container on a REMOTE
- *  docker daemon (e.g. over a TLS docker endpoint). Fast-follow per DUAL-MODE-DESIGN §5. */
-export interface RemoteDockerEnvConfig {
-    /** Container image to run the task in. */
-    image: string;
-    /** Workspace mount path inside the container. */
-    mountPath?: string;
-    /** Remote docker daemon endpoint (e.g. tcp://host:2376 or ssh://user@host). Required for remote-docker. */
+export { localDockerExecutionEnvFactory, type LocalDockerEnvConfig, type LocalDockerEnvDeps, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
+import { type LocalDockerEnvConfig, type LocalDockerEnvDeps } from "./remote-env-local-docker.js";
+/**
+ * Config for the `remote-docker` provider: run each task in a container on a REMOTE docker daemon
+ * (DUAL-MODE-DESIGN §5 — "a user-specified REMOTE host's docker"; registry-core `RemoteExecSpec`).
+ *
+ * It is {@link LocalDockerEnvConfig} with the endpoint made REQUIRED — that is the whole difference, by design:
+ * the container adapter is already daemon-agnostic (workspace `mkdir`'d INSIDE the container, never a host
+ * bind-mount; bytes over `docker cp` / `docker exec cat`, which stream through the daemon API), and the endpoint
+ * rides as `-H <dockerHost>` on every invocation. So every local-docker knob (memory/cpus/pidsLimit/dropAllCaps/
+ * network/timeouts/env/dockerPath) applies unchanged to the remote lane.
+ */
+export interface RemoteDockerEnvConfig extends Omit<LocalDockerEnvConfig, "dockerHost" | "providerLabel"> {
+    /** Remote docker daemon endpoint (e.g. `tcp://host:2376` or `ssh://user@host`). REQUIRED for remote-docker. */
     dockerHost: string;
-    /** Out-of-band env injected into the container (secrets resolved by the control plane). */
-    env?: Record<string, string>;
 }
 /**
- * `remote-docker` factory entry point — wired but an explicit TODO (DUAL-MODE-DESIGN §5 fast-follow). Throws
- * at factory-BUILD time so selecting it before it exists fails loud rather than degrading isolation silently.
+ * `ExecutionEnvFactory` for the TOC `remote-docker` backend (DUAL-MODE-DESIGN §5): a per-task container on
+ * SOMEONE ELSE'S docker daemon (offload — the operator's box stays free; isolation:true, suspendable:false).
+ * Same lifetime contract as local-docker: unconnected/lazy, one container per task, `destroy()` = `docker rm -f`.
+ *
+ * 🔴 **Endpoint credentials are the docker CLI's own** — this adapter deliberately carries none. The docker CLI
+ * reads `DOCKER_CERT_PATH` + `DOCKER_TLS_VERIFY` from the worker's environment (inherited by every spawn) for a
+ * `tcp://` + TLS daemon, and uses `ssh-agent` / `~/.ssh/config` for an `ssh://` one. That keeps key material out
+ * of this process's config objects entirely. Consequence to know: `tcp://…:2376` WITHOUT those env vars fails
+ * loud at connect (the daemon refuses plaintext) — it does not silently downgrade; a plaintext `tcp://…:2375`
+ * daemon is unauthenticated and remains the operator's decision, exactly as in the registry-core schema.
+ * (The registry-core `remote-docker` arm additionally models `tlsCertEnv`/`tlsKeyEnv`/`tlsCaEnv`/`sshKeyEnv` =
+ * env-NAMEs the control plane resolves to PEM BYTES. Materializing those bytes to short-lived 0600 files and
+ * passing `--tlsverify --tlscert/--tlskey/--tlscacert` is the remaining config-surface follow-up, together with
+ * the `provider:"remote-docker"` arm on `AppConfig.remoteExec` — see the note on that union in config-types.ts.)
+ *
+ * Throws at factory-BUILD time on a missing/blank endpoint: a "remote" lane with no endpoint would otherwise
+ * quietly become the LOCAL daemon — an isolation-topology surprise, so it fails loud instead.
  */
-export declare function remoteDockerExecutionEnvFactory(_config: RemoteDockerEnvConfig): ExecutionEnvFactory;
+export declare function remoteDockerExecutionEnvFactory(config: RemoteDockerEnvConfig, deps?: LocalDockerEnvDeps): ExecutionEnvFactory;
 //# sourceMappingURL=remote-env-host.d.ts.map

package/dist/plugins/remote-env-host.js

@@ -28,8 +28,9 @@
  * (`{ ok:true, exitCode }`), never an error.
  *
  * Platforms: macOS + Linux (POSIX shell). Forward-compatible with the `remoteExec` superset: this file also
- * scaffolds the `local-docker` / `remote-docker` providers' factory entry points (typed stubs that throw a
- * clear "not yet implemented" — explicit fast-follow per DUAL-MODE-DESIGN §5; NOT faked green).
+ * hosts the `local-docker` / `remote-docker` providers' factory entry points — both now IMPLEMENTED by the
+ * container adapter in remote-env-local-docker.ts (the two providers differ only in whether the `-H` daemon
+ * endpoint is off-box and required), re-exported/wrapped here so the discriminator has one canonical site.
  */
 import { spawn } from "node:child_process";
 import os from "node:os";
@@ -1647,19 +1648,38 @@ export function hostExecutionEnvFactory(config = {}) {
 // ─────────────────────────────── remoteExec superset: docker providers ───────────────────────────────
 //
 // DUAL-MODE-DESIGN §5 defines a `remoteExec.provider` superset. `host` (above) is implemented; `local-docker`
-// is NOW IMPLEMENTED (the isolation lane) — it lives in its own module (remote-env-local-docker.ts) and is
-// re-exported here so the discriminator entry point + the historical import site stay stable. `remote-docker`
-// (a REMOTE docker daemon over TLS/SSH) is still an explicit fast-follow stub — it throws a clear "not yet
-// implemented" so selecting it fails loud at wiring time instead of silently degrading isolation. NOT faked green.
+// (the isolation lane) and `remote-docker` (that same container lane aimed at a REMOTE daemon) are BOTH
+// implemented by remote-env-local-docker.ts and re-exported / wrapped here so the discriminator entry points +
+// the historical import sites stay stable.
 // `local-docker` (the isolation lane): real implementation moved to remote-env-local-docker.ts. Re-export the
 // factory + config from here so existing wiring (`import { localDockerExecutionEnvFactory } from "./remote-env-host"`)
 // keeps working and the provider discriminator has one canonical entry point.
 export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
+import { localDockerExecutionEnvFactory } from "./remote-env-local-docker.js";
 /**
- * `remote-docker` factory entry point — wired but an explicit TODO (DUAL-MODE-DESIGN §5 fast-follow). Throws
- * at factory-BUILD time so selecting it before it exists fails loud rather than degrading isolation silently.
+ * `ExecutionEnvFactory` for the TOC `remote-docker` backend (DUAL-MODE-DESIGN §5): a per-task container on
+ * SOMEONE ELSE'S docker daemon (offload — the operator's box stays free; isolation:true, suspendable:false).
+ * Same lifetime contract as local-docker: unconnected/lazy, one container per task, `destroy()` = `docker rm -f`.
+ *
+ * 🔴 **Endpoint credentials are the docker CLI's own** — this adapter deliberately carries none. The docker CLI
+ * reads `DOCKER_CERT_PATH` + `DOCKER_TLS_VERIFY` from the worker's environment (inherited by every spawn) for a
+ * `tcp://` + TLS daemon, and uses `ssh-agent` / `~/.ssh/config` for an `ssh://` one. That keeps key material out
+ * of this process's config objects entirely. Consequence to know: `tcp://…:2376` WITHOUT those env vars fails
+ * loud at connect (the daemon refuses plaintext) — it does not silently downgrade; a plaintext `tcp://…:2375`
+ * daemon is unauthenticated and remains the operator's decision, exactly as in the registry-core schema.
+ * (The registry-core `remote-docker` arm additionally models `tlsCertEnv`/`tlsKeyEnv`/`tlsCaEnv`/`sshKeyEnv` =
+ * env-NAMEs the control plane resolves to PEM BYTES. Materializing those bytes to short-lived 0600 files and
+ * passing `--tlsverify --tlscert/--tlskey/--tlscacert` is the remaining config-surface follow-up, together with
+ * the `provider:"remote-docker"` arm on `AppConfig.remoteExec` — see the note on that union in config-types.ts.)
+ *
+ * Throws at factory-BUILD time on a missing/blank endpoint: a "remote" lane with no endpoint would otherwise
+ * quietly become the LOCAL daemon — an isolation-topology surprise, so it fails loud instead.
  */
-export function remoteDockerExecutionEnvFactory(_config) {
-    throw new RemoteExecutionError("unsupported", "remoteExec provider 'remote-docker' is not yet implemented (DUAL-MODE-DESIGN §5 fast-follow) — use 'host', 'local-docker', or 'e2b' until it ships");
+export function remoteDockerExecutionEnvFactory(config, deps = {}) {
+    const dockerHost = config.dockerHost?.trim();
+    if (!dockerHost) {
+        throw new RemoteExecutionError("connect_failed", "remoteExec provider 'remote-docker' requires a non-empty dockerHost (the remote daemon endpoint, e.g. tcp://host:2376 or ssh://user@host) — use provider 'local-docker' for THIS machine's daemon");
+    }
+    return localDockerExecutionEnvFactory({ ...config, dockerHost, providerLabel: "remote-docker" }, deps);
 }
 //# sourceMappingURL=remote-env-host.js.map

package/dist/plugins/remote-env-local-docker.d.ts

@@ -17,8 +17,20 @@ export interface LocalDockerEnvConfig {
     /**
      * DOCKER_HOST override for the docker CLI (e.g. a non-default socket). Passed as `-H <value>` on EVERY docker
      * invocation (not the process env) so it can't leak / drift. Absent = the daemon DOCKER_HOST points at.
+     *
+     * Pointing this OFF-BOX (`tcp://host:2376`, `ssh://user@host`) is exactly the DUAL-MODE-DESIGN §5
+     * **`remote-docker`** provider — see {@link remoteDockerExecutionEnvFactory} (remote-env-host.ts), which is
+     * this adapter with the endpoint required. Nothing else about the class is host-local: the workspace is
+     * `mkdir`'d INSIDE the container (never a bind-mount of a host path) and bytes move by `docker cp` /
+     * `docker exec cat`, which stream over the daemon API.
      */
     dockerHost?: string;
+    /**
+     * Provider NAME reported on the {@link WorkspaceHandle}. Default `"local-docker"`; the `remote-docker` arm
+     * passes `"remote-docker"` so a handle never mislabels which lane it is (the CLASS is shared — `remote-docker`
+     * IS this adapter aimed at a remote daemon). Cosmetic/observability only: it selects no behavior.
+     */
+    providerLabel?: string;
     /** Container memory limit (docker `--memory`, e.g. "2g"). Absent = no limit. */
     memory?: string;
     /** Container CPU limit (docker `--cpus`, e.g. 1.5). Absent = no limit. */
@@ -65,6 +77,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private readonly spawnFn;
     /** Stable container NAME (also our handle id). Created on connect; targeted by every docker exec/cp/rm. */
     private readonly containerName;
+    /** Provider name put on the WorkspaceHandle ("local-docker" | "remote-docker"). Observability only. */
+    private readonly providerName;
     /** Set once the container is up + the workspace dir created. */
     private containerId?;
     private handle?;

package/dist/plugins/remote-env-local-docker.js

@@ -66,6 +66,8 @@ export class RemoteLocalDockerExecutionEnv {
     spawnFn;
     /** Stable container NAME (also our handle id). Created on connect; targeted by every docker exec/cp/rm. */
     containerName;
+    /** Provider name put on the WorkspaceHandle ("local-docker" | "remote-docker"). Observability only. */
+    providerName;
     /** Set once the container is up + the workspace dir created. */
     containerId;
     handle;
@@ -92,6 +94,7 @@ export class RemoteLocalDockerExecutionEnv {
         const id = config.id ?? randomBytes(6).toString("hex");
         const suffix = randomBytes(4).toString("hex"); // always-unique tail so a reused id never collides
         this.containerName = `sema-docker-${sanitizeId(id)}-${suffix}`;
+        this.providerName = config.providerLabel?.trim() || PROVIDER;
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -165,7 +168,7 @@ export class RemoteLocalDockerExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
         this.containerId = run.value.stdout.trim() || this.containerName;
-        this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
+        this.handle = { sandboxId: this.containerName, provider: this.providerName, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
         if (config?.secrets?.length) {
             // Secrets are injected per-command via cfg.env (resolved by the control plane), not at connect — record only.
         }
@@ -197,7 +200,7 @@ export class RemoteLocalDockerExecutionEnv {
             // re-run `docker run --name <same>` → name conflict → the failure path rm -f's the very container we just
             // re-attached to (destroying the running workspace). The name IS our exec/handle target.
             this.containerId = this.containerName;
-            this.handle ??= { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
+            this.handle ??= { sandboxId: this.containerName, provider: this.providerName, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
             return ok(this.handle);
         }
         return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' is not running (gone or stopped) — no managed snapshot to resume`) };
@@ -609,7 +612,11 @@ export class RemoteLocalDockerExecutionEnv {
             return;
         this.containerShellProbed = true;
         try {
-            const r = await this.docker(this.withHostFlag(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"]), { timeoutMs: this.cfg.controlTimeoutMs });
+            // 🔴 NO withHostFlag here — `docker()` already prepends it. A second `-H` is not a harmless repeat: the
+            // docker CLI rejects the whole command (`invalid argument … specify only one -H`), so on every
+            // REMOTE-daemon container (`dockerHost` set — always, on the `remote-docker` arm) the probe used to fail
+            // and silently degrade the user shell to /bin/sh for a reason unrelated to the image.
+            const r = await this.docker(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"], { timeoutMs: this.cfg.controlTimeoutMs });
             if (r.ok && r.value.exitCode === 0 && r.value.stdout.trim().length > 0)
                 this.containerShell = "bash";
         }

package/dist/plugins/run-store-sql.d.ts

@@ -126,9 +126,14 @@ export declare class SqlRunStore {
      * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
      * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
-     * (reaper-revert guard, mirrors setSuspended). 🔴 The store SQL here is exercised by mocked unit tests only — a
-     * real-TiDB integration test of the park→resume→claim invariant is a required-before-GA TODO (the lesson from the
-     * P2 lease-SQL + this needs_review-park bug: mocked tests hide store-SQL defects).
+     * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
+     * `test/run-store-reaper-integration.test.ts` (`inv#1` row ownership across park→resume→handover, `inv#2` two
+     * replicas racing one session ⇒ exactly one claim wins, `inv#3`/`inv#3'` stale-claim takeover vs fresh/parked
+     * claims), closing the former required-before-GA gap. Keep it that way: the P2 lease-SQL bug and this
+     * needs_review-park bug were both born from store SQL that mocked unit tests pass — measured, not asserted, when
+     * the invariant set was built: an upserting (non-exclusive) claim reddened all four real-DB cases while all 111
+     * mocked run-store unit tests stayed green. A mock cannot observe a unique-key claim race, a rolled-back loser,
+     * or a multi-table reaper DELETE.
      */
     setNeedsReview(taskId: string): Promise<void>;
     /**

package/dist/plugins/run-store-sql.js

@@ -206,9 +206,14 @@ export class SqlRunStore {
      * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
      * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
-     * (reaper-revert guard, mirrors setSuspended). 🔴 The store SQL here is exercised by mocked unit tests only — a
-     * real-TiDB integration test of the park→resume→claim invariant is a required-before-GA TODO (the lesson from the
-     * P2 lease-SQL + this needs_review-park bug: mocked tests hide store-SQL defects).
+     * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
+     * `test/run-store-reaper-integration.test.ts` (`inv#1` row ownership across park→resume→handover, `inv#2` two
+     * replicas racing one session ⇒ exactly one claim wins, `inv#3`/`inv#3'` stale-claim takeover vs fresh/parked
+     * claims), closing the former required-before-GA gap. Keep it that way: the P2 lease-SQL bug and this
+     * needs_review-park bug were both born from store SQL that mocked unit tests pass — measured, not asserted, when
+     * the invariant set was built: an upserting (non-exclusive) claim reddened all four real-DB cases while all 111
+     * mocked run-store unit tests stayed green. A mock cannot observe a unique-key claim race, a rolled-back loser,
+     * or a multi-table reaper DELETE.
      */
     async setNeedsReview(taskId) {
         await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', updated_at = ? WHERE task_id = ? AND status IN ('running','needs_review')", "UPDATE task_run SET status = 'needs_review', updated_at = $1 WHERE task_id = $2 AND status IN ('running','needs_review')"), [new Date(), taskId]);

package/dist/sema-registry.d.ts

@@ -10,9 +10,23 @@
  *     (core 1.45), so each model/cascade-rung authenticates with its own upstream key.
  *
  * Per-model `baseUrl` IS transported (a catalog model may live on a different gateway;
- * core brain honors model.baseUrl, absent = "" = boot-env endpoint). TODO remaining: hot-reload
- * of models/roles needs Runner support — today teams hot-reload via the registry, while a models/roles
- * change is logged as "restart to apply".
+ * core brain honors model.baseUrl, absent = "" = boot-env endpoint).
+ *
+ * Hot-reload status (复审 2026-07-29 P1-11 — 亲读判定,取代此处旧的 "models/roles are restart-to-apply"
+ * TODO, which went stale when `mutateInPlace` landed):
+ *   - models/roles/roster/teams/projects/autonomy — **HOT**. `applyEffective` mutates `config.models`/
+ *     `config.roles` IN PLACE, and core's Runner reads `this.deps.models/roles` per task off that very
+ *     reference. Both brains re-resolve `model.baseUrl || config.baseUrl` inside `buildRequest()` on every
+ *     call (core 2.1.0 `brain/openai.js` + `brain/anthropic.js`), so a moved gateway takes effect on the
+ *     next task with no restart.
+ *   - the same plane under a **tier-frozen** Runner — deferred, not hot: core expands a PRIVATE catalog copy
+ *     at construction, so `main` defers the whole plane and the `models-tiers` restart slice signals.
+ *   - **`degrade-route`** — the one genuinely boot-frozen catalog consumer left: reactive degrade
+ *     (`MODEL_DEGRADE_REACTIVE`) bakes the target Model + its gateway + its key into the brain composition
+ *     at boot. It cannot be hot-applied without rebuilding the brain, so it is registered on the existing
+ *     restartRequired /health contract instead (see `restart-signal.ts`). Fail-loud beats serving a stale
+ *     gateway silently on the rate-limit path.
+ *   - skills/mcp/scenarios/runtime-gates — restart-to-apply by construction (baked into the boot wiring).
  *
  * (design/158 A13, internal-lossless) This module is now a FACADE: the implementation lives in
  * `src/config-center/` split by responsibility group (HTTP client / EffectiveConfig application /
@@ -21,7 +35,7 @@
  */
 export { fetchEffective, fetchPrincipalCaps, ConfigCenterHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./config-center/http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, resolveDefaultModelName, logEffectiveDiff, runtimeHasActiveGate, } from "./config-center/apply-effective.js";
-export { restartReasons, planeHasActiveTiers, modelPlaneChanged, type RestartSlice, type RestartSignal, } from "./config-center/restart-signal.js";
+export { restartReasons, planeHasActiveTiers, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type RestartSignal, } from "./config-center/restart-signal.js";
 export { applyCenterSkills, resolveMcpServers, mcpForScenario } from "./config-center/skills-mcp.js";
 export type { CenterSkillManifest, CenterMcpServer, EffectiveConfig, ExecutionRuling, SessionMirrorRuling, } from "./config-center/types.js";
 //# sourceMappingURL=sema-registry.d.ts.map

package/dist/sema-registry.js

@@ -10,9 +10,23 @@
  *     (core 1.45), so each model/cascade-rung authenticates with its own upstream key.
  *
  * Per-model `baseUrl` IS transported (a catalog model may live on a different gateway;
- * core brain honors model.baseUrl, absent = "" = boot-env endpoint). TODO remaining: hot-reload
- * of models/roles needs Runner support — today teams hot-reload via the registry, while a models/roles
- * change is logged as "restart to apply".
+ * core brain honors model.baseUrl, absent = "" = boot-env endpoint).
+ *
+ * Hot-reload status (复审 2026-07-29 P1-11 — 亲读判定,取代此处旧的 "models/roles are restart-to-apply"
+ * TODO, which went stale when `mutateInPlace` landed):
+ *   - models/roles/roster/teams/projects/autonomy — **HOT**. `applyEffective` mutates `config.models`/
+ *     `config.roles` IN PLACE, and core's Runner reads `this.deps.models/roles` per task off that very
+ *     reference. Both brains re-resolve `model.baseUrl || config.baseUrl` inside `buildRequest()` on every
+ *     call (core 2.1.0 `brain/openai.js` + `brain/anthropic.js`), so a moved gateway takes effect on the
+ *     next task with no restart.
+ *   - the same plane under a **tier-frozen** Runner — deferred, not hot: core expands a PRIVATE catalog copy
+ *     at construction, so `main` defers the whole plane and the `models-tiers` restart slice signals.
+ *   - **`degrade-route`** — the one genuinely boot-frozen catalog consumer left: reactive degrade
+ *     (`MODEL_DEGRADE_REACTIVE`) bakes the target Model + its gateway + its key into the brain composition
+ *     at boot. It cannot be hot-applied without rebuilding the brain, so it is registered on the existing
+ *     restartRequired /health contract instead (see `restart-signal.ts`). Fail-loud beats serving a stale
+ *     gateway silently on the rate-limit path.
+ *   - skills/mcp/scenarios/runtime-gates — restart-to-apply by construction (baked into the boot wiring).
  *
  * (design/158 A13, internal-lossless) This module is now a FACADE: the implementation lives in
  * `src/config-center/` split by responsibility group (HTTP client / EffectiveConfig application /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -67,7 +67,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^0.0.46",
+    "@sema-agent/sdk": "^1.0.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",