@sema-agent/server 7.147.0 → 7.149.0

package/dist/server-secret-env.js

@@ -1,5 +1,6 @@
-import { declareWithheldEnv, hostChildEnv, inheritedHostEnv } from "@sema-agent/core";
+import { declareWithheldEnv, hostChildEnv, inheritEnvPolicyProblem, inheritedHostEnv } from "@sema-agent/core";
 import { CONFIG_CATALOG } from "./config-catalog.js";
+import { parseApprovalHmacKeys, parseServiceAuthTokens } from "./auth-keys.js";
 import { ENV_NAME_ALLOWLIST_KNOB_NAMES } from "./env-name-allowlist-knobs.js";
 import { recordOwnCredentialValueNotWithheld, recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
 export const CATALOG_SECRET_ENV_NAMES = new Set(CONFIG_CATALOG.filter((spec) => spec.type === "secret").map((spec) => spec.name));
@@ -10,53 +11,105 @@ export function serverWithheldEnvNames(modelApiKeyEnv = NO_MODEL_ENTRIES) {
 export function serverCredentialValueSources(modelApiKeyEnv = NO_MODEL_ENTRIES) {
     return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
 }
+const CREDENTIAL_FORM_OF = new Map(CONFIG_CATALOG.flatMap((spec) => (spec.credentialForm === undefined ? [] : [[spec.name, spec.credentialForm]])));
+const DROPPED_KEYS_TOLD_BY_LOAD_CONFIG = () => { };
+function credentialsIn(form, raw) {
+    switch (form) {
+        case "whole":
+            return [raw];
+        case "token-table":
+            return [raw, ...Object.keys(parseServiceAuthTokens(raw))];
+        case "key-set":
+            return [raw, ...parseApprovalHmacKeys(raw, DROPPED_KEYS_TOLD_BY_LOAD_CONFIG).map((k) => k.key)];
+        default: {
+            const unreachable = form;
+            throw new Error(`unhandled secret credential form: ${String(unreachable)}`);
+        }
+    }
+}
 let declared;
 let beforeLast;
 const valueRefusalAnnounced = new Set();
 let liveConfig;
 const envValueOf = (name) => process.env[name];
-const valuesOf = (sources) => [...sources].map(envValueOf).filter((v) => typeof v === "string" && v !== "");
+function credentialsHeldBy(source) {
+    const raw = envValueOf(source);
+    if (raw === undefined || raw === "")
+        return [];
+    return [...new Set(credentialsIn(CREDENTIAL_FORM_OF.get(source) ?? "whole", raw))].filter((v) => v !== "");
+}
+function heldValues(held) {
+    return [...held].flatMap(([source, at]) => {
+        const all = credentialsHeldBy(source);
+        return [...at].flatMap((i) => {
+            const value = all[i];
+            return value === undefined ? [] : [value];
+        });
+    });
+}
 export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
     const names = [...new Set([...(declared?.names ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
-    const kept = [...(declared?.valueSources ?? [])];
-    declareWithheldEnv({ names, values: valuesOf(kept) });
-    const valueSources = new Set(kept);
+    const held = new Map(declared?.held ?? []);
+    declareWithheldEnv({ names, values: heldValues(held) });
     for (const source of serverCredentialValueSources(modelApiKeyEnv)) {
-        if (valueSources.has(source) || valuesOf([source]).length === 0)
-            continue;
-        try {
-            declareWithheldEnv({ names, values: valuesOf([...valueSources, source]) });
-            valueSources.add(source);
-        }
-        catch (e) {
-            if (!valueRefusalAnnounced.has(source)) {
-                valueRefusalAnnounced.add(source);
-                recordOwnCredentialValueNotWithheld({ name: source, reason: e instanceof Error ? e.message : String(e) });
+        const at = new Set(held.get(source) ?? []);
+        let refusal;
+        credentialsHeldBy(source).forEach((_, i) => {
+            if (at.has(i))
+                return;
+            try {
+                declareWithheldEnv({ names, values: heldValues(new Map(held).set(source, new Set([...at, i]))) });
+                at.add(i);
+                held.set(source, new Set(at));
             }
+            catch (e) {
+                refusal ??= e instanceof Error ? e.message : String(e);
+            }
+        });
+        if (refusal !== undefined && !valueRefusalAnnounced.has(source)) {
+            valueRefusalAnnounced.add(source);
+            recordOwnCredentialValueNotWithheld({ name: source, reason: refusal });
         }
     }
     beforeLast = declared;
-    declared = { names: new Set(names), valueSources };
+    declared = { names: new Set(names), held };
     return names;
 }
 export function withdrawServerWithheldEnv() {
-    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: valuesOf(beforeLast?.valueSources ?? []) });
+    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: heldValues(beforeLast?.held ?? new Map()) });
     declared = beforeLast;
 }
 export function bindOwnCredentialsConfig(config) {
     liveConfig = config;
 }
+export function ownCredentialNamesNotWithheld(modelApiKeyEnv = NO_MODEL_ENTRIES) {
+    return serverWithheldEnvNames(modelApiKeyEnv).filter((name) => inheritEnvPolicyProblem([name]) === undefined);
+}
+export function ownCredentialDeclarationRefusal() {
+    const missing = ownCredentialNamesNotWithheld();
+    if (missing.length === 0)
+        return undefined;
+    return (`loadConfig(): this process has not declared its own credentials to the engine (${missing.length} of ${serverWithheldEnvNames().length} names are not withheld, e.g. ${missing[0]}) — ` +
+        "call declareServerWithheldEnv() (package root) once before loadConfig(), before any execution environment is built or any child process is started. " +
+        "Without it the name-list knobs' own-credential refusal and the withholding on every host child process read an empty declaration and let this service's credentials through.");
+}
 export function ownCredentialsWithheld() {
-    if (declared === undefined || liveConfig === undefined)
+    if (liveConfig === undefined)
         return false;
-    const own = declared.names;
-    return serverWithheldEnvNames(liveConfig.modelApiKeyEnv).every((name) => own.has(name));
+    return ownCredentialNamesNotWithheld(liveConfig.modelApiKeyEnv).length === 0;
 }
 export function ownCredentialValuesWithheld() {
     if (declared === undefined || liveConfig === undefined)
         return false;
-    const own = declared.valueSources;
-    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => own.has(source) || valuesOf([source]).length === 0);
+    const held = declared.held;
+    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => (held.get(source)?.size ?? 0) === credentialsHeldBy(source).length);
+}
+export function ownCredentialVariable(name) {
+    if (inheritEnvPolicyProblem([name]) !== undefined)
+        return "name";
+    const findings = [];
+    inheritedHostEnv([name], findings);
+    return findings.some((f) => f.kind === "own-credential") ? "value" : undefined;
 }
 export function __resetServerWithheldEnvForTest() {
     declareWithheldEnv({ names: [], values: [] });

package/dist/session-agent.d.ts

@@ -14,8 +14,9 @@
  *
  * 投影律(不另铸):`id` = 元组的 `handle`(耐久 agent 行的 `a…` 键,与 fleet 行的 `id`、`GET /v1/agents/roster` 的 `handle` 同一个串);`parentSessionId` /
  * `rootSessionId` = 元组的同名格(派它的会话 / 委派树的根会话);元组缺哪一格这里就缺哪一格;元组的 `scope`(租户键)/ `placedAt` / `kind` 不上 wire。
- * 键在场 = 这是一只委派子代的会话(元组只存了 `kind` 时是 `{}`);键缺席 = 不是 placed 行(宿主会话、同步委派的子代、`subagent_type: "fork"` 的后台子代 ——
- * 它的会话是父会话的一只普通分叉;`DB_BACKEND=local` 到 7.140.x 停驻时拷进宿主店的子代转录,那一份是普通会话行)、这台部署的店不存元组(无 repo 的内存店
+ * 键在场 = 这是一只后台委派子代的会话(普通后台子代与 `subagent_type: "fork"` 的后台子代同样落元组 —— 引擎 7.63.0 起后台 fork 建会话那一笔也交委派元组;
+ * 元组只存了 `kind` 时是 `{}`);键缺席 = 不是 placed 行(宿主会话、同步委派的子代 —— 含同步 fork,它的会话是父会话的一只普通分叉;`DB_BACKEND=local` 到 7.140.x
+ * 停驻时拷进宿主店的子代转录,那一份是普通会话行)、这台部署的店不存元组(无 repo 的内存店
  * 〔`DB_BACKEND=memory`〕、嵌入方自建且不声明委派分区的店),或那一读没读成 —— 消费方一律读作「这台 server 没有说」,不读作「不是子代」。
  */
 import type { SessionPlacementRecord } from "@sema-agent/core";

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

@@ -14,8 +14,8 @@
  *
  * ## 动词(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)+
+ *    `activeDelegationHandles(scope, 根会话)`(没接耐久店的部署只有这一半)。scope 轴由调用方给(唯一派生 {@link sessionTenantScope})。
+ *  · **parked** 行 ⇒ 按店里该卡的属主格 `expire`(`expireCardUnderStoredScope`:属主格读店的列、不读行体;与 core 自己的本进程仲裁器同一只 CAS)+
  *    `registry.reconcileParkedAgents(stores, scope)` ⇒ 行 `failed`(stoppedBy `system`)、卡离开待决面。任何副本上都做得到 ⇒ 预检把它
  *    算作可达(前提是本部署有 checkpoint 店)。
  *    ⚠️ **不对 parked 行调 `stopTask`**:只在耐久店里的行(park 它的进程不在 / 别的副本 / 重启后 —— parked 行活过重启是常态)
@@ -31,7 +31,7 @@
  * 能在树活着时改根放置 / 住客的三门 —— 删除(`boot/session-faces.ts`)、换绑(`routes/devices.ts`)、导入(`routes/session-sync.ts`)—— 与显式结清口
  * `POST /v1/sessions/:id/children/retire`(`routes/background.ts`)都只经这里:**观察**只有 {@link probeSessionChildren}(同一次枚举交出活子代句柄
  * `liveChildren` 与不可达的那几只),**结清**只有 {@link retireSessionChildren}(结果交首轮观察到的句柄 `observed`);scope 只有一处取
- * {@link sessionChildrenScope}(会话属主 `owner ?? "default"`)。wire 上的 `children` / `remaining` 一律经名册的 id 投影出门。
+ * {@link sessionTenantScope}(会话的引擎租户分区)。wire 上的 `children` / `remaining` 一律经名册的 id 投影出门。
  * 子代半是**写前一次观察**:子代登记在 core 的后台子代店,写者的事务装不进这一读(认领半才是写事务内那一读,`execution-placement-sql.ts` 头注)。
  *
  * ## 循环(有上界)
@@ -40,6 +40,7 @@
  * 两轮之间留一小段退避让它落盘。
  */
 import type { BackgroundAgentStore, CheckpointStore, TaskRegistry } from "@sema-agent/core";
+import { type CardSettlePort } from "./card-settle-stored-scope.js";
 /** 重新枚举的轮数上界。 */
 export declare const RETIRE_MAX_ROUNDS = 6;
 /** 两步共用的枚举口。 */
@@ -47,14 +48,16 @@ interface ChildrenSource {
     agentStore: BackgroundAgentStore | undefined;
     registry: Pick<TaskRegistry, "activeDelegationHandles">;
 }
+/** 预检与结清共用的 checkpoint 店口:作废卡({@link CardSettlePort})+ 引擎对账读卡(`get`)—— 预检说「可达」的前提就是结清做得了这两件,所以两步同一个型。 */
+export type ChildrenCheckpointStore = Pick<CheckpointStore, "get"> & CardSettlePort;
 export interface ProbeSessionChildrenDeps extends ChildrenSource {
     /** 缺席 = 本部署没有耐久审批;撞见 parked 行却没有它 ⇒ 那只作废不了 ⇒ 不可达(拒在删之前)。 */
-    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    checkpointStore: ChildrenCheckpointStore | undefined;
     registry: Pick<TaskRegistry, "activeDelegationHandles" | "getAccessibleTask" | "writerId">;
 }
 export interface RetireSessionChildrenDeps extends ChildrenSource {
     /** 缺席 = 本部署没有耐久审批(不可能有 parked 行);撞见 parked 行却没有它 ⇒ 那只作废不了,留到剩余(预检本该已经拒掉它)。 */
-    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    checkpointStore: ChildrenCheckpointStore | undefined;
     registry: Pick<TaskRegistry, "stopTask" | "reconcileParkedAgents" | "activeDelegationHandles">;
     sleep?: (ms: number) => Promise<void>;
 }
@@ -85,10 +88,12 @@ export type RetireSessionChildrenOutcome = {
     readonly remainingHandles: readonly string[];
 };
 /**
- * 以一只根会话为根的后台子代在哪个 scope 分区里枚举 —— **唯一一处取**:会话属主 `owner ?? "default"`(删除门、换绑 / 导入两门、结清口同读;
- * 子代按 run 的 principal 登记、与会话属主不同源的那一形是既有缺陷,修在这里一处)。
+ * 一只会话的**引擎租户分区** —— **唯一一处取**:以它为根的后台子代、它的后台 shell、它的会话信箱盒,都登记在这一分区(删除门、换绑 / 导入两门、结清口、
+ * 删除协调器的信箱腿与 shell 收割腿、删后收尾的丢箱同读;属主串本身不是 scope)。引擎按任务规格的身份格登记,所以这里读的是**引擎交界**
+ * (`engine-identity.ts` 的 `taskSpecIdentityOf`)从会话属主恢复出的那一格:没带场景的会话 = 属主(逐字节同改前);带场景的会话(属主 `_scn:<场景>:<人>`)=
+ * 引擎登记时用的那一个值(今天是人)—— 按属主串去枚举 / 退役 / 收割会打到一个空分区。无主 ⇒ `"default"`。
  */
-export declare function sessionChildrenScope(owner: string | null): string;
+export declare function sessionTenantScope(owner: string | null): string;
 /**
  * **可达性预检**(零写;协调器在任何破坏性步骤之前调)。parked 行在有 checkpoint 店时可达(expire + reconcile 在任何副本上都成);
  * running 行除非 {@link runsOnAnotherReplica} 都可达(`getAccessibleTask` / `agentStore.get` 都是纯读,不动任何东西)。

package/dist/session-children-retire.js

@@ -1,7 +1,13 @@
+import { partsOf } from "./owner-brands.js";
+import { recoveredSubject } from "./owner-faces.js";
+import { taskSpecIdentityOf } from "./engine-identity.js";
+import { expireCardUnderStoredScope } from "./card-settle-stored-scope.js";
 export const RETIRE_MAX_ROUNDS = 6;
 const RETIRE_BACKOFF_MS = [0, 25, 50, 100, 200, 400];
-export function sessionChildrenScope(owner) {
-    return owner ?? "default";
+export function sessionTenantScope(owner) {
+    if (owner === null)
+        return "default";
+    return taskSpecIdentityOf(partsOf(recoveredSubject(owner))).principal ?? "default";
 }
 async function liveChildren(deps, rootSessionId, scope) {
     const out = new Map();
@@ -69,11 +75,7 @@ async function expireParkedCard(deps, handle, scope) {
     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);
+    await expireCardUnderStoredScope(deps.checkpointStore, row.parkedCheckpointToken);
 }
 export class SessionChildrenStopIncompleteError extends Error {
     sessionId;

package/dist/session-deletion.d.ts

@@ -0,0 +1,88 @@
+/**
+ * **会话的三态:活 → 在删 → 没了**(删会话 × 提交只赢一个的律;规则只写在这里一次,三只会话店与删除协调器同读)。
+ *
+ * ## 律
+ * 一只会话行此刻是三态之一:
+ *  · **活** —— 接受一切读写;
+ *  · **在删** —— 一次删除已经在根行锁里判过「没有在跑的 run、属主是调用方」并立了围栏(写下自己的**删除尝试令牌**),还没删完。在删由持令牌的那一次删除**独占**:
+ *    删除门之外的一切读者与写者把它读作「行不在」(头读、列表、认领点的规则 L、登记 —— 撞上即「已存在」,不新建);认领落不下,于是删除级联的每一腿都只作用在一只
+ *    不会再起回合的会话上;
+ *  · **没了** —— 行删掉了;同 id 的下一次登记是新住客。
+ * 在删**不回到活**(没有放弃删除的臂:子代可达性预检在围栏之前,终刀失败只会重试)⇒ 围栏之后立的外部围栏(会话盒墓碑)不会挡错一只活会话。
+ *
+ * ## 谁写、谁读
+ *  · 围栏(活 → 在删 / 在删 → 在删 = 接管已死的那一次、换令牌)= {@link SessionDeletionFace.fence}:删除路**唯一**的认领判;一次仍可能活着的删除持有的行**不接管**
+ *    (答「在删中」)—— 否则陈旧尝试与接管者交错、接管者删完而同 id 重登记之后,陈旧尝试的下一腿会落在新住客身上;
+ *  · 终刀(在删 → 没了)= 删净一只会话的**执行体**(`src/session-erase.ts`;SQL = 执行器的 `eraseSession`,local = 会话店的删除锁节 `deleteSession(id, owner, token, legs)`):
+ *    根行锁里比属主、判「这一行处于本令牌的在删态」(判官 `judgeSessionWrite` 的 `erase` 词),不是 ⇒ 一行不删;是 ⇒ 同一个事务 / 锁节删完会话挂靠的全部行、行最后删;
+ *  · 执行体之前的每一步进程面动作(不在根行锁里)之前,协调器问 {@link SessionDeletionFace.holds}:令牌被换了(另一次删除接管)⇒ 这次尝试就此停,答「被接管」;
+ *  · 唯一收尾者 = 删除协调器:起服装配完之后按 {@link SessionDeletionFace.pending} 逐只再跑一遍(= 接管**那一只令牌**:读到之后那一次删完、同 id 重登记的新行不被碰);
+ *    持有者已死的在删行,重发的 DELETE 同样是接管。
+ * 持久面:SQL = 旁表 `session_ext.deleting_token`(列属主 `plugins/session-ext-table.ts`);local = 会话元数据边档那一格的 `deleting`。
+ */
+/** 围栏的回执:这一次删除的令牌 + 被删的那一位住客的化身(空间回收的键;存量行没有化身 ⇒ `undefined`)。 */
+export interface SessionDeletionTicket {
+    readonly token: string;
+    readonly incarnation: string | undefined;
+}
+/** 此刻处于在删态的一行(收尾者的输入):它的 id、属主与持有它的令牌(收尾按这一位属主、**只接管这一只令牌**再跑一遍协调器)。 */
+export interface PendingSessionDeletion {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly token: string;
+}
+/**
+ * 一只在删令牌的持有者此刻在哪(协调器答,它记得本进程铸过的每一只令牌):`running` = 本进程里那一次删除还在跑;`ended` = 本进程里那一次已经结束而没删完
+ * (某腿失败 / 被接管)—— 死的;`elsewhere` = 不是本进程铸的(上一个进程 / 别的副本)。
+ */
+export type DeletionHolder = "running" | "ended" | "elsewhere";
+/** 围栏的选项:`holder` = 令牌持有者在哪(协调器的在飞表);`expect` = 只接管这一只令牌(收尾者;活行 / 别的令牌 ⇒ `undefined`)。 */
+export interface SessionDeletionFenceOptions {
+    readonly holder: (token: string) => DeletionHolder;
+    readonly expect?: string;
+}
+/** 围栏的答复:回执(本次立了 / 接管了)· `inProgress`(一次仍可能活着的删除持有这一行 —— 不接管)· `undefined`(行不在 / 属主不是这一位 / 收尾者的令牌对不上)。 */
+export type SessionDeletionFenceAnswer = SessionDeletionTicket | {
+    readonly inProgress: true;
+} | undefined;
+/**
+ * 别的进程里一次删除的令牌**多久之后**才可以被接管(SQL 多副本:另一副本上那一次删除可能还活着,本进程看不见它)—— 令牌是 uuidv7,它的时刻就是那一次尝试的起点。
+ * 一次删除的各腿通常几秒内跑完(子代停止有轮次上界、后台 shell 的硬杀宽限是秒级);十分钟之后仍未删完的读作那一次已死(崩溃 / 进程被杀)。
+ * 如实的边:一次活着却卡过十分钟的删除会被接管,它此后的每一腿之前读到令牌已换、就此停 —— 两腿之间的那一拍是披露的残余(`src/boot/session-faces.ts` 的协调器注)。
+ * local 数据根独占(一个数据根恒一个进程),别的进程的令牌一律是死的 ⇒ 不读这只数。
+ */
+export declare const CROSS_PROCESS_TAKEOVER_AFTER_MS: number;
+/** 一只令牌(uuidv7)的铸造时刻(ms;读不出 ⇒ `undefined`,读者按「刚铸」处置 —— 不接管)。 */
+export declare function deletionTokenMintedAt(token: string): number | undefined;
+/** 会话店的删除面(三只会话店各一只实现,暖缓存包装原样转发;一只能力位 —— 三个动词同在或同缺)。 */
+export interface SessionDeletionFace {
+    /**
+     * 立围栏:根行锁里 ——
+     *  · 活行 ∧ 属主是 `owner`(字面相等,`null` 与 `null` 相等)∧ 不带 `expect` ⇒ 判认领(在 ⇒ 抛 `SessionActiveRunError`,一个字节不写)、写新令牌;
+     *  · 在删行 ∧ 属主等 ∧(不带 `expect` 或持有的就是它)⇒ 持有它的那一次**仍可能活着**(`holder` 答 `running`;SQL 另加:答 `elsewhere` 而令牌铸于
+     *    {@link CROSS_PROCESS_TAKEOVER_AFTER_MS} 之内 —— 别的副本上那一次可能还在跑)⇒ `{ inProgress }`(不接管、不写);否则(那一次已死)⇒ **接管**:换新令牌
+     *    (在删期间认领落不下,不再判);带 `expect` 而持有的不是它 ⇒ `undefined`;
+     *  · 行不在 / 属主不等 / 带 `expect` 而这一行是活的 ⇒ `undefined`(一个字节不写)—— 收尾者永远不把一只活行送进在删。
+     */
+    fence(sessionId: string, owner: string | null, opts: SessionDeletionFenceOptions): Promise<SessionDeletionFenceAnswer>;
+    /** `token` 此刻仍是这只会话的在删令牌(无锁一读;行不在 / 活 / 别的令牌 ⇒ `false`)。 */
+    holds(sessionId: string, token: string): Promise<boolean>;
+    /** 此刻处于在删态的全部行(按 id 排序)。 */
+    pending(): Promise<readonly PendingSessionDeletion[]>;
+}
+/**
+ * 删除协调器的结局(`DELETE /v1/sessions/:id` 读它,一形一句):
+ *  · `{ deleted: true }` —— 这一次删完了(终刀删掉了行);`{ deleted: false }` —— 门验过之后行已不在 / 不是这一位的(什么都没删);
+ *  · `{ active }` —— 围栏判到认领(409 `conflict.session_active_run`,一字节没写);`{ childrenAlive }` —— 子代预检拒(409 `conflict.session_children_alive`,一字节没写);
+ *  · `{ inProgress: true }` —— 同一只会话的另一次删除持有它(仍在跑,或接管了这一次)—— 409 `conflict.session_deleting`,由那一次删完;这次请求不再删任何东西。
+ */
+export type SessionPurgeOutcome = {
+    readonly deleted: boolean;
+} | {
+    readonly active: string;
+} | {
+    readonly childrenAlive: readonly string[];
+} | {
+    readonly inProgress: true;
+};
+//# sourceMappingURL=session-deletion.d.ts.map

package/dist/session-deletion.js

@@ -0,0 +1,8 @@
+export const CROSS_PROCESS_TAKEOVER_AFTER_MS = 10 * 60_000;
+export function deletionTokenMintedAt(token) {
+    const hex = token.replace(/-/g, "");
+    if (!/^[0-9a-f]{32}$/i.test(hex) || hex[12] !== "7")
+        return undefined;
+    return parseInt(hex.slice(0, 12), 16);
+}
+//# sourceMappingURL=session-deletion.js.map

package/dist/session-erase.d.ts

@@ -0,0 +1,145 @@
+/**
+ * **删净一只会话 —— 一只执行体**(两个决定者共用:`DELETE /v1/sessions/:id` 的删除协调器 `boot/session-faces.ts`,与托管留存的会话树清扫)。
+ *
+ * ## 律
+ * 删净一只会话 = **在这只会话的行锁下**删完它挂靠的全部行,行本身最后删:
+ *  · SQL 后端:一个事务(执行器 `stores-sql/retention-store-sql.ts` 的 `eraseSession` / `deleteExpiredSessions`,两只入口跑同一段事务体
+ *    —— 锁行 → 会话座事务内钩判 → 部署行 → 引擎座行 → 行与日志 → 墓碑);
+ *  · local 后端:{@link createLocalSessionEraser} —— 会话店这只会话的写锁一节(判 → 各店动词按 {@link SESSION_TREE_LEGS} → 删行)。
+ * 锁里那一判按决定者:在线删除 = 行的属主是围栏判过的那一位 ∧ `erase`(这一行处于**这一次删除的在删态** —— 令牌比对;会话三态 活 → 在删 → 没了,
+ * 律在 `session-deletion.ts`,围栏是删除协调器的事);留存 = `retention-delete`(没有认领、不在删)。令牌只在围栏判过属主之后写下,同 id 的下一位住客是新行、不带它 ⇒
+ * 一次陈旧 / 被接管的删除在锁里读到的不是自己的令牌,一行不删(`superseded`)。属主那一比是域键的一致性(SQL 的部署行与墓碑按域写,域在事务开之前就要定)。
+ * 会话挂靠的**行**都在锁里(含完成信箱的清除围栏与会话盒):删不掉 ⇒ 行留在删、删除可重试;锁着 ⇒ 碰不到下一位住客。提交之后由**同一只**收尾
+ * {@link createSessionEraseSettler} 处理按内容 / 按住客化身寻址的残余(附件字节、住客空间);SQL 组合座另在提交之后按「入队不晚于提交」清一次
+ * 事务进行中落下的迟到完成行(`retention-deployment.ts` 的 `sweepLateCompletionRows`)。
+ * 不在锁里的:在线删除在围栏之后、执行体之前对这只在删会话做的进程面动作(信箱 retire 围栏、子代结束、scratchpad、后台 shell、删过的 id)——
+ * 删除协调器每一步之前核令牌(`boot/session-faces.ts`);一步已经开跑时被接管的那一拍是协调器注里披露的残余(不是行)。
+ *
+ * ## 决定者之差
+ * 在线删除删的是一只**可能还活着**的会话(删前:子代预检 → 围栏 → 信箱 retire 围栏、子代结束、本进程删过的 id;删后:本副本的进程态);留存只删闲到视界外、
+ * 无活引用、不在删的会话(hold / 候选 / 活引用 / 审计)。行面唯一的差:规则行的 rev 高水位记号(在线留、留存删;`retention-store-sql.ts` 的 `RuleMarks`)。
+ */
+import { type MailboxStore, type ToolResultStore } from "@sema-agent/core";
+import type { Logger } from "./observability/logger.js";
+import type { WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+import type { SpaceReclaimer } from "./workspace-space.js";
+/** 锁里读到的这一位住客(会话行上的属主 + 化身;存量行没有化身 ⇒ `undefined`)。 */
+export interface SessionOccupant {
+    readonly owner: string | null;
+    readonly incarnation: string | undefined;
+}
+/** 一次执行体提交之后交收尾的东西:真删掉的会话(id + 删前属主 + 住客)、本次删掉的附件行的字节哈希、全库无出处卸载结果数。 */
+export interface SessionTreesErased {
+    readonly sessions: readonly {
+        readonly sessionId: string;
+        readonly owner: string | null;
+        readonly incarnation: string | undefined;
+    }[];
+    /** 本次删掉的附件行的字节哈希(收尾按「无行引用才删」释放;local 的附件店随行删字节,恒空)。 */
+    readonly attachmentShas: readonly string[];
+    /** 全库无出处的卸载结果行数(core 口径:这类行任何会话删除都删不到 ⇒ 删除不完整;实体清理归 TTL)。 */
+    readonly unattributableToolResults: number;
+}
+/** 执行体的回执(闭集)。 */
+export type SessionEraseReceipt = 
+/** 这一行此刻不是这一次删除的在删态 —— 另一次删除接管了它(换了令牌)或已经删完(行不在 / 同 id 的新住客)。一行没删。 */
+{
+    readonly outcome: "superseded";
+}
+/** 全部行已删、已提交。 */
+ | {
+    readonly outcome: "erased";
+    readonly trees: SessionTreesErased;
+};
+/** 执行体的入参:哪只会话 + 删除协调器的围栏判过的那一位属主(域键)+ 围栏写下的令牌(判官比的那一只)。 */
+export interface SessionEraseInput {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly token: string;
+}
+/** 删净一只在删会话的执行体(SQL:执行器的组合座交出;local:{@link createLocalSessionEraser})。 */
+export interface SessionEraser {
+    erase(input: SessionEraseInput): Promise<SessionEraseReceipt>;
+}
+/**
+ * 会话树的行腿 —— **闭集,序即执行序**(SQL 事务体的语句序对它:`test/session-erase-single-executor.test.ts` 录制钉按首次出现序比)。
+ * `checkpoint` 腿含停驻 ctx 旁表(SQL 上 ctx 在部署段、检查点行在引擎座段,首次出现序落在这里)。`mailbox` 是行删除之前的**最后一腿**:会话盒的 `drop`
+ * 同时撤掉投递围栏(墓碑随箱亡),之后除了会话行不许再有别的腿(local 上各店逐个落盘,围栏撤了而行还在的那一段窗只容会话行那一步)。
+ */
+export declare const SESSION_TREE_LEGS: readonly ["runs", "approval", "checkpoint", "anchors", "exemption", "attachment", "user_input", "task_list", "workflow_inbox", "tool_result", "policy", "file_history", "mailbox"];
+export type SessionTreeLeg = (typeof SESSION_TREE_LEGS)[number];
+/** local 执行体的各店(缺席 = 本部署没有这只店 ⇒ 这一腿无行可删)。动词与在线协调器此前逐店调的同一组。 */
+export interface LocalSessionTreeStores {
+    readonly runStore: {
+        deleteBySession(sessionId: string): Promise<{
+            removed: number;
+        }>;
+    } | undefined;
+    readonly approvalAskStore: {
+        deleteBySession(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly checkpointStore: {
+        deleteBySession(sessionId: string, owner: string | null): Promise<number>;
+    } | undefined;
+    readonly resumeAnchorStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly approvalExemptionStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly taskAttachmentStore: {
+        deleteBySession(sessionId: string): Promise<number>;
+    } | undefined;
+    readonly userInputLedgerStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly taskListLane: {
+        deleteBySession(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly workflowCompletionInbox: Pick<WorkflowCompletionInbox, "purge"> | undefined;
+    readonly mailboxStore: Pick<MailboxStore, "drop"> | undefined;
+    readonly toolResultStore: Pick<ToolResultStore, "deleteBySession"> | undefined;
+    readonly sessionPolicyStore: {
+        deleteBySession?(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly fileHistoryErasure: {
+        deleteBySession?(scope: string): Promise<unknown>;
+        reap(scope: string, keep: readonly string[]): Promise<unknown>;
+    } | undefined;
+}
+/**
+ * local 会话店的删除锁节(`plugins/local-session-store.ts` 的 `deleteSession`):这只会话的写锁里 —— 行不在 / 属主不是 `owner` ⇒ `undefined`;
+ * `erase` 判(这一行处于 `token` 那一次删除的在删态;不是 ⇒ 抛 `SessionDeletionSupersededError`)—— 两支都一行不删;→ `legs(锁里读到的住客)` → 删行,交回那一位住客。
+ */
+export type LocalSessionDeletionSection = (sessionId: string, owner: string | null, token: string, legs: (occupant: SessionOccupant) => Promise<void>) => Promise<SessionOccupant | undefined>;
+/**
+ * local 后端的执行体:会话店写锁一节里按 {@link SESSION_TREE_LEGS} 跑各店动词(闭集 `switch`,漏一腿 = 编译红)。一腿抛 ⇒ 锁节抛、行不删(重发收敛)。
+ */
+export declare function createLocalSessionEraser(deleteSession: LocalSessionDeletionSection, stores: LocalSessionTreeStores, logger: Pick<Logger, "warn">): SessionEraser;
+/** 收尾要的座(缺席 = 本部署没有这一样残余)。 */
+export interface SessionEraseSettleSeats {
+    /** 附件字节的释放口(SQL 附件店:无行引用才删对象)。 */
+    readonly attachments: {
+        releaseBytes(shas: readonly string[]): Promise<{
+            readonly failed: readonly string[];
+        }>;
+    } | undefined;
+    readonly spaceReclaimer: SpaceReclaimer | undefined;
+    readonly logger: Pick<Logger, "warn">;
+}
+/**
+ * 收尾:一次执行体提交之后对真删掉的会话处理库外残余。答出时附件字节那一步已做完;`spaces` = 住客空间回收那一步
+ * (对象存储上的一串请求,座按契约不抛、抛了已被这里响亮接住 ⇒ 它永不拒):在线删除不等它(应答不等对象存储),留存清扫等它(一轮在截止上收手)。
+ */
+export type SessionEraseSettler = (trees: SessionTreesErased) => Promise<{
+    readonly spaces: Promise<void>;
+}>;
+/**
+ * 两个决定者共用的**收尾**(行已删、已提交)。只收**按内容寻址 / 按住客化身寻址**的残余 —— 碰不到同 id 重登记的下一位住客;
+ * 会话挂靠的行(含完成信箱围栏与行、会话盒)都在执行体的锁里(删不掉 ⇒ 行留着、删除可重试)。每一步失败只记一行 warn,各有兜底:
+ *  ① 附件字节 —— 本次删掉的附件行的哈希,无行引用才删对象(孤儿 GC 兜底);
+ *  ② 住客空间 —— 住客化身在的会话交回收座(答案里的 `spaces`:等不等它是决定者的事;座按契约不抛,抛了这里响亮接住;桶的生命周期规则兜底);
+ *  ③ 全库无出处卸载结果数 > 0 ⇒ 一行 warn(删除不完整的如实告知)。
+ */
+export declare function createSessionEraseSettler(seats: SessionEraseSettleSeats): SessionEraseSettler;
+//# sourceMappingURL=session-erase.d.ts.map

package/dist/session-erase.js

@@ -0,0 +1,115 @@
+import { peerSessionBoxHandle } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { redactIncarnations } from "./session-incarnation.js";
+import { seatText } from "./trace/exit-seat.js";
+import { sessionTenantScope } from "./session-children-retire.js";
+import { SessionDeletionSupersededError } from "./execution-placement.js";
+export const SESSION_TREE_LEGS = ["runs", "approval", "checkpoint", "anchors", "exemption", "attachment", "user_input", "task_list", "workflow_inbox", "tool_result", "policy", "file_history", "mailbox"];
+export function createLocalSessionEraser(deleteSession, stores, logger) {
+    return {
+        async erase({ sessionId, owner, token }) {
+            let unattributable = 0;
+            const leg = async (which, occupant) => {
+                switch (which) {
+                    case "runs":
+                        return void (await stores.runStore?.deleteBySession(sessionId));
+                    case "approval":
+                        return void (await stores.approvalAskStore?.deleteBySession(sessionId));
+                    case "checkpoint":
+                        return void (await stores.checkpointStore?.deleteBySession(sessionId, occupant.owner));
+                    case "anchors":
+                        return void (await stores.resumeAnchorStore?.deleteBySession(sessionId));
+                    case "exemption":
+                        return void (await stores.approvalExemptionStore?.deleteBySession(sessionId));
+                    case "attachment":
+                        return void (await stores.taskAttachmentStore?.deleteBySession(sessionId));
+                    case "user_input":
+                        return void (await stores.userInputLedgerStore?.deleteBySession(sessionId));
+                    case "task_list":
+                        return void (await stores.taskListLane?.deleteBySession(sessionId));
+                    case "workflow_inbox":
+                        return void (await stores.workflowCompletionInbox?.purge(sessionId, occupant.owner));
+                    case "tool_result": {
+                        const report = await stores.toolResultStore?.deleteBySession?.(sessionId);
+                        if (report !== undefined)
+                            unattributable = report.unattributable;
+                        return;
+                    }
+                    case "policy":
+                        return void (await stores.sessionPolicyStore?.deleteBySession?.(sessionId));
+                    case "file_history": {
+                        const erasure = stores.fileHistoryErasure;
+                        if (erasure === undefined)
+                            return;
+                        if (typeof erasure.deleteBySession === "function")
+                            return void (await erasure.deleteBySession(sessionId));
+                        await erasure.reap(sessionId, []);
+                        logger.warn("session_file_history_baselines_retained", {
+                            sessionId,
+                            note: "this file-history store has no whole-scope erase verb (deleteBySession); boundaries were reaped but v1 baselines (original file bytes) remain in the store until it implements that verb — an open deletion-rights gap, not silent",
+                        });
+                        return;
+                    }
+                    case "mailbox":
+                        return void (await stores.mailboxStore?.drop(sessionTenantScope(occupant.owner), peerSessionBoxHandle(sessionId)));
+                    default: {
+                        const unknownLeg = which;
+                        throw new Error(`session erase: no arm for leg ${JSON.stringify(unknownLeg)}`);
+                    }
+                }
+            };
+            let erased;
+            try {
+                erased = await deleteSession(sessionId, owner, token, async (occupant) => {
+                    for (const which of SESSION_TREE_LEGS)
+                        await leg(which, occupant);
+                });
+            }
+            catch (err) {
+                if (err instanceof SessionDeletionSupersededError)
+                    return { outcome: "superseded" };
+                throw err;
+            }
+            if (erased === undefined)
+                return { outcome: "superseded" };
+            return { outcome: "erased", trees: { sessions: [{ sessionId, ...erased }], attachmentShas: [], unattributableToolResults: unattributable } };
+        },
+    };
+}
+export function createSessionEraseSettler(seats) {
+    const { logger } = seats;
+    return async (trees) => {
+        if (trees.attachmentShas.length > 0 && seats.attachments !== undefined) {
+            const released = await seats.attachments.releaseBytes(trees.attachmentShas).catch((err) => ({ failed: trees.attachmentShas, err: seatText("operator-log-text", String(err)) }));
+            if (released.failed.length > 0) {
+                logger.warn("session_erase_attachment_bytes_release_failed", {
+                    shas: trees.attachmentShas.length,
+                    failed: released.failed.length,
+                    ...("err" in released ? { err: released.err } : {}),
+                    effect: "these objects stay until the orphan-object sweep collects them (its grace applies)",
+                });
+            }
+        }
+        const spaces = trees.sessions.flatMap((s) => (s.incarnation === undefined ? [] : [{ sessionId: s.sessionId, spaceKey: s.incarnation }]));
+        let reclaimed = Promise.resolve();
+        if (spaces.length > 0 && seats.spaceReclaimer !== undefined) {
+            reclaimed = seats.spaceReclaimer.reclaim(spaces).catch((err) => {
+                recordFailOpen("server.workspace-space.reclaim-failed", "stage=seat_threw");
+                logger.warn("workspace_space_reclaim_failed", {
+                    sessions: spaces.length,
+                    stage: "seat_threw",
+                    error: seatText("operator-log-text", redactIncarnations(String(err))),
+                    effect: "the ended space's cache volume and snapshot objects may stay (the reclaim seat threw, which its contract forbids; the session delete went ahead) — the bucket's lifecycle rule is the fallback for objects, the volume is deleted by label sema.space",
+                });
+            });
+        }
+        if (trees.unattributableToolResults > 0) {
+            logger.warn("tool_result_unattributable_rows_survive_session_delete", {
+                sessions: trees.sessions.map((s) => s.sessionId),
+                unattributable: trees.unattributableToolResults,
+            });
+        }
+        return { spaces: reclaimed };
+    };
+}
+//# sourceMappingURL=session-erase.js.map