@sema-agent/server 7.147.0 → 7.149.0

package/README.md

@@ -33,7 +33,7 @@ model gateways, and cloud agent execution behind an HTTP/SSE contract.
   or PostgreSQL; a file-backed `local` mode covers single-machine use). Each pooled connection pins its
   own session isolation (`REPEATABLE READ` on the MySQL-protocol leg, `READ COMMITTED` on PostgreSQL) and
   verifies it by reading back; on TiDB the session is switched to pessimistic transaction mode, and boot is
-  refused only when that switch cannot be made or verified — see docs/DEPLOY-PREREQS.md. Any replica can serve any
+  refused only when that switch cannot be made or verified. Any replica can serve any
   run's event stream; a task can suspend on one replica and resume on another.
 - **The full server-side capability surface** (discoverable at `GET /v1/capabilities`):
   asynchronous runs with replayable SSE, durable checkpoints with human-in-the-loop approvals,
@@ -128,7 +128,10 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   (public on npmjs) · images = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
   (both public; `:latest` rolling, `:<sha>` pinned).
 - **Image publishing discontinued**: Container images are no longer published since 7.128.0; the npm package is the only release artifact; self-build steps are in USAGE 9.13.
-- **Library embedding** (package root, e.g. `createHttpServer` + your own `StoreBackend`): after
+- **Library embedding** (package root, e.g. `createHttpServer` + your own `StoreBackend`): first call
+  `declareServerWithheldEnv()` (package root export since 7.148.0) once, before `loadConfig()` and before any execution environment or child process —
+  it declares this process's own credential variables to the engine, so host child processes do not inherit them (under any `inheritEnv` word) and no name-list knob may hand them on;
+  `loadConfig()` refuses (throws) in a process that has not declared, naming that step. The service's own entries do it as their first step. After
   `loadConfig()`, call `composeExecutionLane(config, ctx)` — the HTTP service and `run-local` both do. Since
   7.104.0 the execution-lane start refusals (`LEADER_ENABLED` on the host lane, a multi-tenant posture on a
   shared lane, the device lane without its durable stores) are judged there, not in `loadConfig()`;
@@ -139,14 +142,27 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   Since 7.145.0 it also requires `deploymentMods` — the very array the Runners carry as `mods` (`[]` for an embedding without mods): the server reads it to
   learn whether a prompt screen runs on a leg, and on such a leg stores objective text only once the engine delivered it unchanged (two paths sit outside that: a `verify`
   submission's resume input keeps the request text for its verifier, and that copy is never shown; and the leader lane's durable-worker sub-goal resume inputs, which do not go through that seat and are still stored as submitted — tracked separately); omitting it refuses at construction.
