@sema-agent/server 7.78.1 → 7.79.0

package/dist/governance-http-status.d.ts

@@ -0,0 +1,27 @@
+/**
+ * S-189 —— core `GOVERNANCE_CODES` **闭集**在本分诊面上的逐码处置表。
+ *
+ * 为什么单独一张表而不是继续往下面的 if 链里加行:`failureCodeOf` 是**开集**(顶注写死「消费点一律带
+ * default 臂,禁按穷举写」),而开集里嵌着 core 这一个**闭集注册表**。闭集的成员共享两个性质——同一条
+ * prepare-throw→failed-result 管道、**零计费**(prepare 期就拒了)——所以它们要么被分诊成 4xx/5xx,要么
+ * 就落进 200-with-failed-body 并被 `finalizeTaskResult` **计费**。此前四个成员在 if 链里被点名、另外四个
+ * 静默落 200;core 往注册表加一个码时,server 这边不红不报,新码当场进「200 + 计费」。
+ *
+ * 🔴 表的类型是 `Record<GovernanceCode, …>`:**core 加成员 ⇒ 这里缺行 ⇒ tsc 红**,逼人当场判档。
+ * 值 `null` = **有意**不在本腿分诊(理由逐条写在行上),与「忘了写」在类型上不同形 —— 这是本表存在的
+ * 全部意义:让「没表态」不可能静默发生。开集那一半(下面的 if 链 + `resume_at.` 前缀臂 + default)不动。
+ *
+ * 逐码预期的**行为面**镜像在 `test/resume-anchor.test.ts` 的 S-189 段(同型同义、刻意不共用这张表:
+ * 测试喂码进函数看状态码,不读本表,否则表写错了两边一起错还全绿)。
+ */
+export declare const GOVERNANCE_HTTP_STATUS: {
+    readonly "memory.admission_denied": 403;
+    readonly "memory.admission_required": 503;
+    readonly "memory.capture_optout_denied": 403;
+    readonly "config.tool_mount_denied": 400;
+    readonly "config.locked_key": 400;
+    readonly "usage.window_exhausted": null;
+    readonly "config.compliance_required": null;
+    readonly "config.compliance_denied": null;
+};
+//# sourceMappingURL=governance-http-status.d.ts.map

package/dist/governance-http-status.js

@@ -0,0 +1,11 @@
+export const GOVERNANCE_HTTP_STATUS = {
+    "memory.admission_denied": 403,
+    "memory.admission_required": 503,
+    "memory.capture_optout_denied": 403,
+    "config.tool_mount_denied": 400,
+    "config.locked_key": 400,
+    "usage.window_exhausted": null,
+    "config.compliance_required": null,
+    "config.compliance_denied": null,
+};
+//# sourceMappingURL=governance-http-status.js.map

package/dist/http/routes/approvals-assistant.d.ts

@@ -3,6 +3,19 @@ import type { QuestionAnswer } from "@sema-agent/core";
 import type { CheckpointStoreFull } from "../../plugins/store-backend.js";
 import { type GovernancePosture } from "../active-run-conflict.js";
 import { type RouteCtx } from "../route-ctx.js";
+import { type KeyClosureIssue } from "../../request-key-closure.js";
+/**
+ * FRESH 决裁面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
+ * 全部受理 ⇒ `null`。判据边界与孪生门(`taskBodyKeyIssue` / `taskSettingsKeyIssue`)逐字同一条:
+ * **只判键名**(值形校验归各自既有的门,本门零抢话);体本身非对象 ⇒ 本门不判(留给「body must be
+ * { decision … }」那道根形门,免得同一个体被两句话抢答)。
+ *
+ * 🔴 **重放不额外过门**,也不需要:本腿的幂等回放(`decideIdempotentReplay`)重放的是**同一次请求的同一份
+ * 体**,它与首决走同一条路由、同一道门;而 checkpoint 的 resume 重建腿根本不读这个体(它读盘上的 body,
+ * 走 `resolveSpec` 的宽容层)⇒ 4xx 砖不到任何存量 parked 任务。这与 tasks 面「RESUME 重放不过门」是同一条律
+ * 的两种兑现方式:**门只站在人**(或客户端)**现写的那份字节**上。
+ */
+export declare function decideBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
 export declare const ASSISTANT_PREEMPT_RE: RegExp;
 export declare const ASSISTANT_RESUME_RE: RegExp;
 export declare const ASSISTANT_PLAN_REVIEW_RE: RegExp;

package/dist/http/routes/approvals-assistant.js

@@ -17,6 +17,34 @@ import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_
 import { gatedPrincipal, explicitOperatorOk, isOperator, sendPrincipalRefusal } from "../principal-gate.js";
 import { governanceOriginOf } from "../active-run-conflict.js";
 import { sendResumeOutcome } from "../route-ctx.js";
