@sema-agent/server 7.148.0 → 7.150.0

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -156,6 +156,10 @@ not above `challenge.protocolVersion` into `hello.protocolVersion` — the same
 only the `errorCode` words of that revision (the revision table in §2.1). Nothing is renegotiated after `hello`:
 the revision you declared is the contract for the whole connection. If the highest revision you implement is below
 `DEVICE_MIN_PROTOCOL_VERSION`, the server answers `helloReject: protocol_version_unsupported` (§1.4).
+Revisions are cumulative on the executor's side: an executor that implements revision *N* implements every revision
+below it, so against an older server it declares that server's revision (a revision-5 executor serves a revision-4
+server, whose paths arrive folded — a subset of what revision 5 sends). `DEVICE_MIN_PROTOCOL_VERSION` is the lowest
+revision **this server** accepts, not a floor for your own negotiation.
 
 ### 1.3 The `hello` signature (byte-exact — do not improvise)
 
@@ -247,7 +251,7 @@ sign exactly these bytes with the device's Ed25519 private key.
 |---|---|---|
 | `auth_failed` | deliberately ambiguous: unknown device id, malformed id, malformed epoch, bad signature, or the server's device registry was unreachable | do **not** hammer: back off exponentially. If it never clears, the enrollment is gone — re-enroll. The server will not tell you which of these it was (anti-enumeration) |
 | `revoked` | this device has been revoked. Terminal | stop reconnecting, delete the private key, ask the user to re-enroll (it yields a new `deviceId`) |
-| `protocol_version_unsupported` | your `protocolVersion` is outside the range this server accepts; the frame carries `minProtocolVersion` | upgrade the executor. Never retry-with-a-different-version in a loop |
+| `protocol_version_unsupported` | your `protocolVersion` is outside the range this server accepts; the frame carries `minProtocolVersion` and a one-line `message` that names your revision, the range and — below the floor — the change at the floor revision (§2.1) | upgrade the executor (`message` is fit to show as is). Never retry-with-a-different-version in a loop |
 | `draining` | this replica is shutting down or upgrading and takes no new connections | reconnect with backoff; a replacement replica will accept you |
 | `already_connected` | **the connection lease for this `deviceId` is not available right now**: a previous connection is still considered fresh, the stored lease has not expired yet, or the deployment forbids takeover | retry with bounded backoff — the lease expires on its own (deployment default 45 s, and a previous socket is judged stale after ~3 missed heartbeats). This code does **not** prove another process is alive: a half-open network drop can make your *own* previous connection look fresh. Do not exit permanently on it; do hold a machine-local single-instance lock so you are never racing yourself |
 
@@ -341,8 +345,8 @@ base64 inside JSON fields.
 | Constant | Value | Meaning |
 |---|---|---|
 | `DEVICE_WS_PATH` | `/v1/device/ws` | the upgrade path (prefer the `wsPath` from `/v1/capabilities`) |
-| `DEVICE_PROTOCOL_VERSION` | `4` | the protocol revision this server speaks (the highest it accepts) |
-| `DEVICE_MIN_PROTOCOL_VERSION` | `1` | the lowest revision it accepts; below it (or above the highest), a loud `helloReject` — never a silent downgrade |
+| `DEVICE_PROTOCOL_VERSION` | `5` | the protocol revision this server speaks (the highest it accepts) |
+| `DEVICE_MIN_PROTOCOL_VERSION` | `5` | the lowest revision it accepts (the revision table says why); below it (or above the highest), a loud `helloReject` — never a silent downgrade |
 | `DEVICE_HELLO_DOMAIN_TAG` | `sema.device.hello.v1` | the handshake signature domain tag (§1.3) |
 
 <!-- closed-set: DEVICE_WS_LIMITS -->
@@ -357,25 +361,36 @@ base64 inside JSON fields.
 Note the asymmetry: the transport cap is 1 MiB, and the 4096-byte pre-auth cap is applied **after** the
 frame has been reassembled. Keep `hello` small; it is not a place for long `supports` prose.
 
