@sema-agent/server 7.131.0 → 7.133.0

package/dist/lane-home-probe.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 执行环境的家目录:**声明 × 实测**的唯一判官与唯一的座(纯叶:零值依赖)。
+ *
+ * ## 病(一)—— 声明了却对不上
+ * `REMOTE_EXEC_HOME_DIR` 是运维对「执行环境以哪个用户的家目录运行」的声明,它是 `~/` 形权限规则的基、引擎家锚拒读行(`~/.ssh` / `~/.npmrc` …)
+ * 的落点(`execution-lane-caps.ts` `executionLaneHomeDir` 一只属主,几个消费面同读)。k8s / local-docker / ssh 三条车道的家目录是镜像 / 目标机
+ * 登录用户的属性,boot 期不可知 —— 声明了就照单全收。声明 `/home/y` 而车道真实家目录是 `/home/x` 时,`Edit(~/.ssh/**)` 守的是 `/home/y`,
+ * `/home/x/.ssh` 照读照写,运维与用户零告警:限制写了不生效且无人知。
+ *
+ * ## 病(二)—— 没声明就恒问人
+ * 执行环境不声明家目录时,引擎的家锚拒读行放不下 ⇒ 每一次泄内容的递归读(`grep -r` / `rg` / `git grep` / `tar c`)在全 shell 面恒问人、只读面直接拒。
+ * 家目录是执行环境自己的事实,车道开环境那一拍问一次就知道 —— 不必要运维手填。
+ *
+ * ## 律(一只座、两个来源、一条取值律 —— {@link LaneHomeSeat},四条会问的车道各持一只,不各写一份)
+ *  · **声明在场 ⇒ 声明**(座 = 声明原样)。车道对证与否是车道的姿势(`verifiesDeclared`):对证的车道在开环境那一拍问一次(与命令同一条 shell、同一份 env:
+ *    `printf %s "$HOME"`),两者不一致 ⇒ 这只执行环境不开(拒句点名两值与两条改法),环境答了的判定记在环境上(同一镜像 / 同一目标机再问也是同一个答案,不重试成风暴);
+ *    问不出答案同样不开(证不了声明 = 不拿一个没证过的目录去守),但不记 —— 与任何一次建连失败同,下一次重问;不对证的车道(adb:Android 没有 POSIX 登录家目录,声明是运维的断言)声明照单全收。
+ *  · **没声明 ⇒ 实测**:同一拍问同一句;答出绝对路径 ⇒ 座 = 它,之后不再问;
+ *  · **实测也缺席**(问不出 / 答的不是绝对路径,含空串)⇒ 座缺席(引擎失败关闭,不猜、不补 `/`),环境照开(没声明就没有声明可拒),一行 warn(点名读到了什么与出路)。
+ * 规则基与 422 门在下单那一刻就要家目录,而那一刻执行环境还没开 —— 它们仍只读声明(`executionLaneHomeDir`);实测值只填引擎手里的这一只座。
+ */
+/** 探针答案的行首标记:登录脚本 / profile 往 stdout 打的横幅不会被读成家目录 —— 只认带这个标记的那一行(取最后一行)。 */
+export declare const LANE_HOME_PROBE_MARKER = "sema-lane-home=";
+/**
+ * 执行环境里问家目录的那一句 —— 经车道自己的命令通道跑(同一条 shell、同一份 env),答的就是命令看到的 `$HOME`。
+ * 先换一行再打标记行:横幅没以换行收尾时,标记行照样从行首开始。
+ */
+export declare const LANE_HOME_PROBE_COMMAND = "printf '\\nsema-lane-home=%s\\n' \"$HOME\"";
+/** 一次问家目录的读数:问到了(stdout 原文)/ 没问到(原因)。 */
+export type LaneHomeProbe = {
+    readonly ok: true;
+    readonly stdout: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * 判定:`undefined` = 一致,照开;否则这只环境不开 —— `refusal` 是拒句,`answered` = 环境**答了**它的家目录(不一致 / 不是绝对路径;同一镜像 / 同一登录用户
+ * 再问也是同一个答案 ⇒ 调用方记在环境上),`false` = 没答上(探针失败 / 超时 / 非零退出 / 输出里没有标记行 ⇒ 这一次不开、不记、下一次重问)。
+ */
+export type LaneHomeVerdict = {
+    readonly refusal: string;
+    readonly answered: boolean;
+} | undefined;
+/**
+ * 声明 × 实测的判官。`lane` 只进句子。拒句三形:实测与声明不一致 / 实测不是绝对路径(含空)/ 没问到。每一形都点名声明值与改法,不回显任何别的东西。
+ */
+export declare function judgeLaneHome(lane: string, declared: string, probe: LaneHomeProbe): LaneHomeVerdict;
+/** 起服与每只环境「家目录答不出」那一行 warn 的事件名 —— 一只 code,起服(车道读不了)与环境(实测缺席)共用。 */
+export declare const LANE_HOME_UNDECLARED_EVENT = "execution_lane_home_undeclared";
+/**
+ * 「这条车道的执行环境没有家目录」的一句(纯字符串 ⇒ `build*`):`cause` 说为什么(没声明 + 车道读不了 / 读了没读到),`remedy` 说出路。
+ * 起服那一行(车道没有读数办法)与每只环境那一行(实测缺席)都走它 —— 代价那一半只有一份文字。
+ */
+export declare function buildHomeAbsentNote(lane: string, cause: string, remedy: string): string;
+/** 车道读不了家目录时的出路(起服那一行):声明它。 */
+export declare const DECLARE_HOME_REMEDY = "Declare the home: REMOTE_EXEC_HOME_DIR=<the absolute path the environment's $HOME reads>";
+/** 一行「这只环境没有家目录」的事实:交给运维的那一行 warn 的两个字段。 */
+export interface LaneHomeAbsence {
+    readonly provider: string;
+    readonly note: string;
+}
+/** 这条车道的座怎么长出来:`declared` = 运维声明(`REMOTE_EXEC_HOME_DIR`,boot 期的唯一属主 `executionLaneHomeDir` 的答案);`verifiesDeclared` = 车道对声明对证。 */
+export interface LaneHomeSeatOptions {
+    readonly lane: string;
+    readonly declared: string | undefined;
+    readonly verifiesDeclared: boolean;
+    /** 实测缺席时交出那一行 warn(缺席 = 不交;生产装配由 boot 递一只带去重的报告座,见 {@link createLaneHomeAbsenceReporter})。 */
+    readonly onAbsent?: ((absence: LaneHomeAbsence) => void) | undefined;
+}
+/**
+ * 四条会问家目录的车道(k8s / local-docker / ssh / adb)的适配器配置里与家目录有关的两个键 —— 文字只写这一处,四个配置接口 `extends` 它。
+ */
+export interface LaneHomeConfig {
+    /**
+     * S-213④ / core [ref] —— 运维声明的执行环境 **home 目录**(绝对路径,本环境自己的命名空间里;`REMOTE_EXEC_HOME_DIR`)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**
+     * 就以它为基。值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
+     * 缺席 ⇒ 不声明:车道建环境时自己问执行环境的 `$HOME`({@link LaneHomeSeat});实测也缺席 ⇒ 本 env 的 `homeDir` 座缺席,core 对 `~/` 规则判 `unreadable`
+     * (fail-closed 的 ask),绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
+     */
+    homeDir?: string;
+    /** 实测缺席(没声明、也没问到绝对路径)时交出那一行 warn;缺席 = 不交。生产装配由 boot 递一只带去重的报告座({@link createLaneHomeAbsenceReporter})。 */
+    onHomeAbsent?: (absence: LaneHomeAbsence) => void;
+}
+/**
+ * 一只执行环境的家目录座 —— `ExecutionEnv.homeDir` 的**唯一取值律**:声明在场 ⇒ 声明;否则 ⇒ 车道开环境时实测到的绝对路径;实测也缺席 ⇒ `undefined`(引擎失败关闭)。
+ * 车道只做两件事:`asks` 为真时经自己的命令通道跑一次 {@link LANE_HOME_PROBE_COMMAND},把读数交给 {@link settle};`homeDir` 读 {@link home}。
+ */
+export declare class LaneHomeSeat {
+    private measured;
+    private readonly lane;
+    private readonly declared;
+    private readonly verifiesDeclared;
+    private readonly onAbsent;
+    constructor(options: LaneHomeSeatOptions);
+    /** 座:声明胜,否则实测,否则缺席。 */
+    get home(): string | undefined;
+    /** 这一拍还要不要问:声明在场 ⇒ 只有对证的车道问(每次连接);没声明 ⇒ 问到量出绝对路径为止。 */
+    get asks(): boolean;
+    /**
+     * 收一次读数。声明在场(且车道对证)⇒ {@link judgeLaneHome}:`undefined` = 一致,否则这只环境不开(拒句 + 记不记见 {@link LaneHomeVerdict});
+     * 没声明 ⇒ 读到绝对路径就记下;读不到 / 不是绝对路径 ⇒ 座缺席、交一行 warn、**不拒环境**(`undefined`)—— 没声明就没有声明可拒,引擎对缺席座失败关闭。
+     * 不对证的车道声明在场时不该来问(`asks` 为假),来了照单全收。
+     */
+    settle(probe: LaneHomeProbe): LaneHomeVerdict;
+}
+/**
+ * 每个部署一只的「家目录实测缺席」报告座(闭包 ⇒ `create*`):同一(车道, 句子)只响一行 `execution_lane_home_undeclared`(同一镜像每个 run 的环境都读到同一个缺席,
+ * 每只环境各响一行 = 刷屏),不同的句子各响一次。`warn` 是服务日志的 warn。
+ */
+export declare function createLaneHomeAbsenceReporter(warn: (event: string, fields: Record<string, unknown>) => void): (absence: LaneHomeAbsence) => void;
+//# sourceMappingURL=lane-home-probe.d.ts.map

package/dist/lane-home-probe.js

@@ -0,0 +1,101 @@
+export const LANE_HOME_PROBE_MARKER = "sema-lane-home=";
+export const LANE_HOME_PROBE_COMMAND = `printf '\\n${LANE_HOME_PROBE_MARKER}%s\\n' "$HOME"`;
+const SHOWN_MAX = 256;
+const shown = (raw) => JSON.stringify(raw.length > SHOWN_MAX ? `${raw.slice(0, SHOWN_MAX)}…` : raw);
+const comparable = (p) => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+function markedHome(stdout) {
+    const lines = stdout.split("\n").map((l) => l.replace(/\r$/, ""));
+    const marked = lines.flatMap((l, i) => (l.startsWith(LANE_HOME_PROBE_MARKER) ? [i] : []));
+    if (marked.length === 0)
+        return { why: "the probe printed no home line" };
+    const at = marked[0];
+    if (marked.length > 1 || lines.slice(at + 1).some((l) => l !== ""))
+        return { why: "the probe output holds more than one home line or text after it, so it cannot be read as one path" };
+    return { home: lines[at].slice(LANE_HOME_PROBE_MARKER.length) };
+}
+function readLaneHome(probe) {
+    if (!probe.ok)
+        return { kind: "unread", reason: probe.reason };
+    const marked = markedHome(probe.stdout);
+    if ("why" in marked)
+        return { kind: "unread", reason: marked.why };
+    return marked.home.startsWith("/") ? { kind: "home", home: marked.home } : { kind: "not_absolute", value: marked.home };
+}
+export function judgeLaneHome(lane, declared, probe) {
+    const head = `REMOTE_EXEC_HOME_DIR=${shown(declared)} is the home "~/" permission rules and the engine's home-anchored read-deny rows are placed under on the ${lane} execution lane`;
+    const reading = readLaneHome(probe);
+    if (reading.kind === "unread") {
+        return {
+            refusal: `${head}, but the home of this execution environment could not be read (${reading.reason}) — the declaration cannot be confirmed, so this environment is not started. Fix the lane, or unset REMOTE_EXEC_HOME_DIR (home-relative rules are then refused at submission instead).`,
+            answered: false,
+        };
+    }
+    if (reading.kind === "not_absolute") {
+        return {
+            refusal: `${head}, but this execution environment reports HOME=${shown(reading.value)}, not an absolute path — the declaration cannot be confirmed, so this environment is not started. Give the environment's user a home (HOME), or unset REMOTE_EXEC_HOME_DIR.`,
+            answered: true,
+        };
+    }
+    if (comparable(reading.home) === comparable(declared))
+        return undefined;
+    return {
+        refusal: `${head}, but its commands run with HOME=${shown(reading.home)} — rules would guard ${shown(declared)} while ${shown(reading.home)} stays readable and writable, ` +
+            `so this environment is not started. Set REMOTE_EXEC_HOME_DIR to ${shown(reading.home)}, or run the environment as the user whose home is ${shown(declared)}.`,
+        answered: true,
+    };
+}
+export const LANE_HOME_UNDECLARED_EVENT = "execution_lane_home_undeclared";
+const HOME_ABSENT_COST = "the engine cannot place its home-anchored read-deny rows, so every contents-disclosing recursive read (grep -r, rg, git grep, tar c, …) asks a person on the full shell — " +
+    "no allow rule, mode or bypass releases that question — and is refused on the read-only face, so unattended tasks cannot search code; \"~/\" permission rules are refused at submission.";
+export function buildHomeAbsentNote(lane, cause, remedy) {
+    return `the ${lane} lane declares no home for its execution environment (${cause}): ${HOME_ABSENT_COST} ${remedy}`;
+}
+const DECLARE_ARG = "REMOTE_EXEC_HOME_DIR=<the absolute path the environment's $HOME reads>";
+export const DECLARE_HOME_REMEDY = `Declare the home: ${DECLARE_ARG}`;
+export class LaneHomeSeat {
+    measured;
+    lane;
+    declared;
+    verifiesDeclared;
+    onAbsent;
+    constructor(options) {
+        this.lane = options.lane;
+        this.declared = options.declared;
+        this.verifiesDeclared = options.verifiesDeclared;
+        this.onAbsent = options.onAbsent;
+    }
+    get home() {
+        return this.declared ?? this.measured;
+    }
+    get asks() {
+        return this.declared === undefined ? this.measured === undefined : this.verifiesDeclared;
+    }
+    settle(probe) {
+        if (this.declared !== undefined)
+            return this.verifiesDeclared ? judgeLaneHome(this.lane, this.declared, probe) : undefined;
+        const reading = readLaneHome(probe);
+        if (reading.kind === "home") {
+            this.measured = reading.home;
+            return undefined;
+        }
+        const because = reading.kind === "unread" ? `could not be read (${reading.reason})` : `reads ${shown(reading.value)}, not an absolute path`;
+        const remedy = this.verifiesDeclared
+            ? "Give the environment's user an absolute HOME (a declared REMOTE_EXEC_HOME_DIR is checked against it, so declaring cannot stand in for it)."
+            : `Give the environment's user an absolute HOME, or declare it: ${DECLARE_ARG}.`;
+        this.onAbsent?.({ provider: this.lane, note: buildHomeAbsentNote(this.lane, `REMOTE_EXEC_HOME_DIR is unset and the environment's own $HOME ${because}`, remedy) });
+        return undefined;
+    }
+}
+const ABSENCE_SEEN_MAX = 64;
+export function createLaneHomeAbsenceReporter(warn) {
+    const seen = new Set();
+    return (absence) => {
+        const key = `${absence.provider}\u0000${absence.note}`;
+        if (seen.has(key))
+            return;
+        if (seen.size < ABSENCE_SEEN_MAX)
+            seen.add(key);
+        warn(LANE_HOME_UNDECLARED_EVENT, { provider: absence.provider, note: absence.note });
+    };
+}
+//# sourceMappingURL=lane-home-probe.js.map

package/dist/leader/endpoint.d.ts

@@ -59,7 +59,7 @@ export interface LeaderEndpoint {
      *  With a store in place this Map holds only the runs THIS replica is driving. Exposed for tests. */
     runs: Map<string, LeaderRun>;
 }
-export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody) => Promise<LeaderResult>, opts?: {
+export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody) => Promise<LeaderResult>, opts: {
     logger?: {
         info?: (m: string, x?: Record<string, unknown>) => void;
         error?: (m: string, x?: Record<string, unknown>) => void;
@@ -73,5 +73,8 @@ export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody
     requiredFields?: readonly string[];
     /** [ref] 车4 件1:durable 登记表。缺席 ⇒ 显式的单副本内存降级臂(见文件头注)。 */
     store?: LeaderRunStore;
+    /** S-487 RH-3:「这个调用方读得到这一行 leader run 吗」—— 属主存取器的判官形(`http/owner-access.ts` 的 `createLeaderRunVisibility`,boot 装一次)。
+     *  必填:本模块不自判属主(修前手抄 `owner == null || owner === requester`,缺 [ref] C8 窄互认臂而注称 mirrors runOwnerOk),读面与幂等重放同读它。 */
+    ownerVisible: (principal: string | null | undefined, owner: string | null | undefined) => boolean;
 }): LeaderEndpoint;
 //# sourceMappingURL=endpoint.d.ts.map

