@sema-agent/server 7.90.0 → 7.91.2

package/dist/peer-directory.d.ts

@@ -0,0 +1,114 @@
+/**
+ * [ref] —— core `RunnerDeps.peerDirectory` 的 server 部署席(跨会话互传消息的 server 半场,设计稿
+ * `sema-internal/server/designs/2026-09-19-s72-peer-directory-seat-v1.md` v1.1)。
+ *
+ * ## 一句话
+ *
+ * **目录不是一张要人维护的注册表,是会话列表面那一张派生视图的第二个读者。** 零新注册表、零新写家:
+ * `listPeerSessions({scope})` 每次经**会话枚举面那只同一个函数**(`GET /v1/sessions` 用的那只
+ * `listSessions`)读出来,再把 mailbox 侧的墓碑行(已删会话)并进去。
+ *
+ * ## 为什么复用那只 lister,而不是自己写一条 JOIN(设计稿 §2 给的是 SQL 形,这里收得更紧)
+ *
+ * 设计稿 §4-1 的承重条款是「**成员资格 = 会话读面的那一只属主可读谓词,一字不另写**」。自己写一条 JOIN
+ * 就必须自己带一份属主谓词 —— 那正是兔子洞 S-487「属主判定单一存取器」要消灭的第 10 处手抄,而且两份
+ * 谓词**一定**会漂(存量 `owner IS NULL` 的窄互认臂、`placement_kind IS NULL` 的 [ref] 义务、keyset 排序
+ * 口径三条都要各抄一遍)。改读同一只 `listSessions` 之后,**成员资格**不再是一条需要测试盯住的断言,
+ * 而是结构上的同一次调用;SQL 面因此也一个字节都不用改。
+ *
+ * ⚠️ **共享的是谓词,不是最终集合**(codex 对抗复审 r1 ② 采纳,如实收窄 —— 稿里与本注初版都写成了
+ * 「两面集合相等」,那是**过度承诺**):两面在下面这些地方按设计给出不同的集合,逐条都不是 bug ——
+ *  · **fleet-wide 调用方**:`GET /v1/sessions` 对 service-token / dev-open 形不钉 owner、还认 `?owner=`
+ *    (运维视图);目录**只**按 core 递进来的那一个 scope 分区,永不跨;
+ *  · **分页与搜索**:那条路由有 `?limit`/`?cursor`/`?q=`,目录是一次定量读(见 {@link PEER_DIRECTORY_CAP});
+ *  · **peer 可寻址性过滤**:语法外 / 非小写规范形 / 与别条会话折到同一只箱的 id 都不入目录(下面那道
+ *    单射门),那条路由照列;
+ *  · **墓碑**:目录会多出「正在删除中」的 `deleted` 记录,那条路由不列;
+ *  · **席位差**:那条路由还有 `runStore.listSessions` 的 legacy 兜底,本席刻意不并(见装配点的注)。
+ * 机器钉因此只钉「同一 principal、无 q、无分页、量在 cap 内」那一格的集合相等(它是那条承重条款的
+ * 可执行投影),别把它读成两面恒等。
+ *
+ * ⚠️ 与设计稿的第二处收紧(亲读实现推翻稿面):稿里把谓词写成 `principal-gate.ts runOwnerReadable`。
+ * 亲读两只函数后不成立 —— `runOwnerReadable(p, owner, cfg)` 对 `owner === null` **无条件**放行
+ * (`principal-gate.ts:136-137`,函数体第一行),而**列表面**的第三条件由 store 的
+ * `owner = ? OR owner IS NULL` 承载,开关是 `legacyUnownedAmnestyOpen(requirePrincipal, gateOwner)`
+ * (`security.ts:119`,它的头注逐字:
+ * 「单独存在的唯一理由是**列表面**……单实体读/写点一律用三条件齐的 `legacyUnownedSessionOk`」)。
+ * 拿 `runOwnerReadable` 当列表谓词会让目录比 `GET /v1/sessions` **多列出**别人的无主会话 —— 正好违反
+ * 稿子自己那条对拍。所以这里用的是列表面那一只:`legacyUnownedAmnestyOpen` + 同一个 lister。
+ *
+ * ## scope 轴
+ *
+ * core 递进来的 `access.scope` = `taskScope` = `internals?.registryScope ?? spec.principal ?? "default"`
+ * (core `prepare-task.js`)× server `resolve-spec.ts:701 principal: auth?.principal` ⇒ **裸 principal 串**,
+ * 无 principal 的部署上是字面量 `"default"`,而同一情形下 `session_meta.owner` 是 SQL NULL ——
+ * 这正是窄互认臂(`LEGACY_UNOWNED_AMNESTY_TENANT === "default"`)要接住的那一格,不必另铸编解码。
+ *
+ * ## 各字段的**唯一**来源(设计稿 §2 表;这里不许出现第二处算法)
+ *
+ *  · `schemaVersion` = core 常量 `PEER_SESSION_RECORD_SCHEMA_VERSION`(不手抄数字);
+ *  · `sessionId` = 会话行 id;过不了 core `isPeerSessionId` 的行、以及**箱句柄不是本 scope 独占**的行
+ *    (非小写规范形 / 与别的会话折到同一只箱)**不入视图并计数披露**(不静默,见下方单射门);
+ *  · `scope` = 查询参数原样(视图永不跨 scope —— 这就是设计稿 §4-3 那堵墙的全部实现);
+ *  · `name` = `title`,空 ⇒ `session-<id 前 8>`,`nameSource: "auto"`;
+ *  · `startedAt`/`updatedAt` = 会话行的 `firstActivityAt`/`lastActivityAt`;
+ *  · `liveness` = **会话行在 ⇒ `"live"`**;`"deleted"` 来自 mailbox 墓碑(= 删除级联**在飞**那段窗口;
+ *    墓碑随箱亡,级联跑完之后那个 id 就是「不存在」—— 理由全文在 `plugins/mailbox-recipient-lifecycle.ts`),
+ *    同句柄上**墓碑压过活行**;**`"dead"` v1 不铸**
+ *    (core `list-agents-tool.js:60` 跳过 deleted 行、`:62` 默认跳过 dead 行 —— 行号读的是**装树里的 7.24.2**
+ *    dist,7.23.5 上是 `:49`/`:51`;⇒ 把闲置会话映成 dead
+ *    等于把用户自己的闲置会话从 `ListAgents` 里藏掉,正是本席要解的那个面。忙闲一律走 `tempo`);
+ *  · `tempo` = `sessionTempoOfRunStatus(lastStatus)`(`plugins/store-contracts.ts` 的那**一张**表,
+ *    `GET /v1/sessions` 的 `tempo` 列读的是同一只函数 —— 一处定义两处读);
+ *  · `inboundPosture` = managed 层 `crossSessionInbound === "refuse"` ⇒ `"unavailable"`,否则 `"available"`;
+ *  · `pid` / `procStartMs` / `sockPath` / `cwd` = **恒缺席**(server 会话是耐久可寻址实体,不是进程;
+ *    缺席即 core 的探活臂按 `isPeerSessionProcessAlive` 直接跳过);
+ *  · `peerProtocol` / `peerFeatures` = 不铸(v1 不声明 CC 能力位;core 侧全 optional)。
+ */
+import { type PeerDirectory } from "@sema-agent/core";
+import type { CrossSessionInboundSettingLayers } from "@sema-agent/core";
+import type { Logger } from "./observability/logger.js";
+import type { MailboxRecipientLifecycle } from "./plugins/mailbox-recipient-lifecycle.js";
+import { type SessionListItem } from "./security.js";
+/** 会话枚举面(= `GET /v1/sessions` 用的那只 `OwnerAwareSessionStore.listSessions`)。 */
+export type PeerSessionLister = (opts: {
+    owner?: string;
+    includeUnowned?: boolean;
+    cursor?: {
+        lastActivityAt: string;
+        sessionId: string;
+    };
+    limit: number;
+    q?: string;
+}) => Promise<SessionListItem[]>;
+/**
+ * 一次 `listPeerSessions` 最多铸多少行。
+ *
+ * 🔴 为什么要有上界、而且是**常量**:core 的 ref 铸造(`mintPeerSessionCandidates`)跑在**全集**上,而
+ * `ListAgents` 的结果还有 10 000 字符的硬上界(`LIST_AGENTS_MAX_RESULT_CHARS`)—— 没有上界的话一个有
+ * 几千条会话的 principal 会让每一次 turn 边界都拉一张巨表。做成部署旋钮会多一个「两台机器答案不同」的
+ * 轴(ref 的稳定性依赖集合本身),而这个数字不是策略、是防呆:超出即**响亮截断并计数**(见
+ * `peer_directory_truncated`),不静默。
+ */
+export declare const PEER_DIRECTORY_CAP = 200;
+export interface PeerDirectorySeatCtx {
+    /** 会话枚举面;缺席 ⇒ 不给席(装配点判,见 `boot/runner-deps.ts`)。 */
+    lister: PeerSessionLister;
+    /** mailbox 的收件人生命周期面(墓碑读 + 被活行压过的墓碑撤回)。 */
+    lifecycle: MailboxRecipientLifecycle;
+    /** `config.requirePrincipal` —— 窄互认臂的条件①(与列表面同一个开关)。 */
+    requirePrincipal: boolean;
+    /** managed 层的 `crossSessionInbound` 供层(`cross-session-settings.ts` 的既有解析,不新写)。 */
+    crossSessionInbound: CrossSessionInboundSettingLayers | undefined;
+    logger: Logger;
+}
+/**
+ * peer 目录席 —— `create*`(带行为的对象:每次调用都真读一次两个面)。
+ *
+ * 只实现 `listPeerSessions`。**`restorePeerSession` 刻意不实现**:core 的接口注逐字写着「a directory that
+ * cannot write (a server session table the engine only reads) omits it, and the residual window is disclosed
+ * in the receipt instead」—— 本席读的是会话账,会话行不是由 peer 车道创建的,写回去等于让 peer 车道
+ * 凭一次投递**造出**一条会话行。
+ */
+export declare function createPeerDirectory(ctx: PeerDirectorySeatCtx): PeerDirectory;
+//# sourceMappingURL=peer-directory.d.ts.map