+  Since 7.147.0 `createHttpServer` also refuses to start a single-user deployment (`REQUIRE_PRINCIPAL` not `true`) that names no operator — the same sentence the service's own start-up gives:
+  set `OPERATOR_SINGLE_USER=true` (every caller is the operator) or a named `OPERATOR_PRINCIPALS` in the process environment before `loadConfig()`.
+  The seats `createHttpServer` requires (the type `ServiceCoreDeps`) are `runner`, `runnerFor`, `sideQuery`, `scenarioGate`, `peerDesk`, `deploymentMods`, `config`, `authorize` and `resolveSpec`
+  (`resolveSpec` is the embedder's own map from a request body and identity to a task spec; it returns no `sessionId`, the server stamps the root). Leaving out `runnerFor`, `authorize`,
+  `deploymentMods`, `peerDesk` or `scenarioGate` makes `createHttpServer` throw `createHttpServer: the <seat> seat is required` (followed by the way out) before it routes anything (leaving out `config` throws an unnamed
+  `TypeError`); for `runner`, `sideQuery` and `resolveSpec` the type is the only notice — a plain-JS embedding that leaves one out is accepted at construction.
   Build-time tools (e.g. a catalog editor) read two allowlists from the package root instead of hand-copying them: `RETIRED_ENVS` (the retired-env
   tombstones) and, since 7.110.0, `CATALOG_ENTRY_HEADER_LANES` / `CATALOG_ENTRY_HEADER_NAMES` (+ type `CatalogEntryHeaderName`) — the closed allowlist of
   model-catalog entry `headers` and the API line that reads each name. Both are frozen, the very objects the server judges with.
   A shell that must know which model table a running engine serves, whether the catalog was adopted, and what the start-up route judge says, reads
   `modelPlane` on `GET /v1/models` (`{ servedTable: "env" | "catalog", catalog: "absent" | "adopted" | "refused", refusalCode?, gap? }`) — it asks the server
-  instead of predicting, because the judge's inputs are facts of the serving process. It is answerable only once the engine is up; there is no pre-start probe.
+  instead of predicting, because the judge's inputs are facts of the serving process. Before the engine is up, run the package's `dist/model-plane-probe.js`
+  (subpath `@sema-agent/server/model-plane-probe`; same env and working directory as the engine you are about to start): it runs the first two start-up stages
+  up to the point where the model table is settled, never listens, and prints that same `modelPlane` JSON as one stdout line (byte-identical to the started engine's
+  reading at the end of stage 2; when the boot pull overruns `CONFIG_BOOT_FETCH_BUDGET_MS` it is the fallback served before that pull lands); where the start-up would
+  refuse in those stages it exits non-zero with the start-up's own `fatal` line.
   The start-up's own route judge runs **after** the catalog is applied, not in `loadConfig()`: a hand-built assembly calls `judgeServedModelRoute(config, { envTableIsPlaceholder })`
   (package root) once after its own config-source apply, like `composeExecutionLane`.
+  A runnable reference of this whole chain ships in the package: `node scripts/embed-minimal.mjs` (from the package directory) assembles the nine seats `createHttpServer` requires
+  (package-root factories, the engine's `Runner`, and a one-line `resolveSpec` of its own), serves on the host lane from a throwaway data root on a kernel-assigned loopback port,
+  and prints `EMBED-MINIMAL ok port=<n>`; `--omit <seat>` leaves one seat out and says whether `createHttpServer` refused it at construction (`refused`, exit 2) or took it (`accepted`, exit 3).
 - **Bundled binaries**: the package ships two `bin` entries — `run-local` (single-machine local
   runner) and `sema-up` (deployment bootstrap script).
   - `run-local` boots the same engine in-process, runs one task from the CLI objective, prints the
@@ -195,7 +211,7 @@ The server is configured entirely through environment variables. The most import
 | Variable | Default | What it does |
 |----------|---------|--------------|
 | `PORT` | `8090` | HTTP listen port. `0` = let the OS pick one: the `listening` log line (stdout, info level) and `/health.port` report the port actually bound |
-| `BIND_HOST` (alias `HOST`) | see note | Listen address. An explicit `BIND_HOST` **always wins**. Default: `127.0.0.1` when the write face is unauthenticated (`ALLOW_UNAUTHED_WRITES=true` **and** no service token configured), otherwise all interfaces — deployments with a token are unaffected. Since 3.15.0 the `HOST` alias is **not** fully equivalent: shells commonly set `HOST` to the machine name without the operator knowing, so when the narrowing condition above holds it wins over an inherited `HOST` (logged as `bind_host_from_HOST_env_overridden`). Set `BIND_HOST` explicitly, or configure a service token, to expose the write face. |
+| `BIND_HOST` (alias `HOST`) | see note | Listen address. An explicit `BIND_HOST` **always wins**. Default: `127.0.0.1` when the write face is unauthenticated (`ALLOW_UNAUTHED_WRITES=true` **and** no service token configured), otherwise all interfaces — deployments with a token are unaffected. Since 3.15.0 the `HOST` alias is **not** fully equivalent: shells commonly set `HOST` to the machine name without the operator knowing, so when the narrowing condition above holds it wins over an inherited `HOST` (logged as `bind_host_from_HOST_env_overridden`). To expose the write face, configure a service token — on a single-user deployment (`REQUIRE_PRINCIPAL` off) an explicit non-loopback `BIND_HOST` with an unauthenticated write face refuses to boot (invariant `single-user-anonymous-boundary`); on a multi-tenant deployment an explicit `BIND_HOST` still exposes it. |
 | `MODEL_GATEWAY_BASEURL` | **no default** | OpenAI-compatible gateway base URL (without `/chat/completions`). **No factory default**: every route that rides the openai-compatible lane must resolve to an explicit endpoint — the model's own catalog `baseUrl`, or this knob — else the server refuses to boot, naming the models and printing the explicit local spelling (`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`). An Anthropic-only deployment may leave it unset. Setting `MODEL_GATEWAY_FALLBACK_URLS` without it is refused too |
 | `MODEL_ID` | **required unless a catalog supplies the default** | Default model id — **no factory default since 3.0.0**. Since 7.101.0 the check runs **after** the catalog is applied: `MODEL_ID` **or** a usable catalog default (`config.d/models.json` / the web-admin) is enough; with neither the server refuses to boot (`config.default_model_missing`, naming both ways out). A catalog that is adopted replaces the env model table, so `MODEL_ID` is then not served: the boot is not refused (even with no gateway, when the catalog entries carry their own `baseUrl`) and logs one `config_env_set_but_ineffective` line naming the catalog default that serves (exactly once, at the moment the catalog is first adopted — at boot, or later when it arrives after the boot fetch budget / on a refresh). The old baked-in default was an internal-only model name, so every external deployment failed later and further from the cause: a gateway `400` plus a cascade of title-hook warnings |
 | `MODEL_API_KEY` | — | Gateway API key (optional). Pairs only with `MODEL_GATEWAY_BASEURL`: with no gateway it is not loaded and sent nowhere |
@@ -203,7 +219,7 @@ The server is configured entirely through environment variables. The most import
 | `DB_BACKEND` | `local`* | `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB) / `pg` (PostgreSQL) / `local` (file-backed, no DB) / `memory` (explicit in-memory: nothing survives a restart, durable-runs faces 501). *Bare boot (no DB env at all) defaults to `local` so a single-user machine keeps its runs across restarts; any SQL signal (`SESSION_BACKEND` or `MYSQL_/PG_HOST`) keeps the `mysql` engine default, and `REQUIRE_PRINCIPAL=true` bare boots stay `memory`. (`TIDB_HOST`/`_PORT`/`_USER`/`_PASSWORD`/`_DATABASE`/`_POOL_SIZE` are retired names, not an alias — since 5.0.0 setting any of them refuses to boot, pointing at the `MYSQL_*` replacement; TiDB itself connects fine through `MYSQL_*`, since it speaks the MySQL protocol.) (the local file store has no tenant isolation — a warning says so). A DEFAULT-derived `local` that cannot create its data root degrades to memory with a warning + the `store_backend_degraded` gauge; an EXPLICIT `DB_BACKEND=local` fails loud instead. Setting `mysql`/`pg` explicitly also switches sessions to durable |
 | `SESSION_BACKEND` | `memory`* | `memory` / `mysql` (durable session center) / `auto`. *Defaults to durable when `DB_BACKEND` is explicitly `mysql`/`pg`. (`tidb` is a RETIRED public name — setting it refuses to boot; since 7.57.0 `GET /v1/config/catalog` also echoes the public word `mysql` instead of the internal `tidb` label) |
 | `REMOTE_EXEC` | (required) | Execution lane: `host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb` / `device` / `none` (`none` = no execution environment for the agent's tools: the hands tools never mount, the other tools still run). **Every deployment declares it** (with `CONFIG_PROVIDER=local`, `config.d/remote-exec.json` also declares it); undeclared **refuses to start** with a one-line fix (`REMOTE_EXEC=none` for what an unset non-local deployment did before 7.147.0, `REMOTE_EXEC=host` for an unset `CONFIG_PROVIDER=local` one). Naming a lane without its required env (e.g. `e2b` without `E2B_API_KEY`; an unset, empty or whitespace-only value counts as absent, for every lane and every required key) or an unrecognized value **refuses to start** — no silent downgrade to another lane (fail-closed). `k8s` needs `K8S_SANDBOX_IMAGE` **and** `K8S_NAMESPACE` — the sandbox pods' namespace has no built-in default (the deployment declares it; unset, empty or blank refuses to start; the bundled chart sets it from `sandbox.namespace`). Under `CONFIG_PROVIDER=local` a `config.d/remote-exec.json` **wins over** this env (deliberate: the file is the single-machine source of truth). Since 7.57.0 that preemption is **loud** — `remote_exec_lane_preempted_by_file` names the preempted lane, the effective one, and whether it is an **isolation downgrade** (an isolated lane replaced by a non-isolated one); a file naming a not-yet-wired isolated lane (`e2b`/`k8s`/`ssh`/`adb`) leaves the env lane in force and says so |
-| `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | unset | **SSH lane host-key verification** (`REMOTE_EXEC=ssh` only). `SSH_HOST_FINGERPRINT` = the host key's SHA256 base64 fingerprint (`SHA256:` prefix and `=` padding both optional); `SSH_KNOWN_HOSTS` = a path to a `known_hosts` file, matched literally on `host` / `[host]:port`. **Either one present ⇒ strict verification, a mismatch REFUSES the connection** (the error carries both fingerprints plus an `ssh-keyscan` line); both set ⇒ both must pass. **Both unset ⇒ a loud per-connection warning (`ssh_host_key_unverified`, man-in-the-middle risk) and the connection proceeds** — the deliberate posture for the batch-deploy lane, registered as a P-DEBT fail-open (`docs/FAIL-OPEN-CENSUS.md`). A malformed fingerprint or an unreadable `known_hosts` path **refuses to start**. Not supported in `known_hosts`, on purpose: hashed (`\|1\|…`) lines, wildcard patterns, `@cert-authority` — all skipped, so a host whose only entries are those is REFUSED (`@revoked` is honored and wins over any plain line, whatever the order) |
+| `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | unset | **SSH lane host-key verification** (`REMOTE_EXEC=ssh` only). `SSH_HOST_FINGERPRINT` = the host key's SHA256 base64 fingerprint (`SHA256:` prefix and `=` padding both optional); `SSH_KNOWN_HOSTS` = a path to a `known_hosts` file, matched literally on `host` / `[host]:port`. **Either one present ⇒ strict verification, a mismatch REFUSES the connection** (the error carries both fingerprints plus an `ssh-keyscan` line); both set ⇒ both must pass. **Both unset ⇒ a loud per-connection warning (`ssh_host_key_unverified`, man-in-the-middle risk) and the connection proceeds** — the deliberate posture for the batch-deploy lane, registered as a P-DEBT fail-open (tag `server.exec-lane.ssh-host-key-unverified`, counted in `fail_open_total`). A malformed fingerprint or an unreadable `known_hosts` path **refuses to start**. Not supported in `known_hosts`, on purpose: hashed (`\|1\|…`) lines, wildcard patterns, `@cert-authority` — all skipped, so a host whose only entries are those is REFUSED (`@revoked` is honored and wins over any plain line, whatever the order) |
 | `HOOKS_TIMEOUT_MS` | unset (600000) | Time budget of each handler of the request `settings.hooks` registration (one event's run of the request's hook entries). Unset = 600000 ms — this is the engine's `budgetMs` for the registration (each handler's own time, one event's run of the request's hook entries); when the budget is spent, or the task is cancelled, the command hooks still running in that handler are stopped (SIGTERM, a short grace, then SIGKILL) — they no longer run on to their own `timeout`; the engine's default for an extension (10 s) is not used. `0` is honored as written (a zero budget). The server's own two observer registrations (deny meter, tool trace) do not read it. A non-integer, negative, or above-`setTimeout`-ceiling (2147483647) value **refuses to start** |
 | `MODS_ROOT` / `MODS_PACKAGES` | unset | **Deployment mod packages** loaded into the deployment seat. `MODS_PACKAGES` = a JSON array of `{ "name", "dir", "tier", "options"? }`: `name` is the package's own name (its `.claude-plugin/plugin.json` `name`, spelled exactly); `dir` an absolute path whose real path must sit strictly under the real path of `MODS_ROOT` (an absolute path; compared by path components — a symlink out of the root, a look-alike sibling such as `/mods-evil`, a `..` traversal, or the root itself all refuse to start); `tier` is required (`prepend` / `user` / `append` — the host declares it, a package never does); `options` is handed to the package's `register` as is. The engine's package reader is the only reader of the package files; this server never reads them. Every declared package is loaded once at boot and the whole list goes through the engine's admission: any failure (bad declaration, outside the root, the reader refuses the package, a name mismatch, the admission refuses) **refuses to start** with one single-line sentence naming the slot or the package — the server's own sentence never echoes declared values (paths, `options`); the reader's / admission's own words are passed through (credential shapes redacted, control characters stripped) and may name the package directory. Loaded ⇒ one `mods_package_loaded` log line per package (carrying the engine reader's `digest` — a digest of the bytes of the three package files it read, which tells you which bytes were loaded and is not a code-integrity credential: code the module loads on its own is not in it), `/health.mods.deploymentPackages` and the capability `modsDeploymentPackages: true`; unset (or `[]`) ⇒ both faces stay exactly as without these knobs. A package is **trusted deployment code** — it runs in this process with access to every tenant and the process credentials, the admission is not a sandbox — so install it only from a read-only artifact tree you control. If a package answers `allow` on `PreToolUse` (optionally with `updatedInput`), the engine still adjudicates the final arguments, and what an operator knob asks or refuses (`APPROVAL_REQUIRE`, `APPROVAL_NEVER_AUTO`, `MANUAL_MODE_SHELL_GATE=always`, the ask and deny tiers of `governance.commandPolicy`, …) or the engine mandates does not change because of it — but it can clear an **unmandated** default approval question, so installing a package hands that class of questions to the package author; to have a call asked whatever a package answers, declare it with those knobs. Changing the declaration or a package needs a restart (no automatic restart signal). The config catalog shows `MODS_PACKAGES` as present / length only. `options` is not a credential channel: this server does not withhold package credentials — `MODS_PACKAGES` itself and any variable a package reads are inherited by the model's child processes on the host lane under `inheritEnv: "all"` (only this server's declared own credentials are withheld), so deliver package credentials through a channel the host-lane model shell cannot read |
 | `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane at `SEMA_WEB_ADMIN_URL` — `remote` without that URL refuses to boot). Unset = the center if `SEMA_WEB_ADMIN_URL` is set, else env only. Closed set, matched exactly (7.104.0+): any other value (wrong case, surrounding spaces) refuses to boot; empty = unset |
@@ -218,6 +234,7 @@ The server is configured entirely through environment variables. The most import
 | `MODEL_FIRST_BYTE_TIMEOUT_MS` | unset (core's own default) | The wait from `fetch()` to the response headers, ms (7.103.0; replaces the retired `MODEL_CONNECT_TIMEOUT_MS`, which now **refuses to start** — the TCP + TLS connect is the transport's own clock since core 7.33.0). Unset = no key is passed, core's default applies (plus an upload allowance by request size, and one widened retry of its own). `0` = no engine clock on that segment and the transport's header / body clocks off too (the TCP + TLS connect keeps the transport's own clock). A whole number in `[0, 2147483647]`, anything else refuses to start. With `MODEL_GATEWAY_FALLBACK_URLS` set every gateway route likewise gets the first window plus one widened retry before failover (the server does not pass core's `firstByteRetries`: a caller can turn failover off per request, and that call has no backup behind it). A failover topology must set this knob explicitly: unset, a primary that accepts the connection but never answers is cut over only after core's first-byte lane (default window plus the widened retry) runs out, and a call with a shorter time budget (code-review council lenses, 180 s) is cancelled before the backup is tried; at boot such a deployment logs one `failover_first_byte_lane` warn |
 | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `600000` | First-token timeout (the only watchdog for a stream that opens and never emits; `0` = no engine clock on that segment, the transport's body clock off too. Raised from `120000` in 7.71.0 — a self-hosted backend's long prefill legitimately takes minutes to the first byte; set `120000` to restore the old posture) |
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | Mid-stream idle timeout (`0` = no engine clock on that segment, the transport's body clock off too) |
+| `REAP_RUN_STALE_SEC` | `120` | Run liveness window, seconds: the reaper (every `REAP_INTERVAL_SEC`, default `60`) fails a `running` run whose row has not been touched for this long, and the stop-then-start one-time migrations judge "is an earlier replica still serving" by the same window (a boot refuses while any run on the database heartbeated within it). **Must be greater than the 30 s liveness heartbeat** — a value at or below 30 refuses to boot (the reaper would race a run that is still heartbeating) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` (structured JSON logs) |
 
 **Boolean knobs** accept `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off` (case-insensitive; word table widened
@@ -242,6 +259,12 @@ boundary) — the side-by-side table is in `USAGE.md`, worth reading before pick
 Web search (deployment `WEB_SEARCH_*` env, per-request `settings.webSearch`, the two-lane precedence
 and the tool-level error forms) is documented in `USAGE.md` §9.5.
 
+A single-machine deployment (`CONFIG_PROVIDER=local`) mounts external MCP servers through `config.d/mcp.json`: the entries have
+the same shape as the center's `mcp` domain, and the file stores only env-variable *names* (`envRefs` / `headerRefs`) — the values
+are read from this process's own environment, never from the file. The file is executable configuration, so it is read only from a
+trusted directory (owner and mode are checked before every read; on Windows only the directory structure can be checked). Where the file lives, the entry keys, the credential boundary,
+the posture of an anonymous (no-principal) caller and how it relates to a request body's `mcpServers` are in `USAGE.md` §9.5i-ter.
+
 ## Security & privacy note
 
 > 🔴 **Trace redaction ≠ egress control** (anchor: 脱敏 ≠ 出站控制). Trace redaction (the `«redacted»` markers you see in the
@@ -250,7 +273,7 @@ and the tool-level error forms) is documented in `USAGE.md` §9.5.
 > text.** That route is not just `MODEL_GATEWAY_BASEURL`: it can also be the fallback gateway list
 > (`MODEL_GATEWAY_FALLBACK_URLS`), an independent Anthropic route for `provider:"anthropic"` models
 > (defaults to `https://api.anthropic.com` unless `ANTHROPIC_BASEURL` is set), or a per-model `baseUrl`
-> override the registry can hand a single catalog model (see `docs/ARCHITECTURE.md` §10). To keep
+> override the registry can hand a single catalog model. To keep
 > content from leaving the machine, rely on the **read-side sensitive-path gate** and confirm **every
 > route this deployment can select** points at infrastructure you control — pointing only the default
 > gateway env at a private endpoint is not sufficient. Verification method: `USAGE.md` §9.6.
@@ -268,12 +291,17 @@ One row per endpoint family (not exhaustive):
 | `POST /v1/tasks` · `/v1/tasks/stream` | Synchronous task execution; SSE variant streams typed `TaskEvent`s token by token |
 | `POST /v1/runs` · `GET /v1/runs/:id` | Asynchronous runs: immediate `202`, background execution, poll for status/result |
 | `GET /v1/runs/:id/events` | Replayable SSE (`Last-Event-ID` resume); any replica can serve any run |
-| `POST /v1/runs/:id/cancel` / `steer` / `interrupt` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | Run control verbs: cooperative cancel, mid-run steering, turn-level interrupt (with `text`: cut the in-flight turn + steer, run continues; bare body: halt — cut + stop, the run ends completed with `haltedByUser:true`, session resumable), context compaction, sub-agent steering/resume |
+| `POST /v1/runs/:id/cancel` / `steer` / `interrupt` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | Run control verbs: cooperative cancel, mid-run steering (`priority:"now"` cuts the in-flight turn first and the run continues with the message — the one door for "cut and say"), turn-level interrupt (empty body only: halt — cut + stop, the run ends completed with `haltedByUser:true`, session resumable; any field ⇒ 400), context compaction, sub-agent steering/resume |
 | `/v1/approvals` (list · decide · stream) | Human-in-the-loop approval center backed by durable checkpoints; decisions from any replica |
 | `/v1/sessions` (list · get · fork · init · settings · wake) | Session listing/search, audit inspection, fork, startup bundle |
 | `/v1/workflows` (list · get · stream · agents/:label/steer) | Deterministic workflow orchestration runs with live streams and per-agent steering |
 | `GET /v1/usage` · `GET /v1/policy` | Cumulative spend (when quotas are configured) and effective policy read surface |
 
+Every 4xx/5xx body is `{ error, errorCode, … }`: branch on `errorCode` only — `error` is the sentence for a human. The wording rules for the
+server's own words in that sentence (a closed set of internal words and internal ID shapes, per-code exceptions with their reasons, and the scope —
+values quoted into the sentence, such as a name you sent, are outside it) ship in the package as `docs/error-text-lexicon.json`, the same file the
+server's own wording check reads (its notes are in Chinese).
+
 ## Ecosystem
 
 | Repository | What it is |

package/README.zh-CN.md

@@ -29,7 +29,7 @@
   不进请求体、不进模型、不进沙箱。
 - **无状态设计。** 副本是 cattle:`docker run` 即起一个,挂在负载均衡后想开多少开多少。
   持久化状态 —— 会话、run、可重放事件日志、检查点、审批 —— 全在外部 SQL 存储
-  (任何 MySQL 协议数据库:MySQL/TiDB/MariaDB,或 PostgreSQL;每条池连接自钉会话隔离级(MySQL 协议腿 `REPEATABLE READ`、PostgreSQL `READ COMMITTED`)并回读复核,TiDB 上会话切到悲观事务模式、切不成或复核不符才拒启,见 docs/DEPLOY-PREREQS.md;单机场景另有文件持久化的
+  (任何 MySQL 协议数据库:MySQL/TiDB/MariaDB,或 PostgreSQL;每条池连接自钉会话隔离级(MySQL 协议腿 `REPEATABLE READ`、PostgreSQL `READ COMMITTED`)并回读复核,TiDB 上会话切到悲观事务模式、切不成或复核不符才拒启;单机场景另有文件持久化的
   `local` 模式)。任意副本都能服务任意 run 的事件流;任务可以在一个副本上挂起、在另一个副本上恢复。
 - **完整的服务端能力面**(可在 `GET /v1/capabilities` 发现):
   异步 run + 可重放 SSE、持久化检查点 + 人工审批(HITL)、会话与长期记忆、
@@ -111,7 +111,9 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   (npmjs 公开)· 镜像 = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
   (均 public,`:latest` 滚动 / `:<sha>` 钉版)。
 - **镜像不再发布**:容器镜像自 7.128.0 起不再发布,npm 包是唯一发布件;自建镜像步骤见 USAGE 9.13。
-- **作为库嵌入**(包根导出,如 `createHttpServer` + 自建 `StoreBackend`):`loadConfig()` 之后调
+- **作为库嵌入**(包根导出,如 `createHttpServer` + 自建 `StoreBackend`):先调一次包根的 `declareServerWithheldEnv()`(先于 `loadConfig()`、
+  任何执行环境与子进程)—— 把本进程的自有凭据变量名向引擎声明,宿主子进程在 `inheritEnv` 三词下都继承不到、名单型旋钮也交不出去;没声明的进程里 `loadConfig()` 抛,
+  拒句点名这一步(服务自己的入口第一步就这么做)。`loadConfig()` 之后调
   `composeExecutionLane(config, ctx)` —— HTTP 服务与 `run-local` 都这么做。7.104.0 起执行车道的几条拒启(host 车道上开
   `LEADER_ENABLED`、多租户姿态落在共享车道、device 车道缺耐久店)判在这一步,不在 `loadConfig()` 里;
   `assertExecutionLaneInvariants(config)` 是同一份判据,不做 `config.d/remote-exec.json` 覆写。
@@ -122,7 +124,8 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   `CATALOG_ENTRY_HEADER_NAMES`(+ 型 `CatalogEntryHeaderName`)—— 模型目录条目 `headers` 的闭集白名单及读每个名字的线路。两者都冻结,就是服务端自己判据用的那一只。
   壳要知道一台在跑的引擎服务的是哪张模型表、目录采纳了没有、起服路由判官怎么说,读 `GET /v1/models` 的 `modelPlane`
   (`{ servedTable: "env" | "catalog", catalog: "absent" | "adopted" | "refused", refusalCode?, gap? }`)—— 问 server,不猜:判官的输入是服务进程的事实。
-  只在引擎起来之后可答,没有起服前的预判口。
+  引擎起来之前要同一个答案:跑包里的 `dist/model-plane-probe.js`(子路径 `@sema-agent/server/model-plane-probe`;env / 工作目录 = 将要起的那只引擎的),
+  它跑起服的前两段到模型表定形即停、不监听,stdout 一行就是同一格 JSON(与起服第 2 段末的读数字节同;起服拉取超窗时是拉取落地之前的回落读数);起服会在这两段拒时退非 0,拒句与起服同一行。
   起服自己的路由判官在**目录应用之后**判,不在 `loadConfig()` 里:自建装配在自己的配置源应用之后调一次包根的 `judgeServedModelRoute(config, { envTableIsPlaceholder })`(与 `composeExecutionLane` 同形)。
 - **随包二进制**:包内带两个 `bin` —— `run-local`(单机本地 runner)与
   `sema-up`(部署引导脚本)。
@@ -162,7 +165,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | 变量 | 默认 | 说明 |
 |------|------|------|
 | `PORT` | `8090` | HTTP 监听端口。`0` = 让 OS 分一个:`listening` 日志行(stdout,info 级)与 `/health.port` 报实际绑到的口 |
-| `BIND_HOST`(别名 `HOST`) | 见说明 | 监听地址。显式 `BIND_HOST` **恒生效**。缺省:写面无鉴权时(`ALLOW_UNAUTHED_WRITES=true` **且**未配任何 service token)= `127.0.0.1`,否则全接口——配了 token 的部署不受影响。自 3.15.0 起 `HOST` 别名**不再完全等效**:shell 常把 `HOST` 设成机器名而 operator 并不知情,于是上述收窄条件成立时,收窄压过继承来的 `HOST`(告警事件 `bind_host_from_HOST_env_overridden`)。要暴露写面,显式设 `BIND_HOST`,或配一个 service token。 |
+| `BIND_HOST`(别名 `HOST`) | 见说明 | 监听地址。显式 `BIND_HOST` **恒生效**。缺省:写面无鉴权时(`ALLOW_UNAUTHED_WRITES=true` **且**未配任何 service token)= `127.0.0.1`,否则全接口——配了 token 的部署不受影响。自 3.15.0 起 `HOST` 别名**不再完全等效**:shell 常把 `HOST` 设成机器名而 operator 并不知情,于是上述收窄条件成立时,收窄压过继承来的 `HOST`(告警事件 `bind_host_from_HOST_env_overridden`)。要暴露写面,配一个 service token —— 单用户部署(`REQUIRE_PRINCIPAL` 未开)上写面无鉴权时显式非回环 `BIND_HOST` 起服拒(不变量 `single-user-anonymous-boundary`);多租部署上显式 `BIND_HOST` 照旧暴露。 |
 | `MODEL_GATEWAY_BASEURL` | **无缺省** | OpenAI 兼容网关地址(不带 `/chat/completions`)。**无出厂缺省**:每一条落 openai 兼容腿的路由都必须解析到显式端点 —— 目录条目自己的 `baseUrl`,或本键 —— 否则拒启,拒因点名模型并给出本机写法(`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`)。anthropic 单路由部署可不设。只设 `MODEL_GATEWAY_FALLBACK_URLS` 不设本键同拒 |
 | `MODEL_ID` | **必填(目录给出缺省时可省)** | 缺省模型 id ——**3.0.0 起无出厂缺省**。7.101.0 起判据挪到目录应用**之后**:`MODEL_ID` **或**目录里一条可用的缺省(`config.d/models.json` / 配置控制面)任一在场即可;两者皆无 = 拒启(码 `config.default_model_missing`,指路二选一)。目录一旦被采纳就整张换掉 env 表,`MODEL_ID` 此时不服务:起服不拒(目录条目自带 `baseUrl` 时没有网关也能起),并说一行 `config_env_set_but_ineffective` 点名在服务的目录缺省(目录第一次被采纳的那一拍恰好说一次 —— 启动时,或目录晚到 / 刷新时才第一次采纳)。旧的烤死缺省是内网模型名,外部部署必炸且炸在离根因最远处:网关 `400` + 标题 hook 连环告警 |
 | `MODEL_API_KEY` | — | 网关 key(可选)。只与 `MODEL_GATEWAY_BASEURL` 配对:没设网关时不装载、不发往任何路由 |
@@ -170,7 +173,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `DB_BACKEND` | `local`* | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB —— TiDB 走这个值,**没有** `tidb` 别名,写它启动即拒)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)/ `memory`(显式纯内存)。显式设置 `mysql`/`pg` 时 session 自动转 durable。*单租户裸 boot 缺省 `local`;`REQUIRE_PRINCIPAL=true` 的多租户裸 boot 缺省 `memory`(local 与多租户互斥) |
 | `SESSION_BACKEND` | `memory`* | `memory` / `mysql`(durable 会话中心)/ `auto`。*显式 `DB_BACKEND=mysql/pg` 时默认转 durable。(`tidb` 是**退役公名**,设了拒启;7.57.0 起 `GET /v1/config/catalog` 的回显也归一成公名 `mysql`,不再吐内部标签 `tidb`) |
 | `REMOTE_EXEC` | (必填) | 执行通道:`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb` / `device` / `none`(`none` = 不给智能体的工具执行环境:手带工具不挂,其余工具照常执行)。**每个部署都要声明**(`CONFIG_PROVIDER=local` 形下 `config.d/remote-exec.json` 也算);没声明 ⇒ **启动即拒**,拒句一行给出修法(7.147.0 之前非 local 未设的写 `REMOTE_EXEC=none`,`CONFIG_PROVIDER=local` 未设的写 `REMOTE_EXEC=host`)。点名了通道但必需 env 不全(如 `e2b` 缺 `E2B_API_KEY`;未设、空串或只含空白一律按缺,所有通道、所有必需键同判)或值不在闭集内 ⇒ **启动即拒**——不静默降级到别的通道(fail-closed)。`k8s` 必需 `K8S_SANDBOX_IMAGE` **和** `K8S_NAMESPACE` —— 沙箱 pod 所在的命名空间没有内置缺省(部署自己声明;缺席、空串或只含空白 ⇒ 启动即拒;随包 chart 取 `sandbox.namespace` 显式设)。`CONFIG_PROVIDER=local` 下 `config.d/remote-exec.json` **压过**本 env(刻意:单机形的真源是那份文件);7.57.0 起这次抢占**响亮**——`remote_exec_lane_preempted_by_file` 点名被抢占的 lane、最终生效的 lane,以及它是不是一次**隔离降级**(隔离 lane 被换成不隔离的);文件点了尚未接线的隔离 lane(`e2b`/`k8s`/`ssh`/`adb`)时 env 腿照旧生效并说明 |
