@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/tidb-pool.js

@@ -7,12 +7,13 @@ import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_TOMBSTONE_STATEMENTS } from "../stores-sql/retention-store-sql.js";
 import { TIDB_RETENTION_LANE_STATEMENTS } from "./retention-lane-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
+import { SESSION_META_INCARNATION_COLUMN, SESSION_META_LINEAGE_COLUMNS } from "../session-incarnation.js";
 import { ensureSessionExtTableMysql } from "./session-ext-table.js";
+import { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { INBOX_PAYLOAD_COLUMN } from "./inbox-payload-column.js";
-import { PRINCIPAL_MAX_UTF8_BYTES } from "../security.js";
+import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { SESSION_INDEXES } from "../stores-sql/pg-session-storage.js";
@@ -28,7 +29,8 @@ import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
 import { RETENTION_TOMBSTONE_INDEXES } from "../stores-sql/retention-store-sql.js";
 import { RETENTION_LANE_INDEXES } from "./retention-lane-store-sql.js";
 import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
-import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
+import { acquireAdvisoryLock, releaseAdvisoryLock } from "./ensure-schema-lock-policy.js";
+import { SKILL_EXEMPTION_CUTOFF_ID, markIfAbsentSql, migrationMarkerDdl } from "./one-time-migration-marker.js";
 import { createCloseAwarePool } from "./sql-driver.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
@@ -83,6 +85,9 @@ export const SCHEMA_STATEMENTS = [
      -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.mysql},
+     -- fork 谱系(建这一行的那次 fork 的源会话 id + 源行那一刻的住客令牌;只由 fork 的建行写,core forkRowCells 铸):NULL = 不是 fork 建的行,
+     -- 或这两列落地之前建的 fork(源已不可知,不回填)。列定义的唯一属主 = src/session-incarnation.ts 的 SESSION_META_LINEAGE_COLUMNS。
+     ${SESSION_META_LINEAGE_COLUMNS.mysql},
      PRIMARY KEY (session_id),
      KEY idx_session_meta_owner (owner),
      -- listPlaced 的检索腿(kind + 租户 + 年龄升序);普通会话这三列全 NULL ⇒ 不占索引选择性。
@@ -144,6 +149,11 @@ export const SCHEMA_STATEMENTS = [
      -- deliberately-absent idx_error_code note below.
      error_code  VARCHAR(64)  NULL,
      instance_id VARCHAR(64)  NULL,
+     -- leg_id: the HOLDING LEG — minted at every claim (createRun = first leg, markResuming = the resuming leg) and handed to the claimer; a park
+     -- write lands only for the leg that holds the row (setSuspended / setNeedsReview CAS on it). instance_id says WHERE the live leg is (routing),
+     -- leg_id says WHICH leg it is. NULL = no holding leg on record (a row written before the column existed, or created by an earlier-version
+     -- replica; an earlier-version replica's resume claim leaves the column as it found it).
+     leg_id      VARCHAR(36)  NULL,
      -- job_id (work-view correlation substrate): groups the runs of one logical task across BOTH client doors.
      job_id      VARCHAR(64)  NULL,
      -- source (credential-derived system identity, clay 2026-06-12): which door submitted the run
@@ -349,9 +359,14 @@ export const SCHEMA_STATEMENTS = [
      -- 两列同生同灭(stamp 在场 ⇔ 记录在场);reopen 见到记录即拒(已结算的动作不可重开)。
      execution_outcome JSON   NULL,
      execution_at_ms   BIGINT NULL,
+     -- host_session_id:这张卡**归在哪只会话上**(兑现它的那条 run 的会话;cascade 的级上卡 = 调用方的会话,其余 = session_id)。写口 put 由
+     -- plugins/checkpoint-index-columns.ts 的 hostSessionOf 求值一次;存量行由一次性迁移 M49 自 session_id 回填。按会话找卡的读口(决断 / 取消 / 收割 /
+     -- 续跑输入回收 / 运维队列行)只读它;session_id 只答「这是哪段对话」。列定义的唯一属主 = 同模块的 CHECKPOINT_HOST_SESSION_COLUMN。
+     ${CHECKPOINT_HOST_SESSION_COLUMN.mysql},
      PRIMARY KEY (token),
      KEY idx_checkpoint_status_deadline (status, deadline),
-     KEY idx_checkpoint_session_status (session_id, status)
+     KEY idx_checkpoint_session_status (session_id, status),
+     KEY idx_checkpoint_host_session_status (host_session_id, status)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
      session_id    VARCHAR(190) NOT NULL,
@@ -382,22 +397,27 @@ export const SCHEMA_STATEMENTS = [
      expires_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (session_id, nonce),
      KEY idx_approval_nonce_expires (expires_at_ms)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce_floor (
+     singleton CHAR(1) NOT NULL DEFAULT 'x',
+     floor_ms  BIGINT  NOT NULL,
+     PRIMARY KEY (singleton)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
-     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     from_scope      VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      attempts        INT            NOT NULL,
      PRIMARY KEY (from_scope)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
-     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     to_scope        VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      delivered       INT            NOT NULL,
      PRIMARY KEY (to_scope)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
-     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
-     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     to_scope        VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+     from_scope      VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      delivered       INT            NOT NULL,
      PRIMARY KEY (to_scope, from_scope)
@@ -759,6 +779,7 @@ export const SCHEMA_STATEMENTS = [
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    ) COLLATE utf8mb4_bin`,
+    migrationMarkerDdl("mysql"),
     ...TIDB_APPROVAL_ASK_STATEMENTS,
     ...TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS,
     ...TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS,
@@ -802,19 +823,18 @@ export const SCHEMA_STATEMENTS = [
     ...TIDB_RETENTION_TOMBSTONE_STATEMENTS,
 ];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
+const ENSURE_SCHEMA_LOCK_ID = { dialect: "mysql", name: ENSURE_SCHEMA_LOCK };
+const lockConnOf = (conn) => ({
+    query: async (sql, params) => {
+        const [rows] = await conn.query(sql, params);
+        return { rows };
+    },
+});
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
-    await pollUntilLocked(async () => {
-        const [rows] = await conn.query("SELECT GET_LOCK(?, 0) AS got", [ENSURE_SCHEMA_LOCK]);
-        return Number(rows[0]?.got) === 1;
-    }, { tag, label: `GET_LOCK('${ENSURE_SCHEMA_LOCK}')` });
+    await acquireAdvisoryLock(lockConnOf(conn), ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
-    try {
-        await conn.query("SELECT RELEASE_LOCK(?)", [ENSURE_SCHEMA_LOCK]);
-    }
-    catch (err) {
-        console.warn(`[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
-    }
+    await releaseAdvisoryLock(lockConnOf(conn), ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export const SCHEMA_INDEXES = [
     ...CENTRAL_SCHEMA_INDEXES,
@@ -846,6 +866,7 @@ export async function ensureSchema(pool) {
             return Array.isArray(rows) ? rows : [];
         });
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
+        await conn.query(markIfAbsentSql("mysql"), [SKILL_EXEMPTION_CUTOFF_ID, Date.now()]);
         await ensureIndexes((text, params) => conn.query(text, params), "mysql", SCHEMA_INDEXES);
     }
     finally {

package/dist/plugins/web-search.js

@@ -2,7 +2,9 @@ import { validateHeaderValue } from "node:http";
 import { createSearxngSearchBackend } from "@sema-agent/core";
 import { findUrlCredential, findUrlUserinfo, isHierarchicalUrl } from "@sema-agent/settings-schema";
 import { redactSecrets } from "../trace/redact.js";
+import { createEgressFetch } from "../egress-redirect.js";
 import { buildRequestUrlCredentialRefusal, urlCredentialFacts } from "../url-credential-refusal.js";
+import { readUpstreamJson } from "../upstream-body.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);
@@ -99,7 +101,7 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
     const res = await fetchImpl(url, { headers: { Accept: "application/json", "X-Subscription-Token": token }, signal });
     if (!res.ok)
         throw await httpFailure("brave", res);
-    const data = (await res.json());
+    const data = (await readUpstreamJson(res));
     return normalize(data.web?.results, (r) => ({ title: r.title, url: r.url, snippet: r.description }), max, "brave");
 }
 async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
@@ -117,7 +119,7 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
     });
     if (!res.ok)
         throw await httpFailure("tavily", res);
-    const data = (await res.json());
+    const data = (await readUpstreamJson(res));
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "tavily");
 }
 async function searxngSearch(fetchImpl, cfg, query, max, signal, timeoutMs, opts) {
@@ -151,7 +153,7 @@ function redactedBackendFailure(e) {
     return safe === text ? e : new Error(safe);
 }
 export function createWebSearchBackend(cfg) {
-    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const fetchImpl = createEgressFetch("declare the final search address as WEB_SEARCH_ENDPOINT", cfg.fetchImpl);
     const maxResults = Math.max(1, Math.min(20, cfg.maxResults ?? DEFAULT_MAX_RESULTS));
     const timeoutMs = Math.max(1000, cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const search = async (query, signal, opts) => {

package/dist/plugins/workflow-run-store-sql.d.ts

@@ -62,7 +62,7 @@ import type { WorkflowNotifyJournalStore, WorkflowNotifyJournalEntry } from "../
 import { type WorkflowAgentSessionIndex, type WorkflowAgentSessionRow } from "../orchestration/workflow-agent-session-index.js";
 import { type WorkflowParkDecision, type WorkflowParkDecisionStore } from "../orchestration/workflow-park-decision.js";
 import type { SqlRunStore } from "./run-store-sql.js";
-import { type SqlDriver } from "./sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
 type WorkflowRun = Parameters<WorkflowRunStore["put"]>[1];
 /** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
  *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
@@ -148,6 +148,11 @@ export declare class SqlWorkflowRunStore implements WorkflowRunStore {
         keep?: number;
     }): Promise<number>;
 }
+/**
+ * 立一只会话的**清除围栏**(session 全宽,`run_id = ''`;窗 = `PURGE_FENCE_MS`):此后同属主的 enqueue 落空(`purgedOwner` 缺席 = 属主未知 ⇒ 围全部)。
+ * 语句源唯一:信箱自己的 `purge` 与删净会话的执行体(`retention-deployment.ts` 的部署行,在执行体那一个事务里)同调。Upsert = 再清一次刷新窗。
+ */
+export declare function writeInboxPurgeFenceOn(exec: SqlExec, dialect: SqlDialect, sessionId: string, purgedOwner: string | null | undefined, now: number): Promise<void>;
 /** Dual-dialect `WorkflowCompletionInbox`. See the file header for the dialect-delta ledger. */
 export declare class SqlWorkflowCompletionInbox implements WorkflowCompletionInbox {
     protected readonly db: SqlDriver;

package/dist/plugins/workflow-run-store-sql.js

@@ -168,6 +168,16 @@ export class SqlWorkflowRunStore {
 }
 const KIND_SERVED = "served";
 const KIND_PURGE = "purge";
+export async function writeInboxPurgeFenceOn(exec, dialect, sessionId, purgedOwner, now) {
+    const known = purgedOwner !== undefined ? 1 : 0;
+    await exec.query(dialect === "mysql"
+        ? "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
+            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)"
+        : "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
+            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms", dialect === "mysql"
+        ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, known, now + PURGE_FENCE_MS]
+        : [sessionId, KIND_PURGE, purgedOwner ?? null, known, now + PURGE_FENCE_MS]);
+}
 export class SqlWorkflowCompletionInbox {
     db;
     onWarn;
@@ -241,11 +251,7 @@ export class SqlWorkflowCompletionInbox {
     async purge(sessionId, purgedOwner) {
         const now = Date.now();
         await this.sweepFences(now);
-        await this.db.query(this.q("INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)", "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
-            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms"), this.db.dialect === "mysql"
-            ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]
-            : [sessionId, KIND_PURGE, purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]);
+        await writeInboxPurgeFenceOn(this.db, this.db.dialect, sessionId, purgedOwner, now);
         await this.db.query(this.q("DELETE FROM workflow_completion_inbox WHERE session_id = ?", "DELETE FROM workflow_completion_inbox WHERE session_id = $1"), [sessionId]);
     }
     async markTerminalServed(sessionId, runId) {

package/dist/plugins/workspace-custody.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 执行环境工厂的工作区托管表 —— 「这只工作区现在归谁持有 / 能不能删」的唯一答者。local-docker(容器)与 host(本服务铸的临时目录)两条车道的工厂都经它铸环境、读它判删。
+ *
+ * ## 律
+ * 引擎 park-only 契约:`suspendable:false` 的远端环境断言工作区活过环境对象 —— 续跑由工厂重连到**同一只**工作区;引擎在续跑赢下之后丢掉停驻腿的环境、不销毁它
+ * (销毁了就是拆掉续跑腿正在用的工作区)。所以:
+ *  · **一只身份一只工作区**(身份 = 工厂上下文的 `taskId ?? sessionId`,与引擎交给工具的宿主任务号同一读法):同一身份还有一只没开始收场的环境 ⇒ 交回那一只
+ *    (停驻腿的环境引擎还拿着,续跑腿拿到的就是它);那一只正在收场 ⇒ 等它的收场落定再铸,它欠着的账交给新的这只;没有 ⇒ 铸一只入表。
+ *    同一身份同一时刻只有一条腿(会话锁 + run 认领),交回同一只不会让两条腿同时用它。
+ *  · **工作区的生命归持有它的环境,不归铸它的那一只**:表里每一只成员自己说它此刻持有哪只工作区;一只工作区能不能删 = 表里除问者之外还有没有成员持有它
+ *    ({@link WorkspaceCustody.holder})—— 没有才删,有就把删交给最后放手的那一只。
+ *
+ * ## 两条车道怎么读同一张表
+ *  · local-docker:工作区 = 身份派生名的那只容器;一只身份同一时刻只有一只没收场的成员(上面的交回律),容器名又由身份派生 ⇒ 不可能有第二个持有者,成员收场即删
+ *    (读 {@link WorkspaceCustody.envOf};欠账 = 删除没证实的那只容器,交给同一身份的下一只)。
+ *  · host:工作区 = 本服务铸的临时根;委派子代按父的工作目录落根 ⇒ 子代的环境与父的共持那只根(铸时问 {@link WorkspaceCustody.holder}「谁持有包含这一处的根」),
+ *    收场放手时问同一只「还有谁持有它」—— 父收场时子代还停驻在里面 ⇒ 父不删,子代最后一条腿收场时删。
+ *
+ * ## 出表
+ * 成员收场落定、什么都不欠、什么都不持有({@link CustodyMember.settled})⇒ 出表;没收场的成员(停驻腿的环境)一直在表里(停驻中被店层取消 / 过期的,引擎不销毁它,它持有的工作区
+ * 活到进程退出 —— local-docker 的容器由回收器按 run 行收,host 的目录由退出边界收)。
+ */
+/** 表里的一只成员(一只执行环境)向表说的四件事。 */
+export interface CustodyMember<Leftover> {
+    /** 收场的进度:没开始 ⇒ `undefined`(可以交回给同一身份的下一条腿);开始了 ⇒ 那一次收场(落定之后同一身份才铸新的)。 */
+    readonly releasing: Promise<void> | undefined;
+    /** 收场已落定。 */
+    readonly released: boolean;
+    /** 收场之后仍欠着、要交给同一身份下一只环境的账(local-docker:删除没证实的那只容器);不欠 ⇒ `undefined`。 */
+    readonly leftover: Leftover | undefined;
+    /** 什么都不再欠、不再持有 —— 出表。 */
+    readonly settled: boolean;
+}
+export interface WorkspaceCustody<E extends CustodyMember<L>, L> {
+    /**
+     * 这只身份的环境:还有一只没开始收场的 ⇒ 交回它;正在收场的 ⇒ 等它落定(再看一遍);都落定了 ⇒ 拿走欠账、铸一只入表。
+     * `mint` 抛 ⇒ 什么都不入表,原样抛。
+     */
+    envOf(identity: string, mint: (leftover: L | undefined) => E): Promise<E>;
+    /** 表里一只满足 `holds` 的成员(没有 ⇒ `undefined`)—— 「这只工作区现在还有谁持有」的唯一读法:问者把自己排除在 `holds` 里。 */
+    holder(holds: (member: E) => boolean): E | undefined;
+}
+export declare function createWorkspaceCustody<E extends CustodyMember<L>, L = never>(): WorkspaceCustody<E, L>;
+//# sourceMappingURL=workspace-custody.d.ts.map

package/dist/plugins/workspace-custody.js

@@ -0,0 +1,47 @@
+export function createWorkspaceCustody() {
+    const members = new Map();
+    const sweep = () => {
+        for (const member of members.keys())
+            if (member.settled)
+                members.delete(member);
+    };
+    return {
+        async envOf(identity, mint) {
+            for (;;) {
+                sweep();
+                const closing = [];
+                const owing = [];
+                for (const [member, id] of members) {
+                    if (id !== identity)
+                        continue;
+                    if (member.releasing === undefined)
+                        return member;
+                    if (!member.released)
+                        closing.push(member.releasing);
+                    else if (member.leftover !== undefined)
+                        owing.push(member);
+                }
+                if (closing.length > 0) {
+                    await Promise.allSettled(closing);
+                    continue;
+                }
+                let leftover;
+                for (const member of owing) {
+                    leftover = member.leftover;
+                    members.delete(member);
+                }
+                const env = mint(leftover);
+                members.set(env, identity);
+                return env;
+            }
+        },
+        holder(holds) {
+            sweep();
+            for (const member of members.keys())
+                if (holds(member))
+                    return member;
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=workspace-custody.js.map

package/dist/principal-jwt.d.ts

@@ -1,5 +1,6 @@
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
 import { type ApprovalEnvelope } from "./approval-hmac.js";
+import { type Person } from "./owner-brands.js";
 /**
  * 验签允许的**时钟不一致容差**(秒)—— 本仓这条轴上的单一来源。
  *
@@ -45,8 +46,6 @@ export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[
  * 形:`sha256(utf8(editedPlan))` hex —— 与 `approvalBnd` 同摘要、同编码;逐字节,不归一化(签名器与 worker
  * 必须对同一串字节达成一致,任何"归一化"都是第二个写者)。
  */
-/** 良构 Unicode(无孤立代理项)。`u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。 */
-export declare function isWellFormedUnicode(s: string): boolean;
 export declare function editedPlanBinding(editedPlan: string): string;
 /**
  * JWT `cnf.bnd` = **「这份身份凭据被签发去决哪一张卡」**(动作身份),故只哈希前三位。
@@ -79,10 +78,11 @@ export interface SingleUseProof {
      */
     readonly acceptedBeforeMs: number;
 }
-/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。 */
+/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。`principal` = 这一次决定的证明推出的人
+ *  (带 `Person` 品牌:本函数是它的铸点之一 —— 决定口用它替换请求身份,`http/owner-access.ts` 的 `callerOfDecision` 按请求的场景铸决定者的主体)。 */
 export type DirectDoorProofResult = {
     ok: true;
-    principal: string;
+    principal: Person;
     singleUse?: SingleUseProof;
 } | {
     ok: false;

package/dist/principal-jwt.js

@@ -1,5 +1,7 @@
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
+import { mintPerson } from "./owner-brands.js";
+import { PRINCIPAL_MAX_BYTES, isWellFormedUnicode, principalShapeProblem } from "./principal-shape.js";
 export const PRINCIPAL_JWT_CLOCK_SKEW_SEC = 30;
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
@@ -72,9 +74,6 @@ export function verifyPrincipalJwt(token, keys, expect) {
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
     return { sub: payload.sub, bnd, acceptedBeforeMs: (Math.floor(payload.exp + skew) + 1) * 1000 };
 }
-export function isWellFormedUnicode(s) {
-    return !/\p{Surrogate}/u.test(s);
-}
 export function editedPlanBinding(editedPlan) {
     if (!isWellFormedUnicode(editedPlan))
         throw new Error("editedPlanBinding: editedPlan is not well-formed Unicode (lone surrogate) — utf8 hashing would be lossy");
@@ -104,8 +103,24 @@ export function verifyDirectDoorProof(proof, envelope, config, opts) {
     const ok = verifyApprovalHmac(envelope, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
+    const shape = principalShapeProblem(verified.sub);
+    switch (shape) {
+        case undefined:
+            break;
+        case "not_a_name":
+            return { ok: false, status: 400, errorCode: "principal_not_a_name", error: "principal token subject is not a principal name — the issuer must sign a visible-character identity" };
+        case "reserved":
+            return { ok: false, status: 400, errorCode: "principal_reserved", error: "principal token subject is a reserved identifier (an internal scope sentinel or a scenario subject) — the issuer must sign the person's own identifier" };
+        case "too_long":
+            return { ok: false, status: 400, errorCode: "principal_too_long", error: `principal token subject exceeds ${PRINCIPAL_MAX_BYTES} UTF-8 bytes` };
+        default: {
+            const unknownShape = shape;
+            throw new Error(`verifyDirectDoorProof: unknown principal shape problem ${String(unknownShape)}`);
+        }
+    }
+    const principal = mintPerson(verified.sub);
     return actionBinding
-        ? { ok: true, principal: verified.sub }
-        : { ok: true, principal: verified.sub, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
+        ? { ok: true, principal }
+        : { ok: true, principal, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
 }
 //# sourceMappingURL=principal-jwt.js.map

package/dist/principal-shape.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 🔴 **主体长度的唯一定义:至多这么多个 UTF-8 字节。** 凡判「这只串当不当得了主体 / 主体身份键」的长度,一律读它、按字节数(`Buffer.byteLength(s, "utf8")`):
+ * 本文件的判官、收件箱的键判官(收件箱 scope 就是主体)、记忆退出名单的判、两处运维 `?scope=` 查询、规则面的运维目标、配额三表两方言的身份列宽。
+ * 为什么是字节:主体原样落进的最窄一类列是按字节计宽的 `VARBINARY(190)`(收件箱 / 后台子代 / 名册的键列);按字符计宽的 `VARCHAR(190)`(TiDB utf8mb4 与 PG
+ * 都数码点)装得下任何 190 字节的串(一个码点至少一个字节)。所以 190 字节 ≤ 「190 家族」每一只主体列,升到本尺不需要改任何既有列。
+ * 不同源的 190(会话 / run / 工具调用 id 列的历史宽度惯例、断路器键、跨会话信封来源位、编码后的记忆 scope 列、令牌 scope 声明)不读本常量。
+ */
+export declare const PRINCIPAL_MAX_BYTES = 190;
+/**
+ * 良构 Unicode(无孤立代理项)的唯一判式 —— 主体名判官的一格(下面),也是收件箱键判官与编辑计划绑定摘要的同一读法(住在叶子里,三处都能值导入、不成环)。
+ * `u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。
+ */
+export declare function isWellFormedUnicode(s: string): boolean;
+/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
+ *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
+ *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的超范围面。
+ *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
+ *  resource-suspend scope family); `"__none__"` = the missing-principal read placeholder of the approval
+ *  queue faces up to 7.132.x (7.133.0 reads the anonymous group `"_"` instead; still reserved because a 7.132.x replica in the same
+ *  rolling upgrade lists that scope for anonymous callers, so a tenant by that name would merge with them there); `"_leader"` = leader durable-approval scope
+ *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts); prefix `"_orphan:"` = the owner written on a delegated session whose
+ *  delegation ancestors are gone (`_orphan:<sessionId>`, src/delegated-session-owner.ts) — a caller allowed to authenticate as it
+ *  would read that transcript; prefix `"_scn:"` = a subject that carries a scenario (`_scn:<scenario>:<person>`, `owner-brands.ts` `subjectOf`) —
+ *  a caller allowed to authenticate as it would BE another person's scenario partition. NB the `_leader-` prefix REQUIRES the hyphen — a tenant named
+ *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
+export declare const RESERVED_PRINCIPALS: readonly string[];
+export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
+/** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
+ *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
+ *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
+ *  principal) reads the verdict instead of catching the throw.
+ *
+ *  Order: "is it a name at all" first — the other two rules presuppose a name (a reserved identifier / a name too wide for the
+ *  column), and the `reserved` sentence echoes the value while the `not_a_name` sentence never does (a string that names nobody may be a
+ *  pasted credential). An empty string is `not_a_name` here (the engine's judge says so); so is a string that is not well-formed Unicode (a lone
+ *  surrogate is no character). A header reader that treats a blank header as "no principal" decides that before asking. `too_long` counts UTF-8 bytes
+ *  ({@link PRINCIPAL_MAX_BYTES}). */
+export type PrincipalShapeProblem = "not_a_name" | "reserved" | "too_long";
+export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
+//# sourceMappingURL=principal-shape.d.ts.map

package/dist/principal-shape.js

@@ -0,0 +1,19 @@
+import { principalNameOf } from "@sema-agent/core";
+import { ORPHAN_SESSION_OWNER_PREFIX } from "./delegated-session-owner.js";
+import { SCENARIO_SUBJECT_PREFIX } from "./owner-brands.js";
+export const PRINCIPAL_MAX_BYTES = 190;
+export function isWellFormedUnicode(s) {
+    return !/\p{Surrogate}/u.test(s);
+}
+export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
+export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-", ORPHAN_SESSION_OWNER_PREFIX, SCENARIO_SUBJECT_PREFIX];
+export function principalShapeProblem(principal) {
+    if (principalNameOf(principal) === undefined || !isWellFormedUnicode(principal))
+        return "not_a_name";
+    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
+        return "reserved";
+    if (Buffer.byteLength(principal, "utf8") > PRINCIPAL_MAX_BYTES)
+        return "too_long";
+    return undefined;
+}
+//# sourceMappingURL=principal-shape.js.map

package/dist/project-identity.d.ts

@@ -25,16 +25,17 @@ export declare function assertProjectLayerOwnable(scope: string, envName: string
  */
 export declare function normalizeGitRemoteUrl(url: string): string | undefined;
 /**
- * 任务根 → 项目层身份([ref]):当前档(`r` 优先,没有 origin 退 `p`)+ 本 checkout 的低档(`r` 档时 = 它的 `p` 档)。
- * 缺席形 = 找根的缺席词(`bare` / `unreadable`);git 配置在而读不了 ⇒ `unreadable`。
+ * 任务根 → 项目层身份(文件头「项目身份一条律」):按档序(`project-layer-key.ts` `PROJECT_IDENTITY_TIERS`)取本检出有的各档 ——
+ * 每一档 = 它的身份文本的 {@link digest24}(`m`:记号里的项目 id;`r`:归一后的网络 origin;`p`:canonical 项目根,恒有)。
+ * 链首 = 当前档,其余 = `lowerTiers`(折叠来源)。缺席 = 找根的缺席词(`bare` / `unreadable`);git 配置在而读不了、或记号读不出 ⇒ `unreadable`。
  */
-export declare function projectLayerIdentityOf(taskRoot: string): {
+export declare function projectLayerIdentityOf(taskRoot: string): Promise<{
     readonly root: string;
     readonly identity: ProjectLayerIdentity;
     readonly lowerTiers: readonly ProjectLayerIdentity[];
 } | {
     readonly absent: ProjectIdentityAbsentReason;
-};
+}>;
 /** 一个任务的项目层:core 声明席 + 本 checkout 要折进来的低档 / 退役层(按序,`memory-project-layer.ts` 折)。 */
 export interface ProjectLayerOfTask {
     readonly key: MemoryProjectKey;
@@ -43,11 +44,11 @@ export interface ProjectLayerOfTask {
 /**
  * 任务根 → 项目层([ref]:`userrepo:<属主段>/<档>.<摘要>`,属主 = `owner`,调用方由 `projectLayerOwnerOf(全局层)` 求得)。
  * `foldFrom` = 同一 checkout 能推出的旧层:退役 `repo:<同一路径哈希>`(一次性迁移,窗见 `plugins/one-time-migrations.ts` 登记表 M25)
- * + 当前档是 `r` 时它的 `p` 档(常设律)。
+ * + 当前档之下的每一档(常设律:`m` 档折 `r` / `p`,`r` 档折 `p`)。
  * `taskRoot === undefined` = 调用方**此刻不知道**任务根在本机哪里(根在沙箱/设备盘上;或 host 车道会话没登记 cwd、手落在 factory 现铸的
  * 临时目录)⇒ `unreadable` —— 「我看不到」,不是「这里没有项目」。
  */
-export declare function projectLayerForTaskRoot(taskRoot: string | undefined, owner: string): ProjectLayerOfTask;
+export declare function projectLayerForTaskRoot(taskRoot: string | undefined, owner: string): Promise<ProjectLayerOfTask>;
 /** {@link projectLayerForTaskRoot} 的声明席投影(core `TaskSpec.memory.projectKey`)。 */
-export declare function projectKeyForTaskRoot(taskRoot: string | undefined, owner: string): MemoryProjectKey;
+export declare function projectKeyForTaskRoot(taskRoot: string | undefined, owner: string): Promise<MemoryProjectKey>;
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/project-identity.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { encodeScopeSegment } from "@sema-agent/core";
-import { mintProjectLayerKey, PROJECT_LAYER_KEY_PREFIX, projectLayerOwnerOf } from "./project-layer-key.js";
+import { encodeScopeSegment, NodeExecutionEnv, resolveProjectId } from "@sema-agent/core";
+import { errorCodeOf } from "./observability/err-text.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { mintProjectLayerKey, PROJECT_IDENTITY_TIERS, PROJECT_LAYER_KEY_PREFIX, projectLayerOwnerOf } from "./project-layer-key.js";
 const UNREADABLE = { absent: "unreadable" };
 const BARE = { absent: "bare" };
 function isMissing(err) {
@@ -87,10 +89,7 @@ function canonicalTaskRoot(taskRoot) {
         p = parent;
     }
 }
-function locateProject(taskRoot) {
-    const root = canonicalTaskRoot(taskRoot);
-    if (root === "unreadable")
-        return UNREADABLE;
+function locateProject(root) {
     let sawBareLayout = false;
     for (let dir = root.existing;;) {
         const dotGit = statFact(join(dir, ".git"));
@@ -240,23 +239,47 @@ export function normalizeGitRemoteUrl(url) {
 function cleanRemotePath(p) {
     return p.replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
 }
-export function projectLayerIdentityOf(taskRoot) {
-    const located = locateProject(taskRoot);
+async function markerFact(canonicalTaskRoot) {
+    try {
+        const marker = await resolveProjectId(new NodeExecutionEnv({ cwd: canonicalTaskRoot }), canonicalTaskRoot);
+        return marker === null ? "missing" : { ok: marker.projectId };
+    }
+    catch (err) {
+        recordFailOpen("server.memory.project-marker-unreadable", `code=${errorCodeOf(err) ?? "-"}`);
+        return "unreadable";
+    }
+}
+export async function projectLayerIdentityOf(taskRoot) {
+    const canonical = canonicalTaskRoot(taskRoot);
+    if (canonical === "unreadable")
+        return UNREADABLE;
+    const located = locateProject(canonical);
     if (!("root" in located))
         return located;
-    const path = { tier: "p", digest: digest24(located.root) };
     const origin = located.gitConfig !== undefined ? readOriginRemoteUrl(located.gitConfig) : "missing";
     if (origin === "unreadable")
         return UNREADABLE;
-    const remote = origin === "missing" || origin.ok === undefined ? undefined : normalizeGitRemoteUrl(origin.ok);
-    if (remote === undefined)
-        return { root: located.root, identity: path, lowerTiers: [] };
-    return { root: located.root, identity: { tier: "r", digest: digest24(remote) }, lowerTiers: [path] };
+    const marker = await markerFact(canonical.canonical);
+    if (marker === "unreadable")
+        return UNREADABLE;
+    const identityText = {
+        m: marker === "missing" ? undefined : marker.ok,
+        r: origin === "missing" || origin.ok === undefined ? undefined : normalizeGitRemoteUrl(origin.ok),
+        p: located.root,
+    };
+    const chain = PROJECT_IDENTITY_TIERS.flatMap((tier) => {
+        const text = identityText[tier];
+        return text === undefined ? [] : [{ tier, digest: digest24(text) }];
+    });
+    const [identity, ...lowerTiers] = chain;
+    if (identity === undefined)
+        return UNREADABLE;
+    return { root: located.root, identity, lowerTiers };
 }
-export function projectLayerForTaskRoot(taskRoot, owner) {
+export async function projectLayerForTaskRoot(taskRoot, owner) {
     if (taskRoot === undefined)
         return { key: UNREADABLE, foldFrom: [] };
-    const id = projectLayerIdentityOf(taskRoot);
+    const id = await projectLayerIdentityOf(taskRoot);
     if (!("identity" in id))
         return { key: { absent: id.absent }, foldFrom: [] };
     return {
@@ -264,7 +287,7 @@ export function projectLayerForTaskRoot(taskRoot, owner) {
         foldFrom: [mintRepoScopeKey(id.root), ...id.lowerTiers.map((tier) => mintProjectLayerKey(owner, tier))],
     };
 }
-export function projectKeyForTaskRoot(taskRoot, owner) {
-    return projectLayerForTaskRoot(taskRoot, owner).key;
+export async function projectKeyForTaskRoot(taskRoot, owner) {
+    return (await projectLayerForTaskRoot(taskRoot, owner)).key;
 }
 //# sourceMappingURL=project-identity.js.map

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

@@ -1,7 +1,18 @@
 /** 项目层键的前缀(改名链的前缀词表也读它)。 */
 export declare const PROJECT_LAYER_KEY_PREFIX = "userrepo:";
-/** 身份档:`r` = 仓库身份(origin 远端,跨设备),`p` = 项目根路径(本机)。 */
-export type ProjectIdentityTier = "r" | "p";
+/** 身份档:`m` = 检出的记号(项目 id),`r` = 仓库身份(origin 远端,跨设备),`p` = 项目根路径(本机)。 */
+export type ProjectIdentityTier = "m" | "r" | "p";
+/**
+ * **档序**(高 → 低)—— 唯一成文处。两只读者:
+ *  · 一只检出的档链(`project-identity.ts` `projectLayerIdentityOf`):按本序取它有的各档,链首 = 当前档,其余 = 折叠来源(低档);
+ *  · 同步轮的层序({@link compareProjectLayersForSync}):低档先于高档。
+ */
+export declare const PROJECT_IDENTITY_TIERS: readonly ProjectIdentityTier[];
+/**
+ * 同步轮里两只项目层键的先后:**低档在前**,同档按键序。折叠把条目从低档搬到高档、id 保留 ⇒ 同一轮先在源层推删除、再在高档推新增,
+ * 中心那一侧同一个 id 不会先撞上源层里的自己。不是项目层的键(调用方本不该给)排在最后。
+ */
+export declare function compareProjectLayersForSync(a: string, b: string): number;
 /** 一个项目的身份段(档 + 24 位小写十六进制摘要)。 */
 export interface ProjectLayerIdentity {
     readonly tier: ProjectIdentityTier;

package/dist/project-layer-key.js

@@ -1,7 +1,15 @@
 import { decodeScopeSegment, encodeScopeSegment, parseScopeKey } from "@sema-agent/core";
 export const PROJECT_LAYER_KEY_PREFIX = "userrepo:";
+export const PROJECT_IDENTITY_TIERS = ["m", "r", "p"];
+export function compareProjectLayersForSync(a, b) {
+    const rank = (key) => {
+        const tier = parseProjectLayerKey(key)?.identity.tier;
+        return tier === undefined ? -1 : PROJECT_IDENTITY_TIERS.indexOf(tier);
+    };
+    return rank(b) - rank(a) || (a < b ? -1 : a > b ? 1 : 0);
+}
 const DIGEST = /^[0-9a-f]{24}$/;
-const KEY = /^userrepo:((?:[A-Za-z0-9._-]|%[0-9A-F]{2})+)\/([rp])\.([0-9a-f]{24})$/;
+const KEY = /^userrepo:((?:[A-Za-z0-9._-]|%[0-9A-F]{2})+)\/([mrp])\.([0-9a-f]{24})$/;
 export function projectLayerOwnerOf(globalScope) {
     const parsed = parseScopeKey(globalScope);
     return parsed.kind === "user" ? parsed.principal : globalScope;