+import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "../../request-key-closure.js";
+const DECIDE_BODY_DECLARED_KEYS = [
+    "answer", "boundCallId", "boundInputHash", "checkpointToken", "decision", "reason", "remember", "updatedInput",
+];
+const ACCEPTED_DECIDE_BODY = new Set(DECIDE_BODY_DECLARED_KEYS);
+const UNSUPPORTED_DECIDE_BODY = new Set(["editedPlan", "sessionId", "taskId"]);
+export function decideBodyKeyIssue(raw) {
+    if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(raw, "", ACCEPTED_DECIDE_BODY, UNSUPPORTED_DECIDE_BODY, buckets);
+    if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
+        return null;
+    buckets.unknown.sort();
+    buckets.unsupported.sort();
+    const parts = [
+        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, "unknown (not a decide-request key — check the spelling)")] : []),
+        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, "unsupported (a sibling approval door's field, or a path parameter — never read from this body)")] : []),
+    ];
+    return {
+        message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller ` +
+            `(a misspelled \`remember\` or \`boundInputHash\` silently turns off an exemption / the decision binding). ` +
+            `${parts.join("; ")}. ` +
+            `Accepted: ${[...ACCEPTED_DECIDE_BODY].sort().join(",")}`,
+        unknownKeys: buckets.unknown.slice(0, MAX_KEY_ECHO),
+        unsupportedKeys: buckets.unsupported.slice(0, MAX_KEY_ECHO),
+    };
+}
 export const ASSISTANT_PREEMPT_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/preempt$/;
 export const ASSISTANT_RESUME_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/resume$/;
 export const ASSISTANT_PLAN_REVIEW_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/plan_review$/;
@@ -455,6 +483,13 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'deny', reason?, answer?, checkpointToken?, boundCallId?, boundInputHash?, updatedInput?, remember? }");
                 return;
             }
+            {
+                const keyIssue = decideBodyKeyIssue(body);
+                if (keyIssue) {
+                    sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
+                    return;
+                }
+            }
             if (body.reason !== undefined && typeof body.reason !== "string") {
                 sendError(res, 400, "request.field_invalid", "reason must be a string");
                 return;

package/dist/http/server.js

@@ -9,7 +9,7 @@ import {} from "../config-center/facade.js";
 import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, isDestructiveSessionWrite, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
 import { verifyDirectDoorProof } from "../principal-jwt.js";
 import {} from "../memory-sync.js";
-import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS, parseTaskSettings, taskSettingsKeyIssue } from "../task-settings.js";
+import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS, parseTaskSettings, skillListingBudgetFractionOk, skillListingMaxDescOk, taskSettingsKeyIssue } from "../task-settings.js";
 import { taskBodyKeyIssue } from "../request-key-closure.js";
 import { selfOrchestrationDenial } from "../task-workflow.js";
 import { centerEntitlementSourceWired } from "../runtime-caps-resolver.js";
@@ -650,19 +650,13 @@ export function createHttpServer(rawDeps) {
                 sendError(res, 400, "request.field_invalid", "settings.ultracode must be a boolean");
                 return null;
             }