+`maxFrameBytes` binds the server too: every frame it sends is measured after serialization and is never over the
+cap. An instruction whose frame would be over it is refused before dispatch (you never receive it), and `payload`
+chunks are sliced so that a chunk frame, base64 and envelope included, fits. You can therefore cap the frames you
+accept at `maxFrameBytes`.
+
 #### Protocol revisions and the `errorCode` set
 
 The protocol revision is the only thing an executor can read *before* it sends `hello` (the `challenge` frame
-carries it), so the set of `errorCode` words the server accepts from you is a function of the revision, not a
-separate list. The table gives, per revision, the words **added** at that revision; the set at revision *N* is
-the union of the rows up to *N*, and the full set at the current revision is the §3.3 table.
+carries it), so everything you must know to be correct on this server is a function of the revision, not a
+separate list: the set of `errorCode` words the server accepts from you, and what the frames it sends you mean.
+The table gives, per revision, the words **added** at that revision and any other change made at it; the word set
+at revision *N* is the union of the rows up to *N*, and the full set at the current revision is the §3.3 table.
 
 <!-- closed-set: DEVICE_OUTCOME_ERROR_CODES_BY_REVISION -->
 
-| Revision | `errorCode` words added at this revision |
-|---|---|
-| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` |
-| `2` | `liveness_no_output` |
-| `3` | `name_too_long` |
-| `4` | `symlink_loop` |
-
-Rules: adding a frame or a field is additive and does not raise the revision; adding a word to a closed set the
-server *accepts from you* (today: the `errorCode` set) raises `DEVICE_PROTOCOL_VERSION` and adds a row here; a
-released row never changes. Declare a revision as §1.2 says and send only the words of that revision: an executor
+| Revision | `errorCode` words added at this revision | Other change at this revision |
+|---|---|---|
+| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` | — |
+| `2` | `liveness_no_output` | — |
+| `3` | `name_too_long` | — |
+| `4` | `symlink_loop` | — |
+| `5` | — | every path an instruction carries (`args.path`, `args.paths`, `cwd`) arrives **unfolded** (since server 7.150.0): absolute as written, or anchored at the session's working directory, with `.` / `..` / empty segments kept — the server anchors and never folds. Resolve it as your filesystem does and judge containment on where it resolves (§3.1, §6 item 6). An executor written for revision 4 or below expects folded paths, so this is also the lowest revision the server accepts |
+
+Rules: adding a frame or a field is additive and does not raise the revision. Every other change
+raises `DEVICE_PROTOCOL_VERSION` and adds a row here — a word added to a closed set the server *accepts from you*
+(today: the `errorCode` set; second column), or a **semantic change**, a change in what a frame the server sends you
+means (third column): a semantic change raises the revision. A released row never changes. When an executor written for
+an older revision cannot honor the change, the same release raises `DEVICE_MIN_PROTOCOL_VERSION` to the new
+revision, so such an executor is refused once at `hello` (§1.4) instead of failing call by call.
+Declare a revision as §1.2 says and send only the words of that revision: an executor
 that declared revision 1 never sends `liveness_no_output` (the server does not police this per connection — it
 decodes every connection against the current revision's full set — but a word above your declared revision is outside
 your contract). The same sets are importable:
@@ -407,7 +422,7 @@ zeros, a plus sign, whitespace or a float form are rejected as malformed.
 |---|---|---|
 | `challenge` | `nonce` string, `protocolVersion` int | first frame the server sends, immediately on open |
 | `helloAck` | `ok`, `heartbeatIntervalMs`, `maxInflight`, `gen`, `pendingInstructions`, `chunkWatermarks`, `reconnectGraceMs`, `cancelGraceMs`, `chunkGapTimeoutMs`, `executionCeilingGraceMs` | §1.5 |
-| `helloReject` | `code`, `minProtocolVersion?` | §1.4; the socket closes right after |
+| `helloReject` | `code`, `minProtocolVersion?`, `message?` | §1.4; `minProtocolVersion` and `message` appear on `protocol_version_unsupported` only; the socket closes right after |
 | `instruction` | `gen`, `instructionId`, `rootSessionId`, `issuedSeq` int, `kind`, `args`, `cwd?`, `shellEnv?`, `timeoutMs` int | one unit of work (§3). `cwd` appears on `exec` / `execStream` only, and always there (§3.1) |
 | `payload` | `gen`, `instructionId`, `part` (`begin` \| `chunk` \| `commit`), `offset?`, `dataB64?`, `totalLen?`, `sha256?` | the bytes for a write-family instruction (§3.4) |
 | `cancel` | `gen`, `instructionId` | idempotent; answer with a terminal `result` (§5 R11) |
@@ -480,11 +495,19 @@ silently forgiven: it becomes a gap or a missing terminal, and the instruction e
 
 ### 3.1 The closed set, its arguments, and the success outcome each one owes
 
