@sema-agent/server 7.134.0 → 7.136.0

package/dist/task-a2a.js

@@ -1,65 +1,213 @@
-import { resolveComplianceDenies } from "@sema-agent/core";
-import { isUsableWireName } from "@sema-agent/settings-schema";
-import { HttpError } from "./security.js";
+import { types } from "node:util";
+import { describeNotStringArray, describeValueShape, findUrlCredential, isStringArray } from "@sema-agent/settings-schema";
+import { errorKindOf } from "./observability/err-text.js";
 import { readPlainStringRecord } from "./plain-string-record.js";
 import { readRequestToolAxes } from "./request-tool-axes.js";
-import { echoKeyName } from "./request-key-closure.js";
-import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
+import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
+import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
+import { declarationEntryNotObject, declarationIssueFacts, declarationNameIssue, declarationOverCapFacts, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
-    if (config.lockedConfigKeys?.includes("a2a") === true)
-        return false;
-    if (config.compliancePosture !== undefined) {
-        const denies = resolveComplianceDenies(config.compliancePosture);
-        if (denies.has("a2a_peers"))
-            return false;
-    }
-    return config.requirePrincipal !== true;
+    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
 const HTTP_URL_RE = /^https?:\/\//i;
-function normalizeA2aPeer(e, leg, storedToolAxes) {
-    const dropped = { spec: null };
-    if (!e || typeof e !== "object")
-        return dropped;
-    const o = e;
-    if (!isUsableWireName(o.name))
-        return dropped;
-    if (typeof o.url !== "string" || !HTTP_URL_RE.test(o.url))
-        return dropped;
-    if (o.cardUrl !== undefined && (typeof o.cardUrl !== "string" || !HTTP_URL_RE.test(o.cardUrl)))
-        return dropped;
-    const headers = o.headers === undefined ? undefined : readPlainStringRecord(o.headers);
-    if (headers !== undefined && (!headers.ok || (headers.stripped.length > 0 && leg === "fresh")))
-        return dropped;
-    const lost = headers?.ok === true && headers.stripped.length > 0 ? { headersLost: headers.stripped.map((m) => echoKeyName("headers.", m.name)) } : {};
-    if (o.principalHeader !== undefined && typeof o.principalHeader !== "string")
-        return dropped;
-    if (o.allowSkills !== undefined && !(Array.isArray(o.allowSkills) && o.allowSkills.every((s) => typeof s === "string")))
-        return dropped;
+export const A2A_PEER_ENTRY_KEYS = ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+const A2A_PEER_ENTRY_KEY_SET = new Set(A2A_PEER_ENTRY_KEYS);
+const NO_TOLERATED_KEYS = new Set();
+const A2A_SEAT = {
+    list: "a2aPeers",
+    cap: MAX_REQUEST_A2A_PEERS,
+    subject: "peer",
+    declaration: "an A2A peer declaration",
+    declarations: "A2A peer declarations",
+};
+function peerUrlIssue(key) {
+    return (entry, at) => {
+        const value = entry[key];
+        if (key === "cardUrl" && value === undefined)
+            return undefined;
+        if (typeof value !== "string" || !HTTP_URL_RE.test(value)) {
+            return { path: key, reason: `must be a string starting with "http://" or "https://" (never file://, never a bare host) — got ${describeValueShape(value)}` };
+        }
+        const found = findUrlCredential(value);
+        return found === undefined ? undefined : { path: key, reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit(`${at}.headers`)), credential: found };
+    };
+}
+const HEADERS_RESERVED_MEMBER_PATH = "headers.__proto__";
+const PEER_SNAPSHOT = Symbol("a2aPeerSnapshot");
+function openCloneNode(v, ancestors) {
+    if (v === null || v === undefined || typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        return { done: { ok: true, value: v } };
+    if (typeof v !== "object")
+        return { done: { ok: false, because: `a ${typeof v} value` } };
+    if (types.isProxy(v))
+        return { done: { ok: false, because: "not inspectable" } };
+    if (ancestors.has(v))
+        return { done: { ok: false, because: "cyclic" } };
+    const list = Array.isArray(v);
+    const proto = Object.getPrototypeOf(v);
+    if (list ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+        return { done: { ok: false, because: "not plain data" } };
+    return { frame: { source: v, keys: Object.getOwnPropertyNames(v), target: list ? [] : {}, next: 0 } };
+}
+function putCloneMember(target, key, value, enumerable) {
+    if (enumerable && key !== "__proto__")
+        target[key] = value;
+    else
+        Object.defineProperty(target, key, { value, enumerable, writable: true, configurable: true });
+}
+function cloneDeclaration(value) {
+    try {
+        const ancestors = new Set();
+        const root = openCloneNode(value, ancestors);
+        if ("done" in root)
+            return root.done;
+        ancestors.add(root.frame.source);
+        const stack = [root.frame];
+        for (let frame = stack[stack.length - 1]; frame !== undefined; frame = stack[stack.length - 1]) {
+            const key = frame.keys[frame.next];
+            if (key === undefined) {
+                if (Array.isArray(frame.source) && Array.isArray(frame.target))
+                    frame.target.length = frame.source.length;
+                ancestors.delete(frame.source);
+                stack.pop();
+                continue;
+            }
+            frame.next += 1;
+            if (key === "length" && Array.isArray(frame.target))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(frame.source, key);
+            if (descriptor === undefined)
+                return { ok: false, because: "not inspectable" };
+            if (!("value" in descriptor))
+                return { ok: false, because: "an accessor member" };
+            const child = openCloneNode(descriptor.value, ancestors);
+            if ("done" in child) {
+                if (!child.done.ok)
+                    return child.done;
+                putCloneMember(frame.target, key, child.done.value, descriptor.enumerable === true);
+                continue;
+            }
+            putCloneMember(frame.target, key, child.frame.target, descriptor.enumerable === true);
+            ancestors.add(child.frame.source);
+            stack.push(child.frame);
+        }
+        return { ok: true, value: root.frame.target };
+    }
+    catch (error) {
+        return { ok: false, because: `not inspectable: ${errorKindOf(error)}` };
+    }
+}
+function isPeerSnapshot(value) {
+    return Object.hasOwn(value, PEER_SNAPSHOT);
+}
+function mintPeerSnapshot(entry, reread) {
+    const source = entry;
+    const allowSkills = source.allowSkills;
+    const headers = source.headers;
+    const toolAxes = source.toolAxes;
+    const toolAxesRead = toolAxes === undefined ? undefined : readRequestToolAxes(toolAxes, "a2a");
+    return Object.freeze({
+        [PEER_SNAPSHOT]: true,
+        name: source.name,
+        url: source.url,
+        cardUrl: source.cardUrl,
+        principalHeader: source.principalHeader,
+        allowSkills: Array.isArray(allowSkills) ? Array.from(allowSkills) : allowSkills,
+        headers: headers === undefined ? undefined : readPlainStringRecord(headers),
+        toolAxes: toolAxesRead,
+        toolAxesDeclared: reread && toolAxesRead !== undefined && !toolAxesRead.ok ? cloneDeclaration(toolAxes) : undefined,
+        unknownKeys: Object.keys(source).filter((name) => !A2A_PEER_ENTRY_KEY_SET.has(name)),
+    });
+}
+function snapshotPeer(entry, reread) {
+    return isPeerSnapshot(entry) ? entry : mintPeerSnapshot(entry, reread);
+}
+export function snapshotRequestA2a(raw, options) {
+    if (!Array.isArray(raw))
+        return raw;
+    const kept = raw.slice(0, MAX_REQUEST_A2A_PEERS).map((e) => (e !== null && typeof e === "object" && !Array.isArray(e) ? snapshotPeer(e, options.reread) : e));
+    if (raw.length > MAX_REQUEST_A2A_PEERS)
+        kept.length = raw.length;
+    return kept;
+}
+function toolAxesIssue(read) {
+    return { path: "toolAxes", reason: read.problem };
+}
+function toolAxesNotCloneableIssue(read, clone) {
+    const because = clone === undefined || clone.ok ? "unavailable" : clone.because;
+    return { path: "toolAxes", reason: `declaration not cloneable (${because}) — the one-time migration re-reads the stored declaration as plain JSON data and this one is not; ${read.problem}` };
+}
+const A2A_PEER_KEY_JUDGES = {
+    name: declarationNameIssue,
+    url: peerUrlIssue("url"),
+    cardUrl: peerUrlIssue("cardUrl"),
+    headers: (o) => {
+        const read = o.headers;
+        if (read === undefined)
+            return undefined;
+        if (!read.ok)
+            return { path: "headers", reason: `must be a plain object of string values — ${read.member === undefined ? read.fault : `its member "${echoKeyName("", read.member)}" ${read.fault}`}` };
+        const reserved = read.stripped[0];
+        return reserved === undefined ? undefined : { path: HEADERS_RESERVED_MEMBER_PATH, reason: reserved.fault };
+    },
+    principalHeader: (o) => (o.principalHeader === undefined || typeof o.principalHeader === "string" ? undefined : { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }),
+    allowSkills: (o) => o.allowSkills === undefined || isStringArray(o.allowSkills)
+        ? undefined
+        : { path: "allowSkills", reason: `must be an array of strings (omit the key to leave the peer's skills unrestricted) — got ${describeNotStringArray(o.allowSkills)}` },
+    toolAxes: (o) => {
+        const read = o.toolAxes;
+        return read === undefined || read.ok ? undefined : toolAxesIssue(read);
+    },
+};
+function normalizeA2aPeer(e, leg, at, storedToolAxes) {
+    const dropBecause = (issue) => ({ spec: null, because: declarationIssueFacts(at, issue) });
+    const notObject = declarationEntryNotObject(A2A_SEAT, e, at);
+    if (notObject !== undefined)
+        return { spec: null, because: { field: at, reason: notObject } };
+    const o = snapshotPeer(e, storedToolAxes !== undefined);
+    for (const key of A2A_PEER_ENTRY_KEYS) {
+        const issue = A2A_PEER_KEY_JUDGES[key](o, at);
+        if (issue === undefined)
+            continue;
+        if (issue.credential !== undefined)
+            continue;
+        if (leg === "resume" && issue.path === HEADERS_RESERVED_MEMBER_PATH)
+            continue;
+        if (key === "toolAxes" && storedToolAxes !== undefined)
+            continue;
+        return dropBecause(issue);
+    }
     const spec = { name: o.name, url: o.url };
-    if (typeof o.cardUrl === "string")
+    if (o.cardUrl !== undefined)
         spec.cardUrl = o.cardUrl;
+    const { headers, toolAxes: axes } = o;
     if (headers?.ok === true)
         spec.headers = headers.record;
-    if (typeof o.principalHeader === "string")
+    const lost = headers?.ok === true && headers.stripped.length > 0 ? { headersLost: headers.stripped.map((m) => echoKeyName("headers.", m.name)) } : {};
+    if (o.principalHeader !== undefined)
         spec.principalHeader = o.principalHeader;
-    if (Array.isArray(o.allowSkills))
+    if (o.allowSkills !== undefined)
         spec.allowSkills = o.allowSkills;
-    if (o.toolAxes !== undefined) {
-        const axes = readRequestToolAxes(o.toolAxes, "a2a");
-        if (!axes.ok && storedToolAxes !== undefined) {
-            const before = storedToolAxes.a2a(o.toolAxes);
+    if (axes !== undefined) {
+        if (!axes.ok) {
+            const unread = dropBecause(toolAxesIssue(axes));
+            if (storedToolAxes === undefined)
+                return unread;
+            const declared = o.toolAxesDeclared;
+            if (declared === undefined || !declared.ok)
+                return dropBecause(toolAxesNotCloneableIssue(axes, declared));
+            const before = storedToolAxes.a2a(declared.value);
             if (before === null)
-                return dropped;
+                return unread;
             const again = readRequestToolAxes(before, "a2a");
             if (!again.ok)
-                return dropped;
+                return unread;
             if (again.toolAxes !== undefined)
                 spec.toolAxes = again.toolAxes;
             return { spec, toolAxesReread: axes.problem, ...lost };
         }
-        if (!axes.ok)
-            return dropped;
         if (axes.toolAxes !== undefined)
             spec.toolAxes = axes.toolAxes;
     }
@@ -78,30 +226,44 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
     const dropped = [];
     const toolAxesReread = [];
     const headersLost = [];
-    for (const e of raw.slice(0, MAX_REQUEST_A2A_PEERS)) {
-        const { spec: v, toolAxesReread: reread, headersLost: lost } = normalizeA2aPeer(e, leg, storedToolAxes);
-        if (v) {
-            ok.push(v);
-            if (reread !== undefined)
-                toolAxesReread.push({ peer: v.name, problem: reread });
-            if (lost !== undefined)
-                headersLost.push({ peer: v.name, lost });
+    for (const [i, e] of raw.slice(0, MAX_REQUEST_A2A_PEERS).entries()) {
+        const read = normalizeA2aPeer(e, leg, `${A2A_SEAT.list}[${i}]`, storedToolAxes);
+        if (read.spec !== null) {
+            ok.push(read.spec);
+            if (read.toolAxesReread !== undefined)
+                toolAxesReread.push({ peer: read.spec.name, problem: read.toolAxesReread });
+            if (read.headersLost !== undefined)
+                headersLost.push({ peer: read.spec.name, lost: read.headersLost });
         }
         else
-            dropped.push(e && typeof e === "object" && typeof e.name === "string" ? String(e.name).slice(0, 128) : "<malformed>");
+            dropped.push({ peer: declaredName(e).slice(0, 128), ...read.because });
+    }
+    if (raw.length > MAX_REQUEST_A2A_PEERS) {
+        dropped.push({ peer: `(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`, ...declarationOverCapFacts(A2A_SEAT, raw.length) });
     }
-    if (raw.length > MAX_REQUEST_A2A_PEERS)
-        dropped.push(`(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`);
     return { ok, dropped, toolAxesReread, headersLost };
 }
-export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
-    if (!lockedKeys.has("a2a"))
-        return;
-    if (bodyA2a === undefined || bodyA2a === null)
-        return;
-    throw new HttpError(GOVERNANCE_HTTP_STATUS["config.locked_key"], "`a2aPeers` is administratively locked by this deployment (locked key \"a2a\") — task-supplied A2A peers are refused; locks are config-time and there is no request-time unlock", {
-        code: "config.locked_key",
-    });
+function requestA2aPeerRefusal(entry, at) {
+    const snapshot = snapshotPeer(entry, false);
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyNames(snapshot.unknownKeys, `${at}.`, A2A_PEER_ENTRY_KEY_SET, NO_TOLERATED_KEYS, buckets);
+    if (buckets.unknown.length > 0) {
+        const unknownKeys = buckets.unknown.sort();
+        return {
+            errorCode: "request.body_shape",
+            message: `body: unrecognized key(s) on an A2A peer declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+                `${keyClosureClause(unknownKeys, "unknown (not an a2aPeers[] key — check the spelling)")}. ` +
+                `Accepted per entry: ${[...A2A_PEER_ENTRY_KEYS].sort().join(",")}`,
+            unknownKeys: unknownKeys.slice(0, MAX_KEY_ECHO),
+        };
+    }
+    return judgeDeclarationKeys(A2A_SEAT, snapshot, at, A2A_PEER_ENTRY_KEYS, A2A_PEER_KEY_JUDGES);
+}
+export function requestA2aDeclarationRefusal(list) {
+    return requestDeclarationRefusal(A2A_SEAT, list, requestA2aPeerRefusal);
+}
+export function assertRequestA2aEntries(bodyA2a) {
+    throwDeclarationRefusal(requestA2aDeclarationRefusal(bodyA2a));
 }
 export function mergeRequestA2a(baseline, gated) {
     if (gated.length === 0)

package/dist/task-cwd.d.ts

@@ -1,10 +1,11 @@
+import { type DeploymentShapeInput } from "./deployment-shape.js";
 /**
  * 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,**不碰 fs**。
  * `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「根之上没有东西」的语义一致;尾部分隔符
  * 统一剥掉(根 `/` 除外),让同一目标只有一个 key —— 前缀判域(见 {@link dirCoversPath})靠的就是
  * key 的唯一性。
  *
- * 🔴 **单点**(S-351 起):此前它的一份私有副本住在 `boot/deferred-sandbox-path-env.ts`(沙箱代理的
+ * 🔴 **单点**([ref] 起):此前它的一份私有副本住在 `boot/deferred-sandbox-path-env.ts`(沙箱代理的
  * `absolutePath` 词法臂),而写门豁免域与任务根的判域现在读的是同一条律 —— 两份各自归一就是两个 key
  * 空间,而「豁免域盖没盖住任务根」这种判断在两个 key 空间里可以同时答是和否。
  * (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
@@ -22,97 +23,20 @@ export declare function normalizeAbsolutePathLexically(p: string): string;
  * 段感知由「归一后 + 分隔符前缀」保证:`/a/bc` **不在** `/a/b` 域内。
  */
 export declare function dirCoversPath(dir: string, target: string): boolean;
-/**
- * The deployment-level gate: does THIS deployment honor a caller-supplied `cwd`? TRUE only for the single-user
- * `host` lane (see module header). All cloud/container lanes + any multi-tenant deployment → FALSE (cwd ignored).
- */
-export declare function cwdHonored(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
-/**
- * S-377 —— 「**工具跑的那台机器**就是本进程这台吗」。回答的是一个**文件系统同一性**问题,不是权限问题:
- * server 盘上的一条绝对路径(出厂 `SKILLS_DIR` 下、或中心 plugin 缓存里某个技能自己的目录)对模型的工具**有没有意义**。
- *
- * 判据 = 能力表两位的合取 {@link handsOnWorkerFilePlane}(`coreRemoteExecutionEnv ∧ hostFilePlane`,都读表,
- * 本函数不手写任何车道词):
- * · `host`(run-on-this-machine,无容器)⇒ 真;
- * · `in-process`(`REMOTE_EXEC` 未设)⇒ **假**(S-602,clay 裁 [ref] A 翻面;改前判真)—— 该 lane 根本
- *   没挂手(core 落 `StubExecutionEnv`),「工具的盘」这句话在这里没有指称对象。改前的理由「文件系统同一性
- *   这条轴上确实是同一台机器,判真让规则只剩一条」把**缺席折成了邻居**:wire 上的 `toolsOnThisHost` 因此
- *   对无手部署说真,消费端的 doctor 据此说「工具在本机」。代价如实记:出厂目录形技能在 in-process 上不再带
- *   `baseDir` —— core 律:缺席 ⇒ 结果逐字节同 baseDir 到货之前,而那条 lane 上本来也没有能读它的工具;
- * · 其余每一条(`k8s` / `e2b` / `ssh` / `adb` / `device` / `local-docker`)⇒ 假:工具的盘在别处,
- *   server 自己的路径在那边**不存在**,声明它等于给模型一条指向不存在文件的线索,还顺带把本机目录
- *   布局说了出去;
- * · 认不出的词 ⇒ 假(fail-closed:没认出来的车道不许被当成「本机」)。
- *
- * 🔴 **为什么不复用 {@link cwdHonored}**:那一只是**权限**判据(单用户 ∧ host),它的 `requirePrincipal`
- * 那一半防的是「一个租户的输入把 agent 指向另一个租户的文件」。本谓词判的路径不是调用方给的,是**运维
- * 自己烤进镜像**的出厂内容 —— 每个租户拿到的是同一份,没有跨租户面。把租户判据搭进来会让多租户 host
- * 部署平白失去这条线索,那是**用错轴**(与 `deviceCwdHonored` 拒绝并进 `cwdHonored` 同一条理由)。
- */
-export declare function toolsRunOnThisHost(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-}): boolean;
-/**
- * device lane 的**平行**判别式(device-executor-lane-v2 §4.3.3,车A-4)——「员工在自己设备的项目目录
- * 里干活」是这条车道的存在理由,所以 caller cwd 必须被尊重。
- *
- * 🔴 **为什么不合并进 {@link cwdHonored}**:两闸语义不同,合并会把 host 的单用户约束**放松**。
- *  · `cwdHonored` 的 `requirePrincipal !== true` 防的是「一个租户的输入把 agent 指向 **worker 宿主**上
- *    另一个租户/运维的目录」—— 那是一台共享机器上的跨租户穿越;
- *  · device lane 上那个穿越面**结构性不存在**:路径落在**发起者自己的设备**上,而设备归属已由
- *    `device_session` 绑定行(提交期用验证过的 principal 写下)+ 准入链的 owner 谓词验过。所以本闸
- *    **不要求**单用户 —— 多租户部署里每个员工各连各的设备,正是这条车道的正常形态。
- * 合并两者 = 让 host 车道在多租户下也开始尊重 cwd,那是一条真实的超范围面。
- *
- * 消费者:写侧 = `boot/resolve-spec.ts`(**单写者**,与 cwdHonored 同一处);读侧 =
- * `plugins/remote-env-device.ts` 的工厂(`effectiveDeviceCwd`)。两侧必须同批落 —— 只开写侧会留下一个
- * 没有消费者的登记项(这正是 A-1 把它登记进 `PLANNED_LANE_DIVERGENCES` 而不是当场开的理由)。
- *
- * ⚠️ 刻意**不**连带放开 `additionalDirectories`:那一位在 device v1 上诚实缺席(v2 §4.1 capability
- * projectContext 行:「拆精确字段,device v1 对 unsupported 项显式 false,不打包沿用」)。
- */
-export declare function deviceCwdHonored(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
-/**
- * [ref]P3a — the OTHER host-semantics lane: provider UNSET = the in-process single-user lane. It has NO shell
- * hands (core prepare-task: no factory/executionEnv ⇒ StubExecutionEnv), so the perSession cwd/env registries
- * have no consumer there — but PROCESS-level consumers (hooks commands, the C4 projectContext local read) still
- * see the engine's own `process.cwd()`/`process.env`. When the shell spawned the engine in the caller's own
- * dir/env, a caller override is often ALREADY satisfied by that process state, and a per-task "ignored" warn
- * contradicts it (飞轮双平台观测). Signal-truth split: satisfied ⇒ debug, real mismatch ⇒ warn. True per-session
- * honoring remains `REMOTE_EXEC=host`. Multi-tenant excluded for the same reason as {@link cwdHonored}.
- */
-export declare function inProcessSingleUserLane(config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}): boolean;
 /**
  * [ref](F-1,[ref] 修向 (b')):卡批「不再询问」落盘规则的 **project root** —— 「这次授权是在哪个
  * 工作目录里点的」。取值与既有 cwd 语义同源,不新造坐标系:
  *   1. session 显式注册的 cwd(cwd seam,host lane;与 {@link effectiveHostWorkspace} 第 1 优先级同源)
  *      —— **今天唯一真的会命中的那一臂**;⚠️ 它**不含 lane 判据**,lane 语义完全依赖「`perSessionCwd`
- *      只在 `cwdHonored` 为真时被写」这条跨文件外部不变量(写侧唯一入口 boot/resolve-spec.ts)。这是
+ *      只在部署形表行 `callerCwd` 为真时被写」这条跨文件外部不变量(写侧唯一入口 boot/resolve-spec.ts)。这是
  *      刻意的单写者惯用法,不是疏漏:在消费端补第二道闸 = 把一条不变量拆给两个属主(同族消费者
  *      {@link effectiveHostWorkspace} 形状完全相同)。机器背书 = test/task-cwd.test.ts 的 [ref] 两格。
  *   2. 🔴 **前瞻/防御臂,本仓当前装配下零命中**([ref],2026-08-19 合并重扫 partial,存活断言):
- *      in-process 单用户 lane({@link inProcessSingleUserLane})取引擎自身 `process.cwd()`。它读起来像在
+ *      in-process 单用户 lane(部署形表行 `inProcessSingleUser`)取引擎自身 `process.cwd()`。它读起来像在
  *      服务一个真部署形,其实到不了 —— 该 lane 的 `remoteExec` 未设 ⇒ boot/execution-env.ts 六条工厂臂全
  *      不命中 ⇒ core 落 `StubExecutionEnv` ⇒ `handsEnabled=false` ⇒ 不挂 Bash ⇒ 未知工具在 agent-loop 走
  *      `tool.not_found`(**不进审批座**)⇒ 无 `ruleOffers` ⇒ 本函数在规则车道上根本不被调用;同 lane
- *      第 1 臂也因写侧闸只在 `cwdHonored` 下开而恒空。危害口径按 refuter **降级**:死枝 ≡ 落第 3 臂
+ *      第 1 臂也因写侧闸只在 `callerCwd` 下开而恒空。危害口径按 refuter **降级**:死枝 ≡ 落第 3 臂
  *      `undefined` ≡ core global 缺省 ≡ [ref] 修前行为,**今天零用户可见伤害**,不是「恒不命中」类缺陷。
  *      🚧 **给将来接手的人的红线**:这条 lane 若哪天真接上 hands,root 必须取 `executionEnv.cwd`(core 的
  *      `taskRootFinal` 就是它),**不是** `process.cwd()` —— 两者在静态 env 装配形下可以完全不同,照现注
@@ -134,12 +58,7 @@ export declare function inProcessSingleUserLane(config: {
  * `path.resolve` 不抛 ⇒ 初版的 realpath 失败 F 类兜底臂(`rule-scope-root-unresolvable`)随之退役
  * (census 行同批销,fail-open.ts)。
  */
-export declare function cardRuleScopeRoot(registeredCwd: string | undefined, config: {
-    remoteExec?: {
-        provider?: string;
-    };
-    requirePrincipal?: boolean;
-}, cwd?: () => string): string | undefined;
+export declare function cardRuleScopeRoot(registeredCwd: string | undefined, config: DeploymentShapeInput<"lane" | "principal">, cwd?: () => string): string | undefined;
 /** Is a requested cwd ALREADY the engine process's working dir? realpath BOTH sides (macOS `/tmp` →
  *  `/private/tmp`-class symlinks); either side failing to resolve ⇒ treated as a mismatch (warn — never a
  *  false downgrade). `realpath`/`cwd` are parameters for testability; production passes `fs.realpathSync`. */
@@ -153,7 +72,7 @@ export declare const MAX_ADDITIONAL_DIRS = 64;
 /**
  * [ref] (CC `--add-dir` parity): validate an untrusted `body.additionalDirectories` — extra host dirs the
  * FILE tools may access beyond the containment root (core canonicalizes each into its allowlist + lists them in the
- * `# Environment` block). Gated identically to {@link cwdHonored}: these are the caller's OWN-machine paths, so they
+ * `# Environment` block). Gated by the deployment-shape row `callerOwnsWorkerDisk` (hands on this worker's disk ∧ one owner): these are the caller's OWN-machine paths, so they
  * only make sense — and are only safe — on the single-user host lane (on a cloud/container lane a file-tool root is
  * the sandbox fs, and a multi-tenant lane must never let one caller widen containment onto operator/other-tenant
  * host paths). Each element gets the SAME structural check as `cwd` (absolute, no `..` traversal, no NUL, capped);

package/dist/task-cwd.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
-import { executionLaneOf, handsOnWorkerFilePlane } from "./execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export function normalizeAbsolutePathLexically(p) {
     const collapsed = path.posix.normalize(p.replace(/^\/+/, "/"));
     return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
@@ -10,21 +10,8 @@ export function dirCoversPath(dir, target) {
     const p = normalizeAbsolutePathLexically(target);
     return p === root || p.startsWith(root.endsWith("/") ? root : `${root}/`);
 }
-export function cwdHonored(config) {
-    return config.remoteExec?.provider === "host" && config.requirePrincipal !== true;
-}
-export function toolsRunOnThisHost(config) {
-    const lane = executionLaneOf(config.remoteExec?.provider);
-    return lane !== undefined && handsOnWorkerFilePlane(lane);
-}
-export function deviceCwdHonored(config) {
-    return config.remoteExec?.provider === "device";
-}
-export function inProcessSingleUserLane(config) {
-    return config.remoteExec === undefined && config.requirePrincipal !== true;
-}
 export function cardRuleScopeRoot(registeredCwd, config, cwd = process.cwd) {
-    const raw = registeredCwd ?? (inProcessSingleUserLane(config) ? cwd() : undefined);
+    const raw = registeredCwd ?? (DEPLOYMENT_SHAPE_PREDICATES.inProcessSingleUser.holds(config) ? cwd() : undefined);
     return raw === undefined ? undefined : path.resolve(raw);
 }
 export function satisfiedByProcessCwd(requested, realpath, cwd = process.cwd) {

package/dist/task-mcp.d.ts

@@ -24,6 +24,7 @@
  */
 import { type CompliancePosture, type EngineNotice, type LockedKey, type McpInjectionDropReason, type McpServerSpec } from "@sema-agent/core";
 import { type McpIdentityHeadersIssue, type RequestMcpServerSpec } from "./mcp-assertion-header.js";
+import { type DeclarationRefusal } from "./request-declaration-refusal.js";
 import type { StoredToolAxesRereadM19 } from "./stored-request-tool-axes-m19.js";
 /** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export declare const MAX_REQUEST_MCP_SERVERS = 32;
@@ -43,10 +44,10 @@ export declare const MAX_REQUEST_MCP_SERVERS = 32;
  */
 export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
 /**
- * S-481 —— 一条 `mcpServers[]` 条目在 wire 上的**键闭集**,与它两种传输各自的键闭集。
+ * [ref] —— 一条 `mcpServers[]` 条目在 wire 上的**键闭集**,与它两种传输各自的键闭集。
  *
  * ## 属主为什么在这里
- * 这个文件就是「请求腿的 MCP 条目形」的家({@link normalizeServer} 逐键读的正是这些)。S-481 的探测口
+ * 这个文件就是「请求腿的 MCP 条目形」的家({@link normalizeServer} 逐键读的正是这些)。[ref] 的探测口
  * ({@link import("./capabilities/mcp-probe.js").readMcpProbeBody})要的是**同一个**词表 —— 它在自己那边
  * 再写一份就是一份手抄投影([ref]:任何仓第一排查点),而两份哪天分岔,窄的那一份会把**合法**的键当成
  * 拼写错误 400 掉。
@@ -73,7 +74,7 @@ export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ["args", "command", "env
 export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ["assertionHeader", "headers", "kind", "principalHeader", "url"];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
- * (`requirePrincipal !== true`) — the requester is the super-admin of their own worker, so their `.mcp.json` is
+ * (deployment-shape row `multiTenant` does not hold) — the requester is the super-admin of their own worker, so their `.mcp.json` is
  * authoritative (CC-parity), on ANY execution lane (the stdio command runs on the worker, not the exec env, so the
  * lane is irrelevant — see module header). FALSE on a multi-tenant deployment (a tenant can't make the shared worker
  * run an arbitrary command / connect to an arbitrary URL).
@@ -84,7 +85,7 @@ export declare function mcpInjectionHonored(config: {
     compliancePosture?: CompliancePosture;
 }): boolean;
 /**
- * L-167(core 7.9.1)—— 一条**没有被挂上**的请求腿 MCP 条目的**事实**。宿主报事实,core 铸词:
+ * [ref](core 7.9.1)—— 一条**没有被挂上**的请求腿 MCP 条目的**事实**。宿主报事实,core 铸词:
  * `reason` 的词表属主是 core(`McpInjectionDropReason` = malformed_entry / name_reserved_by_deployment /
  * gate_closed / over_cap),本仓一个词都不枚举,通告的码/受众/句子一个字都不拼。
  *
@@ -97,7 +98,7 @@ export interface McpInjectionDrop {
     /** `malformed_entry` 专用:**哪个键**判不出形。结构性给出(读器在拒的那一行就知道),不从文案里 parse。 */
     readonly field?: string;
 }
-/** L-167:本条腿的用户面通告席。`sessionId` = 路由半场(`auth.sessionId`,与 `spec.sessionId` 同源);
+/** [ref]:本条腿的用户面通告席。`sessionId` = 路由半场(`auth.sessionId`,与 `spec.sessionId` 同源);
  *  `emit` = 收下 core 铸好的 `EngineNotice`。**本模块不知道**它最后落在 SSE、账本还是日志上 —— 那是
  *  投递腿的事,本模块只负责「事实 → core 工厂 → 一条通告」。 */
 export interface McpInjectionDropSeat {
@@ -141,27 +142,22 @@ export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: R
 /** 一条**原始**请求条目上两个身份头的问题类(没有问题 / 不是对象 / 不是 http 传输 ⇒ `undefined`)—— 提交腿的门、探测口、重放腿的披露三处共读,
  *  判据本体在 `mcp-assertion-header.ts`;这里只负责把「条目 → 传输对象」那一步读出来。 */
 export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHeadersIssue | undefined;
-/** 请求面 `mcpServers` 的一次拒:码 + 句 + 词表外的键名表(只在闭集那一形上在场)。两扇门(fresh 提交腿 / 探测口)同一份,状态恒 400。 */
-export interface RequestMcpRefusal {
-    readonly errorCode: "request.body_shape" | "request.field_invalid";
-    readonly message: string;
-    /** 词表外的键,全路径形(`mcpServers[0].transport.header`;已清洗 + 截长 + 排序 + 封顶)。 */
-    readonly unknownKeys?: readonly string[];
-}
 /**
  * 请求面 `mcpServers`「这份声明能不能原样用」的**唯一回答者** —— fresh 提交腿({@link assertRequestMcpEntries})与探测口
  * (`capabilities/mcp-probe.ts` 的 `readMcpProbeBody`)都问它、都原样转述它的答案(码与句逐字相同)。`undefined` = 能原样用,或列表缺席 / `null`(没声明;各门自己定缺席的意思)。
  *
  * ## 律:一个回答者、一个拒形,先列表后条目、条目里先键名后键值,第一处坏形即答
- *  ① **列表**:在场却不是数组 / 超过 {@link MAX_REQUEST_MCP_SERVERS} 条 / 某一条不是对象 ⇒ `400 request.field_invalid`,点名 `mcpServers` 或 `mcpServers[i]`(句尾同一句,见 {@link LIST_REFUSAL_TAIL})。
+ *  ① **列表**:在场却不是数组 / 超过 {@link MAX_REQUEST_MCP_SERVERS} 条 / 某一条不是对象 ⇒ `400 request.field_invalid`,点名 `mcpServers` 或 `mcpServers[i]`(句尾同一句,见 `request-declaration-refusal.ts` 的 `LIST_REFUSAL_TAIL`);
+ *     超上限是撞帽拒的全仓同一形(`limit-refusal.ts`:头一句 `mcpServers has N entries — at most 32 are accepted`,体带 `field` · `reason:"over_cap"` · `count` · `cap`)。
  *     整份拒而不是挂前 32 条 / 摘掉读不出的那条 / 整只忽略:一份被悄悄截短、少了几条或整只没生效的声明,在发送方那里读起来是「生效了」。
  *  ② **键名**:条目层、或 `transport` 按 `kind` 那一形的键闭集之外的键 ⇒ `400 request.body_shape`,拒体带 `unknownKeys`(拼错的键被悄悄不读,同样读起来像生效了)。
  *  ③ **身份头的键组合**(`principalHeader` 与 `assertionHeader` 同设 / `assertionHeader` 非串)⇒ {@link requestEntryIdentityRefusal}(同设那一句对契约包解析期原句逐字)。
- *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link entryFieldRefusal})。
+ *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link declarationFieldRefusal})。
  *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = {@link readRequestToolAxes}(引擎根导出的 `readToolAxes` + 请求腿不收 `boundaryFlow`);`toolFaces` = 引擎根导出的 `readToolFaces`;
  *     `startupTimeoutMs` = 引擎根导出的 `mcpStartupTimeoutMs`(坏值抛 `config.mcp_startup_timeout_invalid`,本门把那一句作原因句);`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
  *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = 契约包读器 {@link readRequestMcpTransport} 的纯数据记录读法;`elicitation` = {@link isElicitationFlag};
- *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名)。
+ *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名);
+ *     读器交回的 http `url` 再问「带不带凭据」= 契约包根的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue})。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
  * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
  * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
@@ -172,7 +168,7 @@ export interface RequestMcpRefusal {
  * 关于 `contentOrigin` 的信任语义(core 把它定性为**部署面**键):请求腿的条目只有在 {@link mcpInjectionHonored} 为真(单用户 = 请求者就是这台 worker 的超管)时才被读进 `TaskSpec.mcp`,
  * 多租户部署整只数组被忽略 ⇒ 租户**结构上**够不着这个键;名字撞车时 baseline 恒赢({@link mergeRequestMcp})⇒ 调用方也改写不了一台**已配置** server 的声明。
  */
-export declare function requestMcpDeclarationRefusal(list: unknown): RequestMcpRefusal | undefined;
+export declare function requestMcpDeclarationRefusal(list: unknown): DeclarationRefusal | undefined;
 /**
  * fresh 提交腿的 `mcpServers` 门:{@link requestMcpDeclarationRefusal} 有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` 原样)。
  *
@@ -224,7 +220,7 @@ export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined,
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 
-/** L-167:本条腿的**用户面**投递口。`sessionId` = 通告的路由半场(缺席 ⇒ 一条都不铸,见
+/** [ref]:本条腿的**用户面**投递口。`sessionId` = 通告的路由半场(缺席 ⇒ 一条都不铸,见
  *  {@link mintInjectionDropNotices});`emit` 收下 core 铸好的通告,由调用腿决定投到哪(见 `boot/resolve-spec.ts`)。
  *  整段缺席(桩、单测、非 HTTP 腿)⇒ 只走日志终点,行为逐字与本件之前相同。 */
 notice?: McpInjectionDropSeat,