-            if (st.skillListingBudgetFraction !== undefined) {
-                const v = st.skillListingBudgetFraction;
-                if (typeof v !== "number" || !Number.isFinite(v) || v <= 0 || v > 1) {
-                    sendError(res, 400, "request.field_invalid", "settings.skillListingBudgetFraction must be a number greater than 0 and at most 1");
-                    return null;
-                }
+            if (st.skillListingBudgetFraction !== undefined && !skillListingBudgetFractionOk(st.skillListingBudgetFraction)) {
+                sendError(res, 400, "request.field_invalid", "settings.skillListingBudgetFraction must be a number greater than 0 and at most 1");
+                return null;
             }
-            if (st.skillListingMaxDescChars !== undefined) {
-                const v = st.skillListingMaxDescChars;
-                if (typeof v !== "number" || !Number.isSafeInteger(v) || v <= 0) {
-                    sendError(res, 400, "request.field_invalid", "settings.skillListingMaxDescChars must be a positive integer");
-                    return null;
-                }
+            if (st.skillListingMaxDescChars !== undefined && !skillListingMaxDescOk(st.skillListingMaxDescChars)) {
+                sendError(res, 400, "request.field_invalid", "settings.skillListingMaxDescChars must be a positive integer");
+                return null;
             }
             if (st.hooks !== undefined && st.hooks !== null) {
                 const hooksParsed = parseHooksConfig(st.hooks);

package/dist/main.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
+import { DEFAULT_MODEL_REF } from "./model-select.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Runner, terminalProjection, createPermissionRuleStoreProvider, InMemoryToolResultStore, TtlSessionStore, uuidv7, defaultTaskRegistry, createAllowDenyPolicy, workflowsCapability, probeSearchBackend, describeStaticWiring, expandTiers, DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
+import { Runner, terminalProjection, createPermissionRuleStoreProvider, InMemoryToolResultStore, TtlSessionStore, uuidv7, defaultTaskRegistry, createAllowDenyPolicy, workflowsCapability, probeSearchBackend, describeStaticWiring, DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
 import { createSessionTitler } from "./session-titler.js";
 import { posIntEnv } from "./session-watch.js";
 import { selectEnvironmentTool } from "./capabilities/select-environment-tool.js";
@@ -469,7 +470,7 @@ async function main() {
     const ensureChildSessionDurable = checkpointStore && config.sessionBackend === "tidb" ? (sessionId) => ensureChildSessionDurableWithPromotion(sessionStore, subRunnerSessions, sessionId) : undefined;
     const webFetchSummarize = createWebFetchSummarizeLane({ brain, config, getKeyResolver: () => configCenter.getKeyResolver(), logger });
     const scenarioDeps = {
-        runner, subRunner, handslessSubRunner, model: "default", skills, repoClient, requirePrincipal: config.requirePrincipal,
+        runner, subRunner, handslessSubRunner, model: DEFAULT_MODEL_REF, skills, repoClient, requirePrincipal: config.requirePrincipal,
         webSearch: webSearch ? webSearch : undefined, metrics, logger, webFetchSummarize,
         backgroundAgentStore: backgroundAgentStore ? backgroundAgentStore : undefined,
         checkpointStore: checkpointStore ? checkpointStore : undefined,
@@ -692,7 +693,7 @@ async function main() {
             engineArmsOnIntent: coreArmsAutoOnIntent(),
             resolveCaps: runtimeCapsPeekResolver,
             classifierModel: () => {
-                const route = classifierRouteFor({ models: expandTiers(config.models, config.tiers ?? {}) ?? config.models, roles: config.roles });
+                const route = classifierRouteFor(runnerDeps);
                 if (route.fault !== undefined)
                     logger.debug("auto_mode_classifier_route_unresolved", { fault: route.fault });
                 return route.id;

package/dist/model-select.d.ts

@@ -23,6 +23,10 @@
  * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
  * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
  */
+/** 调用方**什么都没选**时这条 task 落到的目录 ref —— 即 `config.models.default` 那一格(引擎侧
+ *  `resolveModel("default", catalog)` 解它)。**单点**:读面要说「这台部署的主模型是谁」时读同一个词
+ *  (`auto-mode-face.ts` 的席解析器入参),两处各写一个 `"default"` 字面串正是漂移的成因。 */
+export declare const DEFAULT_MODEL_REF = "default";
 export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, allowlist?: readonly string[]): {
     model: string;
     cleanedObjective: string;

package/dist/model-select.js

@@ -1,11 +1,12 @@
 import { parseModelMention } from "@sema-agent/core";
+export const DEFAULT_MODEL_REF = "default";
 export function resolveTaskModel(bodyModel, objective, catalog, allowlist) {
     const mention = parseModelMention(objective, Object.keys(catalog));
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog) : undefined;
     const present = bodyModel !== undefined && bodyModel !== null;
     const unknown = present && explicit === undefined;
     const repr = typeof bodyModel !== "string" ? `<non-string:${typeof bodyModel}>` : bodyModel === "" ? "<empty-string>" : bodyModel;
-    const model = explicit ?? mention.model ?? "default";
+    const model = explicit ?? mention.model ?? DEFAULT_MODEL_REF;
     const picked = explicit !== undefined ? { ref: explicit, source: "explicit", requested: repr } : mention.model !== undefined ? { ref: mention.model, source: "mention", requested: mention.model } : undefined;
     const notAllowed = picked !== undefined && !isModelAllowlisted(picked.ref, catalog, allowlist)
         ? { requested: picked.requested, resolved: terminalCatalogName(picked.ref, catalog) ?? picked.ref, source: picked.source }

package/dist/observability/fail-open.d.ts

@@ -237,6 +237,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-107 第三十二轮重扫:PuTTY .ppk 容器扫描器(redact.ts redactPpkContainers)在「无合格终止 / 收口后同容器范围再见私钥字段 / 收口后到下一版本头之间夹非空白」三形下从头**吃到输入末尾**(fail-closed 取证丢弃)——终态 errorMessage 座上=整条错误文案变成 «redacted:private-key»,与 redactions_applied_total{private-key} 的诚实替换同形不可分,故要有自己的计数/探针;影子扫不计;计数=多少次整段吃尾。";
     };
+    readonly "server.approval-card.closed-word-out-of-set": {
+        readonly cls: "F";
+        readonly note: "S-249(`approval-card.ts` 的边界窄读族;今天的唯一成员是 `readRuleOffersAbsence`):活卡帧 / `card_json` 的一个**闭集词**座上,键在场而词不在本仓认得的那张表里(世代差,或第三方 producer)⇒ 该座**按缺席**处置。放行的最坏后果=卡上少一行「为什么这次没有规则候选」的解释(壳退回不显示该行),它**不改变任何裁决**——门在引擎里早已判完,本座是展示/观测面;反方向(把一个消费端词表外的值原样上卡)更坏:下游按闭集写的分支会落进 default 臂或渲染出生词。本臂存在的全部理由是**判别**:修前「上游发了个生词」与「上游根本没发这个键」在遥测上同形,而前者意味着本仓的词表该跟着 core 加词了(型面另有两向编译围栏,但那只在**重新编译**时说话,跑在线上的那一版不会自己红)。detail 带座名与那个词(经 redactSecrets 截 40)。";
+    };
     readonly "server.pg-pool.idle-client-error": {
         readonly cls: "F";
         readonly note: "S-55(test [5864] 独立复现):pg 连接池里一条连接被外部终止(pg_terminate_backend / 云端故障切换 / LB 空闲回收)或自身网络错误。**两态一 tag,detail 判别**(`state=idle` / `state=checked-out`;先例=park 墓碑行的两臂 detail 判别):①idle 态 —— node-postgres 语义(pg-pool@3.14.0 makeIdleListener):池在 emit 'error' **之前**已 `_remove` 掉该 client,坏连接自然淘汰,下次 acquire 发新连接,在飞查询零影响;修前 Pool 上无 'error' 监听 ⇒ EventEmitter 把事件转 throw ⇒ uncaughtException ⇒ 整进程 exit 1。②checked-out 态(codex R1-[high] 补,同批修)—— pg-pool 借出时摘 idle 监听(index.js:344),`pool.connect()` 显式持有的连接(事务)在 checkout 期死时 client 直接 emit 'error' 同样打死进程;守卫只观察:中毒 client 的后续查询由 pg 以 `_queryable=false` 响亮拒,归还时池淘汰;同一次 checkout 的死可能双发事件(FATAL 消息 + socket end),warn 逐枚、计数按 checkout 去重。放行的最坏后果 = 下一次 acquire 多付一次建连,故 F 类。必须留痕:「连接不断被外部杀」(故障切换风暴 / 回收策略过激 / 有人在库上清连接)与「一切正常」在服务面同形;每次事件另有逐次结构化 warn(`pg_pool_idle_client_error` / `pg_pool_checked_out_client_error`,含 code/severity),本计数让频率曲线可读。`pool.query()` 快路不在洞内(pg-pool 自带 checkout 期 once('error') 守卫)。mysql2 孪生(tidb-pool)**不同病**:PoolConnection 构造器恒挂 once('error') 库内吞并淘汰、借出期同在(坐标成文在 createTidbPool 头注),故无同族 tag。";

package/dist/observability/fail-open.js

@@ -207,6 +207,10 @@ export const FAIL_OPEN_TAGS = {
     "server.run-terminal.output-truncated": { cls: "F", note: "S-107:持久 error 脱后 UTF-8 字节 > 65,000(TiDB TEXT 65,535 字节)⇒ 脱后切并带标记(切在占位里不是泄漏);计数=多少条终态文案被字节封顶截断" },
     "server.runs.terminal-ledger-write-failed": { cls: "F", note: "S-107(全量门 silent-degradation 棘轮抓出的五处静默 `catch {}`):run 终局链里**账本腿**(flush 缓冲 text/reasoning、append `failed` 行)与终态翻转(setTerminal)已不共命运——账本 INSERT 抛不再让 run 卡 running 到 reaper;但那条抛掉的账本行之前是**静默**吞的。detail `arm=` 四臂(flush-clean-cancel / append-clean-cancel / flush-catch / append-thrown-cancel / append-failed):缺的是 run_events 尾巴(缓冲文本或 failed 事件),run 行本身仍是 durable truth,读面/reaper 容忍缺失,故 F 类;计数=多少次终局账本写失败。" },
     "server.redact.ppk-eat-to-end": { cls: "F", note: "S-107 第三十二轮重扫:PuTTY .ppk 容器扫描器(redact.ts redactPpkContainers)在「无合格终止 / 收口后同容器范围再见私钥字段 / 收口后到下一版本头之间夹非空白」三形下从头**吃到输入末尾**(fail-closed 取证丢弃)——终态 errorMessage 座上=整条错误文案变成 «redacted:private-key»,与 redactions_applied_total{private-key} 的诚实替换同形不可分,故要有自己的计数/探针;影子扫不计;计数=多少次整段吃尾。" },
+    "server.approval-card.closed-word-out-of-set": {
+        cls: "F",
+        note: "S-249(`approval-card.ts` 的边界窄读族;今天的唯一成员是 `readRuleOffersAbsence`):活卡帧 / `card_json` 的一个**闭集词**座上,键在场而词不在本仓认得的那张表里(世代差,或第三方 producer)⇒ 该座**按缺席**处置。放行的最坏后果=卡上少一行「为什么这次没有规则候选」的解释(壳退回不显示该行),它**不改变任何裁决**——门在引擎里早已判完,本座是展示/观测面;反方向(把一个消费端词表外的值原样上卡)更坏:下游按闭集写的分支会落进 default 臂或渲染出生词。本臂存在的全部理由是**判别**:修前「上游发了个生词」与「上游根本没发这个键」在遥测上同形,而前者意味着本仓的词表该跟着 core 加词了(型面另有两向编译围栏,但那只在**重新编译**时说话,跑在线上的那一版不会自己红)。detail 带座名与那个词(经 redactSecrets 截 40)。",
+    },
     "server.pg-pool.idle-client-error": {
         cls: "F",
         note: "S-55(test [5864] 独立复现):pg 连接池里一条连接被外部终止(pg_terminate_backend / 云端故障切换 / LB 空闲回收)或自身网络错误。**两态一 tag,detail 判别**(`state=idle` / `state=checked-out`;先例=park 墓碑行的两臂 detail 判别):①idle 态 —— node-postgres 语义(pg-pool@3.14.0 makeIdleListener):池在 emit 'error' **之前**已 `_remove` 掉该 client,坏连接自然淘汰,下次 acquire 发新连接,在飞查询零影响;修前 Pool 上无 'error' 监听 ⇒ EventEmitter 把事件转 throw ⇒ uncaughtException ⇒ 整进程 exit 1。②checked-out 态(codex R1-[high] 补,同批修)—— pg-pool 借出时摘 idle 监听(index.js:344),`pool.connect()` 显式持有的连接(事务)在 checkout 期死时 client 直接 emit 'error' 同样打死进程;守卫只观察:中毒 client 的后续查询由 pg 以 `_queryable=false` 响亮拒,归还时池淘汰;同一次 checkout 的死可能双发事件(FATAL 消息 + socket end),warn 逐枚、计数按 checkout 去重。放行的最坏后果 = 下一次 acquire 多付一次建连,故 F 类。必须留痕:「连接不断被外部杀」(故障切换风暴 / 回收策略过激 / 有人在库上清连接)与「一切正常」在服务面同形;每次事件另有逐次结构化 warn(`pg_pool_idle_client_error` / `pg_pool_checked_out_client_error`,含 code/severity),本计数让频率曲线可读。`pool.query()` 快路不在洞内(pg-pool 自带 checkout 期 once('error') 守卫)。mysql2 孪生(tidb-pool)**不同病**:PoolConnection 构造器恒挂 once('error') 库内吞并淘汰、借出期同在(坐标成文在 createTidbPool 头注),故无同族 tag。",

package/dist/parked-decide.d.ts

@@ -184,8 +184,13 @@ export interface ParkedDecideResult {
  *
  * · D-1 绑定:操作员在 GET 看到的 `boundCallId`/`boundInputHash` 原样透传,server **绝不重算**;
  *   缺席时回落到行上 persisted 的那两位(core resume 侧做 fail-closed 等值校验)。
- * · `reason` 是**存在性**判定不是真值判定 —— 显式空串("运维选择不写理由")与"没传"是两件事
- *   (姊妹 approval-hmac.ts `env.reason ?? null` 同判据)。
+ * · `reason` 走**存在性**判定(`!== undefined`),不是真值判定 —— 本铸点不折叠,原样上送。
+ *   🔴 但**别把这条读成「空串与缺席在结算上是两件事」**(7.19.0 / [ref] 之前那句话是真的,之后不是):
+ *   上送域的属主是引擎的单铸点,它把空文本折成缺席 ⇒ 到了消费端,`reason:""`、不传 `reason`、
+ *   与一条裸拒**同形**。本腿仍不在这里折,理由是「源头修复禁下游旁路」(下游再折一次就是同一语义的
+ *   第二个写者),不是因为两者可分辨。真正按「空串 ≠ 缺席」办事的只有两个**别的**域:验签载荷
+ *   (approval-hmac.ts 的 `env.reason ?? null` —— 线上原值,折一刀就恒 401)与幂等回放的**身份**判定
+ *   (`decisionReasonOf`,属主是本仓)。三域各有属主,逐域的射程写在 `decisionReasonOf` 的顶注里。
  * · `hostDecision` = 结算**事实**逐字上 outcome;`gateOutcome` 一格 server **永不**填(core 对宿主
  *   自铸的结算词是 pre-CAS 响亮拒)。
  * · `answer` 原样透传([ref]:header 逐字匹配等语义校验全在 core,server 不预判)。

package/dist/plugins/host-workspace-registry.d.ts

@@ -0,0 +1,27 @@
+/** 铸出一个 ephemeral 工作区路径时登记(persistent / 用户自有目录**不**登记 —— 那不是我们的)。 */
+export declare function trackEphemeralHostWorkspace(dir: string): void;
+/**
+ * `destroy()` **删成功之后**注销 —— 注销过的路径兜底腿一个字节都不碰。
+ *
+ * 🔴 「删成功之后」不是措辞:`destroy()` 的 rm 是 best-effort(teardown 契约不许抛),EBUSY / EACCES 被吞掉
+ * 之后目录还在,而 `destroyed` 已置位 ⇒ 第二次 destroy 直接早退。此时若照样注销,这条路径就**永久**失去了
+ * 被兜底回收的机会 —— 登记簿的语义是「我还欠一次清理」,删没删掉才是它该跟着走的事实。
+ */
+export declare function untrackEphemeralHostWorkspace(dir: string): void;
+/** 当前在册数(判据用:钉"登记了"与"注销了",不必去摸文件系统)。 */
+export declare function liveEphemeralHostWorkspaceCount(): number;
+/** 兜底回收的读数。`failed` 非空 ⇒ 消费方必须**响亮**说出来,不许静默吞。 */
+export interface HostWorkspaceReaping {
+    readonly removed: readonly string[];
+    readonly failed: readonly {
+        readonly dir: string;
+        readonly error: string;
+    }[];
+}
+/**
+ * 同步删掉所有仍在册的工作区;删成功的注销,**删失败的留在册上等下一次机会**。
+ * **同步**是硬要求:`process.on("exit")` 里只有同步 I/O 会被执行。幂等(删过的路径 `force:true` 直接 no-op),
+ * 可重复调用 —— 重复调用正是失败项的重试路径。
+ */
+export declare function reapEphemeralHostWorkspaces(): HostWorkspaceReaping;
+//# sourceMappingURL=host-workspace-registry.d.ts.map

package/dist/plugins/host-workspace-registry.js

@@ -0,0 +1,27 @@
+import { rmSync } from "node:fs";
+const LIVE = new Set();
+export function trackEphemeralHostWorkspace(dir) {
+    LIVE.add(dir);
+}
+export function untrackEphemeralHostWorkspace(dir) {
+    LIVE.delete(dir);
+}
+export function liveEphemeralHostWorkspaceCount() {
+    return LIVE.size;
+}
+export function reapEphemeralHostWorkspaces() {
+    const removed = [];
+    const failed = [];
+    for (const dir of [...LIVE]) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            removed.push(dir);
+            LIVE.delete(dir);
+        }
+        catch (e) {
+            failed.push({ dir, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return { removed, failed };
+}
+//# sourceMappingURL=host-workspace-registry.js.map

package/dist/plugins/one-time-migrations.d.ts

@@ -8,6 +8,9 @@ export interface OneTimeMigrationReport {
     readonly retiredSnapshotRows: number;
     /** M2:退役单座列 —— `dropped` = 本次真 DROP COLUMN,`absent` = 早已不在。 */
     readonly retiredSteerSeatColumn: "dropped" | "absent";
+    /** M2:DROP COLUMN 随手丢掉的**陈旧**格数(行已不是 `pending` ⇒ 那条指令再也送不出去;`absent` 时恒 0)。
+     *  非零 = 这次迁移真丢了存量字节,必须让运维看见 —— 与 M1 的 `retiredSnapshotRows` 逐字同一条纪律。 */
+    readonly retiredSteerSeatStaleRows: number;
     /** M3:改名的行数(账本 `tool_end` 行 + 已决 checkpoint 的执行判词列,两者相加)。 */
     readonly askOriginRowsMigrated: number;
 }

package/dist/plugins/one-time-migrations.js

@@ -4,25 +4,28 @@ export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
     retiredSteerSeatColumn: "absent",
+    retiredSteerSeatStaleRows: 0,
 };
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
+const DELIVERABLE_STEER_SEAT_WHERE = "(status = 'pending' OR (status = 'resolved' AND execution_outcome IS NULL))";
 const RETIRED_ASK_ORIGIN = { from: "unresolvable", to: "ancestor_marked" };
 const GATE_BEARING_LEDGER_EVENT_TYPE = "tool_end";
 export class RetiredSteerSeatError extends Error {
     rows;
     code = "checkpoint.pending_steer_seat_retired";
     constructor(rows) {
-        super(`checkpoint.pending_steer_seat_retired: ${rows} checkpoint row(s) still carry a value in the RETIRED single-seat ` +
-            `steering column \`${RETIRED_STEER_SEAT_COLUMN}\`. That seat is gone from the engine (a resume of such a row is ` +
-            `refused pre-CAS), so the value is an operator instruction nothing will ever deliver, and this service refuses ` +
+        super(`checkpoint.pending_steer_seat_retired: ${rows} STILL-DELIVERABLE checkpoint row(s) carry a value in the RETIRED ` +
+            `single-seat steering column \`${RETIRED_STEER_SEAT_COLUMN}\`. That seat is gone from the engine (a resume of such a row ` +
+            `is refused pre-CAS), so the value is an operator instruction nothing will ever deliver, and this service refuses ` +
             `to guess what it should become (folding a bare seat into the queue would mint a queue entry the engine never ` +
-            `wrote). Note that no earlier version ever cleared that cell after delivering it, so most non-NULL cells sit on ` +
-            `rows that can never be resumed again — those are stale and safe to clear: ` +
-            `\`UPDATE checkpoint SET ${RETIRED_STEER_SEAT_COLUMN} = NULL WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL AND ` +
-            `(status = 'expired' OR execution_outcome IS NOT NULL)\`. Any cell left after that is on a still-live row and holds an ` +
-            `undelivered instruction: decide or cancel those runs on server 7.73.x first (or accept dropping the instruction), ` +
-            `then clear the rest (\`UPDATE checkpoint SET ${RETIRED_STEER_SEAT_COLUMN} = NULL WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL\`) ` +
+            `wrote). Only rows a resume can still reach are counted here — \`${DELIVERABLE_STEER_SEAT_WHERE}\`, i.e. pending now, or ` +
+            `reopenable back to pending (the store's only reopen CAS). A cell on any other row sits on a checkpoint that can never ` +
+            `be resumed again, so its instruction was already undeliverable — those are dropped with the column and reported as ` +
+            `\`retiredSteerSeatStaleRows\` in the migration log line, not held against the boot. ` +
+            `Two ways out for the rows above: decide or cancel those runs on server 7.73.x first (the resume delivers the ` +
+            `instruction and the row settles for good), or accept dropping them ` +
+            `(\`UPDATE checkpoint SET ${RETIRED_STEER_SEAT_COLUMN} = NULL WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL AND ${DELIVERABLE_STEER_SEAT_WHERE}\`) ` +
             `and start this version again.`);
         this.rows = rows;
         this.name = "RetiredSteerSeatError";
@@ -112,11 +115,14 @@ async function withPgLock(pool, run) {
 }
 async function migrateOn(db, dialect) {
     const seatColumnPresent = await columnExists(db, dialect, "checkpoint", RETIRED_STEER_SEAT_COLUMN);
+    let retiredSteerSeatStaleRows = 0;
     if (seatColumnPresent) {
-        const seatRows = await db.rows(`SELECT COUNT(*) AS n FROM checkpoint WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL`);
+        const seatRows = await db.rows(`SELECT COUNT(*) AS n FROM checkpoint WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL AND ${DELIVERABLE_STEER_SEAT_WHERE}`);
         const seats = Number(seatRows[0]?.n ?? 0);
         if (seats > 0)
             throw new RetiredSteerSeatError(seats);
+        const staleRows = await db.rows(`SELECT COUNT(*) AS n FROM checkpoint WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL`);
+        retiredSteerSeatStaleRows = Number(staleRows[0]?.n ?? 0);
     }
     const snapshotTablePresent = await tableExists(db, dialect, RETIRED_SNAPSHOT_TABLE);
     const retiredSchemaPresent = seatColumnPresent || snapshotTablePresent;
@@ -161,7 +167,7 @@ async function migrateOn(db, dialect) {
         throw new Error(`one-time migration failed AFTER completing destructive steps — record these before retrying, a retry cannot ` +
             `report them again: ${destroyed.join("; ")}. Underlying failure: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
     }
-    return { retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, askOriginRowsMigrated };
+    return { retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated };
 }
 export function migrateRetiredAskOrigin(type, data) {
     if (type !== GATE_BEARING_LEDGER_EVENT_TYPE)
@@ -184,6 +190,7 @@ export function logOneTimeMigrations(log, backend, report) {
         retiredSnapshotTable: report.retiredSnapshotTable,
         retiredSnapshotRows: report.retiredSnapshotRows,
         retiredSteerSeatColumn: report.retiredSteerSeatColumn,
+        retiredSteerSeatStaleRows: report.retiredSteerSeatStaleRows,
         askOriginRowsMigrated: report.askOriginRowsMigrated,
         note: "one-time persisted-data migrations for this version's retirements (retired whole-tree snapshot index table " +
             "dropped; retired single-seat steering column dropped; retired ask-origin spelling rewritten in place). This " +

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

@@ -44,9 +44,20 @@ export interface AdbEnvDeps {
  *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests. */
 export declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
+    /**
+     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在设备 shell 里解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
+     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
+     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
+     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
+     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
+     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
+     */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: boolean;
     };
     cwd: string;
     private connected;

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

@@ -18,7 +18,7 @@ export function isAdbTransportLost(stderr) {
     return /device offline|device '.*' not found|no devices\/emulators found|connection reset|protocol fault|device disconnected/i.test(stderr);
 }
 export class RemoteAdbExecutionEnv {
-    capabilities = { isolation: false, suspendable: false };
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
     cwd;
     connected = false;
     destroyed = false;

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

@@ -94,9 +94,20 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
      * 谁要把 executor 的工作区改成临时目录,先来改这一行:那一刻这个 `false` 就变成谎话,park 赎回会
      * 落到一个空工作区上而链路上没有任何一层会报错。
      */
+    /**
+     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 就是**命令真正跑的那块文件系统**的权威答案(设备 WS 协议的**必答** `canonicalPath` op)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
+     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
+     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
+     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
+     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
+     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
+     */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: boolean;
     };
     readonly externalContentTarget = true;
     /** [ref]:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */

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

@@ -110,7 +110,7 @@ function assertPosixDevicePlatform(os, deviceId) {
 export class RemoteDeviceExecutionEnv {
     cfg;
     homeDir;
-    capabilities = { isolation: false, suspendable: false };
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
     externalContentTarget = true;
     hostLocalPaths = false;
     cwd;

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

@@ -58,9 +58,20 @@ export interface HostEnvConfig {
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
     /** [ref] §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
+    /**
+     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 就是**命令真正跑的那块文件系统**的权威答案(worker 本机的 `fs.realpath`)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
+     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
+     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
+     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
+     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
+     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
+     */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: boolean;
     };
     /** R7 自唤醒: structural delegation to the injected scheduler backend. `hasScheduler(env)` checks BOTH the method
      *  presence (always, since we implement the interface) AND `schedulerCapabilities.supported===true` — which is only
@@ -235,6 +246,21 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     }): Promise<Result<string, FileError>>;
     /** Resolve a (possibly relative) path against {@link cwd} like the other adapters. Host paths are platform-native. */
     private resolve;
+    /**
+     * S-260 ②:**建之前**先判「我这个用户能不能在那儿建」。
+     *
+     * 不判的话,唯一的读数是 `failed to create host workspace …: EACCES: permission denied, mkdir '<随机子目录>'`
+     * —— 它说的是那个**随机**子目录建不出来,而真正的事实是**父目录**(`HOST_WORKSPACE_BASE`,缺省
+     * `os.tmpdir()`)对本进程的运行用户不可写。运维拿着那条 errno 会去查那个随机路径(它当然不存在),
+     * 查不到根因;更糟的是每一个任务都复发一次同一条。⇒ 前判把它换成一句能直接照做的拒绝:哪个目录、
+     * 哪个用户、改哪个旋钮。
+     *
+     * 只对 **ephemeral** 形做(persistent 形是用户自己的目录,`mkdir -p` 一个已存在的只读 checkout 本来
+     * 就该成功 —— 在那儿加可写判据会把"只读仓库上跑只读任务"这个正当用法拒掉)。
+     * root 与非 POSIX 平台跳过:root 的可写判据恒真(root-squash 的网络盘上反而会假拒),
+     * 而 `process.getuid` 不存在时这条 POSIX 权限判据无从谈起。
+     */
+    private assertWorkspaceParentWritable;
     /** Lazily create the per-task workspace exactly once (memoized; concurrent first-use shares it). */
     private ensurePrepared;
     private shellReady;

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

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
-import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync } from "node:fs";
+import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
@@ -11,6 +11,7 @@ import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeS
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
+import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const HOST_BG_MAX_CONCURRENT = numEnvOr("HOST_BG_MAX_CONCURRENT", 8, 1);
@@ -33,7 +34,7 @@ const UNSUPPORTED_SCHEDULER_CAPS = {
     maxScheduledHorizonSec: 0,
 };
 export class RemoteHostExecutionEnv {
-    capabilities = { isolation: false, suspendable: false };
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
     get schedulerCapabilities() {
         return this.cfg.scheduler?.schedulerCapabilities ?? UNSUPPORTED_SCHEDULER_CAPS;
     }
@@ -143,6 +144,7 @@ export class RemoteHostExecutionEnv {
                 return;
             try {
                 await fs.rm(this.workspaceDir, { recursive: true, force: true });
+                untrackEphemeralHostWorkspace(this.workspaceDir);
             }
             catch {
             }
@@ -1084,14 +1086,52 @@ export class RemoteHostExecutionEnv {
     resolve(p) {
         return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
     }
+    assertWorkspaceParentWritable() {
+        const uid = process.getuid?.();
+        if (uid === undefined || uid === 0)
+            return;
+        let anc = path.dirname(this.workspaceDir);
+        for (;;) {
+            if (existsSync(anc))
+                break;
+            const up = path.dirname(anc);
+            if (up === anc)
+                break;
+            anc = up;
+        }
+        try {
+            accessSync(anc, FS_CONST.W_OK | FS_CONST.X_OK);
+        }
+        catch (cause) {
+            let who = `uid=${uid} gid=${process.getgid?.() ?? "?"}`;
+            try {
+                who = `${os.userInfo().username} (${who})`;
+            }
+            catch {
+                who = `<no passwd entry> (${who})`;
+            }
+            throw new Error(`host workspace base ${anc} is not writable by ${who} — the per-task workspace ${this.workspaceDir} cannot be created. ` +
+                `Point HOST_WORKSPACE_BASE at a directory this user owns, or run the service as the user that owns ${anc}.`, { cause });
+        }
+    }
     ensurePrepared() {
         if (this.prepared)
             return Promise.resolve();
+        if (!this.persistent) {
+            try {
+                this.assertWorkspaceParentWritable();
+            }
+            catch (e) {
+                return Promise.reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        }
         if (!this.preparing) {
             this.preparing = fs
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
                 this.prepared = true;
+                if (!this.persistent)
+                    trackEphemeralHostWorkspace(this.workspaceDir);
             })
                 .catch((e) => {
                 this.preparing = undefined;

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

@@ -119,9 +119,20 @@ export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
 export declare function errorMessageOf(e: unknown): string;
 export { exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
+    /**
+     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,经 pod exec 解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
+     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
+     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
+     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
+     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
+     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
+     */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: true;
     };
     cwd: string;
     private podName?;