@sema-agent/server 7.132.0 → 7.133.0

package/dist/lane-home-probe.js

@@ -4,32 +4,98 @@ 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").filter((l) => l.startsWith(LANE_HOME_PROBE_MARKER));
-    const last = lines[lines.length - 1];
-    return last === undefined ? undefined : last.slice(LANE_HOME_PROBE_MARKER.length).replace(/\r$/, "");
+    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 measured = probe.ok ? markedHome(probe.stdout) : undefined;
-    if (measured === undefined) {
-        const reason = probe.ok ? "the probe printed no home line" : probe.reason;
+    const reading = readLaneHome(probe);
+    if (reading.kind === "unread") {
         return {
-            refusal: `${head}, but the home of this execution environment could not be read (${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).`,
+            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 (!measured.startsWith("/")) {
+    if (reading.kind === "not_absolute") {
         return {
-            refusal: `${head}, but this execution environment reports HOME=${shown(measured)}, 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.`,
+            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(measured) === comparable(declared))
+    if (comparable(reading.home) === comparable(declared))
         return undefined;
     return {
-        refusal: `${head}, but its commands run with HOME=${shown(measured)} — rules would guard ${shown(declared)} while ${shown(measured)} stays readable and writable, ` +
-            `so this environment is not started. Set REMOTE_EXEC_HOME_DIR to ${shown(measured)}, or run the environment as the user whose home is ${shown(declared)}.`,
+        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

@@ -3,10 +3,12 @@
  *
  * 律:请求体上任何一处撞了帽,拒体带同一组机读位 ——
  *  · `field`  = 撞帽的那一处在请求体里的坐标(`skills[1].allowedTools`、`agents[0].denyTools[3]`、`settings.permissions.allow`);
- *  · `reason` = 帽的量纲,闭集两词:`over_cap`(条数:数组的条目数)/ `too_long`(字符数:一段文字的长度);
- *  · `count`  = 送来的量(条数或字符数,量纲由 `reason` 定);
+ *  · `reason` = 帽的量纲,闭集三词:`over_cap`(条数:数组的条目数)/ `too_long`(字符数:一段文字的长度)/ `too_large`(字节数:一份载荷的体积);
+ *  · `count`  = 送来的量(条数、字符数或字节数,量纲由 `reason` 定);
  *  · `cap`    = 帽。
- * 句子的头一句同一句:`<field> has <count> entries|characters — at most <cap> are accepted`;之后各面可以接自己的出路句(为什么拒而不截、怎么改)。
+ * 句子的头一句同一句:`<field> has <count> entries|characters|bytes — at most <cap> are accepted`;之后各面可以接自己的出路句(为什么拒而不截、怎么改)。
+ * 唯一的缺量形:读体读到帽就停 / 库只说「一行装不下」时量不出送来多少 ⇒ {@link limitFactsUnmeasured}(`count` 缺席,`cap` 只在帽已知时在;不编数)。
+ * 已有句子的面(上限早于本模块定下来的受理口各处)句子逐字不变、只加机读位 —— 用 {@link limitFacts} 铸,不改写句子。
  * 帽本身(数字)归各面的属主;本模块只管「撞了帽怎么说、怎么机读」。
  *
  * 量纲 → `reason` 是一张闭表({@link LIMIT_REASONS}):加一种量纲 ⇒ 这里加一行,`reason` 的词随之进闭集,读者穷举读。
@@ -15,10 +17,11 @@
 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`(字符数)。 */
+/** 机读 `reason`:`over_cap`(条数)/ `too_long`(字符数)/ `too_large`(字节数)。 */
 export type LimitReason = (typeof LIMIT_REASONS)[LimitMeasure];
 /** 一处撞帽的机读位(原样进拒体:`refusalBody` 的 facts / `HttpError.extra`;型别名而不是接口 —— 要能直接当 `Record<string, unknown>` 用)。 */
 export type LimitFacts = {
@@ -27,6 +30,13 @@ export type LimitFacts = {
     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;
@@ -36,6 +46,8 @@ export interface LimitRefusal {
 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`)。

package/dist/limit-refusal.js

@@ -1,10 +1,13 @@
-export const LIMIT_REASONS = { entries: "over_cap", characters: "too_long" };
+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) };

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

@@ -18,13 +18,16 @@
  *    所以读器(契约包的 `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,把键直接投进引擎规格(发送由引擎座兑现)。
  */
@@ -60,9 +63,27 @@ export declare function mcpIdentityHeadersIssue(transport: Record<string, unknow
 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

@@ -14,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.js

@@ -1,11 +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);
 }

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

package/dist/memory-project-layer.js

@@ -0,0 +1,46 @@
+import { migrateScope } from "@sema-agent/core";
+import { memoryProjectLayerFor } from "./memory-scope.js";
+export function createMemoryProjectLayers(deps) {
+    const fold = async (backend, from, to) => {
+        let report;
+        try {
+            report = await migrateScope(backend, from, to);
+        }
+        catch (err) {
+            deps.log.warn("memory_project_layer_fold_failed", { from, to, err: String(err), note: "entries stay where they are; the next task in this project retries" });
+            return;
+        }
+        if (report.moved > 0)
+            deps.log.info("memory_project_layer_folded", { from, to, moved: report.moved, cursorMoved: report.cursorMoved });
+        if (report.conflicts.length > 0) {
+            deps.log.warn("memory_project_layer_fold_conflicts", { from, to, conflicts: report.conflicts.length, note: "conflicting entries stay in the old layer; the next task in this project retries" });
+        }
+    };
+    const occupied = async (backend, sources) => {
+        const out = [];
+        for (const from of sources) {
+            if ((await backend.listHeaders([from])).some((h) => h.scope === from))
+                out.push(from);
+        }
+        return out;
+    };
+    return {
+        async prepare(config, scope, taskRoot) {
+            const layer = memoryProjectLayerFor(config, scope, taskRoot);
+            const current = layer?.key.scope;
+            if (layer === undefined || current === undefined)
+                return layer?.key;
+            const backend = deps.backend;
+            if (backend !== undefined && (await occupied(backend, layer.foldFrom)).length > 0) {
+                const foldAll = async () => {
+                    for (const from of await occupied(backend, layer.foldFrom))
+                        await fold(backend, from, current);
+                };
+                await (deps.syncRunner !== undefined ? deps.syncRunner.exclusive(foldAll) : foldAll());
+            }
+            deps.syncRunner?.track(current);
+            return layer.key;
+        },
+    };
+}
+//# sourceMappingURL=memory-project-layer.js.map

package/dist/memory-scope.d.ts

@@ -1,7 +1,7 @@
 import { FileMemoryEngineBackend, type TaskSpec } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import { type ExecutionLane } from "./execution-lane-caps.js";
-import { type MemoryProjectKey } from "./project-identity.js";
+import { type MemoryProjectKey, type ProjectLayerOfTask } from "./project-identity.js";
 /** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
 export declare const V2_SCOPE_PREFIXES: readonly string[];
 /**
@@ -41,17 +41,19 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  * S-512 / [ref] ① —— 这一请求的**项目身份声明**(`TaskSpec.memory.projectKey`)的唯一属主。
  *
  * **一条规则,与车道无关**(主会话 09-23 裁 ②):项目根 = spec 解析出的**真任务根**(`boot/resolve-spec.ts`
- * 的 `realTaskRootOf`,S-177 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求 canonical
- * 项目根并铸 `repo:` 键(in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是
- * 「项目 = 任务根指向的地方」,不需要另一个词);读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、
- * spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,core 铸 operator 通知
- * `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
+ * 的 `realTaskRootOf`,S-177 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求项目身份并铸项目层键
+ * (in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是「项目 = 任务根指向的地方」,不需要另一个词);
+ * 读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,
+ * core 铸 operator 通知 `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
+ *
+ * 🔴 S-640 键形:项目层 = **全局层的属主 × 项目身份**,`userrepo:<属主段>/<档>.<摘要>`(文法 `project-layer-key.ts`,身份 `project-identity.ts`);
+ * 属主 = `projectLayerOwnerOf(scope)`。
  *
  * 🔴 **写家只落复制路径覆盖得到的层**(7.98.0 合并复审 F1,主会话裁「统一规则,不做特判」):写家 = 读列表里、本部署
- * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层,
- * 读列表与 7.97.0 同形 —— 否则开了 `MEMORY_SYNC_*` 的部署会把新记忆写进一个同步腿从不碰的层(静默不同步)。
- * 覆盖面只经 {@link memoryReplicationCoverage} 求(调用点零 `if (memorySync)`);以后项目层同步落地,只改覆盖面的
- * 来源,本规则不动。让位由启动通知 `memory_project_scope_yields_to_sync` 说出来(`config.ts` 记忆域,读同一只覆盖面)。
+ * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层 —— 否则开了
+ * `MEMORY_SYNC_*` 的部署会把新记忆写进一个同步腿从不碰的层(静默不同步)。覆盖面只经 {@link memoryReplicationCoverage} 求(调用点零
+ * `if (memorySync)`);S-640 改的只是覆盖面的**来源**(一条复制路径复制它那一层与同属主的全部项目层),本规则一字不动。让位由启动通知
+ * `memory_project_scope_yields_to_sync` 说出来(`config.ts` 记忆域,读同一只覆盖面与 {@link replicatesProjectLayersOf})。
  * 缺席声明(`{ absent }`)不受覆盖面影响:它本来就写全局层,通知说的是「为什么没有项目层」。
  *
  * 返回 `undefined` 只有三形,都不是「忘了」:
@@ -60,20 +62,25 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  *  · 本任务的项目层不在复制覆盖面里(见上)—— 让位给全局层。
  */
 export declare function memoryProjectKeyFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): MemoryProjectKey | undefined;
+/** {@link memoryProjectKeyFor} 的同一条规则,带上本 checkout 要折进当前层的旧层(`memory-project-layer.ts` 读它)。 */
+export declare function memoryProjectLayerFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): ProjectLayerOfTask | undefined;
 /**
  * 本部署记忆的**复制覆盖面** —— 唯一属主(7.98.0 合并复审 F1)。「复制路径」= 把某一层记忆搬出本机的腿;今天只有一条:
- * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`),它只同步**一层**(`config.memorySync.scope`,core
- * `syncMemoryScope` 按 `scope ===` 取条目)。没有复制路径 ⇒ `unreplicated`(没有哪一层会被复制落下)。
+ * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`)。🔴 S-640:一条复制路径复制**它那一层**(`config.memorySync.scope`)
+ * **以及同一属主的全部项目层**(`userrepo:<属主>/…`,属主 = `projectLayerOwnerOf(那一层)`)—— 同步腿按同一判据选层
+ * (`memory-sync-client.ts` 读 {@link replicationCovers})。没有复制路径 ⇒ `unreplicated`(没有哪一层会被复制落下)。
  */
 export type MemoryReplicationCoverage = {
     readonly kind: "unreplicated";
 } | {
-    readonly kind: "scopes";
-    readonly scopes: readonly string[];
+    readonly kind: "layers";
+    readonly layers: readonly string[];
 };
 export declare function memoryReplicationCoverage(config: Pick<ServiceConfig, "memorySync">): MemoryReplicationCoverage;
-/** 覆盖面是否含这一层(`unreplicated` 含一切)。 */
+/** 覆盖面是否含这一层(`unreplicated` 含一切;复制层本身,或它同属主的项目层)。 */
 export declare function replicationCovers(coverage: MemoryReplicationCoverage, scope: string): boolean;
+/** 覆盖面复制不复制属主 `owner` 的项目层(有一条复制层与它同属主)。启动通知与 {@link replicationCovers} 读同一只判据。 */
+export declare function replicatesProjectLayersOf(coverage: MemoryReplicationCoverage, owner: string): boolean;
 /**
  * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core [ref]) materializes and
  * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
@@ -242,7 +249,7 @@ export declare function memoryStoreRootMovedRefusal(e: unknown): (Error & {
 export declare function memorySpecForRequest(scope: string | undefined, 
 /** S-512 / [ref] ①:本请求的项目身份声明({@link memoryProjectKeyFor} 的产物)。**必填位**(不是可选参数):
  *  每个铸点都得写出一个值 —— `undefined` 只合法地表示「本任务不按项目键控」(多租户 / 记忆暗 / 项目层不在复制覆盖面里)。
- *  · `{ scope: repoKey }` ⇒ 读 = `[repoKey, scope, ...extras]`、`writeScope` **显式** = `repoKey`(core 缺省取末层
+ *  · `{ scope: projectKey }`(S-640 起 `userrepo:…`)⇒ 读 = `[projectKey, scope, ...extras]`、`writeScope` **显式** = 项目层(core 缺省取末层
  *    = 全局层,不钉就是 M-03 本身;core 另有 `config.memory_write_scope_mismatch` 兜这一向);
  *  · `{ absent }` ⇒ 读 = `[scope, ...extras]`、`writeScope` 显式 = `scope`(全局层),core 铸 `memory.project_scope_absent`;
  *  · 两形都把声明原样落 `TaskSpec.memory.projectKey`(core 的生效面回显它)。 */

package/dist/memory-scope.js

@@ -2,7 +2,8 @@ import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
 import { executionLaneCaps, executionLaneOf } from "./execution-lane-caps.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
-import { projectKeyForTaskRoot } from "./project-identity.js";
+import { projectLayerForTaskRoot } from "./project-identity.js";
+import { parseProjectLayerKey, projectLayerOwnerOf } from "./project-layer-key.js";
 const V2_SCOPE_PREFIX_BY_KIND = {
     user: "user:",
     org: "org:",
@@ -28,22 +29,37 @@ export function memoryScopeFor(config, principal, projectId) {
     return config.memoryScope;
 }
 export function memoryProjectKeyFor(config, scope, taskRoot) {
+    return memoryProjectLayerFor(config, scope, taskRoot)?.key;
+}
+export function memoryProjectLayerFor(config, scope, taskRoot) {
     if (config.requirePrincipal === true || scope === undefined)
         return undefined;
-    const declared = projectKeyForTaskRoot(taskRoot);
-    if (declared.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), declared.scope))
+    const layer = projectLayerForTaskRoot(taskRoot, projectLayerOwnerOf(scope));
+    if (layer.key.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), layer.key.scope))
         return undefined;
-    return declared;
+    return layer;
 }
 export function memoryReplicationCoverage(config) {
-    return config.memorySync === undefined ? { kind: "unreplicated" } : { kind: "scopes", scopes: [config.memorySync.scope] };
+    return config.memorySync === undefined ? { kind: "unreplicated" } : { kind: "layers", layers: [config.memorySync.scope] };
 }
 export function replicationCovers(coverage, scope) {
     switch (coverage.kind) {
         case "unreplicated":
             return true;
-        case "scopes":
-            return coverage.scopes.includes(scope);
+        case "layers": {
+            if (coverage.layers.includes(scope))
+                return true;
+            const projectLayer = parseProjectLayerKey(scope);
+            return projectLayer !== undefined && replicatesProjectLayersOf(coverage, projectLayer.owner);
+        }
+    }
+}
+export function replicatesProjectLayersOf(coverage, owner) {
+    switch (coverage.kind) {
+        case "unreplicated":
+            return true;
+        case "layers":
+            return coverage.layers.some((layer) => projectLayerOwnerOf(layer) === owner);
     }
 }
 export function memoryEngineRemoteLanePosture(config) {
@@ -140,7 +156,7 @@ export function memorySpecForRequest(scope, projectKey, memoryWrite, defaultScop
     const projectScope = projectKey?.scope;
     if (projectScope !== undefined && projectScope === scope) {
         throw new Error(`memory project scope ${JSON.stringify(projectScope)} equals the global memory scope (MEMORY_SCOPE) — the project layer and the global layer would be one directory. ` +
-            "Set MEMORY_SCOPE to a name outside the server-minted project-key family (see src/project-identity.ts).");
+            "Set MEMORY_SCOPE to a name outside the server-minted project-key families (see src/project-layer-key.ts).");
     }
     const isV2 = isV2ScopeKey;
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && s !== projectScope && arr.indexOf(s) === i);