-| `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | 未设 | **SSH 通道主机密钥校验**(仅 `REMOTE_EXEC=ssh`)。前者 = 主机公钥的 SHA256 base64 指纹(`SHA256:` 前缀与 `=` 填充都可选);后者 = `known_hosts` 文件路径,按 `host` / `[host]:port` **逐字**匹配行。**任一在场 ⇒ 严格校验,不符即拒连**(拒因带两半指纹 + `ssh-keyscan` 取指纹指路一行);两只同时在场 ⇒ 合取(都要过)。**两只全缺席 ⇒ 每连接一条响亮 warn(`ssh_host_key_unverified`,中间人风险)后照常连** —— 批量部署通道的既定姿态,已登记为 P-DEBT fail-open(`docs/FAIL-OPEN-CENSUS.md`)。指纹拼错 / `known_hosts` 路径读不到 ⇒ **启动即拒**。`known_hosts` 里**刻意不支持**:hashed(`\|1\|…`)行、通配符 pattern、`@cert-authority` —— 一律跳过,于是只有这些条目的主机会被**拒连**(`@revoked` 照常生效,且无论写在哪一行都优先于普通匹配行) |
+| `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | 未设 | **SSH 通道主机密钥校验**(仅 `REMOTE_EXEC=ssh`)。前者 = 主机公钥的 SHA256 base64 指纹(`SHA256:` 前缀与 `=` 填充都可选);后者 = `known_hosts` 文件路径,按 `host` / `[host]:port` **逐字**匹配行。**任一在场 ⇒ 严格校验,不符即拒连**(拒因带两半指纹 + `ssh-keyscan` 取指纹指路一行);两只同时在场 ⇒ 合取(都要过)。**两只全缺席 ⇒ 每连接一条响亮 warn(`ssh_host_key_unverified`,中间人风险)后照常连** —— 批量部署通道的既定姿态,已登记为 P-DEBT fail-open(tag `server.exec-lane.ssh-host-key-unverified`,计入 `fail_open_total`)。指纹拼错 / `known_hosts` 路径读不到 ⇒ **启动即拒**。`known_hosts` 里**刻意不支持**:hashed(`\|1\|…`)行、通配符 pattern、`@cert-authority` —— 一律跳过,于是只有这些条目的主机会被**拒连**(`@revoked` 照常生效,且无论写在哪一行都优先于普通匹配行) |
 | `HOOKS_TIMEOUT_MS` | 未设(600000) | 请求 `settings.hooks` 那张扩展注册**每个 handler** 的时间预算(一个事件跑一遍本请求的钩子条目)。未设 = 600000 ms —— 这是引擎对这张注册的 `budgetMs`(每个 handler 自己的时间:一个事件跑一遍本请求的钩子条目);预算到、或任务被取消,这个 handler 里还在跑的命令钩子会被叫停(SIGTERM → 短宽限 → SIGKILL),不再跑到自己的 `timeout`;不用引擎给扩展的缺省(10 s)。`0` **按字面生效**(零预算)。本服务自己的两张观察注册(拒绝计量 / 工具追踪)不读它。非整数 / 负数 / 超 `setTimeout` 上限(2147483647)⇒ **启动即拒** |
 | `MODS_ROOT` / `MODS_PACKAGES` | 未设 | **部署座装载的 mod 包**。`MODS_PACKAGES` = JSON 数组,每项 `{ "name", "dir", "tier", "options"? }`:`name` = 包自己的名(`.claude-plugin/plugin.json` 的 `name`,逐字同);`dir` 绝对路径,真实路径须严格落在 `MODS_ROOT`(绝对路径)的真实路径之下(按路径分量判 —— 符号链接出根、`/mods-evil` 这类前缀相似的兄弟目录、`..` 遍历、根本身都拒启);`tier` 必填(`prepend` / `user` / `append`,宿主声明,包不自报);`options` 原样交包的 `register`。包里的文件只有引擎的读包者一只读者,本服务不读。每只声明的包起服装一次、整列交引擎准入:任一失败(声明坏、越根、读包者拒包、名不同、准入拒)⇒ **拒启**,一行拒句点名哪一席或哪只包 —— 本服务自己写的句子不回显声明的值(路径、`options`);读包者 / 准入交回的话原样透传(凭据形换记号、剥控制字符),其中可能点名包目录。装上了 ⇒ 每包一行 `mods_package_loaded` 日志(带引擎读包者交回的 `digest` —— 装载件三件字节摘要,认得出装的是哪几份字节,非完整性凭据:模块自己再加载的代码不在其内)、`/health.mods.deploymentPackages` 与能力位 `modsDeploymentPackages: true`;未设(或 `[]`)⇒ 两面与没有这两根旋钮时逐字节同。包是**受信的部署代码** —— 在本进程里跑、可触全部租户与进程凭据,准入不是沙箱 —— 只从你控制的只读物料树装。包若在 `PreToolUse` 上答 `allow`(可带 `updatedInput`),引擎仍按最终参数裁决,运维旋钮要问或要拒的(`APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` / `MANUAL_MODE_SHELL_GATE=always` / `governance.commandPolicy` 的问档与拒档等)与引擎强制的问句不因它改变,但**未被强制的**缺省审批问句它能清掉 —— 装包就是把这一类问句的决定权交给包作者;要某类调用无论包怎么答都问人,用这些旋钮声明。改声明或换包要重启(没有自动重启信号)。配置目录对 `MODS_PACKAGES` 只回在场位与长度。`options` 不是凭据通道:本服务不替包扣凭据 —— `MODS_PACKAGES` 本身与包自己读的任何变量,在宿主车道 `inheritEnv: "all"` 下都会被模型的子进程继承(只有本服务声明的自有凭据被扣),包要的凭据请经宿主车道模型 shell 读不到的渠道交付 |
 | `CONFIG_PROVIDER` | 未设 | 配置来源:`local`(单机文件 `config.d/`)/ `remote`(`SEMA_WEB_ADMIN_URL` 那只 registry 控制面 —— 写了 `remote` 而没设这个地址拒启)。未设 = 设了 `SEMA_WEB_ADMIN_URL` 即中心,否则纯 env。闭集、逐字比较(7.104.0 起):其余任何值(大小写不同、带首尾空白)拒启;空串 = 未设 |
