@sema-agent/server 7.30.0 → 7.31.0

package/dist/security.d.ts

@@ -38,12 +38,63 @@ export interface SessionListItem {
  * 不含读面,也不含 `POST /v1/tasks` 那条提交腿 —— 它有自己的同族门(别重复拦,双拦会让错误归因变糊)。
  */
 export declare function isDestructiveSessionWrite(method: string, url: string): boolean;
+/** [4198] 窄互认第二臂的租户键字面量 —— 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的那一个,
+ *  也是壳 [4195]G1 翻面后随请求带的那一个。**不是哨兵**([4183] 措辞):它是单机形的真租户键。 */
+export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
+/**
+ * [4198] 窄互认**第二臂**(clay 裁 A / [4225] 下达;cli [4238] 表态即发)—— `legacyShellOwner`
+ * (本文件 createAuthorizer 内 + http/server.ts `runOwnerOk`)的对称孪生。
+ *
+ * 病灶:7.8.0 第一臂承接的是 `owner === "anon:shell-live"` 哨兵行;此后壳把无主表示法归一为
+ * **缺席**,于是 1.0.82 及更早留下的存量会话 owner 列是 **null**。壳 1.0.83 起随请求带
+ * `default` 主([4195] G1 闸口),`null !== "default"` ⇒ 存量会话在 session 面
+ * **列表不出现 / fork 404 / delete 静默 {deleted:false} / workspace 404**(三面矩阵 [4198] 面3;
+ * fleet 面与 run 读面天然连续,面1/面2 零施工)。
+ *
+ * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
+ *   ① 单机形 `!requirePrincipal` —— 多租部署本臂**死路**(header 必到、键必具名);
+ *   ② 存量行恰为无主 `owner === null` —— 任何具名 owner 的行不受影响;
+ *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
+ * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租泄露。
+ *
+ * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
+ * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
+ *
+ * ── 逐面判过、**刻意不放行**的三处(免得后人当遗漏再补一次)────────────────────────────────
+ *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
+ *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[4198] 帖文里「单读 404」一句
+ *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
+ *  · `PUT /v1/sessions/:id/policy` 的 `owner === null ⇒ 409 conflict.session_ownerless`:那是**有意的
+ *    fail-closed** —— 无主会话没有稳定的 run-principal,存下去的规则读不到、静默失效。放宽它等于制造
+ *    一条 fail-open,不在本臂辖域。
+ *  · `…/sync/*`(PULL/PUSH/import):PULL 虽是只读、形同 workspace,但这一族**带一条破坏性 import 腿**
+ *    (`isDestructiveSessionWrite` 明列),而 [4198]/[4225] 裁的是会话**读面与生命周期**四门。放宽一个
+ *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
+ *
+ * @param requirePrincipal `config.requirePrincipal`(条件①)
+ * @param gateOwner `sessionOwnerScope(ForWrite)` 判出的**已验证**主(条件③;fleet-wide 面不经本臂)
+ * @param owner 存量行的 owner 列(条件②)
+ */
+export declare function legacyUnownedSessionOk(requirePrincipal: boolean, gateOwner: string | null, owner: string | null): boolean;
+/**
+ * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
+ *
+ * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
+ * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
+ * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
+ * 单实体读/写点(fork/delete/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
+ */
+export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 export type OwnerAwareSessionStore = SessionStore & {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
     register?: (sessionId: string, owner: string | null) => Promise<void>;
-    /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column). */
+    /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column).
+     *  `includeUnowned` = [4198] 窄互认第二臂的**第三条件**(`owner IS NULL`)的 SQL 承载位:置真时
+     *  谓词放宽为 `owner = ? OR owner IS NULL`。只在 `owner` 在场时有意义(路由已判①③);`owner` 缺席
+     *  (fleet-wide)时本位无效——那一面本来就不钉 owner。 */
     listSessions?: (opts: {
         owner?: string;
+        includeUnowned?: boolean;
         cursor?: {
             lastActivityAt: string;
             sessionId: string;

package/dist/security.js

@@ -37,6 +37,57 @@ export function isDestructiveSessionWrite(method, url) {
         return /^\/v1\/sessions\/[^/]+\/(sync\/import|fork)$/.test(url);
     return false;
 }
+/** [4198] 窄互认第二臂的租户键字面量 —— 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的那一个,
+ *  也是壳 [4195]G1 翻面后随请求带的那一个。**不是哨兵**([4183] 措辞):它是单机形的真租户键。 */
+export const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
+/**
+ * [4198] 窄互认**第二臂**(clay 裁 A / [4225] 下达;cli [4238] 表态即发)—— `legacyShellOwner`
+ * (本文件 createAuthorizer 内 + http/server.ts `runOwnerOk`)的对称孪生。
+ *
+ * 病灶:7.8.0 第一臂承接的是 `owner === "anon:shell-live"` 哨兵行;此后壳把无主表示法归一为
+ * **缺席**,于是 1.0.82 及更早留下的存量会话 owner 列是 **null**。壳 1.0.83 起随请求带
+ * `default` 主([4195] G1 闸口),`null !== "default"` ⇒ 存量会话在 session 面
+ * **列表不出现 / fork 404 / delete 静默 {deleted:false} / workspace 404**(三面矩阵 [4198] 面3;
+ * fleet 面与 run 读面天然连续,面1/面2 零施工)。
+ *
+ * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
+ *   ① 单机形 `!requirePrincipal` —— 多租部署本臂**死路**(header 必到、键必具名);
+ *   ② 存量行恰为无主 `owner === null` —— 任何具名 owner 的行不受影响;
+ *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
+ * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租泄露。
+ *
+ * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
+ * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
+ *
+ * ── 逐面判过、**刻意不放行**的三处(免得后人当遗漏再补一次)────────────────────────────────
+ *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
+ *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[4198] 帖文里「单读 404」一句
+ *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
+ *  · `PUT /v1/sessions/:id/policy` 的 `owner === null ⇒ 409 conflict.session_ownerless`:那是**有意的
+ *    fail-closed** —— 无主会话没有稳定的 run-principal,存下去的规则读不到、静默失效。放宽它等于制造
+ *    一条 fail-open,不在本臂辖域。
+ *  · `…/sync/*`(PULL/PUSH/import):PULL 虽是只读、形同 workspace,但这一族**带一条破坏性 import 腿**
+ *    (`isDestructiveSessionWrite` 明列),而 [4198]/[4225] 裁的是会话**读面与生命周期**四门。放宽一个
+ *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
+ *
+ * @param requirePrincipal `config.requirePrincipal`(条件①)
+ * @param gateOwner `sessionOwnerScope(ForWrite)` 判出的**已验证**主(条件③;fleet-wide 面不经本臂)
+ * @param owner 存量行的 owner 列(条件②)
+ */
+export function legacyUnownedSessionOk(requirePrincipal, gateOwner, owner) {
+    return owner === null && legacyUnownedAmnestyOpen(requirePrincipal, gateOwner);
+}
+/**
+ * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
+ *
+ * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
+ * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
+ * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
+ * 单实体读/写点(fork/delete/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
+ */
+export function legacyUnownedAmnestyOpen(requirePrincipal, gateOwner) {
+    return !requirePrincipal && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
+}
 /** The shape core's `uuidv7()` mints: canonical 8-4-4-4-12 lowercase hex with version nibble `7` and the RFC-4122
  *  variant (`8`/`9`/`a`/`b`). Used to shape-validate a caller-supplied session id on the §0.5 fork/delete routes so
  *  a crafted id (LIKE metacharacters, over-long, non-canonical) is rejected up front — a SECOND layer behind the

package/dist/wall-clock-jump-guard.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 墙钟阶跃守卫 —— 给「按墙钟绝对 deadline 做终局判定」的清算腿加一道**单调钟佐证**。
+ *
+ * 病灶(test [4232] 场景①,libfaketime 真实构造,宿主真钟全程未碰):审批 SLA=45s,把进程内墙钟
+ * **前拨 1 小时**,真实只等了约 14 秒审批卡就被 D-D deny-sweep 判超时自动拒绝。链条是清楚的:
+ * `checkpoint.deadline` 是 core 在 `put` 时按**当时的墙钟**铸的绝对时刻(必须是墙钟——它要跨进程
+ * 重启存活,单调基准一重启就没了),而 sweep 每拍拿 `Date.now()` 去比 `deadline <= cutoff`。墙钟凭空
+ * 前跳 J 毫秒 ⇒ 判定钟凭空多走 J 毫秒 ⇒ 人还没走开,窗就没了。
+ *
+ * [4235] core 半场三定性把判定半场划给本仓:`totalWaitMs` 的墙钟**记账**是设计如此(要跨 durable
+ * resume 延续),不改形;**判定**侧可以在进程内用单调钟做窗口佐证,与账面字段互不牵连。本模块就是那道佐证。
+ *
+ * ## 判据(为什么是「宽限一个完整 SLA」)
+ * 直觉修法是把 cutoff 改成 `now - 累计前跳量`。它不成立:core 在跳变**之后**铸的 deadline 用的是**新**
+ * 墙钟,拿旧墙钟去比 ⇒ 新卡凭空多活 J 毫秒,而 J 可以是任意大。补偿量若衰减,cutoff 又会以 2 倍速前进。
+ * 两条路都把一个有界缺陷换成一个无界缺陷。
+ *
+ * 本模块改判**宽限**:检出一次前跳后,按**单调钟**静默 `grace = slaMs` 毫秒不做判定。
+ *
+ * 🔴 **宽限量是一个完整 SLA,不是 `min(J, S)`**(codex 对抗复审 R1 [high] 三,验真后修 —— 第一版正是
+ * `min(J, S)`,而那条「J < S 时宽限恰好补平损失」的证明**是错的**)。错在哪:宽限只是**推迟**判定,
+ * 它消不掉墙钟从此**永久领先** J 毫秒这件事。反例(逐字复算):S=45s,gate 在真实 t=0 铸出(deadline =
+ * W0+45s),真实 t=1s 时前跳 J=10s。`min(J,S)`=10s ⇒ 宽限到真实 t=11s;此后墙钟恒为 `W0+t+10`,
+ * 于是 deadline 在 **真实 t=35s** 就被判到期 —— 仍旧少给了整整 10 秒。
+ *
+ * 取满一个 S 才成立,证明是:宽限结束的时刻 t_g = t_jump + S(单调钟量)。
+ *   · 跳变**之前或当时**就在等的 gate:它在 t_g 之前不可能被判,故真实等待 ≥ S ✔
+ *   · 跳变**之后**在 t_x 铸出的 gate:deadline 用的是跳变后的钟 ⇒ 它按墙钟到期的时刻恰好对应真实
+ *     t_x + S(墙钟与单调钟从跳变后起同速),宽限只可能把它再往后推,绝不会提前 ✔
+ * 即**任一审批席都拿得到不少于一个完整 SLA 的真实时间**;单次阶跃下判定最多被推迟一个 S。
+ *
+ * 🔴 **「有界且一次性自清」只对单次阶跃成立**(codex 对抗复审 R2 [high] 五,验真后修 —— 第一版把这句话
+ * 写成了无条件的,那是错的):每次前跳都把窗延到「此刻 + 一个 S」,所以**只要每个 S 内再跳一次**,窗就
+ * 永远续下去,deny 腿被静默关停 —— 而它是一条 **fail-closed** 腿,永久不跑比跑早了更坏。
+ * 收口 = 一串连续跳变的**累计宽限总上限**(缺省 `2 × S`:一个 S 覆盖有证明的单次阶跃,第二个 S 容一串
+ * 短促跳变即 NTP 连续大步修正的真实形);撞上上限就**响亮**恢复判定(`onGraceCapped`),此后宁可按一个
+ * 不稳的钟判,也不让 fail-closed 腿永远不跑。绝对兜底始终另有一层:`checkpoint.terminal_at_ms` 由别的
+ * reap 腿执行、不经本守卫。
+ *
+ * ## 方向与响亮度(#157 安全轴)
+ * 宽限只会**推迟**一个 fail-closed 动作(deny),绝不会放行任何东西 —— 方向安全。但它必须**响亮**:
+ * 检出即 warn(带跳变量与宽限量),宽限期内每拍 info。绝对兜底仍在:`checkpoint.terminal_at_ms`
+ * (put 时钉死的绝对上限)由另一条 reap 腿执行,不经本守卫 ⇒ 悬挂不可能无限。
+ *
+ * 后拨(墙钟相对单调钟**倒退**)不触发宽限:它只会让 deadline 显得更远 ⇒ 判定被推迟,已经是安全方向。
+ * 仍然 warn —— 一次没人知道的钟倒退是运维事实,不是可以吞掉的噪声。
+ */
+/** 判定为「阶跃」的漂移阈值。低于它的漂移是 tick 抖动 / 事件循环延迟 / NTP 缓变(≤500ppm,60s 拍上仅 30ms),
+ *  不是拨表。误判的代价只是**推迟**一次 deny ≤ 宽限量,所以宁可取得低一些。 */
+export declare const DEFAULT_CLOCK_JUMP_THRESHOLD_MS = 2000;
+/** `slaMs` 缺省(部署没配 `APPROVAL_TIMEOUT_SEC` 时)—— 与 `tool-approval.ts` 的
+ *  `DEFAULT_APPROVAL_TTL_MS` 同值同义:一次审批交互的量级。 */
+export declare const DEFAULT_CLOCK_JUMP_GRACE_MS: number;
+export interface WallClockJumpGuard {
+    /**
+     * 每次清算前调用一次,传入本次清算**要用的那个墙钟读数**(判定基准本身,不是另取一次 `Date.now()`
+     * ——否则守卫看的钟和判定用的钟不是同一个)。
+     *
+     * @returns `true` = 本拍可按墙钟判定;`false` = 刚检出前跳,单调宽限未走完,本拍**整拍让开**。
+     */
+    admit(wallNowMs: number): boolean;
+}
+export interface WallClockJumpGuardOptions {
+    /** 宽限上界 = 被保护窗口的 SLA(审批腿=`approvalTimeoutSec * 1000`);缺省 {@link DEFAULT_CLOCK_JUMP_GRACE_MS}。 */
+    slaMs?: number;
+    /** 单调钟 seam。缺省 `performance.now()` —— 本仓既定单调域(server.ts/shutdown.ts/sighup-idle.ts 同源)。 */
+    monotonic?: () => number;
+    /** 墙钟 seam,**只用于构造当拍取首个锚点**(判定仍用 `admit` 的入参)。缺省 `Date.now`。
+     *  codex R2 [high] 五:没有它,`lastWall` 要等第一次 `admit` 才有值 ⇒ 构造之后、首拍之前的那次前跳
+     *  **测不出来**,而那正是「进程刚起来、pending gate 已在库里」的真实窗口。 */
+    now?: () => number;
+    /** 阈值 seam;缺省 {@link DEFAULT_CLOCK_JUMP_THRESHOLD_MS}。 */
+    jumpThresholdMs?: number;
+    /** 一串连续跳变累计宽限的**总上限**,自本串第一次跳变起算;缺省 `2 × slaMs`(理由见 `admit` 内注)。 */
+    maxTotalGraceMs?: number;
+    /** 检出阶跃:`jumpMs > 0` = 前拨(触发宽限),`< 0` = 后拨(只留痕,不宽限)。 */
+    onJump?: (info: {
+        jumpMs: number;
+        graceMs: number;
+    }) => void;
+    /** 宽限期内每拍一次。 */
+    onSuppressed?: (info: {
+        remainingMs: number;
+    }) => void;
+    /** 累计宽限撞上总上限、守卫**强制恢复判定**时一次(响亮放行,不是悄悄放行)。 */
+    onGraceCapped?: (info: {
+        totalGraceMs: number;
+    }) => void;
+}
+export declare function createWallClockJumpGuard(opts?: WallClockJumpGuardOptions): WallClockJumpGuard;
+//# sourceMappingURL=wall-clock-jump-guard.d.ts.map

package/dist/wall-clock-jump-guard.js

@@ -0,0 +1,118 @@
+/**
+ * 墙钟阶跃守卫 —— 给「按墙钟绝对 deadline 做终局判定」的清算腿加一道**单调钟佐证**。
+ *
+ * 病灶(test [4232] 场景①,libfaketime 真实构造,宿主真钟全程未碰):审批 SLA=45s,把进程内墙钟
+ * **前拨 1 小时**,真实只等了约 14 秒审批卡就被 D-D deny-sweep 判超时自动拒绝。链条是清楚的:
+ * `checkpoint.deadline` 是 core 在 `put` 时按**当时的墙钟**铸的绝对时刻(必须是墙钟——它要跨进程
+ * 重启存活,单调基准一重启就没了),而 sweep 每拍拿 `Date.now()` 去比 `deadline <= cutoff`。墙钟凭空
+ * 前跳 J 毫秒 ⇒ 判定钟凭空多走 J 毫秒 ⇒ 人还没走开,窗就没了。
+ *
+ * [4235] core 半场三定性把判定半场划给本仓:`totalWaitMs` 的墙钟**记账**是设计如此(要跨 durable
+ * resume 延续),不改形;**判定**侧可以在进程内用单调钟做窗口佐证,与账面字段互不牵连。本模块就是那道佐证。
+ *
+ * ## 判据(为什么是「宽限一个完整 SLA」)
+ * 直觉修法是把 cutoff 改成 `now - 累计前跳量`。它不成立:core 在跳变**之后**铸的 deadline 用的是**新**
+ * 墙钟,拿旧墙钟去比 ⇒ 新卡凭空多活 J 毫秒,而 J 可以是任意大。补偿量若衰减,cutoff 又会以 2 倍速前进。
+ * 两条路都把一个有界缺陷换成一个无界缺陷。
+ *
+ * 本模块改判**宽限**:检出一次前跳后,按**单调钟**静默 `grace = slaMs` 毫秒不做判定。
+ *
+ * 🔴 **宽限量是一个完整 SLA,不是 `min(J, S)`**(codex 对抗复审 R1 [high] 三,验真后修 —— 第一版正是
+ * `min(J, S)`,而那条「J < S 时宽限恰好补平损失」的证明**是错的**)。错在哪:宽限只是**推迟**判定,
+ * 它消不掉墙钟从此**永久领先** J 毫秒这件事。反例(逐字复算):S=45s,gate 在真实 t=0 铸出(deadline =
+ * W0+45s),真实 t=1s 时前跳 J=10s。`min(J,S)`=10s ⇒ 宽限到真实 t=11s;此后墙钟恒为 `W0+t+10`,
+ * 于是 deadline 在 **真实 t=35s** 就被判到期 —— 仍旧少给了整整 10 秒。
+ *
+ * 取满一个 S 才成立,证明是:宽限结束的时刻 t_g = t_jump + S(单调钟量)。
+ *   · 跳变**之前或当时**就在等的 gate:它在 t_g 之前不可能被判,故真实等待 ≥ S ✔
+ *   · 跳变**之后**在 t_x 铸出的 gate:deadline 用的是跳变后的钟 ⇒ 它按墙钟到期的时刻恰好对应真实
+ *     t_x + S(墙钟与单调钟从跳变后起同速),宽限只可能把它再往后推,绝不会提前 ✔
+ * 即**任一审批席都拿得到不少于一个完整 SLA 的真实时间**;单次阶跃下判定最多被推迟一个 S。
+ *
+ * 🔴 **「有界且一次性自清」只对单次阶跃成立**(codex 对抗复审 R2 [high] 五,验真后修 —— 第一版把这句话
+ * 写成了无条件的,那是错的):每次前跳都把窗延到「此刻 + 一个 S」,所以**只要每个 S 内再跳一次**,窗就
+ * 永远续下去,deny 腿被静默关停 —— 而它是一条 **fail-closed** 腿,永久不跑比跑早了更坏。
+ * 收口 = 一串连续跳变的**累计宽限总上限**(缺省 `2 × S`:一个 S 覆盖有证明的单次阶跃,第二个 S 容一串
+ * 短促跳变即 NTP 连续大步修正的真实形);撞上上限就**响亮**恢复判定(`onGraceCapped`),此后宁可按一个
+ * 不稳的钟判,也不让 fail-closed 腿永远不跑。绝对兜底始终另有一层:`checkpoint.terminal_at_ms` 由别的
+ * reap 腿执行、不经本守卫。
+ *
+ * ## 方向与响亮度(#157 安全轴)
+ * 宽限只会**推迟**一个 fail-closed 动作(deny),绝不会放行任何东西 —— 方向安全。但它必须**响亮**:
+ * 检出即 warn(带跳变量与宽限量),宽限期内每拍 info。绝对兜底仍在:`checkpoint.terminal_at_ms`
+ * (put 时钉死的绝对上限)由另一条 reap 腿执行,不经本守卫 ⇒ 悬挂不可能无限。
+ *
+ * 后拨(墙钟相对单调钟**倒退**)不触发宽限:它只会让 deadline 显得更远 ⇒ 判定被推迟,已经是安全方向。
+ * 仍然 warn —— 一次没人知道的钟倒退是运维事实,不是可以吞掉的噪声。
+ */
+/** 判定为「阶跃」的漂移阈值。低于它的漂移是 tick 抖动 / 事件循环延迟 / NTP 缓变(≤500ppm,60s 拍上仅 30ms),
+ *  不是拨表。误判的代价只是**推迟**一次 deny ≤ 宽限量,所以宁可取得低一些。 */
+export const DEFAULT_CLOCK_JUMP_THRESHOLD_MS = 2_000;
+/** `slaMs` 缺省(部署没配 `APPROVAL_TIMEOUT_SEC` 时)—— 与 `tool-approval.ts` 的
+ *  `DEFAULT_APPROVAL_TTL_MS` 同值同义:一次审批交互的量级。 */
+export const DEFAULT_CLOCK_JUMP_GRACE_MS = 5 * 60_000;
+export function createWallClockJumpGuard(opts = {}) {
+    const monotonic = opts.monotonic ?? (() => performance.now());
+    const threshold = opts.jumpThresholdMs ?? DEFAULT_CLOCK_JUMP_THRESHOLD_MS;
+    const graceCap = opts.slaMs !== undefined && opts.slaMs > 0 ? opts.slaMs : DEFAULT_CLOCK_JUMP_GRACE_MS;
+    // codex R2 [high] 五(验真后修):首拍锚点**真的**在构造时取(旧形只初始化了单调锚,墙钟锚留 undefined,
+    // 而注释却写着「构造时取」—— 注在撒谎,且后果具体:构造之后、第一次 admit 之前的那次前跳测不出来,
+    // 那正是「进程刚起来、pending gate 已在库里」的真实窗口)。
+    let lastWall = (opts.now ?? Date.now)();
+    let lastMono = monotonic();
+    let graceUntilMono;
+    /** 本串连续跳变的起点(单调钟)。`undefined` = 当前不在宽限中。 */
+    let burstStartMono;
+    // 一串跳变累计宽限的总上限。为什么需要它(codex R2 [high] 五的第二半):每次前跳都把窗延到「此刻 +
+    // 一个 SLA」,于是**只要每个 SLA 内再跳一次**,窗就永远续下去 —— deny 腿被静默关停,而它是一条
+    // **fail-closed** 腿,永久不跑比跑早了更坏。旧注「有界且一次性自清」在连续跳变下是假的。
+    // 2×SLA 的取值:一个 SLA 覆盖单次阶跃(那是有证明的那一支),第二个 SLA 容一串短促跳变(NTP 连续
+    // 大步修正的真实形);再往后钟已属病态,此时**宁可按一个不稳的钟判**也不能让 fail-closed 腿永远不跑。
+    const maxTotalGrace = opts.maxTotalGraceMs !== undefined && opts.maxTotalGraceMs > 0 ? opts.maxTotalGraceMs : graceCap * 2;
+    return {
+        admit(wallNowMs) {
+            const mono = monotonic();
+            const prevWall = lastWall;
+            const monoDelta = mono - lastMono;
+            lastWall = wallNowMs;
+            lastMono = mono;
+            // 漂移 = 墙钟走的量 − 单调钟走的量。两者本该逐毫秒并进;差额就是拨表量。
+            const driftMs = wallNowMs - prevWall - monoDelta;
+            if (driftMs > threshold) {
+                // codex R1 [high] 三:**整一个 SLA**,与跳变量无关(`min(driftMs, graceCap)` 的证明是错的,
+                // 反例逐字见模块头注 —— 宽限推迟不了「墙钟从此永久领先」这件事)。
+                const graceMs = graceCap;
+                if (burstStartMono === undefined)
+                    burstStartMono = mono; // 本串的起点(总上限自它起算)
+                const until = mono + graceMs;
+                // 取 max:宽限期内又跳一次 ⇒ 窗延到更晚的那个,不被后一次的小跳缩短。
+                if (graceUntilMono === undefined || until > graceUntilMono)
+                    graceUntilMono = until;
+                opts.onJump?.({ jumpMs: Math.round(driftMs), graceMs: Math.round(graceMs) });
+            }
+            else if (driftMs < -threshold) {
+                // 后拨:判定被推迟=安全方向,不宽限(宽限只会把安全方向再推远)。但要留痕。
+                opts.onJump?.({ jumpMs: Math.round(driftMs), graceMs: 0 });
+            }
+            if (graceUntilMono !== undefined && burstStartMono !== undefined) {
+                const elapsedInBurst = mono - burstStartMono;
+                if (elapsedInBurst >= maxTotalGrace) {
+                    // 撞上总上限 ⇒ **响亮**恢复判定(不是悄悄放行)。绝对兜底另有一层:`checkpoint.terminal_at_ms`
+                    // 由别的 reap 腿执行、不经本守卫,所以即使这里也失灵,悬挂仍不可能无限。
+                    opts.onGraceCapped?.({ totalGraceMs: Math.round(elapsedInBurst) });
+                    graceUntilMono = undefined;
+                    burstStartMono = undefined;
+                    return true;
+                }
+                if (mono < graceUntilMono) {
+                    opts.onSuppressed?.({ remainingMs: Math.round(graceUntilMono - mono) });
+                    return false;
+                }
+                graceUntilMono = undefined;
+                burstStartMono = undefined;
+            }
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=wall-clock-jump-guard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.30.0",
+  "version": "7.31.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",

package/dist/boot/lexical-path-env.d.ts

@@ -1,10 +0,0 @@
-import { FileError, StubExecutionEnv, type Result } from "@sema-agent/core";
-/**
- * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
- * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
- * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
- */
-export declare class LexicalPathExecutionEnv extends StubExecutionEnv {
-    absolutePath(path: string): Promise<Result<string, FileError>>;
-}
-//# sourceMappingURL=lexical-path-env.d.ts.map

package/dist/boot/lexical-path-env.js

@@ -1,88 +0,0 @@
-/**
- * #156 —— 非 host lane(e2b/k8s/ssh/adb/local-docker)写门的**纯路径规则**过渡形所用的裁决 env。
- *
- * ## 它解决的缺口
- *
- * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 都把写目标交给
- * `canonicalizeTarget(env, …)` 去「问 fs 要真身」。host lane 上那个 env 就是 hand 工具真正写的那块盘,
- * 答案可信。沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
- * spec 期手边只有 worker 本机的 fs——拿它去裁沙箱里的路径会答错(exists/symlink 全是别人机器上的事实),
- * 而**错误的 allow 比没有门更糟**。所以 [816]/[820] 当年在沙箱 lane 诚实不挂门(wiring=undefined ⇒
- * 三个模式臂全回落 base 规则,写门整条缺席)。#153 的 ③ 号注把这笔记成了余款,#156 是它的过渡还款。
- *
- * ## 这个 env 是什么
- *
- * 一个**没有文件系统**的 env:除 `absolutePath` 外的每一个 fs 面(exists / canonicalPath / fileInfo /
- * read* / write* / listDir / createDir / …)与 shell 面都继承 core 的 `StubExecutionEnv`,
- * 恒返回 `not_supported` 错误(`readLink` 是可选面,Stub 干脆没有——core 把缺席当「symlink 不可解」,
- * 且该分支在本 env 恒不可达:exists 先错就进了 canonicalizeNewPath)——这不是伪装,这就是本 env 的诚实回答:**spec 期我们确实不知道沙箱里
- * 那块盘上有什么**。`absolutePath` 是唯一被赋予真实语义的一面,而它本来就是纯路径运算(不碰盘):
- * POSIX 绝对路径做词法归一后原样奉还,其余一律「不知道」。
- *
- * ## 由此得到的裁决语义(core dist 亲读推出,`tools/fs/safety.js` canonicalizeTarget)
- *
- *  · 绝对路径(`/…`):`absolutePath` ok ⇒ core 进 exists 探测 ⇒ 我们返回错误 ⇒ core 按「该路径尚不存在」
- *    走 `canonicalizeNewPath`,那里逐级 exists 也全错 ⇒ 原样返回我们给的词法绝对路径。于是 canonical key
- *    = **词法归一后的路径**,`canonicalPath` / `fileInfo` / `readLink` 三面在这条路上根本不可达。
- *  · 相对路径 / `~/…` / Windows 盘符形:`absolutePath` 返回错误 ⇒ `canon.ok=false` ⇒ 写门直接
- *    `ask`(fail-closed)。沙箱的 cwd 在 spec 期不可知,这正是我们要的偏置——**不猜沙箱工作目录**。
- *  · 反斜杠 UNC 形(`\\host\share\…`)是唯一**不经过**本 env 的形:core 的 `canonicalizeTarget` 在入口
- *    就把它短路成 `ok:true, key=原样`(复审 2026-08-05 dist 亲读+实测)。结果不变——写门无放行域可越,
- *    落 defaultWrite 的 `ask`;sensitive 段匹配按 `[\\/]` 双分隔符切段,`\\host\share\.env` 照样 deny。
- *  · sensitivePatterns 的 deny 腿照常施加:它按 canonical key 的**路径段**做 glob 匹配,词法 key 足够,
- *    且在 `combinePolicies` 折叠里 deny 恒胜(session 豁免 / accept 域越不过)。
- *  · `isExempt`(会话「本会话不再询问」探针)是 name-keyed 的,不做 fs 裁决,任何 lane 都安全,照接。
- *
- * ## 已知残余面(过渡形的边界,不是疏漏)
- *
- *  · **symlink 形**:词法裁决看不见符号链接。沙箱里一个名字普通的软链可以指向守卫段(`.ssh` 等),
- *    我们只会给 `ask` 而不是 `deny`;host lane 上 core 会 canonicalize 出真身并 deny。相应地,core 的
- *    `unresolvedSymlink ⇒ deny` 那条腿在本 env 下永不触发。注意豁免会话下的口径(codex 复审 E):
- *    name-keyed 豁免不看路径,这类词法无害的软链目标在豁免会话里是 **allow** 而非 ask——这是本残余面
- *    在「操作员已授 don't-ask-again」情形下的完整代价,host lane 同情形仍会 deny。
- *  · **exempt/accept 域**:沙箱 lane 既无可信 cwd 也无 scratchpad 对应物,故本过渡形**一个自动放行域都
- *    不铸**(见 resolve-spec 的 wiring)。代价是 acceptEdits 在沙箱 lane 退化成与 default 同形(全 ask);
- *    这是 fail-safe 方向,与 host lane「accept 域解析不出 ⇒ 该域不生效」的哨兵先例同口径。
- *  · **`cwd` 字段**:继承 `StubExecutionEnv` 的 `"/"` 占位。本 env 只活在 policy 折叠里,core 的两个
- *    policy 都不读 `env.cwd`(相对路径基准走 `rootPath` 形参,而我们不给)——它不代表沙箱的工作目录。
- *
- * ## 终局 seam
- *
- * 正解是让写门在**工具执行时刻**拿到真沙箱 env:core [2751] 已排期给 `HookToolContext` 加一个只读的
- * env 能力窄面(174/#22 窗)。那一面到货后,本过渡形整体退役换正解——届时沙箱 lane 与 host lane 走同
- * 一条真 fs 裁决,上面三条残余面一并消失。
- */
-import { posix } from "node:path";
-import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
-/** 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,不碰 fs。
- *  `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「沙箱根之上没有东西」的语义一致。
- *  尾部分隔符统一剥掉(根 `/` 除外),让同一目标只有一个 key ——前缀判域靠的就是 key 的唯一性。
- *  (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
- *   不是它的抄本——若日后 core 导出,这里应改为直接复用。) */
-function normalizeAbsolutePathLexically(path) {
-    const collapsed = posix.normalize(path.replace(/^\/+/, "/"));
-    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
-}
-/**
- * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
- * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
- * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
- */
-export class LexicalPathExecutionEnv extends StubExecutionEnv {
-    absolutePath(path) {
-        // POSIX 绝对形是沙箱 lane(全 Linux)上 hand 工具的书面契约形。其余一切——相对路径、`~`、
-        // `C:\…`——在 spec 期都无法诚实解析成一个沙箱内的绝对路径,返回错误让 core 落 ask。
-        // (反斜杠 UNC 形根本到不了这里:core 在 canonicalizeTarget 入口短路,见文件头「由此得到的裁决语义」。)
-        // codex 复审 A(2026-08-05):含 NUL 的字符串不是合法 POSIX 路径(任何 fs 面都写不进去),但词法归一
-        // 会照样给它铸出 canonical key——`\0` 尾巴让守卫段 glob 失配,豁免会话下还能拿 allow。拒收让 canon
-        // 在豁免咨询**之前**就失败 ⇒ 恒 ask。
-        if (path.includes("\u0000")) {
-            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and rejects a path containing a NUL byte (not a representable POSIX path)", path)));
-        }
-        if (!path.startsWith("/")) {
-            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and cannot resolve a non-absolute path (the sandbox working directory is unknown at spec time)", path)));
-        }
-        return Promise.resolve(ok(normalizeAbsolutePathLexically(path)));
-    }
-}
-//# sourceMappingURL=lexical-path-env.js.map

package/dist/capabilities/oa-tools.d.ts

@@ -1,15 +0,0 @@
-import type { ToolSpec } from "@sema-agent/core";
-/**
- * OA scenario — tools are thin HTTP clients to the OA backend's existing APIs (read = /api/v1/*,
- * write = /api/assets/*). The shared service token + the request's principal are forwarded so OA
- * enforces THAT end-user's RBAC + audit (the service never holds per-user creds). Decoupled: the
- * service knows no OA schema/DB — OA stays the source of truth (its /api/v1/meta is self-describing).
- */
-export interface OaCtx {
-    baseUrl: string;
-    token: string;
-    principal?: string;
-}
-export declare function oaTools(ctx: OaCtx): ToolSpec[];
-export declare const oaPrompt: import("@sema-agent/core").PromptProvider;
-//# sourceMappingURL=oa-tools.d.ts.map

package/dist/capabilities/oa-tools.js

@@ -1,54 +0,0 @@
-import { Type } from "typebox";
-import { stablePrompt } from "./prompt.js";
-async function oaFetch(ctx, path, init) {
-    if (!ctx.baseUrl || !ctx.token)
-        return "OA 后端未配置(OA_API_BASEURL / OA_SERVICE_TOKEN)";
-    try {
-        const res = await fetch(ctx.baseUrl + path, {
-            method: init?.method ?? "GET",
-            headers: {
-                "content-type": "application/json",
-                authorization: `Bearer ${ctx.token}`,
-                ...(ctx.principal ? { "x-agent-principal": ctx.principal } : {}),
-            },
-            body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
-        });
-        const text = await res.text();
-        if (!res.ok)
-            return `OA ${res.status}: ${text.slice(0, 600)}`;
-        return text.slice(0, 60_000);
-    }
-    catch (e) {
-        return `调用 OA 失败：${e.message}`;
-    }
-}
-const needWrite = (ctx) => (!ctx.principal ? "缺少身份(principal)，无法代表用户写库；请让调用方带上 x-agent-principal。" : null);
-export function oaTools(ctx) {
-    const obj = Type.Object({}, { additionalProperties: true });
-    return [
-        { name: "oa_schema", effect: "read", description: "取 OA 数据结构(每类资产的字段/必填/条件必填 requiredWhen/联动 showWhen/枚举、生命周期、表名)。建/改前先调它，别凭记忆。", parameters: Type.Object({}), execute: () => oaFetch(ctx, "/api/v1/meta") },
-        { name: "oa_alerts", effect: "read", description: "派生告警：GP 闲置(已注册未变现) / APP 未上架(已接广告未 LIVE)。", parameters: Type.Object({}), execute: () => oaFetch(ctx, "/api/v1/alerts") },
-        { name: "oa_list", effect: "read", description: "列出某类资产。type∈gp/package/ad-platform/ad-unit/email/environment/proxy。可选 q 关键字。", parameters: Type.Object({ type: Type.String(), q: Type.Optional(Type.String()) }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/entities/${encodeURIComponent(x.type)}${x.q ? `?q=${encodeURIComponent(x.q)}` : ""}`); } },
-        { name: "oa_get", effect: "read", description: "取某资产详情(敏感字段为掩码)。", parameters: Type.Object({ type: Type.String(), id: Type.String() }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/entities/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}`); } },
-        { name: "oa_lookup", effect: "read", description: "约定字段值反查(同手机/证件=同一实物)。field: phone|idCardNo|bizLicenseNo。", parameters: Type.Object({ field: Type.String(), value: Type.String() }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/lookup?field=${encodeURIComponent(x.field)}&value=${encodeURIComponent(x.value)}`); } },
-        { name: "oa_create", effect: "write", description: "创建实体(走 OA 校验+当前用户 RBAC+审计)。type + data(字段对象，参照 oa_schema)。失败会返回缺失/非法字段。", parameters: Type.Object({ type: Type.String(), data: obj }), execute: (a) => { const e = needWrite(ctx); if (e)
-                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}`, { method: "POST", body: x.data ?? {} }); } },
-        { name: "oa_update", effect: "write", description: "改字段(敏感留空=保持原值；状态字段改不动，用 oa_transition)。", parameters: Type.Object({ type: Type.String(), id: Type.String(), data: obj }), execute: (a) => { const e = needWrite(ctx); if (e)
-                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}`, { method: "PATCH", body: x.data ?? {} }); } },
-        { name: "oa_transition", effect: "write", description: "受控状态流转(先 oa_schema 看可用迁移；风险/弃用等需 note)。", parameters: Type.Object({ type: Type.String(), id: Type.String(), to: Type.String(), note: Type.Optional(Type.String()) }), execute: (a) => { const e = needWrite(ctx); if (e)
-                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}/transition`, { method: "POST", body: { to: x.to, note: x.note ?? null } }); } },
-    ];
-}
-// OA business prompt MOVED OUT — migration complete (design/29, 2026-06-05). Persona / 工作准则 / UI
-// markers (::FORM:: / ::GOTO:: / ::SUGGEST:: / ::ISSUE_FORM::) / 分级确认 / 报bug流程 are OA's business,
-// and OA now injects the WHOLE thing per request via `request.systemPrompt` (it holds the service token,
-// content is stable per OA version → cacheable prefix; page context still rides `objective`). Keeping
-// any of it here would just DUPLICATE OA's prompt, so the base is EMPTY — single source of truth = OA.
-// The service stays business-agnostic: it provides the oa_* tools (referenced by NAME from OA's prompt;
-// they carry their own descriptions) and nothing else. `stablePrompt` keeps STABLE→VARIABLE order —
-// OA's systemPrompt is appended after this (empty) base, before core's <user_memory>.
-// (::ISSUE_FORM:: is parsed/rendered + submitted entirely by OA's frontend via OA /api/ai/issue — the
-//  service never touches it; `open_gitea_issue` remains only as the unattended/automated fallback.)
-const OA_SYSTEM = "";
-export const oaPrompt = stablePrompt(OA_SYSTEM);
-//# sourceMappingURL=oa-tools.js.map

package/dist/finance/cost-taxonomy.d.ts

@@ -1,34 +0,0 @@
-export interface InfraCostRates {
-    toolCallMicroUsd: number;
-    sandboxSecMicroUsd: number;
-    egressGbMicroUsd: number;
-}
-export interface InfraUsage {
-    toolCalls: number;
-    sandboxWalltimeMs: number;
-    egressBytes: number;
-}
-export interface InfraCostBreakdown {
-    toolCallMicroUsd: number;
-    sandboxWalltimeMicroUsd: number;
-    egressMicroUsd: number;
-    totalMicroUsd: number;
-}
-export interface LlmCostBreakdown {
-    llmRootMicroUsd: number;
-    nestedSubagentMicroUsd: number;
-    memoryConsolidationMicroUsd: number;
-    compactionMicroUsd: number;
-}
-export interface SupervisorCostBreakdown {
-    llm: LlmCostBreakdown | null;
-    infra: InfraCostBreakdown;
-    totalMicroUsd: number;
-}
-export declare function infraCost(usage: InfraUsage, rates: InfraCostRates): InfraCostBreakdown;
-export declare function composeSupervisorCost(llm: LlmCostBreakdown | null, llmTotalMicroUsd: number, infra: InfraCostBreakdown): SupervisorCostBreakdown;
-export declare function hasInfraPricing(r: InfraCostRates): boolean;
-export declare function infraUsageFromEvents(events: ReadonlyArray<{
-    type?: string;
-}>, runDurationMs: number): InfraUsage;
-//# sourceMappingURL=cost-taxonomy.d.ts.map

package/dist/finance/cost-taxonomy.js

@@ -1,26 +0,0 @@
-const nonNeg = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
-export function infraCost(usage, rates) {
-    const toolCallMicroUsd = nonNeg(usage.toolCalls) * nonNeg(rates.toolCallMicroUsd);
-    const sandboxWalltimeMicroUsd = (nonNeg(usage.sandboxWalltimeMs) / 1000) * nonNeg(rates.sandboxSecMicroUsd);
-    const egressMicroUsd = (nonNeg(usage.egressBytes) / 1_000_000_000) * nonNeg(rates.egressGbMicroUsd);
-    return {
-        toolCallMicroUsd,
-        sandboxWalltimeMicroUsd,
-        egressMicroUsd,
-        totalMicroUsd: toolCallMicroUsd + sandboxWalltimeMicroUsd + egressMicroUsd,
-    };
-}
-export function composeSupervisorCost(llm, llmTotalMicroUsd, infra) {
-    return { llm, infra, totalMicroUsd: nonNeg(llmTotalMicroUsd) + infra.totalMicroUsd };
-}
-export function hasInfraPricing(r) {
-    return r.toolCallMicroUsd > 0 || r.sandboxSecMicroUsd > 0 || r.egressGbMicroUsd > 0;
-}
-export function infraUsageFromEvents(events, runDurationMs) {
-    return {
-        toolCalls: events.reduce((n, e) => (e.type === "tool_start" ? n + 1 : n), 0),
-        sandboxWalltimeMs: nonNeg(runDurationMs),
-        egressBytes: 0,
-    };
-}
-//# sourceMappingURL=cost-taxonomy.js.map