@sema-agent/server 7.103.2 → 7.105.0

package/dist/security.d.ts

@@ -3,6 +3,7 @@ import { type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
+import type { SessionFaceReader } from "./session-incarnation.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
  *  output (§0.5). Mirrors {@link RunStore}'s shipped `SessionSummary` shape so the wire response is unchanged. */
 export interface SessionListItem {
@@ -16,7 +17,7 @@ export interface SessionListItem {
     /** K-5c (shell §K): the latest run's task_id — the shell's one-hop live-tail re-attach anchor on resume. */
     lastRunId: string | null;
     /** [ref]([ref]/[ref]):the LATEST run's **engine run id**(`TaskResult.runId`)when known —— OMIT-when-absent,
-     *  恒不铸 null。runs-ledger listers 从 latest run 的终局 `result` JSON 提取(⇒ 在跑 latest 键诚实缺席);
+     *  恒不铸 null。runs-ledger listers 从 latest run 的 `result` JSON 提取(终局与 park 时写、认领续跑即清空 —— S-173 ⇒ 在跑 latest 键诚实缺席);
      *  local lister 走 `noteTaskRun` 席实时记录(⇒ 在跑也在场)——两面缺席集合不完全相等,读法一致:
      *  缺席 = 「此行无已知 engine runId」,禁读成其它含义。⚠️ 与 `lastRunId`(= latest run 的 **task_id**)
      *  是两条身份轴,命名对齐 core `SessionStoreSummary.lastTaskRunId`。wire:additive 键零投影透传
@@ -94,6 +95,9 @@ export declare function legacyUnownedSessionOk(requirePrincipal: boolean, gateOw
 export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 export type OwnerAwareSessionStore = SessionStore & {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
+    /** S-790 / S-506([ref] §2)—— 属主 + **化身**一次读(`undefined` = 无此会话;行在而化身为空 ⇒ 响亮拒)。规则的唯一属主
+     *  是 `src/session-incarnation.ts`。只关心属主的消费点照旧读 `ownerOf`;判「这还是不是同一位住客」的读它。 */
+    sessionFaceOf?: SessionFaceReader;
     register?: (sessionId: string, owner: string | null) => Promise<void>;
     /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column).
      *  `includeUnowned` = [ref] 窄互认第二臂的**第三条件**(`owner IS NULL`)的 SQL 承载位:置真时

package/dist/session-children-retire.d.ts

@@ -0,0 +1,92 @@
+/**
+ * S-790 件B([ref] §3)—— **删会话带走以它为根的后台子代**:一只会话被删,以它为根的子代跟着结束 —— parked 的作废
+ * (行转终态,审批卡随之离开待决面),在跑的停掉。**这件事做完,才删会话元数据**(调用方:`boot/session-faces.ts` 的删除协调器)。
+ *
+ * ## 两步、两种失败,类型上分开(合并复审 gpt-6 腿 [high] 之后的形,裁定 2026-09-28)
+ *  1. {@link probeSessionChildren} —— **可达性预检,零写**。在协调器的任何破坏性步骤**之前**跑:有本进程结束不了的子代(在别的副本上
+ *     跑的 running 行:本进程没有它的句柄、耐久行的写者不是本进程 —— 本进程 `stopTask` 对它只答 `not_local`)⇒
+ *     `{ reachable: false, unreachableHandles }`,协调器立刻答 409 `conflict.session_children_alive`,一行不删。409 的语义因此只有一句:**拒在删之前**。
+ *     (修前的形是「先删账本、再结束子代、结束不了再答 409」—— 409 说「什么都没删」,而 run / event 账本已经提交删除了。)
+ *  2. {@link retireSessionChildren} —— 结束子代(预检之后、账本删除之后)。停不净的只可能是**时序**失败(本进程发出的停止还没落盘 /
+ *     一只在预检与停止之间冒出来的子代),不是可达性 ⇒ `{ stopped: "incomplete", remainingHandles }`,协调器按既有腿的失败契约**抛**
+ *     {@link SessionChildrenStopIncompleteError}(路由通用 500),不删 session_meta,幂等重试收敛。
+ *  「一个 `remaining > 0` 同时表示两件事」的双关由此消失:预检的失败是 409,结束的失败是 500,两只函数、两个返回型。
+ *
+ * ## 动词(core 板 [ref] ⑧⑨ 给定;本车第零步探针 `test/core-probe-parked-stop-root-access.test.ts` 真跑证实)
+ *  · 枚举 = `agentStore.listBySession(scope, 根会话)`(耐久行,锚 = 行的 session / parent / root 任一),并上本进程登记表里的
+ *    `activeDelegationHandles(scope, 根会话)`(没接耐久店的部署只有这一半)。scope 轴由调用方给(协调器:会话行的 `owner ?? "default"`)。
+ *  · **parked** 行 ⇒ `checkpointStore.expire(token, 卡自己的 scope)`(与 core 自己的本进程仲裁器同一只 CAS)+
+ *    `registry.reconcileParkedAgents(stores, scope)` ⇒ 行 `failed`(stoppedBy `system`)、卡离开待决面。任何副本上都做得到 ⇒ 预检把它
+ *    算作可达(前提是本部署有 checkpoint 店)。
+ *    ⚠️ **不对 parked 行调 `stopTask`**:只在耐久店里的行(park 它的进程不在 / 别的副本 / 重启后 —— parked 行活过重启是常态)
+ *    `stopTask` 什么都不改;本进程里的活 handle 先 expire 再 stopTask,core 答误导的 `park_resume_won`(core [ref] 原文)。
+ *  · **running** 行 ⇒ `stopTask(handle, { scope, sessionId: 根会话 })` ⇒ `killed`。可达与否**只有一个判据**,与 core `stopTask` 答 `not_local`
+ *    的那一条同源({@link runsOnAnotherReplica}):本进程**没有**这只句柄(不论状态)**且**耐久行 running、写者(`writerId`)不是本进程
+ *    (`registry.writerId`)⇒ 不可达(别的副本 / 写它的进程已不在)。本进程有句柄 —— 哪怕已经 killed、终态写还在飞 —— 或耐久行的写者就是
+ *    本进程 ⇒ 可达,交给有上界的结束循环(已停的句柄上 `stopTask` 是 no-op,循环等耐久写落地;等不到就是时序失败 500)。
+ *    (修复验证轮两条 opus 腿同命中:修前预检看的是内存句柄的**状态**(不是 running / pending ⇒ 够不着),本副本刚停、写在飞的子代因此被答成
+ *    「在别的副本上」的 409 —— 同一个「这只子代在不在本进程」的判断有两个写者。)
+ *
+ * ## 循环(有上界)
+ * 作废 / 停止与一次并发的 `/decide` 可能交错:expire 的 CAS 输给了决定腿的 resolve ⇒ 那只子代被唤醒成 running ⇒ 下一轮枚举看见
+ * 它、停掉它。循环到「枚举不出活的子代」为止,轮数有上界({@link RETIRE_MAX_ROUNDS});本进程 kill 的耐久写是 core 的异步写链,
+ * 两轮之间留一小段退避让它落盘。
+ */
+import type { BackgroundAgentStore, CheckpointStore, TaskRegistry } from "@sema-agent/core";
+/** 重新枚举的轮数上界。 */
+export declare const RETIRE_MAX_ROUNDS = 6;
+/** 两步共用的枚举口。 */
+interface ChildrenSource {
+    agentStore: BackgroundAgentStore | undefined;
+    registry: Pick<TaskRegistry, "activeDelegationHandles">;
+}
+export interface ProbeSessionChildrenDeps extends ChildrenSource {
+    /** 缺席 = 本部署没有耐久审批;撞见 parked 行却没有它 ⇒ 那只作废不了 ⇒ 不可达(拒在删之前)。 */
+    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    registry: Pick<TaskRegistry, "activeDelegationHandles" | "getAccessibleTask" | "writerId">;
+}
+export interface RetireSessionChildrenDeps extends ChildrenSource {
+    /** 缺席 = 本部署没有耐久审批(不可能有 parked 行);撞见 parked 行却没有它 ⇒ 那只作废不了,留到剩余(预检本该已经拒掉它)。 */
+    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    registry: Pick<TaskRegistry, "stopTask" | "reconcileParkedAgents" | "activeDelegationHandles">;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** 可达性预检的结果(零写)。`unreachableHandles` 只含本进程结束不了的那几只;可达的子代不在这里。 */
+export type SessionChildrenReachability = {
+    readonly reachable: true;
+    readonly live: number;
+} | {
+    readonly reachable: false;
+    readonly live: number;
+    readonly unreachableHandles: readonly string[];
+};
+/** 结束子代的结果。`incomplete` = 时序失败(本进程的停止还没落盘 / 预检之后冒出来的子代),不是可达性。 */
+export type RetireSessionChildrenOutcome = {
+    readonly stopped: "all";
+    readonly found: number;
+    readonly rounds: number;
+} | {
+    readonly stopped: "incomplete";
+    readonly found: number;
+    readonly rounds: number;
+    readonly remainingHandles: readonly string[];
+};
+/**
+ * **可达性预检**(零写;协调器在任何破坏性步骤之前调)。parked 行在有 checkpoint 店时可达(expire + reconcile 在任何副本上都成);
+ * running 行除非 {@link runsOnAnotherReplica} 都可达(`getAccessibleTask` / `agentStore.get` 都是纯读,不动任何东西)。
+ */
+export declare function probeSessionChildren(deps: ProbeSessionChildrenDeps, rootSessionId: string, scope: string): Promise<SessionChildrenReachability>;
+/** 以 `rootSessionId` 为根、在 `scope` 分区里的后台子代:作废 parked、停掉 running,重新枚举到没有活的为止(有上界)。 */
+export declare function retireSessionChildren(deps: RetireSessionChildrenDeps, rootSessionId: string, scope: string): Promise<RetireSessionChildrenOutcome>;
+/**
+ * 结束子代这一步的**时序**失败(可达性已在预检过了):本进程发出的停止在上界内没有全部落地。协调器抛它 ⇒ 路由通用 500;
+ * session_meta 不删(E21「子腿失败 ⇒ 不删 meta ⇒ 幂等重试收敛」的既有契约),账本那一腿此时已经删了 —— 与任何一条子腿中途失败同形。
+ * 文案不带句柄(句柄进运维 warn `session_delete_children_stop_incomplete`)。
+ */
+export declare class SessionChildrenStopIncompleteError extends Error {
+    readonly sessionId: string;
+    readonly remaining: number;
+    constructor(sessionId: string, remaining: number);
+}
+export {};
+//# sourceMappingURL=session-children-retire.d.ts.map

package/dist/session-children-retire.js

@@ -0,0 +1,85 @@
+export const RETIRE_MAX_ROUNDS = 6;
+const RETIRE_BACKOFF_MS = [0, 25, 50, 100, 200, 400];
+async function liveChildren(deps, rootSessionId, scope) {
+    const out = new Map();
+    if (deps.agentStore !== undefined) {
+        for (const s of await deps.agentStore.listBySession(scope, rootSessionId)) {
+            if (s.status === "running" || s.status === "parked")
+                out.set(s.handle, { handle: s.handle, status: s.status });
+        }
+    }
+    for (const handle of deps.registry.activeDelegationHandles(scope, rootSessionId)) {
+        if (!out.has(handle))
+            out.set(handle, { handle, status: "running" });
+    }
+    return [...out.values()];
+}
+export async function probeSessionChildren(deps, rootSessionId, scope) {
+    const live = await liveChildren(deps, rootSessionId, scope);
+    const unreachableHandles = [];
+    for (const child of live) {
+        const unreachable = child.status === "parked" ? deps.checkpointStore === undefined : await runsOnAnotherReplica(deps, child.handle, rootSessionId, scope);
+        if (unreachable)
+            unreachableHandles.push(child.handle);
+    }
+    return unreachableHandles.length === 0 ? { reachable: true, live: live.length } : { reachable: false, live: live.length, unreachableHandles };
+}
+async function runsOnAnotherReplica(deps, handle, rootSessionId, scope) {
+    if (deps.registry.getAccessibleTask(handle, { scope, sessionId: rootSessionId }) !== undefined)
+        return false;
+    if (deps.agentStore === undefined)
+        return false;
+    const row = await deps.agentStore.get(handle, scope);
+    return row?.status === "running" && row.writerId !== deps.registry.writerId;
+}
+export async function retireSessionChildren(deps, rootSessionId, scope) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let live = await liveChildren(deps, rootSessionId, scope);
+    const found = live.length;
+    let rounds = 0;
+    while (live.length > 0 && rounds < RETIRE_MAX_ROUNDS) {
+        rounds++;
+        let parkedSeen = false;
+        for (const child of live) {
+            if (child.status === "parked") {
+                parkedSeen = true;
+                await expireParkedCard(deps, child.handle, scope);
+            }
+            else {
+                await deps.registry.stopTask(child.handle, { scope, sessionId: rootSessionId }, deps.agentStore !== undefined ? { agentStore: deps.agentStore } : {});
+            }
+        }
+        if (parkedSeen && deps.agentStore !== undefined && deps.checkpointStore !== undefined) {
+            await deps.registry.reconcileParkedAgents({ agentStore: deps.agentStore, checkpointStore: deps.checkpointStore }, scope, Date.now());
+        }
+        await sleep(RETIRE_BACKOFF_MS[Math.min(rounds, RETIRE_BACKOFF_MS.length - 1)]);
+        live = await liveChildren(deps, rootSessionId, scope);
+    }
+    return live.length === 0
+        ? { stopped: "all", found, rounds }
+        : { stopped: "incomplete", found, rounds, remainingHandles: live.map((c) => c.handle) };
+}
+async function expireParkedCard(deps, handle, scope) {
+    if (deps.agentStore === undefined || deps.checkpointStore === undefined)
+        return;
+    const row = await deps.agentStore.get(handle, scope);
+    if (row === null || row.status !== "parked" || row.parkedCheckpointToken === undefined)
+        return;
+    const token = row.parkedCheckpointToken;
+    const cp = await deps.checkpointStore.get(token);
+    if (cp === null || cp.status !== "pending")
+        return;
+    await deps.checkpointStore.expire(token, cp.scope);
+}
+export class SessionChildrenStopIncompleteError extends Error {
+    sessionId;
+    remaining;
+    constructor(sessionId, remaining) {
+        super(`session ${sessionId}: ${remaining} background agent(s) this replica stopped had not settled within ${RETIRE_MAX_ROUNDS} rounds — ` +
+            `the session record was kept so the delete can be retried (it converges once they settle)`);
+        this.sessionId = sessionId;
+        this.remaining = remaining;
+        this.name = "SessionChildrenStopIncompleteError";
+    }
+}
+//# sourceMappingURL=session-children-retire.js.map

package/dist/session-error-wire.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 🔴 **core `SessionError` 闭集 → HTTP 的唯一映射**(S-612,server 7.104.0;设计稿 [ref] §2.1)。
+ *
+ * ## 为什么要一只属主
+ * 修前 wire 上只有**一处**认得 `SessionError` 的码:`http/routes/session-sync.ts` 的暂存导入腿把 `invalid_session`
+ * 手写成 422。其余每一条路都把它交给全局兜底 ⇒ `500 internal.error "internal error"`,码丢。core 7.30.0(#1041)
+ * 给文件会话店铸了 `corrupt_session`(存档没有会话头 ⇒ 这只会话唤不醒),而它在 wire 上一个名字都没有
+ * (真跑读数见 S-612 收车档 §0:冷启动时三条提交口与每一条经归属探针 / 读存档碰到它的口都答 500 `internal.error`;
+ * owner 已知时同步口是 200 + failed 体、并照常走计费收尾)。
+ *
+ * ## 为什么多一个 `face` 参数(而不是单参)
+ * core 的 `invalid_session` 是**同词两义**(亲读 dist:`engine/session/import-validate.js` 的导入门拒调用方交来的
+ * 日志,`engine/session/storage-base.js` 的建树 / 走根拒**已存**日志里指向缺席条目的叶子或祖先 —— 后者即 core #1077)。
+ * 本仓对它的成文义是前者(调用方的日志没过校验 ⇒ 422),而后者今天在打开会话的各口上答的是通用 500 / 同步口
+ * 200 + failed(S-612 的 3b 负控格钉住这一形,#1077 落地后按 core 的新码再对一次)。单参签名装不下这件事:要么
+ * 打开面的每个消费点都写一句 `code === "corrupt_session"` 特判,要么把 #1077 形从今天的应答改成「你交的日志坏了」。
+ * ⇒ 面是映射的一维,写进属主,不散在消费点。
+ *  · `"open"`   —— 为某只会话**打开它已存的日志**(提交各腿的引擎 prepare、鉴权门的归属探针、直接读会话的口);
+ *  · `"import"` —— 校验 / 写入**调用方交来的**日志(2c session-sync 的暂存导入)。
+ *
+ * ## 逐词(`undefined` = 登记过的留白:这个词在这一面上没有自己的 wire 答复,站点的既有处置照旧)
+ *  · `corrupt_session` —— 两面同答 **500 `corrupt_session`**。这只会话的存档读不出、唤不醒。不是 4xx:调用方没做错
+ *    任何事;不是 503:重试改不了判(修复在运维手里)—— 与会话规则店的 `corrupt` 同一档同一理由。码不另铸(core 的词
+ *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
+ *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
+ *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);
+ *    `open` 面留白(#1077 形,见上)。
+ *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
+ *    列表里的缺席),码位各不相同,不由本表统一。
+ *  · `invalid_entry` / `invalid_fork_target` / `placement_refused` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
+ *    应答(它们在 core 的追加 / 分叉 / 放置面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
+ *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 由提交腿的 CAS 冲突臂按结果处置(`runs.ts`
+ *    `isSessionConflictResult`),`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
+ *
+ * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
+ * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。
+ */
+import type { SessionError } from "@sema-agent/core";
+/** core `SessionError` 的码闭集(core 不从包根导出这个型名 ⇒ 从导出类的 `code` 键派生,不手抄)。 */
+export type SessionErrorCode = SessionError["code"];
+/** 映射的面(见文件头注)。 */
+export type SessionErrorFace = "open" | "import";
+/** 一个词在一面上的 wire 答复。 */
+export interface SessionErrorWire {
+    readonly status: number;
+    readonly errorCode: string;
+    /**
+     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。只有 import 面的 `invalid_session` 用它:core 导入门的原句点名的是
+     * 调用方日志里的条目 id / 父子关系,修前这一口就只回一句固定话(冻结在 `test/api-error-text-freeze.test.ts` 的
+     * 常量锚格),本批逐字不改。
+     */
+    readonly sentence?: string;
+}
+/** import 面 `invalid_session` 的固定句(修前 session-sync 暂存导入腿那一行的原文)。 */
+export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+export declare function sessionErrorHttp(code: SessionErrorCode, face: SessionErrorFace): SessionErrorWire | undefined;
+export declare function isSessionErrorCode(code: string): code is SessionErrorCode;
+//# sourceMappingURL=session-error-wire.d.ts.map

package/dist/session-error-wire.js

@@ -0,0 +1,38 @@
+export const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
+const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
+export function sessionErrorHttp(code, face) {
+    switch (code) {
+        case "corrupt_session":
+            return CORRUPT_SESSION;
+        case "invalid_session":
+            return face === "import" ? INVALID_ENTRIES : undefined;
+        case "not_found":
+        case "invalid_entry":
+        case "invalid_fork_target":
+        case "placement_refused":
+        case "storage":
+        case "conflict":
+        case "unknown":
+            return undefined;
+        default: {
+            const unhandled = code;
+            throw new Error(`unhandled SessionError code: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+const SESSION_ERROR_CODE_PRESENCE = {
+    not_found: true,
+    invalid_session: true,
+    invalid_entry: true,
+    invalid_fork_target: true,
+    storage: true,
+    conflict: true,
+    placement_refused: true,
+    corrupt_session: true,
+    unknown: true,
+};
+export function isSessionErrorCode(code) {
+    return Object.hasOwn(SESSION_ERROR_CODE_PRESENCE, code);
+}
+//# sourceMappingURL=session-error-wire.js.map

package/dist/session-incarnation.d.ts

@@ -0,0 +1,61 @@
+/** 会话元数据的一次读:属主 + 化身(同一行、同一次读)。 */
+export interface SessionFace {
+    /** `null` = 登记为无主的会话。 */
+    readonly owner: string | null;
+    /** 这一位住客的化身令牌(非空;空值在读口就响亮拒了)。 */
+    readonly incarnation: string;
+}
+/** 读口的形(三只会话店 + 缓存包装层同一个签名)。 */
+export type SessionFaceReader = (sessionId: string) => Promise<SessionFace | undefined>;
+/** 铸一只新化身(铸点见头注,只在新建行)。 */
+export declare function mintSessionIncarnation(): string;
+/** 日志里点名一只化身时唯一允许的形:前 8 位。完整令牌不进任何日志正文。 */
+export declare function incarnationLogPrefix(incarnation: string): string;
+/**
+ * 把一段**不归本仓撰写**的文本(典型:core 记忆引擎的事故披露句 —— `memory.session_incarnation_mismatch` 逐字带着两只令牌)落日志之前,
+ * 把其中每一只化身形的串截成 {@link incarnationLogPrefix}(前 8 位 + `…`)。规则只有一条:完整令牌不进日志正文;前 8 位留着对账。
+ */
+export declare function redactIncarnations(text: string): string;
+/**
+ * 两次读是不是**同一位住客**:都在、化身逐字相等。任一次读不到(会话不在)⇒ 不是 —— 没有「读不到就当相同」的臂。
+ * 属主是否等于某个身份是调用方自己的判据(赎回面比的是卡的权威 principal),不在这里。
+ */
+export declare function sameSessionOccupant(before: SessionFace | undefined, after: SessionFace | undefined): boolean;
+/**
+ * 会话行在、化身却是空的 —— 响亮拒(头注「读到空化身」一条)。具名类型:调用方按类型认它,不按文案。
+ * 文案不带任何令牌(本来就是空的),只点名会话 id 与出路。
+ */
+export declare class SessionIncarnationMissingError extends Error {
+    readonly sessionId: string;
+    readonly code = "session.incarnation_missing";
+    constructor(sessionId: string);
+}
+/**
+ * 店把一行原始列读成 {@link SessionFace} 的唯一口(三只店共用 —— 空值判据只写这一处)。
+ * `incarnation` 不是非空字符串 ⇒ {@link SessionIncarnationMissingError}。
+ */
+export declare function sessionFaceFromRow(sessionId: string, owner: string | null, incarnation: unknown): SessionFace;
+/**
+ * session-sync **整段换装**(replace)时化身的去留 —— 三只店共用的一句判据:换装删掉再插回的是**同一位住客**的那一行
+ * (删除带属主门),所以行在、属主相同、化身非空 ⇒ 沿用;行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
+ */
+export declare function carriedIncarnation(prior: {
+    owner?: unknown;
+    incarnation?: unknown;
+} | undefined, owner: string | null): string;
+/**
+ * `session_meta.incarnation` 的列定义 —— 两方言各一句,**唯一属主**:中央 DDL(`tidb-pool.ts` / `pg-session-storage.ts` 的
+ * `CREATE TABLE session_meta`)与一次性迁移 M5 的 `ADD COLUMN`(`plugins/one-time-migrations.ts`)都内插这同一串,
+ * 于是「新库建出来的列」与「存量库补上的列」逐字同形(S-547 起服列册探针比的是列名,形由这里保证)。
+ *
+ * `NOT NULL DEFAULT ''`:空串就是「没铸过」的唯一表示 —— 读口对它响亮拒({@link SessionIncarnationMissingError})。
+ * 缺省值只为两件事存在:①存量表 `ADD COLUMN` 在两方言上一句成立(PG 对非空表加无缺省的 NOT NULL 列直接拒);
+ * ②一条漏铸的写腿落下的是**读得出来的错**(读口拒),而不是一条插入期的 500 —— 两形都 fail-closed,前者还能被迁移补上。
+ * 宽度 64:`randomUUID()` 是 36 字符,留出余量但不给任意长串留位。
+ */
+export declare const SESSION_META_INCARNATION_COLUMN: {
+    readonly name: "incarnation";
+    readonly tidb: "incarnation VARCHAR(64) NOT NULL DEFAULT ''";
+    readonly pg: "incarnation VARCHAR(64) COLLATE \"C\" NOT NULL DEFAULT ''";
+};
+//# sourceMappingURL=session-incarnation.d.ts.map

package/dist/session-incarnation.js

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+export function mintSessionIncarnation() {
+    return randomUUID();
+}
+export function incarnationLogPrefix(incarnation) {
+    return incarnation.slice(0, 8);
+}
+const INCARNATION_TOKEN_SHAPE = /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/gi;
+export function redactIncarnations(text) {
+    return text.replace(INCARNATION_TOKEN_SHAPE, (token) => `${incarnationLogPrefix(token)}…`);
+}
+export function sameSessionOccupant(before, after) {
+    return before !== undefined && after !== undefined && before.incarnation === after.incarnation;
+}
+export class SessionIncarnationMissingError extends Error {
+    sessionId;
+    code = "session.incarnation_missing";
+    constructor(sessionId) {
+        super(`session ${sessionId} has no incarnation token: every session row is minted one when it is created, and rows written before ` +
+            `7.104.0 get one from the one-time migration that runs at boot (plugins/one-time-migrations.ts, entry M5). An empty value ` +
+            `after that means a write path that did not mint one, or a hand-edited row — it is refused rather than read as "matches anyone". ` +
+            `Restart a 7.104.0+ replica so the migration backfills it, or delete the session.`);
+        this.sessionId = sessionId;
+        this.name = "SessionIncarnationMissingError";
+    }
+}
+export function sessionFaceFromRow(sessionId, owner, incarnation) {
+    if (typeof incarnation !== "string" || incarnation === "")
+        throw new SessionIncarnationMissingError(sessionId);
+    return { owner, incarnation };
+}
+export function carriedIncarnation(prior, owner) {
+    if (prior !== undefined && (prior.owner ?? null) === owner && typeof prior.incarnation === "string" && prior.incarnation !== "") {
+        return prior.incarnation;
+    }
+    return mintSessionIncarnation();
+}
+export const SESSION_META_INCARNATION_COLUMN = {
+    name: "incarnation",
+    tidb: "incarnation VARCHAR(64) NOT NULL DEFAULT ''",
+    pg: `incarnation VARCHAR(64) COLLATE "C" NOT NULL DEFAULT ''`,
+};
+//# sourceMappingURL=session-incarnation.js.map

package/dist/session-policy-wire.d.ts

@@ -16,10 +16,16 @@
  *        自陈「Malformed shape → 400(never a downstream TypeError)」,这一半没守);
  *      · `loosenReasons` 的每一臂都从 `prior` 出发,**prior 为空时恒回空集** ⇒ tighten-only 门对一条
  *        全新的会话放行任何内容,坏形因此连「收紧门」这一层都碰不到。
- * ⇒ 类修:一只读者,键集由 `keyof SessionPermissionRules` **派生**(下方 `RULE_FIELD_PRESENCE` 的
- * `satisfies Record<keyof SessionPermissionRules, true>`:core 加桶 ⇒ 缺键**编译红**;core 删桶 ⇒
+ * ⇒ 类修:一只读者,键集由 `keyof SessionPermissionRules` **派生**(下方 `RULE_FIELD_ROLE` 的
+ * `satisfies Record<keyof SessionPermissionRules, RuleFieldRole>`:core 加桶 ⇒ 缺键**编译红**;core 删桶 ⇒
  * 多键**编译红**),两条腿同调。
  *
+ * ── S-800(7.105.0):同一只读者多判一问 —— 写得进却跑不了的工具名 ─────────────────────────────────
+ * 两条写入腿是 server 往会话规则店写的**全部**写口,所以「写口 fail-closed」收成一只**写口读者**
+ * ({@link readWritableSessionPermissionRules} = 形读者 + {@link legacyToolNameOf}),两腿同调,将来第三条写入腿
+ * 调同一只也同得。判词多一种(`legacy-tool-name`),两腿各把它映射成 `400 rules.legacy_tool_name`(映射点仍在各自
+ * 站点:码位只放字面量)。形读者本身不变 —— SQL 店的读回也用它,读回不许判名字(理由见写口读者头注)。
+ *
  * ── 文案也在这里(codex 一轮追加:两条腿各铸一份句子 = 第二份手抄)───────────────────────────────
  * 初版把 wire 文案留在两个路由各自铸,理由是错误文案冻结门(`test/api-error-text-freeze.test.ts`)锚的是
  * `src/http/` 桶里的 `sendError` 站点。codex 一轮指出那等于**把同一句话写了两遍**(`sessions.ts` 与
@@ -28,10 +34,52 @@
  * 渲染器对每一种判词的输出字节,且对判词闭集穷尽(加一种判词 ⇒ 那一格编译红)。文案一个字节未改。
  */
 import type { SessionPermissionRules, SessionPolicyError, SessionRulesRecord } from "@sema-agent/core";
+declare const RULE_FIELD_ROLE: {
+    readonly toolAllow: "tool-name";
+    readonly toolDeny: "tool-name";
+    readonly allowDirs: "path";
+    readonly commandAllow: "command";
+    readonly commandDeny: "command";
+};
 /** core `SessionPermissionRules` 的桶名全集(派生,不是手抄)。 */
 export declare const SESSION_PERMISSION_RULE_FIELDS: readonly (keyof SessionPermissionRules)[];
-/** 一条规则体的形问题。判词而非文案(见文件头注的「文案属主」一段)。 */
-export type SessionPermissionRulesProblem = 
+/** 装工具名的那几桶(由 {@link RULE_FIELD_ROLE} 派生的型)。 */
+export type ToolNameRuleField = {
+    [K in keyof typeof RULE_FIELD_ROLE]: (typeof RULE_FIELD_ROLE)[K] extends "tool-name" ? K : never;
+}[keyof typeof RULE_FIELD_ROLE];
+/**
+ * S-800(client-core [ref] CC-226;server [ref];core [ref])—— 「写得进、跑不了、撤不掉」的工具名。
+ *
+ * 两臂,逐字对应 core 7.33.8 准备阶段名审计抛 `config.legacy_tool_name` 的那两臂(判据只用 core **导出**的
+ * 两件,零镜像表 —— 表随 core 钉版走):
+ *  · `"retired"`:名字在 core 的 `RETIRED_TOOL_NAMES` 里;`guidance` = 那张表给它的一句现役指引(原样);
+ *  · `"unprefixed-namespace"`:名字里有 `"__"` 分隔符,而 `protocolOf(name)` 认不出它属于哪个协议。
+ *
+ * 为什么在**写口**判:会话规则店只准非 operator 收紧,删掉一条 deny 算放宽 ⇒ 写进去的这种名字属主自己删不掉,
+ * 而准备阶段见它就整只拒启 ⇒ 这个会话之后的每一跑都起不来。写口是唯一还来得及说「不」的地方。
+ *
+ * ⚠️ **比准备阶段严一格**(方向安全,与 client-core 0.83.6 的 KL-157 同向):准备阶段对**本 run 名册里挂着**的
+ * 同名工具放行(部署自己挂了一只叫 `Task` 的工具就不审计它),写口看不到将来哪一跑的名册 ⇒ 一律拒。
+ * 受伤的是「部署自带与退役名同名的工具、又要在会话规则里点它」的形;出路 = 部署级工具策略(不经会话规则店)。
+ * ⚠️ **过渡形**:core 已表态(#1156,7.34.1)把这两臂抽成一只导出纯函数并在会话规则店写口即拒 —— 到货后本函数
+ * 换成调 core 那只(拒因原样透传),三份判定收成一份。
+ *
+ * 🔴 **为什么不复用 `config.ts` 的 `findUnmatchableToolNames`**(本仓另一只按名字判的单点;读过实现后裁):两只回答的
+ * 不是同一个问题。那一只问「部署名单里这条名字会不会**永远匹配不上**活工具」—— 它刻意豁免 `allow`(白名单匹配不上 =
+ * fail-closed 且当场可见),并且拒两段 MCP 名 `mcp__srv`(一名两义)与 core 文法编不出的串。本函数问的是「引擎见到这条
+ * 会话规则会不会**拒启**」:引擎准备阶段的名审计对 `allow` 桶照样抛(豁免它 = 放过一条砖化路径),对 `mcp__srv` 却
+ * **不**抛(会话层自 core 5.55 / 5.56 起把它当整对端覆盖形真命中)。判据只能逐字跟 core 那两臂走,不能借另一只的口径。
+ * 两只在「退役名」「无前缀 `__` 名」两臂上同源(都读 core 导出的同两件),7.34.1 提货时一并换调 core 的导出函数。
+ */
+export type LegacyToolName = {
+    why: "retired";
+    guidance: string;
+} | {
+    why: "unprefixed-namespace";
+};
+export declare function legacyToolNameOf(name: string): LegacyToolName | undefined;
+/** 一条规则体的**形**问题。判词而非文案(见文件头注的「文案属主」一段)。 */
+export type SessionPermissionRulesShapeProblem = 
 /** 整体不是一只普通对象(`null` / 数组 / 标量 / 缺席)。 */
 {
     kind: "not-an-object";
@@ -41,22 +89,45 @@ export type SessionPermissionRulesProblem =
     kind: "field-not-string-array";
     field: keyof SessionPermissionRules;
 };
-/** {@link readSessionPermissionRules} 的读数:坏形给判词,好形给**已收窄**的规则体(调用方零 cast)。 */
-export type SessionPermissionRulesRead = {
-    problem: SessionPermissionRulesProblem;
+/** 一条**要写进店**的规则体的问题 = 形问题 ∪ S-800 的名字问题(判据 {@link legacyToolNameOf})。 */
+export type SessionPermissionRulesProblem = SessionPermissionRulesShapeProblem
+/** S-800:形对,但工具名桶里有一条写进去就跑不了的名字。 */
+ | {
+    kind: "legacy-tool-name";
+    field: ToolNameRuleField;
+    name: string;
+    legacy: LegacyToolName;
+};
+/** 两只读者的读数:有问题给判词,没问题给**已收窄**的规则体(调用方零 cast)。`P` = 这只读者会给的判词集。 */
+export type SessionPermissionRulesRead<P extends SessionPermissionRulesProblem = SessionPermissionRulesProblem> = {
+    problem: P;
     rules?: undefined;
 } | {
     problem?: undefined;
     rules: SessionPermissionRules;
 };
 /**
- * 读一只 wire 上的 `SessionPermissionRules`:形不对给判词,形对给**只含五桶**的规则体。
+ * **形读者**:读一只 `SessionPermissionRules`,形不对给判词,形对给**只含五桶**的规则体。三个消费者:两条写入腿
+ * (经 {@link readWritableSessionPermissionRules})与 SQL 店的**读回**(`session-policy-store-sql.ts` 的
+ * `readSessionRulesBody`:读不出形的行判 `corrupt`)。
  *
  * 认识面窄得刻意:**只判形**,不判内容(桶内字符串的 pattern 文法、路径是否可达、tighten-only 是否成立
- * 都不在这里 —— 前两者归 core 的 rule 文法与 `normalizeRules`,后者归 `putRules` 的收紧门)。
- * 未知键**照旧忽略**(不是新的拒因):core 的 `normalizeRules` 本来就只搬这五桶,本读者与它同口径。
+ * 都不在这里 —— 前两者归 core 的 rule 文法与 `normalizeRules`,后者归 `putRules` 的收紧门;S-800 的名字判官
+ * 只在**写口**那一只读者里,见下)。未知键**照旧忽略**(不是新的拒因):core 的 `normalizeRules` 本来就只搬这五桶,
+ * 本读者与它同口径。
  */
-export declare function readSessionPermissionRules(raw: unknown): SessionPermissionRulesRead;
+export declare function readSessionPermissionRules(raw: unknown): SessionPermissionRulesRead<SessionPermissionRulesShapeProblem>;
+/**
+ * **写口读者**(S-800)= 形读者 + 名字判官:两条写入腿(`PUT /v1/sessions/:id/policy`、sync/import 的 `policy`
+ * 面经 {@link readSessionRulesRecords})往会话规则店写之前的**唯一**判据。两问,按序:
+ *  ① 形(同 {@link readSessionPermissionRules};一份坏形的体答形的 400);
+ *  ② 工具名桶里的每一条过 {@link legacyToolNameOf} —— 写进去之后属主撤不掉、会话之后每一跑都起不来的名字,
+ *     写口是唯一来得及拒的地方。
+ * 🔴 **只在写口,不在读回**:SQL 店读回同一行时只判形(形读者)。一条早先写进去的退役名行必须**读得出来** ——
+ * 那是运营方清掉它的唯一路径(operator 的 PUT 先读写前快照),也是 core 准备阶段报 `config.legacy_tool_name`
+ * 而不是一只 500 `corrupt` 的前提。把判官放进形读者会让读回把它判坏(7.105.0 车QQ 双库套件实抓,修在同批)。
+ */
+export declare function readWritableSessionPermissionRules(raw: unknown): SessionPermissionRulesRead;
 /** 一条 `SessionRulesRecord` 的形问题(`policy[]` 的元素级;桶级问题原样转载在 `rules` 位)。 */
 export type SessionRulesRecordProblem = 
 /** `policy` 本身不是数组。 */
@@ -90,6 +161,8 @@ export type SessionRulesRecordsRead = {
 };
 /**
  * 读 sync/import 的 `policy` 面(`SessionRulesRecord[]`)。好形返回**已收窄**的记录数组,坏形给判词。
+ * 它只服务那一条**写入**腿(导入的记录随后 `putRules` 进店),所以每条记录的规则体走**写口读者**
+ * {@link readWritableSessionPermissionRules}(与 PUT 腿同一只判官)。
  *
  * `rev`:记录里带的 `rev` 是**导出端的**乐观锁读数,`putRules` 侧一进门就 `stripRev` 掉(`sameRulesContent`
  * 也比的是去 rev 的字节形),所以它在本读者里只是过境位 —— 非数字即当缺席(不是拒因:一个坏 rev 改变不了
@@ -98,6 +171,15 @@ export type SessionRulesRecordsRead = {
 export declare function readSessionRulesRecords(raw: unknown): SessionRulesRecordsRead;
 /** 桶级判词 → 人话。闭集穷尽:{@link SessionPermissionRulesProblem} 加一种判词 ⇒ 本 switch 编译红。 */
 export declare function describeSessionPermissionRulesProblem(p: SessionPermissionRulesProblem): string;
+/**
+ * S-800:一只 `policy[]` 判词**是不是**「写得进却跑不了的名字」那一类 —— 是就交回那一格(桶 + 名字),
+ * 调用点据此发 `rules.legacy_tool_name`,否则发形的码。闭集穷尽两层:记录级判词或桶级判词加一种 ⇒ 编译红,
+ * 新判词不会静默落进某一个码。
+ */
+export declare function legacyToolNameProblemOf(p: SessionRulesRecordProblem): {
+    field: ToolNameRuleField;
+    name: string;
+} | undefined;
 /** `policy[]` 判词 → 人话(sync/import 腿在它前面拼 `policy: `)。闭集穷尽同上。 */
 export declare function describeSessionRulesRecordProblem(p: SessionRulesRecordProblem): string;
 /**
@@ -115,7 +197,10 @@ export declare function describeSessionRulesRecordProblem(p: SessionRulesRecordP
  *
  * 逐词:
  *  · `conflict`(409)—— CAS 输了,重读 `rev` 再来。**码位与状态逐字不变**。
- *  · `loosen_forbidden`(403)—— 非 operator 想放松。**码位与状态逐字不变**。
+ *  · `loosen_forbidden`(403)—— 非 operator 想放松。**码位与状态逐字不变**。⚠️ 这个词还有**第二个铸点**(S-546 B5,
+ *    如实登记、未改):PG 后端的 SQL 双生对含 NUL / 孤代理字节的规则拒收时借用了它
+ *    (`plugins/session-policy-store-sql.ts` 的 `pgHasUnstorable` 臂)—— 那一形**既非放宽也非越权**,operator 写同样撞上;
+ *    core 的闭集里没有「输入不可存」这个词,改码位要先裁定新码与 PUT / 2c 导入两条入口同判(DEBTS S-546 B5)。
  *  · `corrupt`(**500**)—— 店读不出它自己该读的那份字节(记号/行被列外篡改或撕裂)。
  *    不是 4xx:调用方没做错任何事,它也改不了这件事;不是 503:重试改不了判(core 成文的修复路径是
  *    **人**去改回或删掉那一行,而删记号要交出它握着的那个号)。
@@ -124,4 +209,5 @@ export declare function sessionPolicyErrorHttp(code: SessionPolicyError["code"])
     status: number;
     errorCode: string;
 };
+export {};
 //# sourceMappingURL=session-policy-wire.d.ts.map