@@ -182,6 +185,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `MODEL_FIRST_BYTE_TIMEOUT_MS` | 未设(core 缺省) | `fetch()` → 响应头的等待,毫秒(7.103.0 起;取代退役的 `MODEL_CONNECT_TIMEOUT_MS`,设了旧键**拒启** —— core 7.33.0 起建连(TCP + TLS)是传输层自己的钟)。未设 = 不传键,core 缺省当家(另加按请求体大小的上传宽限,到点 core 自有一次加宽重试)。`0` = 该段不设引擎钟、传输层的响应头 / 响应体钟也关(TCP + TLS 建连仍归传输层自己的钟)。须为 `[0, 2147483647]` 内整数,其余拒启。配了 `MODEL_GATEWAY_FALLBACK_URLS` 时每条网关路由同样是首窗 + 一次加宽重试之后才切备(server 不铸 core `firstByteRetries`:调用方可按请求关 failover,那一次身后没有备)。failover 拓扑须显式设:未设时接了连接却不回头的主网关要等 core 的首字节 lane(缺省窗 + 加宽重试)走完才切备,预算更短的调用(code-review council 镜头 180 s)在备网关被尝试之前就被取消;这类部署起服时打一条 `failover_first_byte_lane` warn |
 | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `600000` | 首 token 超时(开流不吐字的唯一看门狗;`0` = 该段不设引擎钟、传输层响应体钟也关。7.71.0 起由 `120000` 提高 —— 自托管后端长 prefill 下首字合理地就要等几分钟;要旧姿态显式设 `120000`) |
 | `MODEL_IDLE_TIMEOUT_MS` | `300000` | 流中 idle 超时(`0` = 该段不设引擎钟、传输层响应体钟也关) |