-Every `path` in `args` arrives **already absolute and POSIX-normalized** — the server resolved it against
-the session's working directory before sending. `exec` and `execStream` additionally carry `cwd`, which is
-**always present and always absolute**: run the command in exactly that directory. There is no implicit
-base to fall back to, so an executor needs no branch for a missing or relative `cwd`. Every other kind
-carries no `cwd` — its paths are already absolute.
+Every `path` in `args` arrives **already absolute** — the server anchored a relative one at the session's
+working directory before sending — and **as written: a `..` or `.` segment, or an empty one, is never folded**
+(revision 5, §2.1). Hand it to your
+filesystem as it is. The kernel resolves `..` component by component, so a `..` that follows a symbolic link
+goes where the link leads (`<root>/bridge/../next` with `bridge -> elsewhere/sub` is `<root>/elsewhere/next`,
+not `<root>/next`) — and that is the file the engine's gates judged: they asked you about this same spelling
+(`exists` / `canonicalPath` / `fileInfo` / `readLink`). `exec` and `execStream` additionally carry `cwd`, which is
+**always present and always absolute** (unfolded the same way): run the command in exactly that directory.
+There is no implicit base to fall back to, so an executor needs no branch for a missing or relative `cwd`.
+Every other kind carries no `cwd` — its paths are already absolute. The paths the server reports back are its
+own spellings, not the ones you return: `fileInfo` reports the path it asked; `listDir` reads only the leaf name
+(last segment) of each entry's `WireFileInfo.path` and reports the entry as `<asked path>/<leaf>`, so a listed
+entry can be asked again as written.
 
 <!-- closed-set: DEVICE_INSTRUCTION_KINDS -->
 
@@ -567,8 +590,8 @@ a moment ago. If you omit `created`, the consumer reports the weaker of the two
 
 `message` is required on the failure arm and is shown to the model — make it specific.
 
-This is the full set at the current revision (`3`); the revision table in §2.1 says which revision each word arrived
-with, and an executor sends only the words of the revision it declared (§1.2).
+This is the full set at the current revision (`DEVICE_PROTOCOL_VERSION`, §2.1); the revision table in §2.1 says which revision
+each word arrived with, and an executor sends only the words of the revision it declared (§1.2).
 
 <!-- closed-set: DEVICE_OUTCOME_ERROR_CODES -->
 
@@ -972,11 +995,16 @@ These two are a real distinction to the caller: `not_started` is safely retryabl
    *Honest boundary*: this is a decision-and-audit property, not enforcement against a compromised
    machine. The protocol assumes an honest executor; it protects against races and mistakes, not against
    an executor that lies.
-6. **Respect `workspaceRoot` and resolve nothing yourself.** Paths arrive absolute and normalized; the
-   server has already resolved them against the session's working directory, falling back to the
-   `workspaceRoot` you registered. Do not re-interpret them, do not expand `~`, do not follow a different
-   base. You **may** enforce your own containment policy on top (refusing paths outside a root you are
-   willing to serve) — if you do, refuse with `permission_denied`. What you must never do is silently
+6. **Respect `workspaceRoot` and resolve nothing yourself.** Paths arrive absolute and unfolded; the
+   server has already anchored them at the session's working directory, falling back to the
+   `workspaceRoot` you registered. Do not re-interpret them: never fold a `..` lexically (with a link before
+   it, the folded spelling names a different file than the one the gates judged), do not expand `~`, do not
+   follow a different base. You **may** enforce your own containment policy on top (refusing paths outside a
+   root you are willing to serve) — judge it on where the path resolves (the real path of its existing part),
+   never on a string prefix of the spelling (`<root>/../etc` starts with `<root>/`); if you refuse, refuse
+   with `permission_denied`. Negative control: with `bridge` a link to `/opt/x/sub` (outside the root),
+   `<root>/bridge/../next` resolves to `/opt/x/next` — the link carried the `..` out of the root, so the
+   answer is `permission_denied` (not `not_found`, not success). What you must never do is silently
    redirect a path to somewhere else: a write that lands in a different place than the caller adjudicated
    is the exact failure this lane is built to prevent.
 7. **Do not cache and replay results.** No answer may be served from a cache keyed by command text, path

package/docs/error-text-lexicon.json