package/dist/peer-directory.js

@@ -0,0 +1,136 @@
+import { PEER_SESSION_RECORD_SCHEMA_VERSION, isPeerSessionId, peerSessionBoxHandle, SESSION_BOX_PREFIX, } from "@sema-agent/core";
+import { sessionTempoOfRunStatus } from "./plugins/store-contracts.js";
+import { legacyUnownedAmnestyOpen } from "./security.js";
+export const PEER_DIRECTORY_CAP = 200;
+function autoName(sessionId) {
+    return `session-${sessionId.slice(0, 8)}`;
+}
+function sessionIdOfBoxHandle(handle) {
+    return handle.slice(SESSION_BOX_PREFIX.length);
+}
+export function createPeerDirectory(ctx) {
+    const { lister, lifecycle, requirePrincipal, crossSessionInbound, logger } = ctx;
+    return {
+        listPeerSessions: async (access) => {
+            const scope = access.scope;
+            const includeUnowned = legacyUnownedAmnestyOpen(requirePrincipal, scope);
+            const rows = await lister({ owner: scope, ...(includeUnowned ? { includeUnowned: true } : {}), limit: PEER_DIRECTORY_CAP + 1 });
+            const truncated = rows.length > PEER_DIRECTORY_CAP;
+            if (truncated) {
+                logger.warn("peer_directory_truncated", {
+                    scope,
+                    cap: PEER_DIRECTORY_CAP,
+                    note: "this principal has more sessions than the peer directory lists in one read — the sessions beyond the cap are NOT addressable on the cross-session lane this turn (newest-first by last activity, so the oldest drop out)",
+                });
+            }
+            const posture = crossSessionInbound?.managed === "refuse" ? "unavailable" : "available";
+            let tombstones = [];
+            try {
+                tombstones = await lifecycle.listRetiredRecipients(scope, SESSION_BOX_PREFIX);
+            }
+            catch (err) {
+                logger.warn("peer_directory_tombstones_unreadable", { scope, err: String(err) });
+            }
+            const retired = new Map();
+            for (const t of tombstones) {
+                if (!t.handle.startsWith(SESSION_BOX_PREFIX))
+                    continue;
+                retired.set(t.handle, t);
+            }
+            const out = [];
+            let ungrammatical = 0;
+            let notCanonical = 0;
+            const byBox = new Map();
+            for (const [i, r] of rows.entries()) {
+                if (!isPeerSessionId(r.sessionId)) {
+                    if (i < PEER_DIRECTORY_CAP)
+                        ungrammatical += 1;
+                    continue;
+                }
+                const handle = peerSessionBoxHandle(r.sessionId);
+                const g = byBox.get(handle) ?? { handle, ids: [], rows: [] };
+                if (g.ids.includes(r.sessionId)) {
+                    logger.warn("peer_directory_duplicate_session_row", { scope, box: handle, kept: r.sessionId, dropped: r.sessionId });
+                    continue;
+                }
+                g.ids.push(r.sessionId);
+                g.rows.push({ row: r, inPage: i < PEER_DIRECTORY_CAP });
+                byBox.set(handle, g);
+            }
+            const foldCollisions = [];
+            for (const g of byBox.values()) {
+                if (g.ids.length > 1) {
+                    foldCollisions.push({ box: g.handle, sessions: [...g.ids] });
+                    continue;
+                }
+                const only = g.rows[0];
+                if (!only.inPage)
+                    continue;
+                const r = only.row;
+                if (r.sessionId !== r.sessionId.toLowerCase()) {
+                    notCanonical += 1;
+                    continue;
+                }
+                if (retired.has(g.handle))
+                    continue;
+                const started = Date.parse(r.firstActivityAt);
+                const updated = Date.parse(r.lastActivityAt);
+                const tempo = sessionTempoOfRunStatus(r.lastStatus);
+                out.push({
+                    schemaVersion: PEER_SESSION_RECORD_SCHEMA_VERSION,
+                    sessionId: r.sessionId,
+                    scope,
+                    name: r.title !== null && r.title.trim() !== "" ? r.title : autoName(r.sessionId),
+                    nameSource: "auto",
+                    startedAt: Number.isFinite(started) ? started : 0,
+                    updatedAt: Number.isFinite(updated) ? updated : 0,
+                    liveness: "live",
+                    ...(tempo !== undefined ? { tempo } : {}),
+                    inboundPosture: posture,
+                });
+            }
+            if (ungrammatical > 0) {
+                logger.warn("peer_directory_ungrammatical_sessions_skipped", {
+                    scope,
+                    skipped: ungrammatical,
+                    grammar: "^[A-Za-z0-9_-]{1,80}$",
+                    note: "these sessions exist and are listed by GET /v1/sessions, but their ids cannot be spelled as a `session.<id>` peer address — they are neither addressable nor drainable on the cross-session lane (the engine refuses the lane for such a session by name, `peer.session_id_ungrammatical`)",
+                });
+            }
+            if (notCanonical > 0) {
+                logger.warn("peer_directory_non_canonical_sessions_skipped", {
+                    scope,
+                    skipped: notCanonical,
+                    note: "these sessions exist and are listed by GET /v1/sessions, but their ids are not lower-case canonical — the peer box handle folds to lower case, so publishing them could not keep the id→box mapping injective. They are NOT addressable on the cross-session lane; mint lower-case session ids to use it",
+                });
+            }
+            for (const c of foldCollisions) {
+                logger.warn("peer_directory_session_id_case_fold_collision", {
+                    scope,
+                    box: c.box,
+                    sessions: c.sessions,
+                    note: "these sessions of this principal fold to the SAME peer box handle, so NONE of them is published in the peer directory and none is addressable on the cross-session lane (fail-closed: the engine mounts its box drain on the folded handle for every one of them, so publishing any single one would let the others consume its messages). Root fix = a case-canonical session-id grammar on the submit face (a breaking change, tracked separately); until then do not mint session ids that differ only by case",
+                });
+            }
+            for (const t of retired.values()) {
+                const sessionId = sessionIdOfBoxHandle(t.handle);
+                if (!isPeerSessionId(sessionId))
+                    continue;
+                out.push({
+                    schemaVersion: PEER_SESSION_RECORD_SCHEMA_VERSION,
+                    sessionId,
+                    scope,
+                    name: t.label !== undefined && t.label.trim() !== "" ? t.label : autoName(sessionId),
+                    nameSource: "auto",
+                    startedAt: t.retiredAt,
+                    updatedAt: t.retiredAt,
+                    liveness: "deleted",
+                    diedAt: t.retiredAt,
+                    inboundPosture: posture,
+                });
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=peer-directory.js.map

package/dist/permission-rule-vocab.d.ts

@@ -1,4 +1,4 @@
-import type { RuleApprovalRecord } from "@sema-agent/core";
+import type { RuleApprovalRecord, RuleBehavior } from "@sema-agent/core";
 /**
  * `PersistedRuleTool` **不再是闭词表**(core 7.9.0 / [ref]):工具名自 core 的**目录**派生
  * (`pathTarget` 声明 ⇒ 路径文法;`Bash` ⇒ 命令文法),型是 `string`。于是本文件对它的处置从
@@ -16,6 +16,32 @@ export declare function isPersistedRuleTool(name: string): boolean;
  * —— `//abs`、`~/`、`/root-relative`、cwd 相对,段内 `*`、跨段 `**`)。
  */
 export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path"];
+/**
+ * S-511 —— `RuleBehavior` 每一员在**无同意仪式的直接写口**(`POST /v1/rules`)上的逐员表态。
+ *
+ * 为什么是一张**表**而不是一句 `behavior !== "allow"`:后者对 core 加员是**静默放行** —— 将来多一个
+ * 放宽方向的态,它会直接从这条收紧口写进店,而没有任何一行代码会红。`Record<RuleBehavior, boolean>`
+ * 少一员就是编译红([ref] 词表纪律:未知词必须是编译错),新词由人显式表态,而**方向由 `false` 兜底**
+ * —— 加一员而忘了表态是编译红,表态成 `false` 是恒拒,两条路都不会悄悄放宽。
+ *
+ * 判据本身是 core 成文的那条不对称(`removePersistedRule` 头注逐字):收紧不需要同意仪式
+ * (「a host may narrow on a user's behalf, it may not widen」),放宽需要 —— 所以 `allow` 的家是
+ * 「一次点头」那条路(ask 回决携规则 / 导入面的票仪式),不是这条口。
+ */
+export declare const DIRECT_RULE_WRITE_ADMITS: {
+    /** 放宽方向:一次人的点头才铸得出它,本口恒拒(端点侧 400,文案在冻结门里)。 */
+    readonly allow: false;
+    /** 收紧:一条常驻拒绝。 */
+    readonly deny: true;
+    /** 收紧:一条常驻提问(它把自动放行降级成问人,方向同样是收紧)。 */
+    readonly ask: true;
+};
+/** 能经直接写口落店的那几员 —— 从上表**派生**,于是「允许哪几员」只有一个说话人。 */
+export type DirectWritableRuleBehavior = {
+    [B in RuleBehavior]: (typeof DIRECT_RULE_WRITE_ADMITS)[B] extends true ? B : never;
+}[RuleBehavior];
+/** 判别式谓词(收窄到 {@link DirectWritableRuleBehavior}):端点判过之后,`allow` 在**类型上**到不了写家。 */
+export declare function isDirectWritableRuleBehavior(behavior: RuleBehavior): behavior is DirectWritableRuleBehavior;
 /** [ref] §2.3 B3:batch offer 成员的判别位(`command` = 历史逐段 Bash 规则;`directoryRead` = cd 段铸的目录只读授权)。 */
 export declare const RULE_OFFER_BATCH_MEMBER_KINDS: readonly ["command", "directoryRead"];
 /** [ref] §3.5:一段「为什么仍未被覆盖」的闭三词集(`redirection` 永久逐次 / `no_rule_form` 无可覆盖形 / `cap_overflow` 去重+帽挤出)。 */

package/dist/permission-rule-vocab.js

@@ -5,6 +5,14 @@ export function isPersistedRuleTool(name) {
 export const PERSISTED_RULE_MATCHES = ["exact", "prefix", "wildcard", "subpath", "path"];
 const MATCHES_PIN = true;
 void MATCHES_PIN;
+export const DIRECT_RULE_WRITE_ADMITS = {
+    allow: false,
+    deny: true,
+    ask: true,
+};
+export function isDirectWritableRuleBehavior(behavior) {
+    return DIRECT_RULE_WRITE_ADMITS[behavior];
+}
 export const RULE_OFFER_BATCH_MEMBER_KINDS = ["command", "directoryRead"];
 const MEMBER_KINDS_PIN = true;
 void MEMBER_KINDS_PIN;

package/dist/plugins/mailbox-recipient-lifecycle.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 信箱**收件人生命周期面**([ref])—— core `MailboxStore` 契约里被点名、但机制**刻意不由 core 命名**的
+ * 那一半:「这个收件人正在被部署删掉」。
+ *
+ * core 的原话(`core/store-contracts/mailbox-store-contract.ts` 的 `MailboxTombstonedRecipientContractHooks`
+ * 逐字):「Put `(scope, handle)` into the deployment's PRE-DELETE state — whatever that is for this backend
+ * (a cascade marking the session row, a `deleting` column, a tombstone table). Core does not name the
+ * mechanism, only what `append` must then do.」 ⇒ 本文件就是 server 侧那个 "whatever"。
+ *
+ * ## 两个动词,各答一个问题
+ *
+ *  · {@link MailboxRecipientLifecycle.retireRecipient} —— **只打标,不清仓**。打标之后 `append` 响亮拒
+ *    (`MAILBOX_TOMBSTONED_RECIPIENT_CODE`),但**已入箱的消息、活着的租约一个都不动**。这不是口味问题:
+ *    core 的 T2 试剂盒有两格逐字钉它 ——「拒的是入口,不是清仓:被拒的 append 零副作用,已入箱的消息按原
+ *    seq/内容原封不动」与「副作用轴 · 活租约:被拒的 append 不得动别人手上的租约」。所以会话删除级联要
+ *    清箱时,是 `retireRecipient` **之后再** `drop`(两个动词两件事,见下)。
+ *  · {@link MailboxRecipientLifecycle.listRetiredRecipients} —— 目录用它把「正在删除中」那条记录
+ *    (`liveness: "deleted"`)补出来。
+ *
+ * ## 墓碑的寿命 = 箱的寿命(`drop` 即扫,**没有** revive 动词)
+ *
+ * `retireRecipient` 打的标随 `drop(scope, handle)` **一起消失**:盒的生命周期终结,收件人这个态也就没有
+ * 附着的对象了。这不是省事,是 core 自己的清扫规则 —— 它的参照目录 `createInMemoryPeerDirectory.sweep`
+ * 逐字写着「a non-live row is removable ONLY while its box is EMPTY」,而 `drop` 恰恰是把箱清空那一步;
+ * 契约对墓碑的要求只有「the host's deletion cascade writes it BEFORE dropping the box」(**写在丢箱之前**),
+ * 没有要求它活过丢箱。
+ *
+ * 🔴 **为什么这条设计比「墓碑永久 + 一个撤回动词」严格更好**(codex 对抗复审 r1 三条 [high] 之一,验真后重设计):
+ * 会话 id 由调用方自选(`http/admission.ts:153` 只有长度门,`security.ts:187-199` 明写刻意不加形状门),
+ * 删掉之后**同一个 id 可以被重新登记**(`run-local --session myproject`、留存腿删后用户再跑同名会话)。
+ * 永久墓碑于是需要一个「这个收件人回来了」的撤回口,而那个判据**在读面上判不出来** —— 会话删除级联是
+ * 「子腿先、`session_meta` 最后」(E21 次序契约),所以级联在飞的那一段里,活会话行与新墓碑是**同时**
+ * 存在的:任何「有活行就撤标」的规则都会在删除进行中把围栏拆掉(实序:retire → 目录读到旧活行 → 撤标 →
+ * 投递成功 → drop 把它删掉 = 一条有 `queued` 回执的消息被吞)。改成「墓碑随箱亡」之后:
+ *  · 撤回动词**不存在** ⇒ 那条竞态结构上不可达,读面也不再写任何东西;
+ *  · 重新登记的 id 天然可用(箱与墓碑在上一次 `drop` 里一起没了),不依赖任何时钟比较;
+ *  · 代价如实:级联**跑完之后**向那个 id 投递拿到的是「查无此会话」而不是「已删除」——「已删除」这一句
+ *    只在级联在飞的那段窗口内说得出。两者都是拒、都不 park,差的只有措辞。
+ *
+ * ## `drop` 与 `retire` 仍是两个动词(别合并成一个)
+ *
+ * `retireRecipient` **只打标**:此后 append 响亮拒,但已入箱的消息与活租约一个都不动(core T2 试剂盒的
+ * 两格副作用判据)。`drop` 才清仓,并同时扫掉墓碑。会话删除级联两件都做,**先 retire 再 drop**。
+ *
+ * ## 缺席形是**能力差**,不是兜底
+ *
+ * 看不见收件人生命周期的后端(local 车道用的是 core 自带的 `FileMailboxStore`)由
+ * {@link createDropOnlyRecipientLifecycle} 服务:retire ⇒ 直接 `drop`(箱真清空、投递真拒 —— 只是拒的
+ * 措辞退化成「查无此会话」而不是「已删除」),墓碑清单恒空 ⇒ 目录不铸 `deleted` 行。这不是静默降级:
+ * 后端选择点(`boot/stores.ts` 的 `mailbox_store_enabled` 行)逐次落 `recipientTombstones` 读数,
+ * 披露在 `docs/DEPLOY-PREREQS.md`。方向上它也不放宽任何东西 —— 两种形都**不收**给已删会话的信。
+ */
+import type { MailboxStore } from "@sema-agent/core";
+/** 一条墓碑(= 一个已退役的收件人)。 */
+export interface MailboxRecipientTombstone {
+    /** 盒句柄(会话盒 = `session.<小写 id>`)。 */
+    readonly handle: string;
+    /** 退役时刻(epoch ms)——目录据此铸 `diedAt`。 */
+    readonly retiredAt: number;
+    /** 退役前的显示名(会话的删前 `title`);缺席 = 当时没有可用的名字。 */
+    readonly label?: string;
+}
+export interface MailboxRecipientLifecycle {
+    /**
+     * 把 `(scope, handle)` 置入**预删除态**:此后 `append` 一律以 `MAILBOX_TOMBSTONED_RECIPIENT_CODE` 拒。
+     * **只打标**——不删消息、不动租约、不碰盒行的高水位(理由 = core T2 试剂盒的两格副作用判据,见模块头)。
+     * 幂等(重复 retire 只更新时刻/名字)。
+     *
+     * @returns 是否真的落了一张耐久墓碑。`false` = 本后端没有预删除态,箱已被直接 `drop`
+     *          (拒的方向不变,退化的只有拒绝措辞与「正在删除中」那一行的可见性)。
+     */
+    retireRecipient(scope: string, handle: string, at: number, label?: string): Promise<boolean>;
+    /** 本 scope 下句柄以 `handlePrefix` 开头的墓碑。无预删除态的后端恒返回空。 */
+    listRetiredRecipients(scope: string, handlePrefix: string): Promise<readonly MailboxRecipientTombstone[]>;
+}
+/**
+ * 看不见收件人生命周期的后端的诚实形:retire = 直接把箱 `drop` 掉(**不**打标,因为没有可打标的地方),
+ * 墓碑清单恒空。
+ *
+ * 🔴 与 `retireRecipient` 的 "只打标不清仓" 契约**有意不同**,且这不是违约:契约的那两格判据是给
+ * **有**预删除态的后端写的(它们要能在拒收的同时保住已入箱的消息给运维/留存腿看);没有预删除态的后端
+ * 唯一能做到「此后不再收信」的动作就是把箱清掉,`false` 返回值就是这件事的机器可读声明。core 的 T2
+ * 试剂盒**不挂**在这种后端上(它自己的注逐字:只挂看得见收件人生命周期的后端)。
+ */
+export declare function createDropOnlyRecipientLifecycle(store: MailboxStore): MailboxRecipientLifecycle;
+//# sourceMappingURL=mailbox-recipient-lifecycle.d.ts.map

package/dist/plugins/mailbox-recipient-lifecycle.js

@@ -0,0 +1,10 @@
+export function createDropOnlyRecipientLifecycle(store) {
+    return {
+        retireRecipient: async (scope, handle) => {
+            await store.drop(scope, handle);
+            return false;
+        },
+        listRetiredRecipients: async () => [],
+    };
+}
+//# sourceMappingURL=mailbox-recipient-lifecycle.js.map

package/dist/plugins/mailbox-store-sql.d.ts

@@ -46,8 +46,15 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
+import type { MailboxRecipientLifecycle, MailboxRecipientTombstone } from "./mailbox-recipient-lifecycle.js";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
+/** [ref] 收件人墓碑表(预删除态的**唯一**真源;形与理由见 `mailbox-recipient-lifecycle.ts` 模块头)。
+ *  🔴 为什么是**新表**而不是给 `mailbox` 加两列:加列走的是本仓「删库重建、不开 ALTER seam」那条政策
+ *  (存量库首跑必红);而 `CREATE TABLE IF NOT EXISTS` 一张新表在存量库上零破坏、零运维动作。语义上也更干净
+ *  —— `mailbox` 行是**盒**事实(next_seq / lease),墓碑是**收件人**事实,两者的生命周期本来就不同
+ *  (`drop` 同时终结两者 —— 墓碑随箱亡,理由全文见 `mailbox-recipient-lifecycle.ts` 模块头)。 */
+export declare const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏 `peer_meta` 行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记 `mailbox_peer_meta_corrupt`
  *  (scope/handle/seq/code),运维按 seq 修行。 */
@@ -58,7 +65,7 @@ export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
 /** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgMailboxSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const MAILBOX_INDEXES: readonly IndexSpec[];
 export declare function ensurePgMailboxSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
-export declare class TiDBMailboxStore implements MailboxStore {
+export declare class TiDBMailboxStore implements MailboxStore, MailboxRecipientLifecycle {
     private readonly pool;
     private readonly logger?;
     /** [ref]([ref] §1.2⑥):跨进程安全**显式**声明 —— core 的 `mailboxCrossProcessMountVerdict` 只对字面 `true` 放行
@@ -79,8 +86,15 @@ export declare class TiDBMailboxStore implements MailboxStore {
     reap(scope: string, now: number, opts?: {
         maxAgeMs?: number;
     }): Promise<number>;
+    /** 见 {@link MailboxRecipientLifecycle.retireRecipient}。**只打标**:不删消息、不动租约、不碰 next_seq。
+     *  锁序 = 盒行先(与 append / claim / ack / drop / reap 五面统一 —— ABBA 死锁形不许在这里重开),
+     *  于是 retire 与并发 append 在同一把行锁上串行:要么 append 先拿到 seq、要么它读到墓碑被拒,没有中间态。 */
+    retireRecipient(scope: string, handle: string, at: number, label?: string): Promise<boolean>;
+    /** 见 {@link MailboxRecipientLifecycle.listRetiredRecipients}。前缀查带 `ESCAPE`(句柄是开集串,
+     *  `_`/`%` 若被当通配会把**别的**收件人一起列出来 —— 与本仓 `?q=` 面同一条 escapeLike 纪律)。 */
+    listRetiredRecipients(scope: string, handlePrefix: string): Promise<readonly MailboxRecipientTombstone[]>;
 }
-export declare class PgMailboxStore implements MailboxStore {
+export declare class PgMailboxStore implements MailboxStore, MailboxRecipientLifecycle {
     private readonly pool;
     private readonly logger?;
     /** [ref] 跨进程安全显式声明(TiDB 孪生同注:事务 + 盒行 FOR UPDATE 锁序是真值前提;终验 = test/mailbox-cross-process-kit.test.ts pg 腿)。 */
@@ -98,5 +112,7 @@ export declare class PgMailboxStore implements MailboxStore {
     reap(scope: string, now: number, opts?: {
         maxAgeMs?: number;
     }): Promise<number>;
+    retireRecipient(scope: string, handle: string, at: number, label?: string): Promise<boolean>;
+    listRetiredRecipients(scope: string, handlePrefix: string): Promise<readonly MailboxRecipientTombstone[]>;
 }
 //# sourceMappingURL=mailbox-store-sql.d.ts.map

package/dist/plugins/mailbox-store-sql.js

@@ -1,8 +1,23 @@
-import { MAILBOX_INVALID_PEER_META_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
+import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { escapeLike } from "./sql-escape.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
+export const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
+const TOMBSTONE_LABEL_MAX_CHARS = 120;
+function boundedLabel(label) {
+    if (label === undefined || label === "")
+        return null;
+    return label.length > TOMBSTONE_LABEL_MAX_CHARS ? label.slice(0, TOMBSTONE_LABEL_MAX_CHARS) : label;
+}
+function tombstonedRecipientError(scope, handle) {
+    return new MailboxStoreError(MAILBOX_TOMBSTONED_RECIPIENT_CODE, `MailboxStore.append: recipient ${JSON.stringify(handle)} in scope ${JSON.stringify(scope)} is in this deployment's pre-delete state (refusing — nothing was parked; a receipt here would be one the deletion cascade is about to tear up)`);
+}
+function rowToTombstone(r) {
+    const label = r.label === null || r.label === undefined ? undefined : bufToStr(r.label);
+    return { handle: bufToStr(r.handle), retiredAt: Number(r.retired_at_ms), ...(label !== undefined ? { label } : {}) };
+}
 function assertScope(scope) {
     if (scope === undefined || scope === "") {
         throw new Error("MailboxStore.append: refusing a message without a scope");
@@ -131,6 +146,14 @@ export async function ensureTiDBMailboxSchema(pool) {
     peer_meta TEXT NULL,
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
+  ) COLLATE utf8mb4_bin`);
+    await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
+    scope_key VARBINARY(190) NOT NULL,
+    handle VARBINARY(190) NOT NULL,
+    retired_at_ms BIGINT NOT NULL,
+    -- 退役前的显示名(会话的删前 title)。纯显示面:目录据它铸 PeerSessionRecord.name;NULL = 当时无名可用。
+    label TEXT NULL,
+    PRIMARY KEY (scope_key, handle)
   ) COLLATE utf8mb4_bin`);
     await ensureIndexes((text, params) => pool.query(text, params), "mysql", MAILBOX_INDEXES);
 }
@@ -158,6 +181,13 @@ export async function ensurePgMailboxSchema(q) {
     hop_chain TEXT COLLATE "C", -- core 5.17.0 design/176(TiDB twin 同注:NULL = 缺席且有语义)
     peer_meta TEXT COLLATE "C", -- S-90 core fc52b4d4 design/385 片2b(TiDB twin 同注:typed peer 记录 JSON;NULL = 缺席且有语义)
     PRIMARY KEY (scope_key, handle, seq)
+  )`);
+    await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
+    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
+    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    retired_at_ms BIGINT NOT NULL,
+    label TEXT COLLATE "C", -- TiDB twin 同注:纯显示面,NULL = 无名可用
+    PRIMARY KEY (scope_key, handle)
   )`);
     await ensureIndexes(q, "pg", MAILBOX_INDEXES);
 }
@@ -200,6 +230,9 @@ export class TiDBMailboxStore {
                 await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
                 [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             }
+            const [tomb] = await c.query(`SELECT 1 FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]);
+            if (tomb.length > 0)
+                throw tombstonedRecipientError(scope, handle);
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = ? WHERE scope_key = ? AND handle = ?`, [seq + 1, scope, handle]);
             await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain, peerMeta]);
@@ -247,6 +280,7 @@ export class TiDBMailboxStore {
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
+            await c.query(`DELETE FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
         });
     }
     async reap(scope, now, opts) {
@@ -273,6 +307,24 @@ export class TiDBMailboxStore {
             return dropped;
         });
     }
+    async retireRecipient(scope, handle, at, label) {
+        assertScope(scope);
+        assertIdentityChars("scope", scope);
+        assertIdentityChars("handle", handle);
+        assertKeyBytes("scope", scope);
+        assertKeyBytes("handle", handle);
+        await this.tx(async (c) => {
+            await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
+            await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]);
+            await c.query(`INSERT INTO ${MAILBOX_TOMBSTONE_TABLE} (scope_key, handle, retired_at_ms, label) VALUES (?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE retired_at_ms = VALUES(retired_at_ms), label = VALUES(label)`, [scope, handle, at, boundedLabel(label)]);
+        });
+        return true;
+    }
+    async listRetiredRecipients(scope, handlePrefix) {
+        const [rows] = await this.pool.query(`SELECT handle, retired_at_ms, label FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle LIKE ? ESCAPE '\\\\'`, [scope, `${escapeLike(handlePrefix)}%`]);
+        return rows.map(rowToTombstone);
+    }
 }
 export class PgMailboxStore {
     pool;
@@ -327,6 +379,9 @@ export class PgMailboxStore {
                 ]);
                 ({ rows } = await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
             }
+            const { rows: tomb } = await c.query(`SELECT 1 FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
+            if (tomb.length > 0)
+                throw tombstonedRecipientError(scope, handle);
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = $1 WHERE scope_key = $2 AND handle = $3`, [seq + 1, scope, handle]);
             await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain, peerMeta]);
@@ -375,6 +430,7 @@ export class PgMailboxStore {
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
+            await c.query(`DELETE FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
         });
     }
     async reap(scope, now, opts) {
@@ -401,5 +457,25 @@ export class PgMailboxStore {
             return dropped;
         });
     }
+    async retireRecipient(scope, handle, at, label) {
+        assertScope(scope);
+        this.assertIdentity("scope", scope);
+        this.assertIdentity("handle", handle);
+        assertKeyBytes("scope", scope);
+        assertKeyBytes("handle", handle);
+        const bounded = boundedLabel(label);
+        const stored = bounded === null ? null : pgSanitizeText(bounded);
+        await this.tx(async (c) => {
+            await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [scope, handle, scope]);
+            await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
+            await c.query(`INSERT INTO ${MAILBOX_TOMBSTONE_TABLE} (scope_key, handle, retired_at_ms, label) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (scope_key, handle) DO UPDATE SET retired_at_ms = EXCLUDED.retired_at_ms, label = EXCLUDED.label`, [scope, handle, at, stored]);
+        });
+        return true;
+    }
+    async listRetiredRecipients(scope, handlePrefix) {
+        const { rows } = await this.pool.query(`SELECT handle, retired_at_ms, label FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle LIKE $2 ESCAPE '\\'`, [scope, `${escapeLike(handlePrefix)}%`]);
+        return rows.map(rowToTombstone);
+    }
 }
 //# sourceMappingURL=mailbox-store-sql.js.map