package/dist/leader/endpoint.js

@@ -3,6 +3,7 @@ import { redactErrorMessage, redactHead, redactLeaderResult, redactLeaderResultW
 import { withPrincipal } from "../observability/principal-context.js";
 import {} from "../plugins/leader-run-store-sql.js";
 import { idemKeyOf } from "../http/idempotency.js";
+import { refusalBody } from "../http/refusal-body.js";
 function statusForLeaderResult(result) {
     if (result.conflict)
         return "needs_human";
@@ -28,7 +29,7 @@ function idemShapeError(raw) {
     }
     return undefined;
 }
-export function createLeaderEndpoint(runLeader, opts = {}) {
+export function createLeaderEndpoint(runLeader, opts) {
     const runs = new Map();
     const memIdem = new Map();
     function reap() {
@@ -126,19 +127,19 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
     function getBody(run) {
         return { status: 200, body: { id: run.id, status: run.status, ...redactedView(run) } };
     }
-    const NOT_FOUND = { status: 404, body: { error: "leader run not found", errorCode: "not_found.leader_run" } };
+    const NOT_FOUND = { status: 404, body: refusalBody({ errorCode: "not_found.leader_run", message: "leader run not found" }) };
     async function handle(method, url, body, caller, idempotencyKey) {
         const requester = caller?.principal ?? null;
         const idemCaller = caller ?? { principal: null, source: null };
         if (method === "POST" && url === "/v1/leader") {
             const b = body;
             if (!b || typeof b.objective !== "string" || b.objective.trim() === "") {
-                return { status: 400, body: { error: "missing 'objective' string", errorCode: "request.body_shape" } };
+                return { status: 400, body: refusalBody({ errorCode: "request.body_shape", message: "missing 'objective' string" }) };
             }
             if (opts.requiredFields) {
                 const missing = opts.requiredFields.filter((f) => typeof b[f] !== "string" || b[f].trim() === "");
                 if (missing.length > 0) {
-                    return { status: 400, body: { error: `missing required field(s): ${missing.join(", ")}`, errorCode: "request.body_shape" } };
+                    return { status: 400, body: refusalBody({ errorCode: "request.body_shape", message: `missing required field(s): ${missing.join(", ")}` }) };
                 }
             }
             const owner = requester;
@@ -146,15 +147,15 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
             if (idempotencyKey != null) {
                 const bad = idemShapeError(idempotencyKey);
                 if (bad)
-                    return { status: 400, body: { error: bad, errorCode: "request.body_shape" } };
+                    return { status: 400, body: refusalBody({ errorCode: "request.body_shape", message: bad }) };
                 scopedIdem = idemKeyOf(idempotencyKey, idemCaller, "leader");
             }
             reap();
             if (opts.store) {
                 const { created, run } = await opts.store.createRun({ objective: b.objective, owner, idemKey: scopedIdem });
                 if (!created) {
-                    if (run.owner != null && run.owner !== owner) {
-                        return { status: 409, body: { error: "idempotency key already used by another principal", errorCode: "conflict.leader_run_exists" } };
+                    if (!opts.ownerVisible(requester, run.owner)) {
+                        return { status: 409, body: refusalBody({ errorCode: "conflict.leader_run_exists", message: "idempotency key already used by another principal" }) };
                     }
                     return { status: 202, body: { leaderRunId: run.id, status: run.status } };
                 }
@@ -175,13 +176,13 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
             drive(id, b, owner);
             return { status: 202, body: { leaderRunId: id, status: "running" } };
         }
-        const ownerOk = (owner) => owner == null || owner === requester;
+        const ownerOk = (owner) => opts.ownerVisible(requester, owner);
         if (method === "GET" && url === "/v1/leader") {
             if (idempotencyKey == null)
-                return { status: 400, body: { error: "idempotencyKey is required: pass the raw Idempotency-Key the submission was sent with", errorCode: "request.query_invalid" } };
+                return { status: 400, body: refusalBody({ errorCode: "request.query_invalid", message: "idempotencyKey is required: pass the raw Idempotency-Key the submission was sent with" }) };
             const bad = idemShapeError(idempotencyKey);
             if (bad)
-                return { status: 400, body: { error: bad, errorCode: "request.query_invalid" } };
+                return { status: 400, body: refusalBody({ errorCode: "request.query_invalid", message: bad }) };
             const key = idemKeyOf(idempotencyKey, idemCaller, "leader");
             if (opts.store) {
                 const run = await opts.store.getByIdem(key);

package/dist/limit-refusal.d.ts

@@ -0,0 +1,59 @@
+/**
+ * **帽的拒**(一张表条数太多 / 一段文字太长)在本仓受理口的一只写法:句子的头一句 + 机读位,一处铸。
+ *
+ * 律:请求体上任何一处撞了帽,拒体带同一组机读位 ——
+ *  · `field`  = 撞帽的那一处在请求体里的坐标(`skills[1].allowedTools`、`agents[0].denyTools[3]`、`settings.permissions.allow`);
+ *  · `reason` = 帽的量纲,闭集三词:`over_cap`(条数:数组的条目数)/ `too_long`(字符数:一段文字的长度)/ `too_large`(字节数:一份载荷的体积);
+ *  · `count`  = 送来的量(条数、字符数或字节数,量纲由 `reason` 定);
+ *  · `cap`    = 帽。
+ * 句子的头一句同一句:`<field> has <count> entries|characters|bytes — at most <cap> are accepted`;之后各面可以接自己的出路句(为什么拒而不截、怎么改)。
+ * 唯一的缺量形:读体读到帽就停 / 库只说「一行装不下」时量不出送来多少 ⇒ {@link limitFactsUnmeasured}(`count` 缺席,`cap` 只在帽已知时在;不编数)。
+ * 已有句子的面(上限早于本模块定下来的受理口各处)句子逐字不变、只加机读位 —— 用 {@link limitFacts} 铸,不改写句子。
+ * 帽本身(数字)归各面的属主;本模块只管「撞了帽怎么说、怎么机读」。
+ *
+ * 量纲 → `reason` 是一张闭表({@link LIMIT_REASONS}):加一种量纲 ⇒ 这里加一行,`reason` 的词随之进闭集,读者穷举读。
+ */
+/** 量纲 → 机读 `reason` 词(闭集)。 */
+export declare const LIMIT_REASONS: {
+    readonly entries: "over_cap";
+    readonly characters: "too_long";
+    readonly bytes: "too_large";
+};
+/** 帽的量纲:条数 / 字符数 / 字节数(句子里就是这个词)。 */
+export type LimitMeasure = keyof typeof LIMIT_REASONS;
+/** 机读 `reason`:`over_cap`(条数)/ `too_long`(字符数)/ `too_large`(字节数)。 */
+export type LimitReason = (typeof LIMIT_REASONS)[LimitMeasure];
+/** 一处撞帽的机读位(原样进拒体:`refusalBody` 的 facts / `HttpError.extra`;型别名而不是接口 —— 要能直接当 `Record<string, unknown>` 用)。 */
+export type LimitFacts = {
+    readonly field: string;
+    readonly reason: LimitReason;
+    readonly count: number;
+    readonly cap: number;
+};
+/**
+ * 撞了帽、却**量不出**送来多少的机读位:读体读到帽就停(体没读完 —— 不为量一个数把 8 MiB 之外的字节再读进内存),或库只说「一行装不下」、不说多大。
+ * 同一组键的缺量形:`field` / `reason`(量纲定)恒在,`cap` 只在帽已知时在,`count` 恒缺席 —— 缺席就是「量不出」,不编数。
+ */
+export type UnmeasuredLimitFacts = Pick<LimitFacts, "field" | "reason"> & {
+    readonly cap?: number;
+};
+/** 一处撞帽的拒:句子 + 机读位。 */
+export interface LimitRefusal {
+    readonly message: string;
+    readonly facts: LimitFacts;
+}
+/** 撞帽的头一句(全仓同一句;`field` 是句子里点名的那一处)。 */
+export declare function describeLimit(field: string, measure: LimitMeasure, count: number, cap: number): string;
+/** 机读位:`reason` 由量纲定。 */
+export declare function limitFacts(field: string, measure: LimitMeasure, count: number, cap: number): LimitFacts;
+/** 缺量形的机读位({@link UnmeasuredLimitFacts}):`reason` 仍由量纲定;`cap` 只在帽已知时给。 */
+export declare function limitFactsUnmeasured(field: string, measure: LimitMeasure, cap?: number): UnmeasuredLimitFacts;
+/**
+ * 一处撞帽的拒:句子 = {@link describeLimit}(+ `tail`:该面的出路句,接在头一句之后),机读位 = {@link limitFacts}(`field` 同一个坐标)。
+ * `sentenceField` 只在该面的句子沿用另一种点名写法时给(子代定义的句子写作 `agents[0]: agent.name`,机读位仍是体内坐标 `agents[0].name`)。
+ */
+export declare function limitRefusal(field: string, measure: LimitMeasure, count: number, cap: number, opts?: {
+    readonly tail?: string;
+    readonly sentenceField?: string;
+}): LimitRefusal;
+//# sourceMappingURL=limit-refusal.d.ts.map

package/dist/limit-refusal.js

@@ -0,0 +1,15 @@
+export const LIMIT_REASONS = { entries: "over_cap", characters: "too_long", bytes: "too_large" };
+export function describeLimit(field, measure, count, cap) {
+    return `${field} has ${count} ${measure} — at most ${cap} are accepted`;
+}
+export function limitFacts(field, measure, count, cap) {
+    return { field, reason: LIMIT_REASONS[measure], count, cap };
+}
+export function limitFactsUnmeasured(field, measure, cap) {
+    return cap === undefined ? { field, reason: LIMIT_REASONS[measure] } : { field, reason: LIMIT_REASONS[measure], cap };
+}
+export function limitRefusal(field, measure, count, cap, opts = {}) {
+    const head = describeLimit(opts.sentenceField ?? field, measure, count, cap);
+    return { message: opts.tail === undefined ? head : `${head}. ${opts.tail}`, facts: limitFacts(field, measure, count, cap) };
+}
+//# sourceMappingURL=limit-refusal.js.map

package/dist/main.js

@@ -15,7 +15,7 @@ async function main() {
     const s02 = await runStage02(s01);
     const s03 = await runStage03(s02);
     const s04 = await runStage04(s03);
-    const s05 = runStage05(s04);
+    const s05 = await runStage05(s04);
     await settleHostLaneShell(s05.config, s05.logger);
     const s06 = runStage06(s05);
     const s07 = await runStage07(s06);

package/dist/mcp-assertion-header.d.ts

@@ -15,16 +15,19 @@
  *  · **fresh 提交腿**:判出问题 ⇒ 同步 400(同设 `request.body_shape`;值不是字符串 `request.field_invalid`)。
  *  · **其余腿(耐久 resume 重放存量 body)**:**不拒、不丢 server** —— 存量 body 里这个键当时是被静默忽略的,server 当时是挂着的;
  *    此刻把 server 摘掉,一条 park 在该 server 工具审批上的任务批准后会撞 `resume.tool_unavailable` 并重开检查点,而每次重试重放同一份 body ⇒ 永远卡住。
- *    所以读器 {@link readMcpIdentityHeaders} 的处置是**降级到升级前的读法**:`principalHeader` 胜(照挂,与升级前逐字相同),`assertionHeader` 不生效;
+ *    所以读器(契约包的 `readMcpIdentityHeaders`,`normalizeServer` 的 http 传输读两个身份头用它)的处置是**降级到升级前的读法**:`principalHeader` 胜(照挂,与升级前逐字相同),`assertionHeader` 不生效;
  *    不静默 —— 真挂上的这类条目由 {@link noteMcpAssertionHeaderIgnored} 说一行 warn(部署声明面没有这一格:配置不是被重放的存量任务,契约包解析期那一刀直接丢这一条)。
  *
- * ## 发送归引擎座(本版只承载,不发送)
- * core 的 http 传输只有 `url` / `headers` / `principalHeader`,**没有**断言头座。所以本键承载到「铸 core 规格」为止:
- * 请求面在 {@link toCoreMcpServerSpec} 剥掉它,settings 面的 `resolveMcpServers` 不投它;两处都用同一只
- * {@link noteMcpAssertionHeaderNotSent} 说出一行 info(声明在、发送未接)—— 披露,不是兜底:server 照常挂载、不带断言头,
- * 要求断言的托管连接器会拒这些调用,运维据这一行知道原因在哪。
- *
- * ## 退役(编译期自动逼,零人工记忆)
+ * ## 发送归引擎座(本版只承载,不发送)—— 「发不发」只有一只开关
+core 的 http 传输只有 `url` / `headers` / `principalHeader`,**没有**断言头座。所以本键承载到「铸 core 规格」为止:
+请求面在 {@link toCoreMcpServerSpec} 剥掉它,settings 面的 `resolveMcpServers` 不投它;两处都用同一只
+{@link noteMcpAssertionHeaderNotSent} 说出一行 info(声明在、发送未接)—— 披露,不是兜底:server 照常挂载、不带断言头,
+要求断言的托管连接器会拒这些调用,运维据这一行知道原因在哪。
+「这台 server 发不发」是**一个事实**,只有一只开关 {@link MCP_ASSERTION_HEADER_SENT} 说它;读它的地方共五处,全经 {@link withholdsMcpAssertionHeader} 这一只谓词
+(能力位 `GET /v1/capabilities` 的 `mcpAssertionHeaderSent` 直读开关本人):请求面剥键、settings 面不投、一行 info、探测口整条拒、能力位。所以「位为真」与「还在说发送未接」
+结构上不可能同时成立,消费方按位分支、位真时不再看到任何披露句;发送座到货的那天翻的就是这一行(与下面的退役门同批)。
+
+## 退役(编译期自动逼,零人工记忆)
  * 引擎的 http 传输一旦长出同名座,{@link _CoreHasNoAssertionSeat} 当场编译红:届时删本文件里的 {@link RequestMcpServerSpec}
  * 扩展与 {@link toCoreMcpServerSpec} 的剥键、两处 info,把键直接投进引擎规格(发送由引擎座兑现)。
  */
@@ -56,21 +59,31 @@ export type McpIdentityHeadersIssue = "both_set" | "not_a_string";
  * 两类同时成立时报 `both_set`(先名字后值)。stdio 传输不判(两键在 stdio 形上本就不存在,契约包同判)。
  */
 export declare function mcpIdentityHeadersIssue(transport: Record<string, unknown>): McpIdentityHeadersIssue | undefined;
-/**
- * 读器的这一格(`normalizeServer` 的 http 传输读两个身份头):字符串才收;**`principalHeader` 胜**——它在场(不论值形)时 `assertionHeader` 不收。
- * 于是 normalize 后的形**结构上不可能同带两键**(`mcpIdentityHeadersIssue` 的 `both_set` 在读器之后不存在),重放存量 body 的处置因此就是升级前的读法。
- */
-export declare function readMcpIdentityHeaders(transport: Record<string, unknown>): {
-    principalHeader?: string;
-    assertionHeader?: string;
-};
 /** 同设的拒句 —— 对契约包解析期那一句**逐字**(`server` = 条目名,调用方负责清洗后传入)。 */
 export declare function describeMcpIdentityHeadersConflict(server: string): string;
 /** `assertionHeader` 值不是字符串的**原因句**(不带条目名与键路径:点名由请求面统一的拒形 `entryFieldRefusal` 负责;值的形状只说种类,不回显值本身:它是一个调用方写的头名位置,可能是任何东西)。 */
 export declare function describeMcpAssertionHeaderNotAString(value: unknown): string;
-/** 这一条请求面条目是否声明了 `assertionHeader`(= 铸 core 规格时会被剥掉、需要说一行的那一类)。 */
-export declare function declaresMcpAssertionHeader(spec: RequestMcpServerSpec): boolean;
-/** 请求面条目 → 交给引擎的规格:剥掉 `assertionHeader`(引擎无座);其余逐字不动。声明过它的条目由调用方另说一行 info。 */
+/**
+ * 引擎的 http 传输有没有断言头发送座 —— **全仓唯一的开关**。今天没有(core 的 http 传输无同名座,见头注与退役门)⇒ `false`:声明在、发送未接。
+ * 翻真 = 这一行 + 删退役门 + 把 {@link RequestHttpMcpTransport} 并进引擎型;剥键、披露、探测口拒、settings 面投影、能力位 `mcpAssertionHeaderSent` 随它一起翻
+ * (五处都读 {@link withholdsMcpAssertionHeader} / 本常量,没有第六处)。声明成 `boolean` 而不是字面 `false`:谓词里的真臂是活代码(单测传 `sent=true` 钉它),不是被收窄掉的死分支。
+ */
+export declare const MCP_ASSERTION_HEADER_SENT: boolean;
+/**
+ * 这一份 `assertionHeader` 声明是不是「被扣下」的那一类(需要剥键、需要说一行 info、探测口要拒的那一类)—— 即**声明了,而发送座不在**。
+ * 三处消费(剥键 / 披露 / 探测口拒)与 settings 面的投影共读这一只;`sent` 缺省读开关,单测传显式值钉另一臂。
+ */
+export declare function withholdsMcpAssertionHeader(assertionHeader: unknown, sent?: boolean): boolean;
+/** {@link withholdsMcpAssertionHeader} 在请求面条目上的读法:只有 http 传输有这个键(stdio 形上它不存在)。 */
+export declare function specWithholdsMcpAssertionHeader(spec: RequestMcpServerSpec): boolean;
+/**
+ * settings 面铸 spec 时「这个键投不投进引擎规格」:发送座在(`sent` 真)且声明了字符串 ⇒ 投,否则整键缺席。今天恒为空对象(开关假);
+ * 开关翻真的那天 settings 面因此自动跟着投,不会出现「位说发了、部署声明面却没投」。
+ */
+export declare function sentMcpAssertionHeaderMember(assertionHeader: unknown, sent?: boolean): {
+    assertionHeader?: string;
+};
+/** 请求面条目 → 交给引擎的规格:被扣下的 `assertionHeader` 剥掉(引擎无座);其余逐字不动。被扣下的条目由调用方另说一行 info。 */
 export declare function toCoreMcpServerSpec(spec: RequestMcpServerSpec): McpServerSpec;
 /** `noteMcpAssertionHeaderNotSent` 的日志行名(运维 grep 用;请求面与 settings 面同一个名字)。 */
 export declare const MCP_ASSERTION_HEADER_NOT_SENT = "mcp_assertion_header_not_sent";

package/dist/mcp-assertion-header.js

@@ -7,12 +7,6 @@ export function mcpIdentityHeadersIssue(transport) {
         return "not_a_string";
     return undefined;
 }
-export function readMcpIdentityHeaders(transport) {
-    return {
-        ...(typeof transport.principalHeader === "string" ? { principalHeader: transport.principalHeader } : {}),
-        ...(transport.principalHeader === undefined && typeof transport.assertionHeader === "string" ? { assertionHeader: transport.assertionHeader } : {}),
-    };
-}
 export function describeMcpIdentityHeadersConflict(server) {
     return `mcp server "${server}" sets both principalHeader and assertionHeader — an http entry names ONE header for the identity it sends: keep principalHeader (the end-user principal) or assertionHeader (the connector assertion), not both`;
 }
@@ -20,11 +14,18 @@ export function describeMcpAssertionHeaderNotAString(value) {
     const kind = value === null ? "null" : Array.isArray(value) ? "an array" : `a ${typeof value}`;
     return `must be a string (the HTTP header NAME the connector assertion travels in) — got ${kind}; omit the key to send no assertion header`;
 }
-export function declaresMcpAssertionHeader(spec) {
-    return spec.transport.kind === "http" && spec.transport.assertionHeader !== undefined;
+export const MCP_ASSERTION_HEADER_SENT = false;
+export function withholdsMcpAssertionHeader(assertionHeader, sent = MCP_ASSERTION_HEADER_SENT) {
+    return !sent && assertionHeader !== undefined;
+}
+export function specWithholdsMcpAssertionHeader(spec) {
+    return spec.transport.kind === "http" && withholdsMcpAssertionHeader(spec.transport.assertionHeader);
+}
+export function sentMcpAssertionHeaderMember(assertionHeader, sent = MCP_ASSERTION_HEADER_SENT) {
+    return sent && typeof assertionHeader === "string" ? { assertionHeader } : {};
 }
 export function toCoreMcpServerSpec(spec) {
-    if (spec.transport.kind !== "http" || spec.transport.assertionHeader === undefined)
+    if (spec.transport.kind !== "http" || !withholdsMcpAssertionHeader(spec.transport.assertionHeader))
         return spec;
     const { assertionHeader: _declaredNotSent, ...transport } = spec.transport;
     return { ...spec, transport };

package/dist/mcp-tool-faces.d.ts

@@ -58,6 +58,11 @@ export type McpToolFacesRead = {
 /**
  * 从任一腿的原始条目里读出 `toolFaces` —— **三条腿共用的唯一判据点**。
  * 缺席 ⇒ 合形无覆盖层;整只不是对象 / **任一只**工具的面判不出形 ⇒ `ok:false`(调用方整条 server 不收)。
+ *
+ * 🔴 工具名是 `__proto__` ⇒ 同样判不出形,**响亮拒**:按名存面的记录装不下它 —— JSON 的自有键 `"__proto__"` 写进记录那一步走的是原型的设置器,
+ * 键从结果里消失而判官答 `ok`,那条 server 照挂、收窄面叠层被无声丢掉。方向与本模块头注同(收窄声明在场就必须原样可用)。
+ * 只拒这一个名字:`constructor` / `toString` 等其余根原型成员名写进记录是普通自有键、不丢,引擎按名查面也取得到 —— 拒它们是给重放存量 body 的腿
+ * 新添一条「整条 server 不进」,不是修这个病。
  */
 export declare function readMcpToolFaces(v: unknown): McpToolFacesRead;
 export {};

package/dist/mcp-tool-faces.js

@@ -1,10 +1,9 @@
 import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_PATH_ABSENCES, TOOL_PATH_ACCESSES, TOOL_PATH_BASES } from "@sema-agent/core";
+import { isStringArray } from "@sema-agent/settings-schema";
+import { quotedCallerText } from "./caller-text-echo.js";
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-function isStringArray(v) {
-    return Array.isArray(v) && v.every((x) => typeof x === "string");
-}
 function memberOf(table, v) {
     return typeof v === "string" && table.includes(v);
 }
@@ -92,9 +91,12 @@ export function readMcpToolFaces(v) {
         return { ok: false, problem: `toolFaces is ${Array.isArray(v) ? "an array" : typeof v}, not an object of per-tool faces` };
     const faces = {};
     for (const [tool, raw] of Object.entries(v)) {
+        if (tool === "__proto__") {
+            return { ok: false, problem: `toolFaces names tool "__proto__" — a per-tool record cannot hold a face under that name (writing it sets the record's prototype instead of a key), so the declaration would silently vanish` };
+        }
         const face = readOneFace(raw);
         if (face === undefined)
-            return { ok: false, problem: `the declared face for tool ${JSON.stringify(tool)} does not fit the tool-face shape` };
+            return { ok: false, problem: `the declared face for tool ${quotedCallerText(tool)} does not fit the tool-face shape` };
         faces[tool] = face;
     }
     return Object.keys(faces).length > 0 ? { ok: true, faces } : { ok: true };

package/dist/memory-project-layer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * S-640(S-512 片二)—— 一个任务的**项目层准备一步**:求键 → 把同一 checkout 的旧层折进当前层 → 交给同步腿跟踪。
+ * HTTP 腿(`boot/resolve-spec.ts`)与 run-local 腿共用这一只;键的规则只在 `memory-scope.ts` `memoryProjectLayerFor`(本模块不判让位、不铸键)。
+ *
+ * ## 折叠(`foldFrom`,由 `project-identity.ts` `projectLayerForTaskRoot` 给出,按序)
+ *  · 退役 `repo:<sha256(根)[:24]>` 层 —— **一次性迁移**(7.98.0–7.132.x 的项目键;窗、删法见 `plugins/one-time-migrations.ts` 登记表 M25);
+ *  · 当前档为 `r`(origin 远端)时本 checkout 的 `p` 档 —— **常设律**(先 `git init` 后加远端的项目,加远端那一刻不丢项目记忆)。
+ * 折 = core `migrateScope`(id 保留、rev 按新 scope 重算、逐条 CAS;冲突留原地,下一个任务再折)。**不记「已折」**:每个任务先读一眼旧层
+ * (`listHeaders`,空就不动),旧层之后又来了条目(仍在跑的旧任务 harvest、同步把别处的改动拉回旧层)下一个任务照折。
+ * 🔴 **与同步轮串行**:旧层若是被同步的层(`p` 档),在飞的那一轮的应答(拉回的改动 / 删除)按 id 落盘 —— 折在它前面,应答会把刚折走的条目改回旧层
+ * 或在新层上删掉它。所以有东西要折时,折叠排进同步腿的串行链(`MemorySyncRunner.exclusive`):等在飞的那一轮落定再折,折的时候没有轮在飞。
+ * 折在 spec 返回之前完成(`await`)⇒ 这一任务挂载时就看得见折进来的条目(代价如实:有东西要折又恰有一轮在飞时,任务起步等那一轮)。
+ * 折叠失败不挡任务(响亮 warn,条目原地不动、下次再折):项目层记忆暂时少了旧层那几条,比任务起不来更接近用户要的东西。
+ *
+ * ## 跟踪
+ * 当前层在复制覆盖面里(否则规则已让位、根本走不到这里)且有同步腿 ⇒ `track(scope)`:本地还没有条目也每轮拉它 —— 第二台设备第一次进这个项目
+ * 就拉得到第一台写的(拉回来可能晚于本任务挂载:第一个任务看不见,下一个任务看得见,如实)。
+ */
+import { type MemoryBackend } from "@sema-agent/core";
+import type { ServiceConfig } from "./config-types.js";
+import type { MemorySyncRunner } from "./memory-sync-client.js";
+import type { MemoryProjectKey } from "./project-identity.js";
+export interface MemoryProjectLayers {
+    /** 这一任务的项目层声明(`TaskSpec.memory.projectKey`);`undefined` 的三形同 `memoryProjectKeyFor`。 */
+    prepare(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): Promise<MemoryProjectKey | undefined>;
+}
+export declare function createMemoryProjectLayers(deps: {
+    /** 本部署的记忆引擎 backend(File 或 SQL 孪生);缺席 ⇒ 没有可折的盘(记忆暗时调用方根本不会问)。 */
+    backend: MemoryBackend | undefined;
+    /** 同步腿(开同步时在场):跟踪当前层;有东西要折时折叠排进它的串行链。 */
+    syncRunner: Pick<MemorySyncRunner, "track" | "exclusive"> | undefined;
+    log: {
+        info(msg: string, fields?: Record<string, unknown>): void;
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+}): MemoryProjectLayers;
+//# sourceMappingURL=memory-project-layer.d.ts.map