@@ -0,0 +1,317 @@
+{
+  "description": [
+    "错误响应体 `{ error, errorCode, … }` 里 `error` 文案的用词约束。`error` 是给人读的一句话,`errorCode` 才是机器面(程序按码分支,不按文案);这份词表约束的是文案怎么写,不是协议。本服务自己的错误文案词域检查读的就是这一份文件,没有第二份。",
+    "射程:约束的是本服务自己写的那部分句子。句中插进来的值 —— 调用方送来的名字 / 路径 / id、上游或引擎的原话 —— 原样带出,不在这份词表的约束里;按词表判一句 `error` 时先把这些插入值剔掉(例:请求点名了一个叫 `council` 的模型而目录里没有,拒句里引着的这个名字不算命中)。",
+    "`words`:内部词闭集 —— 引擎 / 本服务内部机件的名字,判据是「调用方在 wire 上拿不到这个名字」。`error` 文案里不出现其中任何一个词:把 `words.match.pattern` 里的 `{word}` 换成词、按 `words.match.flags` 编译成正则来匹配。式子两头的 `\\b` 是承重的:wire 字段名的拼法(如 `checkpointToken`)不是整词,不命中;连字符是词边界(`workflow-agent` 里的 `workflow` 命中)。屈折形逐个列成成员,不做词干化(`park` 与 `parked` 是两件事)。",
+    "`idShapes`:内部编号形。`error` 文案里不出现任何一形:`shapes[].pattern` 按 `idShapes.flags` 编译成正则来匹配。",
+    "`pardons`:逐族放行 —— 唯一的例外来源。一条放行按族 `family` 生效(`<HTTP 状态码>:<errorCode>`);带 `where` 时只放行该族里含这个子串的那一句,不带时该族只有一句文案;`words` 是那一句上放行的词(都是 `words` 闭集的成员);`why` 说这个词在这一族上是调用方自己看得见、拿得到、写得出的哪一样东西(路径段 / wire 字段 / 错误码的拼写 / 旋钮名 / 状态词)。不在放行里的命中都不该出现在 `error` 文案里。"
+  ],
+  "words": {
+    "match": {
+      "pattern": "\\b{word}\\b",
+      "flags": "i"
+    },
+    "groups": [
+      {
+        "forms": [
+          "workflow",
+          "workflows"
+        ],
+        "why": "引擎内部的 workflow 执行通道;产品义(`/v1/workflows` 资源、`Workflow` 工具)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "child",
+          "children"
+        ],
+        "why": "引擎的父子代角色名;产品义(调用方自己在一条 run 下起的后台 agent)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "host",
+          "hosts"
+        ],
+        "why": "引擎的宿主会话角色(「宿主会话 / 宿主的下一跑」);产品义(worker 所在机器的文件系统路径)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "park",
+          "parks",
+          "parking"
+        ],
+        "why": "挂起对象的名词 / 动词形 —— wire 上只有形容词 `parked`,没有这三个形;错误码自己拼着它的族按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "parked"
+        ],
+        "why": "wire 状态词(`GET /v1/agents/roster` 的 `?status=` 闭集成员);在待决 / decide 面上是产品词,但仍逐族放行、不整词豁免,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "lane",
+          "lanes"
+        ],
+        "why": "本服务对「执行通道 / 部署形」的内部自称;错误码自己拼着它的族按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "leader",
+          "leaders"
+        ],
+        "why": "编排席的内部名;产品义(`POST /v1/leader` 端点)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "subagent",
+          "subagents"
+        ],
+        "why": "引擎内部的角色名;产品义(`/v1/runs/:id/subagents` 路径段)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "council",
+          "councils"
+        ],
+        "why": "复审席的内部名 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "checkpoint",
+          "checkpoints"
+        ],
+        "why": "挂起点对象的内部名;产品义(错误码目录里在册的部署件名)按族放行,见 `pardons`。"
+      },
+      {
+        "forms": [
+          "leg",
+          "legs"
+        ],
+        "why": "本服务对「一段执行」的内部自称 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "seam",
+          "seams"
+        ],
+        "why": "本服务对「可替换接缝」的内部自称 —— wire 上没有这个拼写。"
+      },
+      {
+        "forms": [
+          "twin",
+          "twins"
+        ],
+        "why": "本服务对「另一后端的孪生实现」的内部自称 —— wire 上没有这个拼写。"
+      }
+    ]
+  },
+  "idShapes": {
+    "flags": "",
+    "shapes": [
+      {
+        "pattern": "\\bS-\\d+",
+        "label": "内部工单号(S-nnn)"
+      },
+      {
+        "pattern": "\\bA-\\d+(?:\\.\\d+)*",
+        "label": "内部审计号(A-nnn.n)"
+      },
+      {
+        "pattern": "\\bB-\\d+",
+        "label": "内部缺陷号(B-nnn)"
+      },
+      {
+        "pattern": "\\bC-R\\d+",
+        "label": "内部裁定号(C-Rnn)"
+      },
+      {
+        "pattern": "\\bdesign/\\d+",
+        "label": "内部设计稿号(design/nnn)"
+      },
+      {
+        "pattern": "\\[\\d{3,4}\\]",
+        "label": "内部讨论帖号([nnnn])"
+      },
+      {
+        "pattern": "车[A-Z]{1,2}\\b",
+        "label": "内部作业名(车XX)"
+      },
+      {
+        "pattern": "\\bwf_[0-9a-f]{6,}",
+        "label": "内部扫描号(wf_xxxxxxxx)"
+      }
+    ]
+  },
+  "pardons": [
+    {
+      "family": "400:request.field_invalid",
+      "where": "host path",
+      "words": [
+        "host"
+      ],
+      "why": "「absolute host path」限定的是调用方自己在 `cwd` / `additionalDirectories` / `additionalReadDirectories` 里送的那些路径 —— `host` 在这里是「worker 跑在哪台机器上」的产品义,不是引擎里的 HOST 会话角色。"
+    },
+    {
+      "family": "404:not_found.workflow",
+      "words": [
+        "workflow"
+      ],
+      "why": "`/v1/workflows/:id` 面自己的 404 —— 调用方 URL 里写的就是这个资源名,错误码 `not_found.workflow` 也逐字拼着它。"
+    },
+    {
+      "family": "400:request.path_malformed",
+      "where": "malformed workflow path",
+      "words": [
+        "workflow"
+      ],
+      "why": "路径段名(`/v1/workflows/…`),调用方自己写进 URL 的那一段。"
+    },
+    {
+      "family": "501:capability.workflow_store_required",
+      "where": "workflow",
+      "words": [
+        "workflow"
+      ],
+      "why": "两句都点名调用方够得着的东西:`GET /v1/workflows/:id/journal` 这张脸,以及部署旋钮 `WORKFLOW_RUN_STORE`(它自己的拼写里就有 WORKFLOW)。"
+    },
+    {
+      "family": "501:capability.self_orchestration_required",
+      "where": "workflow",
+      "words": [
+        "workflow",
+        "workflows"
+      ],
+      "why": "`/v1/workflows` 提交面与 `GET /v1/capabilities` 的 `workflows` 能力位 —— 长的那句自己就把那个 JSON 键(`workflows:false`)拼了出来。"
+    },
+    {
+      "family": "404:not_found.task_handle",
+      "words": [
+        "workflow",
+        "workflows"
+      ],
+      "why": "这句自己点名 `GET /v1/workflows/:id/journal` —— 指的是调用方接下来该去读的那张脸,不是引擎车道。"
+    },
+    {
+      "family": "404:not_found.subagent",
+      "words": [
+        "workflow",
+        "child",
+        "children"
+      ],
+      "why": "`workflow` = 同上那张 journal 读面;`child`/`children` = 调用方自己在这条 run 下起的后台 agent —— 它们在 `/v1/runs/:id/subagents` 与 `GET /v1/agents/roster` 上都有行,亲缘关系是调用方自己造的。"
+    },
+    {
+      "family": "400:request.path_malformed",
+      "where": "malformed subagent path",
+      "words": [
+        "subagent"
+      ],
+      "why": "路径段名(`/v1/runs/:id/subagents/…`),调用方自己写进 URL 的那一段。"
+    },
+    {
+      "family": "501:capability.run_store_required",
+      "where": "subagent",
+      "words": [
+        "subagent"
+      ],
+      "why": "同一段路径名的两条能力拒(`/v1/runs/:id/subagents/…` 的读面与流面)—— 主语就是调用方刚才请求的那条路径。"
+    },
+    {
+      "family": "404:not_found.checkpoint",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "错误码自身即 `not_found.checkpoint` —— 码与文案同词,调用方读码、读文案得到同一件事;不依赖任何它发不出去的字段。"
+    },
+    {
+      "family": "404:not_found.parked_checkpoint",
+      "words": [
+        "parked",
+        "checkpoint"
+      ],
+      "why": "两个词都在错误码自己的拼写里(`not_found.parked_checkpoint`);`parked` 另是 `GET /v1/agents/roster` 的 `?status=` 闭集成员。"
+    },
+    {
+      "family": "501:capability.checkpoint_store_required",
+      "where": "checkpoint store",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "运维面 501,码自身就是 `capability.checkpoint_store_required` —— `checkpoint store` 是错误码目录里在册的那只部署件的名字。"
+    },
+    {
+      "family": "501:feature.preemption_disabled",
+      "where": "checkpoint store",
+      "words": [
+        "checkpoint"
+      ],
+      "why": "同一只部署件,名字来自同一份错误码目录(`capability.checkpoint_store_required`)—— 运维读这句时要装的就是目录里那一件;与同句的 `RESOURCE_SUSPEND` 是两样东西,理由不靠那个旋钮。"
+    },
+    {
+      "family": "400:decide.parked_remember_unsupported",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `decide.parked_remember_unsupported`;主语是调用方在 `GET /v1/agents/roster` 上看得到的那一行,`parked` 是那张脸 `?status=` 闭集里的词。"
+    },
+    {
+      "family": "409:decide.claim_lost",
+      "where": "parked agent is already claimed",
+      "words": [
+        "parked"
+      ],
+      "why": "同 decide 族:主语是 `GET /v1/agents/roster` 上状态值逐字为 `parked` 的那一行 —— 这句说的是「你挑的那一行被别人先认领了」。"
+    },
+    {
+      "family": "409:decide.gate_moved",
+      "words": [
+        "parked"
+      ],
+      "why": "同 decide 族:`re-parked` 说的是那一行又回到了 roster `?status=` 闭集里的同一个值 —— 调用方的动作(重读待决列表)正是由这个词决定的。"
+    },
+    {
+      "family": "409:decide.not_parked",
+      "where": "moved under this decide",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `decide.not_parked` —— 码与文案说的是同一个 roster 状态值离开了,两边同词。"
+    },
+    {
+      "family": "410:gone.ask_parked",
+      "words": [
+        "parked"
+      ],
+      "why": "错误码自身即 `gone.ask_parked`,且 `tool_approval` 帧上有一个同名 additive 键 `parked`(契约 §7b)—— 这个词调用方在两处都见得到。"
+    },
+    {
+      "family": "425:parking.ask_retry",
+      "words": [
+        "park"
+      ],
+      "why": "错误码自身即 `parking.ask_retry` —— 「mid-park」是这个码的自然语言拼法,重试就会告诉调用方它最终落在哪。"
+    },
+    {
+      "family": "500:internal.error",
+      "where": "the parked approval",
+      "words": [
+        "parked"
+      ],
+      "why": "这句说的是赎回一张后台审批卡失败:主语是那张卡,`parked` 是 `GET /v1/agents/roster` 的 `?status=` 闭集与 `tool_approval` 帧同名键上的同一个词。"
+    },
+    {
+      "family": "501:capability.device_lane_required",
+      "words": [
+        "lane"
+      ],
+      "why": "错误码自身即 `capability.device_lane_required` —— `device execution lane` 是这个码在错误码目录里的全称,旋钮 `REMOTE_EXEC=device` 在同句里给出兑现路径。"
+    },
+    {
+      "family": "404:not_found.leader_run",
+      "words": [
+        "leader"
+      ],
+      "why": "`POST /v1/leader` / `GET /v1/leader/:id` 端点名,也是错误码自身的拼写(`not_found.leader_run`)、能力位名(`capabilities.leader`)与旋钮名(`LEADER_ENABLED`)。"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.148.0",
+  "version": "7.150.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",
@@ -45,9 +45,11 @@
     "scripts/drain-check-local.mjs",
     "scripts/drain-check.mysql.sql",
     "scripts/drain-check.pg.sql",
+    "scripts/embed-minimal.mjs",
     "deploy/sema-up",
     "deploy/facts",
     "docs/DEVICE-EXECUTOR-PROTOCOL.md",
+    "docs/error-text-lexicon.json",
     "wire-changes/",
     "USAGE.md",
     "MIGRATION.md"
@@ -82,7 +84,7 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
     "@sema-agent/core": "7.66.0",
-    "@sema-agent/settings-schema": "24.0.0",
+    "@sema-agent/settings-schema": "25.1.0",
     "e2b": "2.36.0",
     "libsodium-wrappers": "0.8.4",
     "mysql2": "3.22.6",