@sema-agent/server 7.29.0 → 7.30.0-rc.1

package/USAGE.md

@@ -667,11 +667,26 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 >   治理拍),锁上会让**每一条**任务在引擎门口被拒,而那把锁本就无物可守(策略已是部署所有、请求放松不了);
 >   ②`mcp` + 部署自己配了 MCP 服务器——部署的服务器走同一个字段,锁上同样每条腿必拒。两者都在**启动期**点名拒,
 >   不留给运维在每条任务上猜。
-> - `RETENTION_MAX_AGE_DAYS=<非负数>`:托管留存期**声明**。⚠️ **不要读成「数据会按期删」**:本版没有任何 store
->   声明托管留存能力、也没有留存调度面,所以这根旋钮目前只做两件事——喂引擎的启动期能力校验(把
->   `retentionPolicy` 一并写进 `LOCKED_CONFIG_KEYS` 而 store 不能删 ⇒ **拒启**,杜绝「策略锁着、数据永存」),
->   以及在配了策略却无执行面时打一条启动 warn(`retention_policy_not_executed`)。真执行(调度/重试/副本协调/
->   逐行审计)是后续批。
+> - `RETENTION_MAX_AGE_DAYS=<非负数>`:托管留存**视界**(天;`0` 合法=立即可删)。坏值(非数/负数/设了但为空)
+>   一律拒启——删数据的旋钮不许 NaN 流通。**它只是"保留多久"这句声明**;真正按它删数据的是下面两根。
+> - `RETENTION_SWEEP_INTERVAL_SEC=<非负整数>`(默认 `0` = **关**;上限 `2147483` 秒 ≈ 24.8 天):
+>   托管留存 **sweep lane** 的节律。`>0` 才起这条腿。越上限拒启(`setInterval` 的 32 位 delay 帽:溢出会被
+>   Node 静默重置成 1ms,把一次"偶尔扫一遍"变成近乎连续的破坏性事务流)。
+>   🔴 **半配置一律拒启**(不看有没有上锁):`>0` 而 ①没配 `RETENTION_MAX_AGE_DAYS`(没有视界就算不出 cutoff)、
+>   或 ②后端不是 SQL(`DB_BACKEND=mysql|pg`;local/文件后端诚实声明 `retention:"none"`,没有任何东西会删行)
+>   ⇒ 启动期点名拒。**多副本安全**:互斥靠库内单行 **sweep 租约**(fencing token 随每一条破坏性审计行走),
+>   与 `LEADER_ENABLED` **无关**——不必先开 leader 面。
+> - `RETENTION_MODE=audit-only|enforce`(默认 `audit-only`):灰度档。`audit-only` = lane 照跑照判、每个域记一条
+>   `audit_only` 审计行(三个候选计数),**一条破坏性方法都不调**;`enforce` = 真删。闭集,拼错的词拒启
+>   (静默落回默认档 = 运维以为在删而其实没删)。**回滚边界 = 翻回 `audit-only`**(已删不可逆),所以先在
+>   `audit-only` 上读几天审计行确认命中集无误再翻。
+>
+>   **配套的 operator 面**(全部 `operator-only`,见 `OPERATOR_PRINCIPALS`):
+>   - `PUT /v1/ops/retention/holds/:domain` / `DELETE …` —— 按域下/解 **legal hold**(冻结期该域整体跳过;
+>     空路径段 `…/holds/` 寻址**无主桶**,即单用户部署里那唯一的域)。放置与解除各写一条审计行,
+>     且**状态变更与审计行同一个事务**(不存在"解冻了但账上没有")。
+>   - `GET /v1/ops/retention/audit?domain=&limit=&before=` —— 审计读面(keyset 分页,游标形同名册面)。
+>   - 能力位 `capabilities.retention` = `{mode, maxAgeDays}`(lane 开着)或 `null`(关着)。
 
 > **⚠️ hook-wired 部署里,parked 后台子代可能赎回不了(常态,不是升级窗口)。**
 > 引擎 5.19.0 起,一个任务的 **PreToolUse screening 面下延管辖它委派出去的子代**,于是 hook-wired 父

package/dist/boot/governance-seams.d.ts

@@ -71,6 +71,19 @@ export interface GovernanceSeamsCtx {
         name: string;
         store: object | undefined;
     }>;