+| `REAP_RUN_STALE_SEC` | `120` | run 判活窗(秒):收割器(每 `REAP_INTERVAL_SEC`,缺省 `60`)把行 `REAP_RUN_STALE_SEC` 内没被碰过的 `running` run 判死;停-迁-起的一次性迁移也用这同一个窗判「更早版本的副本是否还在服务」(窗内库里还有 run 在心跳 ⇒ 起服拒)。**必须大于 30 s 的心跳周期** —— 设成 30 或更小起服拒(收割器会和仍在正常心跳的 run 抢) |
 | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`(结构化 JSON 日志) |
 
 **布尔旋钮收 `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`**(大小写不敏感;词表自 7.16.0 起放宽)。
@@ -202,6 +206,10 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`、两车道优先级、工具层错误形)
 见 `USAGE.md` §9.5。
 
+单机部署(`CONFIG_PROVIDER=local`)在 `config.d/mcp.json` 里挂外置 MCP 服务器:条目与配置中心的 `mcp` 域同形,文件里只存环境变量的**名**
+(`envRefs` / `headerRefs`),值从本进程自己的环境里读、从不来自文件。这份文件是可执行配置,所以只从受信目录读(每次读之前判属主与模式;Windows 上只判得了目录结构)。
+文件放哪、条目有哪些键、凭据的边界、匿名(不带 principal)调用方的姿态、以及它与请求体 `mcpServers` 的关系,见 `USAGE.md` §9.5i-ter。
+
 ## 安全与隐私提示
 
 > 🔴 **trace 脱敏 ≠ 出站控制。** trace 脱敏(你在账本 / SSE / turns / 审批预览里看到的 `«redacted»`
@@ -210,8 +218,7 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 > `/v1/sessions/:id/sync/*`(逐字 durable log 出入)——这两面是**原形**——**发往「该 run 实际选中的模型路由」的请求体是工具结果原文**。
 > 这条路由不止 `MODEL_GATEWAY_BASEURL` 一根:还可能是备用网关列表(`MODEL_GATEWAY_FALLBACK_URLS`)、
 > `provider:"anthropic"` 模型的独立直连路由(缺省根 `https://api.anthropic.com`,除非显式配
-> `ANTHROPIC_BASEURL`)、或 web-admin 可对单个目录模型下发的 per-model `baseUrl` 覆盖(见
-> `docs/ARCHITECTURE.md` §10)。要让内容不出机器,靠**读侧敏感路径门**,并核对**本部署会被选中的每一条
+> `ANTHROPIC_BASEURL`)、或 web-admin 可对单个目录模型下发的 per-model `baseUrl` 覆盖。要让内容不出机器,靠**读侧敏感路径门**,并核对**本部署会被选中的每一条
 > 路由**都指向自己控制的基础设施——只把默认网关 env 指到私有端点是不够的。验法见 `USAGE.md` §9.6。
 
 ## HTTP API 概览
@@ -227,12 +234,15 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 | `POST /v1/tasks` · `/v1/tasks/stream` | 同步任务执行;SSE 变体逐 token 流式输出类型化 `TaskEvent` |
 | `POST /v1/runs` · `GET /v1/runs/:id` | 异步 run:立即 `202`,后台续跑,轮询状态/结果 |
 | `GET /v1/runs/:id/events` | 可重放 SSE(`Last-Event-ID` 续订);任意副本可服务任意 run |
-| `POST /v1/runs/:id/cancel` / `steer` / `interrupt` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | run 控制动词:协作式取消、运行中转向、turn 级中断(切当前在飞 turn,run 继续)、上下文压缩、子智能体转向/恢复 |
+| `POST /v1/runs/:id/cancel` / `steer` / `interrupt` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | run 控制动词:协作式取消、运行中转向(`priority:"now"` 先切断在飞 turn、run 带这句话继续 ——「切断并说话」只有这一扇门)、turn 级中断(只收空体:halt,切断 + 停,run 以 `haltedByUser:true` 完成、会话可续;带任何字段 ⇒ 400)、上下文压缩、子智能体转向/恢复 |
 | `/v1/approvals`(list · decide · stream) | 人工审批中心,底座是持久化检查点;任意副本都能批复 |
 | `/v1/sessions`(list · get · fork · init · settings · wake) | 会话列表/检索、审计回溯、fork、启动包 |
 | `/v1/workflows`(list · get · stream · agents/:label/steer) | 确定性 workflow 编排 run,带实时流与逐 agent 转向 |
 | `GET /v1/usage` · `GET /v1/policy` | 累计花费(配置配额时)与生效策略只读面 |
 
+每个 4xx/5xx 响应体都是 `{ error, errorCode, … }`:程序只按 `errorCode` 分支,`error` 是给人读的那句话。那句话里本服务自己写的部分有用词约束(内部词闭集与内部编号形、
+按错误码逐族的放行与理由,以及射程 —— 句中插进来的值,如你送来的名字,不在约束里),随包在 `docs/error-text-lexicon.json` —— 本服务自己的文案检查读的就是这一份。
+
 ## 生态导航
 
 | 仓库 | 是什么 |