+    /**
+     * #270 车1 —— **本 build 是否真的接了留存执行器**(sweep lane;车2 的 `startRetentionLane()`)。
+     * 缺席 = `false`。
+     *
+     * 🔴 为什么这一位必须存在(codex 对抗复审 R2-[critical],验真后修):core 的
+     * `assertRetentionCapability` 只读**店的声明位**。#270 车1 让三只 SQL 店如实声明了 `"managed"`
+     * (它们的行确实由托管留存删),于是那道门从此**放行** locked policy —— 可执行器还在车2 手里。
+     * 两者之间的窗口如果什么都不做,后果正是本仓最忌的那种:部署自述「策略已受管」、审计与能力面
+     * 也这么说,而**没有任何东西在删数据**;车1 之前那条 `retention_policy_not_executed` 的响亮 warn
+     * 还会因为"有 managed 店在场"而**静音**。
+     * ⇒ 判据改成问「有没有东西真会删」,而不是「有没有店说自己被管」。车2 接上 lane 时把这一位传 true。
+     */
+    retentionExecutorWired?: boolean;
 }
 /**
  * 件C 的装配相容性判据(纯,可单测)——见文件头「两条判据」。

package/dist/boot/governance-seams.js

@@ -132,11 +132,13 @@ export function createGovernanceSeams(ctx) {
     }
     // 件D:留存期。先跑 core 的启动期校验(策略值本身 + 锁着时的店能力),再补一条本仓特有的诚实 warn。
     const retentionPolicy = config.retentionPolicy;
-    assertRetentionCapability({ policy: retentionPolicy, locked: lockedKeys.has("retentionPolicy"), stores: retentionStores });
+    const locked = lockedKeys.has("retentionPolicy");
+    assertRetentionCapability({ policy: retentionPolicy, locked, stores: retentionStores });
     if (retentionPolicy !== undefined) {
         // 声明位的读法与 core 的校验口**同一个结构型**(`RetentionDeclaring`)——不自造一个平行的形状,
         // 否则「core 认为这店 managed / 我方认为不是」这种分歧会静默存在。
         const managed = retentionStores.filter((s) => s.store?.retention === "managed");
+        const executorWired = ctx.retentionExecutorWired === true;
         if (managed.length === 0) {
             logger.warn("retention_policy_not_executed", {
                 maxAgeDays: retentionPolicy.maxAgeDays,
@@ -145,6 +147,24 @@ export function createGovernanceSeams(ctx) {
                     "engine for the startup capability check and will become effective when a managed-retention store + scheduler land.",
             });
         }
+        else if (!executorWired) {
+            // 🔴 #270 车1(codex R2-[critical] 验真后修):**店说 managed ≠ 有人在删**。
+            //  · locked ⇒ **拒启**:core 的门因为声明位而放行了,可这台机上没有执行器 —— 那正是它文案里
+            //    「policy locked, data immortal」的实况,只是伪装成了合规。拒启保住的是车1 之前的**同一个**
+            //    行为(那时店声明 none ⇒ core 直接拒),不是新增的严格。
+            //  · 未锁 ⇒ **响亮 warn**(不拒启):未锁的策略本就是一句声明,但它此前那条 warn 会被「有 managed
+            //    店在场」静音,于是最需要说话的那一刻反而没声音。
+            const detail = `retention policy is configured (maxAgeDays=${retentionPolicy.maxAgeDays}) and ${managed.length} wired store(s) declare ` +
+                `retention:"managed", but THIS BUILD WIRES NO RETENTION EXECUTOR (the sweep lane) — nothing enumerates domains or calls ` +
+                `the destructive store methods, so no data is deleted on the policy's account. A "managed" declaration is a statement ` +
+                `about who OWNS deleting those rows, not proof that a scheduler is running.`;
+            if (locked) {
+                throw new Error(`${detail} Refusing to start with the retentionPolicy key LOCKED: a locked policy over a deployment that does not ` +
+                    `actually delete is exactly the "policy locked, data immortal" posture the engine's capability check exists to ` +
+                    `prevent. Unlock the key, remove the policy, or run a build whose retention sweep lane is wired.`);
+            }
+            logger.warn("retention_policy_not_executed", { maxAgeDays: retentionPolicy.maxAgeDays, note: detail });
+        }
     }
     return { compliancePostureResolver, lockedConfig, retentionPolicy, lockedKeys };
 }

package/dist/boot/retention-lane.d.ts

@@ -0,0 +1,206 @@
+/**
+ * #270 车2 —— 托管留存的 **sweep lane**(设计稿 `docs/DESIGN-270-retention-lane.md` v1.3 §3/§4/§7)。
+ *
+ * ── 为什么是独立文件、独立定时器,而不是折进 `startReapers()`(设计稿 §3 首条)───────────────────
+ * `boot/reapers.ts` 里那二十条腿全都是**容忍多副本**的幂等清理:每台副本各扫各的,重复扫一遍只是浪费。
+ * 本 lane 相反 —— 它按「三方法依赖序」跑一段**有状态**的序列(expire → deleteSessions → deleteOrphans),
+ * 并给每一轮打一个 fencing token 写进不可变审计。这条约束(单执行者)混进那个 tick 会被稀释成
+ * 「反正大家都幂等」,而幂等救不了「两个副本各写一半审计、token 交错」。所以:自己的定时器、自己的
+ * durable 租约、自己的失败隔离。
+ *
+ * ── 互斥 = durable lease,**不是** `LEADER_ENABLED`(设计稿 §3,codex F1 亲验坐实)───────────────
+ * 仓内 `leaderEnabled` 是纯布尔配置门(gate 端点与腿注册),零选举/零租约/零 fencing —— 每台配 true 的
+ * 副本都会「自认 leader」。lane 与它**解耦**:租约自持互斥,operator 不必先开 leader 面。
+ *
+ * ── 时序契约(逐条都是判据,别重排)────────────────────────────────────────────────────────────
+ *  ① 每 tick 开头抢/续租(`lease.acquire`)。抢不到 ⇒ **本 tick 零写、零调用、静默返回**(不是错误:
+ *     "别人在跑"是正常的多副本稳态,每 tick 打一条 warn 只会把日志变成噪音)。
+ *  ② 抢到 ⇒ 枚举域;**对每个 domain,在动它之前**复核**并续**租约(`lease.renew`,一条 CAS)。复核点在**每 domain 前**
+ *     而不是每 tick 前,这一格是承重的:一轮 sweep 的时长随域数增长,而租约 TTL 是固定的 2×interval ——
+ *     只在轮首复核等于「开轮时还在,那这一轮剩下的几百个域都算数」,那正是丢租之后继续删数据的形。
+ *  ③ 模式分家(§4):`audit-only` 只调 `previewRetention` 记 `audit_only` 行,**一条破坏性方法都不调**;
+ *     `enforce` 才调三方法。两支在代码里**物理分开**(不是同一段带 `if` 的调用序)—— 自审判据「grep 三个
+ *     方法名只出现在 enforce 臂」靠的就是这个形。
+ *  ④ 单 domain 失败 ⇒ 记 `failed` 行 + **继续下一 domain**(一个坏租户不钉死整轮);同 domain 连败
+ *     ≥ {@link RETENTION_SWEEP_STUCK_THRESHOLD} ⇒ `retention_sweep_stuck` 指标 + **一次性** warn。
+ *
+ * ── 破坏性审计行的属主(§6 F5)────────────────────────────────────────────────────────────────
+ * `expired_checkpoints`/`deleted_sessions`/`deleted_tool_results` 三行由**店**在删除的同一个 DB 事务里写
+ * (车1 已实现)。lane **不补记**它们 —— 补记 = 「删了但审计没落地」的窗口重新打开。receipt 在本文件里
+ * 只做两件事:二次确认(日志/指标)与「本轮到底动了多少」的读数。
+ */
+import type { RetentionPolicy, RetentionReceipt } from "@sema-agent/core";
+import type { RetentionMode } from "../config-types.js";
+/** 同 domain 连续失败多少次算「卡住了」(fail-loud 的阈值)。`5` 与 reaper 家族的
+ *  `REAPER_FAILURE_WARN_THRESHOLD` 同值同理由:一次抖动(一次重连、一次超时)正是容错要吸收的,
+ *  只有**连败**才越过「可诊断」这条线。 */
+export declare const RETENTION_SWEEP_STUCK_THRESHOLD = 5;
+/** 租约 TTL = 本倍数 × sweep 间隔(设计稿 §3)。`2` = 允许一轮跑满一个完整间隔还有余量,再多就该让位。 */
+export declare const RETENTION_LEASE_TTL_FACTOR = 2;
+/**
+ * lane 消费的**执行器**面 —— core `ManagedRetentionCapability` 的三方法 + 车1 的非契约窄读口
+ * `previewRetention`(audit-only 档的读数源;core 契约无 count 面)+ 声明位。
+ *
+ * 🔴 三方法的入参是 core 契约形的**超集**(多一个 `audit`):车1 的店在运行期对缺席的审计上下文
+ * fail-closed 抛错,所以这里把它写进类型 —— 让「忘了传」变成编译错,而不是一次运行期的破坏性调用被拒。
+ */
+export interface RetentionExecutor {
+    readonly retention?: "managed" | "none";
+    listRetentionDomains(): Promise<readonly string[]>;
+    previewRetention(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<{
+        checkpoints: number;
+        sessions: number;
+        toolResults: number;
+    }>;
+    expireCheckpoints(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+    deleteOrphanToolResults(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+}
+/** 破坏性调用的入参(判定时点的三格随行 —— 理由逐字见车1 `RetentionAuditContext` 的头注)。 */
+export interface RetentionDestructiveInput {
+    domain: string;
+    cutoffMs: number;
+    audit: {
+        mode: RetentionMode;
+        policyDays: number;
+        fencingToken: number | null;
+    };
+}
+/** 非破坏性审计行的写口(lane 侧属主的那五个词)。 */
+export interface RetentionAuditSink {
+    append(row: {
+        domain: string;
+        action: "audit_only" | "skipped_legal_hold" | "failed" | "hold_placed" | "hold_released";
+        mode: RetentionMode;
+        policyDays: number;
+        fencingToken: number | null;
+        deleted: number;
+        skipped: number;
+        tombstones: number;
+        error?: string;
+    }): Promise<void>;
+}
+/** sweep 租约的窄口(真身 = `plugins/retention-lane-store-sql.ts` 的 `SqlRetentionLaneStore`)。 */
+export interface RetentionLeaseHandle {
+    acquire(): Promise<{
+        held: true;
+        fencingToken: number;
+    } | {
+        held: false;
+    }>;
+    /**
+     * 「本轮的执行权还在我手上吗」**并同时续租** —— 每 domain 前调一次(见文件头时序契约②)。
+     * `false` = 不再属于我 ⇒ 当场中止本轮。
+     *
+     * 🔴 名字是 `renew` 而不是 `stillMine`(codex R1-[high] 之后改的):它**有写副作用**,叫一个纯读的
+     * 名字会让下一个读者以为可以随便多调几次。合成一条 CAS 的两个理由(原子性 + 长轮次的续租机会)
+     * 逐字见 `plugins/retention-lane-store-sql.ts` 的同名方法。
+     */
+    renew(fencingToken: number): Promise<boolean>;
+    release(): Promise<void>;
+}
+/** 日志/指标座(窄到真实消费面 —— 测试用两行字面量驱动同一段生产代码)。 */
+export interface RetentionLaneLogger {
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+}
+export interface RetentionLaneMetrics {
+    inc(name: string, labels?: Record<string, string>, by?: number): void;
+}
+/** 一轮 sweep 的全部依赖(纯口,零 `ServiceConfig` —— 一轮的行为不该随一个 120 键的对象漂)。 */
+export interface RetentionSweepCtx {
+    policy: RetentionPolicy;
+    mode: RetentionMode;
+    executor: RetentionExecutor;
+    audit: RetentionAuditSink;
+    lease: RetentionLeaseHandle;
+    logger: RetentionLaneLogger;
+    metrics: RetentionLaneMetrics;
+    now(): number;
+    /** 可选的 hold 预检(§5 v1.3:**省调优化,不承重** —— 承重判在店事务内)。缺席 ⇒ 不预检。 */
+    holdInForce?(domain: string): Promise<boolean>;
+    /**
+     * 同 domain 的连败计数(**跨轮存活**:调用方持有它)。一轮内新建等于永远数不过 1 —— 与
+     * `createThrottledReaperCatch` 必须建在 `setInterval` 之外是同一条理由。
+     */
+    streaks?: Map<string, number>;
+}
+/** 一轮的读数(给日志与判据用;lane 自己不做任何决策依赖它)。 */
+export interface RetentionSweepOutcome {
+    /** 本轮真正处理完的 domain 数(丢租中止时 = 中止之前那些)。 */
+    ranDomains: number;
+    /** 枚举出来的 domain 总数(抢不到租时为 0 —— 那时连枚举都不做)。 */
+    totalDomains: number;
+    /** 本轮是否因为**丢租**中止。 */
+    lostLease: boolean;
+    /** 本轮是否拿到了执行权(false = 别人在跑,零写)。 */
+    held: boolean;
+    /** 本轮的 fencing token(未持租时 undefined)。 */
+    fencingToken?: number;
+}
+/**
+ * lane **自持的** boot 不变式(设计稿 §7,codex F3)—— 与 core 的 `assertRetentionCapability` 是两道门,
+ * 各答各的问题:
+ *  · core 那道问的是「**锁着**的策略会不会盖在一只删不了的店上」——只在 locked 时说话;
+ *  · **本道**问的是「lane 开着的时候,它真的能删吗」——**不看 locked 状态**。
+ *
+ * 为什么后者必须存在:core 的门在 `locked=false` 时整条放行,于是
+ *  ① `RETENTION_SWEEP_INTERVAL_SEC>0` 而 policy 缺席 = 没有有效 cutoff 的 sweep(每 tick 什么都算不出来,
+ *     读数一路 0,看起来像"没有候选");
+ *  ② unlocked policy × 一只 `"none"` 的店照样过检 —— 部署于是**广告了一个不执行的留存面**:能力位说
+ *     `{mode,maxAgeDays}`、审计表也在长,而那只店的行谁都没在删。
+ * 两者都在**启动期**拒(安全控件不得半开),不是让运维从一台"启动成功、什么也没删"的机器上猜。
+ *
+ * @param locked 只进文案(让拒启信息能说清"你锁没锁都一样拒");**判据本身不读它** —— 这一格的存在
+ *               就是为了让"不看 locked"这句话在签名上可见,而不是靠注释声明。
+ */
+export declare function assertRetentionLaneWirable(input: {
+    intervalSec: number;
+    policy: RetentionPolicy | undefined;
+    executor: RetentionExecutor | undefined;
+    stores: ReadonlyArray<{
+        name: string;
+        store: {
+            retention?: "managed" | "none";
+        } | object | undefined;
+    }>;
+    locked?: boolean;
+}): void;
+/**
+ * 跑**一轮** sweep(纯函数式的一拍:自己不排期、不建定时器)。导出是判据面的需要 ——
+ * 一个只能靠真定时器推进的 lane 要么让判据睡真时间,要么让判据去证一个假时钟。
+ */
+export declare function runRetentionSweepOnce(ctx: RetentionSweepCtx): Promise<RetentionSweepOutcome>;
+/** `startRetentionLane` 的装配面 = 一轮的依赖 + 节律。 */
+export interface RetentionLaneCtx extends RetentionSweepCtx {
+    intervalSec: number;
+}
+/**
+ * 起飞后的 lane 控制器(`create*` 形:有行为有状态)。
+ *
+ * 🔴 `stop()` 为什么必须**可等**(codex 对抗复审 R1-[high],验真后加):`clearInterval` 只挡住**新** tick,
+ * 它不等当前这一轮。旧形的收尾链停表之后紧跟着就让租 ⇒ 新副本立刻接租,而旧副本还在删同一个域的
+ * 数据 —— 一个由**正常** SIGTERM/SIGINT 稳定触发的双执行者窗口(比任何竞态都好复现)。
+ * 正确的次序是:停表 → **等在飞那一轮落地** → 让租 → 关连接池。
+ */
+export interface RetentionLaneController {
+    /** 停表并**等**在飞那一轮落地(幂等;从不抛 —— 收尾链不该被一条清理腿打断)。 */
+    stop(): Promise<void>;
+    /** 立刻起一轮(**判据面**:让 stop 的语义可以在不睡真时间、也不换假时钟的前提下被证)。 */
+    runNow(): void;
+}
+/**
+ * 起 lane,返回控制器(`undefined` = lane 关着,**根本没建**定时器)。
+ *
+ * 三条与 reaper 家族同款的纪律:
+ *  · `unref()` 紧跟 `setInterval` —— 定时器绝不可持住进程;
+ *  · **重入守卫**:一轮的时长随域数与库延迟增长,越过 interval 就会叠罗汉压同一批行(邻居五腿同形)。
+ *    ⚠️ 守卫的代价是「一轮里只有轮首那一次续租机会」——所以每 domain 前那条 `renew` 是承重的,不是装饰;
+ *  · 一轮内部的任何异常都在轮内被吞掉并记账(`runRetentionSweepOnce` 的 per-domain catch),这里再兜一层
+ *    是为了「租约抢占本身失败」这种**轮外**故障 —— 它不该变成一条 unhandled rejection 把进程带走。
+ */
+export declare function startRetentionLane(ctx: RetentionLaneCtx): RetentionLaneController | undefined;
+//# sourceMappingURL=retention-lane.d.ts.map

package/dist/boot/retention-lane.js

@@ -0,0 +1,279 @@
+import { recordFailOpen } from "../observability/fail-open.js"; // #157:上报臂的登记式兜底(F 类,census 第 28 行)
+/** 同 domain 连续失败多少次算「卡住了」(fail-loud 的阈值)。`5` 与 reaper 家族的
+ *  `REAPER_FAILURE_WARN_THRESHOLD` 同值同理由:一次抖动(一次重连、一次超时)正是容错要吸收的,
+ *  只有**连败**才越过「可诊断」这条线。 */
+export const RETENTION_SWEEP_STUCK_THRESHOLD = 5;
+/** 租约 TTL = 本倍数 × sweep 间隔(设计稿 §3)。`2` = 允许一轮跑满一个完整间隔还有余量,再多就该让位。 */
+export const RETENTION_LEASE_TTL_FACTOR = 2;
+/** 一天的毫秒数(cutoff 换算;本地常量,避免为一个数字引一整只时间工具)。 */
+const DAY_MS = 86_400_000;
+/**
+ * lane **自持的** boot 不变式(设计稿 §7,codex F3)—— 与 core 的 `assertRetentionCapability` 是两道门,
+ * 各答各的问题:
+ *  · core 那道问的是「**锁着**的策略会不会盖在一只删不了的店上」——只在 locked 时说话;
+ *  · **本道**问的是「lane 开着的时候,它真的能删吗」——**不看 locked 状态**。
+ *
+ * 为什么后者必须存在:core 的门在 `locked=false` 时整条放行,于是
+ *  ① `RETENTION_SWEEP_INTERVAL_SEC>0` 而 policy 缺席 = 没有有效 cutoff 的 sweep(每 tick 什么都算不出来,
+ *     读数一路 0,看起来像"没有候选");
+ *  ② unlocked policy × 一只 `"none"` 的店照样过检 —— 部署于是**广告了一个不执行的留存面**:能力位说
+ *     `{mode,maxAgeDays}`、审计表也在长,而那只店的行谁都没在删。
+ * 两者都在**启动期**拒(安全控件不得半开),不是让运维从一台"启动成功、什么也没删"的机器上猜。
+ *
+ * @param locked 只进文案(让拒启信息能说清"你锁没锁都一样拒");**判据本身不读它** —— 这一格的存在
+ *               就是为了让"不看 locked"这句话在签名上可见,而不是靠注释声明。
+ */
+export function assertRetentionLaneWirable(input) {
+    if (input.intervalSec <= 0)
+        return; // lane 关 ⇒ 本门整条不判(缺省姿态,#210「缺席不在律内」)
+    const lockNote = input.locked === true ? " (the retentionPolicy key is LOCKED, but this gate refuses either way)" : "";
+    if (input.policy === undefined) {
+        throw new Error(`RETENTION_SWEEP_INTERVAL_SEC=${input.intervalSec} arms the managed-retention sweep lane, but RETENTION_MAX_AGE_DAYS is not ` +
+            `configured — the lane would run with NO horizon to compute a cutoff from, enumerate domains every tick and delete nothing, ` +
+            `while the capability surface advertises a retention face that does not exist${lockNote}. Set RETENTION_MAX_AGE_DAYS, or set ` +
+            `RETENTION_SWEEP_INTERVAL_SEC=0 to leave the lane off.`);
+    }
+    if (input.executor === undefined) {
+        throw new Error(`RETENTION_SWEEP_INTERVAL_SEC=${input.intervalSec} arms the managed-retention sweep lane, but this deployment wires NO retention ` +
+            `executor — the destructive store methods live on the SQL backends only (DB_BACKEND=mysql|pg); the local/file backend honestly ` +
+            `declares retention:"none" and nothing would delete a row${lockNote}. Run a SQL backend, or set RETENTION_SWEEP_INTERVAL_SEC=0.`);
+    }
+    // 三方法俱全:声明位说 `managed` 不等于方法在场(一个第三方 store 可以只写声明)。逐个点名缺的那个,
+    // 因为运维要能从这句话直接查到是哪一面没接上。
+    // 逐个方法名走**闭集常量**而不是断言成 `Record<string, unknown>`:`executor[m]` 在 `m` 是键联合时
+    // 类型上就是「那几个方法的联合」,`typeof … !== "function"` 直接判得了 —— 一处宽松断言都不需要,
+    // 而且契约面加一个方法时这张表漏补是**编译红**(`satisfies` 那一行),不是运行期漏检。
+    const executor = input.executor;
+    const CONTRACT_METHODS = ["listRetentionDomains", "previewRetention", "expireCheckpoints", "deleteExpiredSessions", "deleteOrphanToolResults"];
+    for (const m of CONTRACT_METHODS) {
+        if (typeof executor[m] !== "function") {
+            throw new Error(`the wired retention executor is missing \`${m}\` — a store that declares retention:"managed" PROMISES the whole ` +
+                `ManagedRetentionCapability contract, and the sweep lane calls every method of it${lockNote}. Refusing to start with a ` +
+                `half-implemented retention face.`);
+        }
+    }
+    // 每只被 lane 消费的店都必须诚实声明 managed。`store: undefined` 的行跳过(那一面这台压根没装,
+    // 与 core 的同款判据逐字同姿势 —— 缺席的店不是"不删",它是"没有行"）。
+    const notManaged = input.stores.filter((s) => s.store !== undefined && s.store.retention !== "managed").map((s) => s.name);
+    if (notManaged.length > 0) {
+        throw new Error(`RETENTION_SWEEP_INTERVAL_SEC=${input.intervalSec} arms the managed-retention sweep lane, but these wired store(s) do NOT declare ` +
+            `retention:"managed": ${notManaged.join(", ")}${lockNote}. Their rows would be advertised as governed by the retention policy ` +
+            `while nothing deletes them. Wire a backend whose stores are managed, or set RETENTION_SWEEP_INTERVAL_SEC=0.`);
+    }
+}
+/**
+ * 跑**一轮** sweep(纯函数式的一拍:自己不排期、不建定时器)。导出是判据面的需要 ——
+ * 一个只能靠真定时器推进的 lane 要么让判据睡真时间,要么让判据去证一个假时钟。
+ */
+export async function runRetentionSweepOnce(ctx) {
+    const claim = await ctx.lease.acquire();
+    if (!claim.held)
+        return { ranDomains: 0, totalDomains: 0, lostLease: false, held: false };
+    const fencingToken = claim.fencingToken;
+    const policyDays = ctx.policy.maxAgeDays;
+    const cutoffMs = ctx.now() - policyDays * DAY_MS;
+    const streaks = ctx.streaks;
+    const domains = await ctx.executor.listRetentionDomains();
+    let ranDomains = 0;
+    let lostLease = false;
+    for (const domain of domains) {
+        // ── 丢租即停:复核在**每 domain 前**(文件头时序契约②)。中止后不写任何"我中止了"的审计行 ——
+        //    那一行会带着一个已经不属于我们的 fencing token 落进不可变账。
+        if (!(await ctx.lease.renew(fencingToken))) {
+            lostLease = true;
+            ctx.logger.warn("retention_sweep_lease_lost", {
+                fencingToken,
+                processedDomains: ranDomains,
+                totalDomains: domains.length,
+                note: "the sweep lease is no longer ours (another replica took it, or our own lease expired because this round outran 2x the sweep interval); aborting the round mid-way. Nothing further is touched; the next holder re-enumerates from scratch (every leg is idempotent).",
+            });
+            break;
+        }
+        try {
+            // hold 预检(§5 v1.3:**省调优化,不承重**)。它省掉的是「一个冻结的大租户每轮仍然跑三条跨表
+            // 事务」;承重的判据在店事务内的哨兵行锁上,所以这里读到 false 而事务内读到 true 是**合法**的
+            // (那时店自己零删全 skip)。
+            if (ctx.holdInForce !== undefined && (await ctx.holdInForce(domain))) {
+                await ctx.audit.append({ domain, action: "skipped_legal_hold", mode: ctx.mode, policyDays, fencingToken, deleted: 0, skipped: 0, tombstones: 0 });
+                ranDomains++;
+                streaks?.set(domain, 0);
+                continue;
+            }
+            // ── 模式分家(§4)。两支**物理分开**:破坏性方法名只出现在 enforce 那一支里。
+            if (ctx.mode === "audit-only") {
+                await sweepDomainAuditOnly(ctx, { domain, cutoffMs, policyDays, fencingToken });
+            }
+            else {
+                await sweepDomainEnforce(ctx, { domain, cutoffMs, policyDays, fencingToken });
+            }
+            ranDomains++;
+            streaks?.set(domain, 0);
+        }
+        catch (err) {
+            ranDomains++;
+            await recordDomainFailure(ctx, { domain, policyDays, fencingToken, err });
+        }
+    }
+    return { ranDomains, totalDomains: domains.length, lostLease, held: true, fencingToken };
+}
+/** audit-only 支(§4):**一条破坏性方法都不调**,只把候选计数记进一行 `audit_only`。 */
+async function sweepDomainAuditOnly(ctx, d) {
+    const p = await ctx.executor.previewRetention({ domain: d.domain, cutoffMs: d.cutoffMs });
+    // 三候选数进 receipt 的三列(设计稿 §6 逐字:「audit_only 行 = preview 三数」)。列名沿用
+    // deleted/skipped/tombstones 而不是另开三列:同一张追加表两套列语义会让读它的 SQL 必须先分支 action。
+    await ctx.audit.append({
+        domain: d.domain,
+        action: "audit_only",
+        mode: "audit-only",
+        policyDays: d.policyDays,
+        fencingToken: d.fencingToken,
+        deleted: p.checkpoints,
+        skipped: p.sessions,
+        tombstones: p.toolResults,
+    });
+}
+/**
+ * enforce 支(§3):三方法按**依赖序** —— 先让过期的 checkpoint 过门(它是会话树的一条活引用腿),
+ * 再删会话树(它落的墓碑是孤儿结果的域归属证据),最后清孤儿结果。倒过来任何一步都会让下一步少删一批,
+ * 靠"下一拍自然收敛"补 —— 那是把一个可以现在做对的顺序换成一个延迟。
+ *
+ * 🔴 破坏性审计行**不在这里写**(§6 F5:店在删除同事务内已写)。receipt 只做二次确认与日志。
+ */
+async function sweepDomainEnforce(ctx, d) {
+    const input = {
+        domain: d.domain,
+        cutoffMs: d.cutoffMs,
+        audit: { mode: "enforce", policyDays: d.policyDays, fencingToken: d.fencingToken },
+    };
+    const checkpoints = await ctx.executor.expireCheckpoints(input);
+    const sessions = await ctx.executor.deleteExpiredSessions(input);
+    const toolResults = await ctx.executor.deleteOrphanToolResults(input);
+    const touched = checkpoints.deleted + sessions.deleted + toolResults.deleted;
+    if (touched > 0) {
+        ctx.metrics.inc("retention_rows_swept_total", { domain: "" }, touched); // 域不进标签(高基数);域维在审计表上
+        ctx.logger.info("retention_swept", {
+            domain: d.domain,
+            fencingToken: d.fencingToken,
+            checkpoints: checkpoints.deleted,
+            sessions: sessions.deleted,
+            toolResults: toolResults.deleted,
+            skipped: checkpoints.skipped + sessions.skipped + toolResults.skipped,
+            tombstones: checkpoints.tombstones + sessions.tombstones + toolResults.tombstones,
+        });
+    }
+}
+/**
+ * 单 domain 失败的记账(§3:`failed` 行 + 继续下一 domain;连败 ≥ 阈值 ⇒ 指标 + 一次性 warn)。
+ *
+ * 🔴 整段**总不抛**:它是 catch 臂里的收尾,一个 poison error(`Symbol.toPrimitive` 抛)或一条抛异常的
+ * 日志/审计写口若从这里逃出去,就会打断 for 循环、饿死后面每一个 domain —— 那正是 per-domain 隔离
+ * 存在的理由的反面(reapers.ts 的 per-scope 循环踩过同一形,注释在彼)。
+ */
+async function recordDomainFailure(ctx, d) {
+    // poison error(抛异常的 `Symbol.toPrimitive`/`toString`)⇒ 落一句**自陈**的占位文案而不是空转:
+    // 审计行里写着「原因取不出来」比写着 "unknown error" 诚实,读账的人据此知道该去看进程日志。
+    let message;
+    try {
+        message = d.err instanceof Error ? d.err.message : String(d.err);
+    }
+    catch {
+        message = "<error object whose toString() itself threw — see the process log for the raw rejection>";
+    }
+    /** 审计行落地了吗 —— 进下面那条 warn 的 meta。**不是装饰**:审计写不进去时,`retention_audit` 里
+     *  会缺这一条 `failed` 行,而运维只有从日志里读到这一位才知道"账本自己也断了"。 */
+    let auditRowWritten = true;
+    try {
+        await ctx.audit.append({
+            domain: d.domain,
+            action: "failed",
+            mode: ctx.mode,
+            policyDays: d.policyDays,
+            fencingToken: d.fencingToken,
+            deleted: 0,
+            skipped: 0,
+            tombstones: 0,
+            error: message.slice(0, 2000),
+        });
+    }
+    catch {
+        // 审计写口自己坏了(库不可达 —— 通常就是上一步失败的同一个原因)。下面那条 warn 仍要发出去,
+        // 并且**带上这一位**:否则「审计表里没有这条 failed 行」看起来会像"这一轮根本没跑到这个域"。
+        auditRowWritten = false;
+    }
+    const streaks = ctx.streaks;
+    const streak = (streaks?.get(d.domain) ?? 0) + 1;
+    streaks?.set(d.domain, streak);
+    try {
+        ctx.logger.warn("retention_sweep_domain_failed", { domain: d.domain, fencingToken: d.fencingToken, consecutiveFailures: streak, auditRowWritten, err: message });
+        if (streak >= RETENTION_SWEEP_STUCK_THRESHOLD) {
+            ctx.metrics.inc("retention_sweep_stuck", {}, 1);
+            // 一次性:阈值一到就打一条、并把计数归零,于是**仍然坏着**的域每再连败一个完整阈值才报一次
+            // (不是首次之后永远静音,也不是每轮刷屏)——与 `createThrottledReaperCatch` 逐字同形。
+            ctx.logger.warn("retention_sweep_stuck", {
+                domain: d.domain,
+                consecutiveFailures: streak,
+                lastError: message,
+                note: "this retention domain has failed its sweep for RETENTION_SWEEP_STUCK_THRESHOLD consecutive rounds — its data is NOT being retained per policy. Check retention_audit rows with action='failed' for this domain.",
+            });
+            streaks?.set(d.domain, 0);
+        }
+    }
+    catch {
+        // 上报**自己**抛了(poison error 的 toString / 一条抛异常的 logger transport)。这里绝不能让它逃出去:
+        // 逃出去会打断 per-domain 循环、饿死后面每一个域 —— 而 per-domain 隔离正是这条腿存在的理由
+        // (reapers.ts 的 per-scope 循环踩过同一形)。走登记过的 F 类兜底口,于是这条臂有计数、有探针行、
+        // 有一次性 warn,而不是一次无痕的沉默(#157 / FAIL-OPEN-CENSUS 第 28 行)。
+        recordFailOpen("server.retention.sweep-report-dropped", `domain=${d.domain}`);
+    }
+}
+/**
+ * 起 lane,返回控制器(`undefined` = lane 关着,**根本没建**定时器)。
+ *
+ * 三条与 reaper 家族同款的纪律:
+ *  · `unref()` 紧跟 `setInterval` —— 定时器绝不可持住进程;
+ *  · **重入守卫**:一轮的时长随域数与库延迟增长,越过 interval 就会叠罗汉压同一批行(邻居五腿同形)。
+ *    ⚠️ 守卫的代价是「一轮里只有轮首那一次续租机会」——所以每 domain 前那条 `renew` 是承重的,不是装饰;
+ *  · 一轮内部的任何异常都在轮内被吞掉并记账(`runRetentionSweepOnce` 的 per-domain catch),这里再兜一层
+ *    是为了「租约抢占本身失败」这种**轮外**故障 —— 它不该变成一条 unhandled rejection 把进程带走。
+ */
+export function startRetentionLane(ctx) {
+    if (ctx.intervalSec <= 0)
+        return undefined;
+    const streaks = ctx.streaks ?? new Map(); // 跨轮存活:必须建在 setInterval **之外**
+    /** 在飞那一轮(`undefined` = 空闲)。它同时是重入守卫与 `stop()` 的等待对象 —— 一个变量两用刻意为之:
+     *  两个变量必然在某次改动后不同步,而不同步的方向是「stop 以为没人在跑」。 */
+    let inFlight;
+    let stopped = false;
+    const runOnce = () => {
+        if (stopped || inFlight !== undefined)
+            return;
+        inFlight = runRetentionSweepOnce({ ...ctx, streaks })
+            .then(() => undefined)
+            .catch((err) => {
+            try {
+                ctx.logger.warn("retention_sweep_round_failed", { err: err instanceof Error ? err.message : String(err) });
+            }
+            catch {
+                // 同 `recordDomainFailure` 的上报臂:一条抛异常的 logger transport 不许把这条 `.catch` 变成
+                // 一个 floating rejection(Node 默认处理下会带走整个进程)。
+                recordFailOpen("server.retention.sweep-report-dropped", "round");
+            }
+        })
+            .finally(() => {
+            inFlight = undefined;
+        });
+    };
+    const timer = setInterval(runOnce, ctx.intervalSec * 1000);
+    timer.unref?.();
+    return {
+        runNow: runOnce,
+        stop: async () => {
+            stopped = true;
+            clearInterval(timer);
+            // 等在飞那一轮落地。`inFlight` 自己已经把所有异常吞掉了(上面的 catch),所以这里不会抛;
+            // 再挂一条 catch 是因为收尾链绝不该被一条清理腿打断 —— 哪怕是被将来某次改动引入的新抛点。
+            await inFlight?.catch(() => undefined);
+        },
+    };
+}
+//# sourceMappingURL=retention-lane.js.map

package/dist/boot/shutdown.d.ts

@@ -16,6 +16,7 @@
 import { Runner, type RunnerDeps } from "@sema-agent/core";
 import type { ServiceConfig } from "../config.js";
 import type { createHttpServer } from "../http/server.js";
+import type { RetentionLaneController } from "./retention-lane.js";
 import type { Logger } from "../observability/logger.js";
 import type { startOtlpExporter } from "../observability/otel-exporter.js";
 import type { CostQuota } from "../observability/cost-quota.js";
@@ -36,6 +37,13 @@ export interface ShutdownCtx {
             stop(): void;
         };
     };
+    /** #270 车2:托管留存 sweep lane 的**控制器**(`undefined` = lane 关着,压根没建定时器)。与 `reaper`
+     *  同列文件头契约 3,但严格更强:那些腿只要停表就够了,本腿的 tick 打的是跨十余张表的**破坏性**事务
+     *  ⇒ 必须 `await stop()` 等在飞那一轮真正落地,**然后**才让租、才关连接池(见 hardShutdown 内的三步注)。 */
+    retentionLane: RetentionLaneController | undefined;
+    /** #270 车2:主动让租(把 sweep 租约的到期时间归零)—— 优雅停机后另一副本不必等满一个 TTL 才接手。
+     *  best-effort:一次失败只意味着"下一位等 TTL",绝不阻塞停机。缺席 = lane 关着。 */
+    releaseRetentionLease: (() => Promise<void>) | undefined;
     otelExporter: ReturnType<typeof startOtlpExporter> | undefined;
     breakerState: ReturnType<BreakerStateStore["startRefresh"]> | undefined;
     costQuota: CostQuota | CostQuotaStore | undefined;