@sema-agent/server 7.145.0 → 7.146.0

package/dist/boot/engine-lease.d.ts

@@ -28,7 +28,8 @@
  *     `ENGINE_AUTO_EXIT` / `SEMA_PARENT_PID` 的表态上。
  *  2. **自退判据 = 三合取,且必须持续满 `linger`**(`linger` = 孤儿态 `orphan.lingerMs`,否则 `lingerMs`):
  *       · 附着租约集空(`attachedStreams() === 0`);
- *       · 无在飞 run(`inflight() === 0` —— **与 /health 的 `inflight` 同一只 getter**,不另立第二判据);
+ *       · 无必须等完的活(`inflight() === 0` —— 读 `drainState.blockingInflight` = **阻断集** `http + leader`,与排空等的、SIGHUP 空闲窗**同一只**,不另立第二判据;
+ *         `/health.inflight` 是它再加会话驻留的后台 shell / monitor 的**总数**:同一份分项 `/health.inflightBreakdown` 派生的两个事实,不是两套计数,见下「已知收窄」);
  *       · HTTP 触点静默(`now() - lastActivityAt() >= lingerMs`),**且**最后一条附着流的**离场**
  *         也已满窗(`now() - lastAttachEndedAt() >= lingerMs` —— codex R1-F1,见该 dep 的注)。
  *     任何一条不满足即把计时清零(连续性判据,不是累计)。
@@ -67,22 +68,99 @@
  *    已由 `inflight()` 结构性守住;parked 行是 durable 的,引擎退掉不丢:下次起来仍可赎回(spawn 形里
  *    「下次」就是壳的下一次 spawn)。伤害面 = 一条 parked run 的赎回被推迟到下次启动,不是丢失。
  *    这是**允许的收窄,不是静默**:有了廉价 parked 计数口(或本腿改成事件驱动)之后应当补上。
- *  · **活过父 run 的后台子代理不入判据**(codex R1 [high] 验真后**如实登记**,不是本件引入:[ref] 之前
- *    父死走的是**当场** drain,而 `drainThenShutdown` 读的是同一只 `inflight()` ⇒ 同一个缺口,只是那时
- *    连这 2s 都没有)。`inflight()` 的口径是**本副本的 HTTP 腿 ∪ leader 腿**(`http/server.ts` 的
- *    `inflightRuns`/`steerableRuns`/两只计数器),而 core 侧 `backgroundScope:"session"` 的子代理可以
- *    **活过**生它的那条 HTTP 腿 —— 那之后它在本腿眼里是 0。伤害面 = 壳没了且没人附着时,一条还在跑的
- *    后台子代理会随引擎的受控退被中断(它的账本行照常落终态,不是静默丢)。收口需要一只**廉价**的
- *    「本副本活跃子代理数」读口(与 parked 那条同族:要么 core 给计数,要么本腿改事件驱动),归属
- *    `inflight()` 的属主而不是本腿 —— 在那之前这条收窄**成文在此**,不许再被读成「bg 全被守住」。
+ *  · **会话驻留的后台 shell / monitor 与活过父 run 的后台子代理都不入判据**(两件事实不同,同一条判据)。
+ *    阻断集 `http + leader` 是「还有没有**必须等完**的活」:HTTP 腿(在飞 run 集 · 同步计费腿 · admission 期请求)与 leader 腿。
+ *    会话驻留的后台 shell / monitor(`session-resident-background.ts` 读;running ∧ 会话驻留 ∧ 非 retain)**报**在 `/health.inflight`(总数)与
+ *    `inflightBreakdown.sessionResident` 里 —— 外部判官据此判「这台引擎此刻托管着多少活」—— 但**不阻断**自退:它不是一条腿,等它没有意义,而一只不退出的 shell
+ *    (`while true`)若阻断,崩溃孤儿引擎就永生(孤儿窗 / SIGHUP 空闲窗同读阻断集,排空也每次等满窗)。窗到 / 排空完成,退出边界的后台收割
+ *    (`reapAllSessionBackground` + 硬面,`boot/exit-boundary.ts`)收掉它们;retain 行按 retain 既有语义活过受控退。伤害面 = 壳没了且没人附着时,引擎照退、
+ *    驻留的进程随受控退被收掉(与 7.145.x 逐字同,**本件不改这一行为**,只把它报出来)。
+ *    后台**子代理**(agent 行)同样不入(codex R1 [high] 验真后如实登记,不是本件引入:[ref] 之前父死走的是**当场** drain,而 `drainThenShutdown` 读的是同一只 `inflight()` ⇒ 同一个缺口):
+ *    core 侧 `backgroundScope:"session"` 的子代理可以**活过**生它的那条 HTTP 腿,那之后它在本腿眼里是 0;伤害面 = 一条还在跑的后台子代理会随引擎的受控退被中断(它的账本行照常落终态,不是静默丢)。
+ *    这条收窄**成文在此**,不许再被读成「bg 全被守住」。
  *  · **`/health` 探针不算触点**:`lastActivityAt` 的属主(`http/server.ts` 的 `noteActivity`)按既有契约
  *    把 `/health` 与 `/metrics*` 排除在活性时钟之外(常态采样噪音不得把空闲窗永远撑开)。⇒ 一只**只**
  *    轮询 `/health` 的壳不构成租约。这与 SIGHUP 空闲窗的判据同源,刻意保持一致而非在本腿另开一份。
+ *
+ * ## [ref]:首次附着前的宽限 —— 窗表从两态变三态(判据 / 钟 / 出口都不变;[ref] 起并进下面那张四行车道表)
+ *
+ * 病:壳在 spawn 与**首次接触**之间被饿住(一次性 `-p` 车道 / CI / 高载宿主)超过 owned 窗 ⇒ 一只**从没被碰过**
+ * 的引擎按 owned 窗自退,壳醒来起步失败。收法只改「生效窗 = f(态)」这一张表,不加第二只钟、不加第二条自退路径:
+ *
+ *  | 态(优先级从上到下) | 进入                                     | 生效窗                         |
+ *  |----------------------|------------------------------------------|--------------------------------|
+ *  | 孤儿                 | 装了孤儿车道 ∧ 看门狗已判父死            | `orphan.lingerMs`              |
+ *  | 候首触               | 起服以来还没有过非探针触点 ∧ 非孤儿      | `max(lingerMs, firstAttach.windowMs)` |
+ *  | 已触(owned)        | 有过触点 ∧ 非孤儿                        | `lingerMs`                     |
+ *
+ *  · **首触的唯一属主 = 活性时钟的写者**(`http/server.ts` 的 `noteActivity`,{@link EngineLeaseFirstAttachLane.firstTouchAt}):
+ *    第一个非探针请求(含打开 SSE 流 —— 它本身就是一个非探针请求)写一次就定,之后不回 null ⇒ 态**单向**。探针律不变;
+ *    **在飞不翻态**(boot 赎回的 leader 腿没有客户端到场 —— 它在跑时三合取本就不成立,跑完仍按候首触窗计)。
+ *  · **孤儿压过候首触**:宽限保护的是「父还活着、只是被饿住」的壳;父没了就没人会回来,顶注 7 那句「壳在接触前崩了 ⇒ 孤儿窗内退」不变。
+ *  · **宽限只拉长不缩短**:`max(lingerMs, …)` —— 旋钮 `0`(或任何不大于 owned 窗的值)= 候首触窗落成 owned 窗 = [ref] 前逐字同;
+ *    owned 窗 = `Infinity`(`ENGINE_AUTO_EXIT` 关着)⇒ 候首触窗也是 `Infinity`。
+ *  · **拍频与 `/health.engineLease.lingerMs` 不变**:候首触窗 ≥ owned 窗,不进「最短窗」推导(顶注 9 / [ref])。
+ *
+ * ## [ref]([ref] v3):交接车道 —— 一只车道函数、一张四行表、一只区间、一只谓词
+ *
+ * 「Move to background and exit」:壳经 `POST /v1/engine/handover` 把引擎交给后台、自己退出(不 SIGTERM 引擎);下一只壳 `POST /v1/engine/attach`
+ * 即收回。规则只有一条 —— 车道是闭集 {@link ENGINE_LANES},由 {@link deriveEngineLane} 一处派生(从上到下第一条成立者),每条车道 = 表里一行:
+ *
+ *  | 车道                 | 进入                                   | 窗(唯一选窗处 `windowOf`)            | 后台 shell 计入工作 | SIGHUP 空闲窗 |
+ *  |----------------------|----------------------------------------|----------------------------------------|---------------------|---------------|
+ *  | handover             | 交接口置位(attach 口清位)            | `handover.lingerMs`                    | 是                  | 让位本腿      |
+ *  | orphan               | 装了孤儿车道 ∧ 看门狗已判父死          | `orphan.lingerMs`                      | 否                  | 照旧          |
+ *  | awaitingFirstAttach  | 还没有过非探针触点                     | `max(lingerMs, firstAttach.windowMs)`  | 否                  | 照旧          |
+ *  | owned                | 其余                                   | `lingerMs`                             | 否                  | 照旧          |
+ *
+ *  · **工作谓词一只**({@link laneWork}):附着 > 0 ∨ 在飞 > 0 ∨(本车道计后台 shell ∧ 运行中、引擎一退就会被收掉的后台 shell > 0)。本腿与
+ *    `sighup-idle.ts` 都只调它(读者词 `"lease"` / `"sighup"`);SIGHUP 读者在「让位」那一格恒读到「有工作」—— handover 车道的寿命只归本腿这一只
+ *    定时器,终端关闭不会按另一套谓词 / 另一个窗把引擎拆掉(两只定时器判同一件事 = 两条自退律,顶注 6 那句纪律)。
+ *  · **后台 shell 只在 handover 那一格计入**:owned / orphan 若也计,一只 `while true` 就让崩溃孤儿永生([ref] 倒退)。不是特判,是表里一格的值。
+ *  · **孤儿照旧只由看门狗判**(没有租约集):交接压过孤儿;父已死时 attach ⇒ 回到 orphan(与 [ref]「复用孤儿引擎」同)。壳在交接之后退出不是
+ *    本腿的事件 —— 车道一直是 handover,直到新的 attach。
+ *  · **交接车道与计数读口捆在一起**({@link EngineLeaseHandoverLane},与孤儿车道同理):缺席 ⇒ 门不建、车道结构上不可达。读口 = 退出边界此刻会硬收的
+ *    后台 shell 行数(`boot/exit-boundary.ts` 的 `countShellsExitWouldKill`;数与收同一只 `includeRetained`);装配层只按「非多租户」给,
+ *    不再有「读口缺席」这一态。它**不是** `/health.inflightBreakdown.sessionResident`(那是总数里会话驻留的分项;两问之差见 exit-boundary 那只函数的注)。
+ *  · **窗与拍频**:交接窗进「最短窗」推导(本腿会执行它);判据 / 钟 / 出口(SIGTERM 那条 drain + `exit-last.json`)全不变。
+ *  · 自退读数 `lane` 一键说清那一拍的车道(`orphan` / `firstAttachWindowExpired` 两只布尔随 `exit-last.json` 格式 3 退役 —— 同一事实只留一种读法);
+ *    不变量 `reason !== "idle"` ⟺ `lane === "orphan"`,同一处铸出。
  */
 import type { ParentOrphanReason } from "../parent-watch.js";
 /** 自退检查拍频的**上限**。**不开 env 旋钮**(与 `PARENT_WATCH_INTERVAL_MS` 同纪律:有真需求再议,
  *  防旋钮增殖);实际拍频由顶注 9 的推导取更小者。 */
 export declare const ENGINE_LEASE_TICK_MS = 15000;
+/** [ref] 车道闭集(书写序 = 派生优先序,见 {@link deriveEngineLane})。 */
+export declare const ENGINE_LANES: readonly ["handover", "orphan", "awaitingFirstAttach", "owned"];
+export type EngineLane = (typeof ENGINE_LANES)[number];
+/** 车道表里与配置无关的两列(窗那一列随配置,在 {@link createEngineLeaseTracker} 的 `windowOf` 里一处选)。
+ *  `Record<EngineLane, …>`:加一条车道而这里没跟 ⇒ 编译红。 */
+export interface EngineLaneRow {
+    /** 运行中、引擎一退就会被收掉的后台 shell 计入工作谓词吗。 */
+    readonly countsBackgroundShells: boolean;
+    /** SIGHUP 空闲窗在这条车道上让位本腿吗(让位 = SIGHUP 读者恒读到「有工作」)。 */
+    readonly sighupYieldsToLease: boolean;
+}
+export declare const ENGINE_LANE_TABLE: Readonly<Record<EngineLane, EngineLaneRow>>;
+/** 车道派生 —— **唯一**一处(从上到下第一条成立者;交接压过孤儿,孤儿压过候首触)。三个输入都是持久态。 */
+export declare function deriveEngineLane(s: {
+    readonly handedOver: boolean;
+    readonly orphaned: boolean;
+    readonly touched: boolean;
+}): EngineLane;
+/** 工作谓词的采样输入。`backgroundShells` 惰性:只在本车道计它时才读(那是一次注册表遍历)。 */
+export interface EngineWorkSample {
+    readonly attached: number;
+    readonly inflight: number;
+    readonly backgroundShells: () => number;
+}
+/** 谁在读工作谓词(闭集):本腿 = `"lease"`;SIGHUP 空闲窗 = `"sighup"`。 */
+export type EngineWorkReader = "lease" | "sighup";
+/**
+ * **一只**工作谓词(采样格;活性钟 / 离场钟 / 连续空闲满窗由各读者自己的窗判)。`lane` 缺席 = 租约腿未装配(纯服务器形)或已停 ——
+ * 那时没有任何一行可读,谓词 = 附着 ∨ 在飞(与 [ref] 之前的 SIGHUP 逐字同)。
+ */
+export declare function laneWork(lane: EngineLane | undefined, s: EngineWorkSample, reader: EngineWorkReader): boolean;
 /**
  * 孤儿态读数(装配层把看门狗的 `onOrphaned` 落成这一笔)。
  *
@@ -109,55 +187,142 @@ export interface EngineLeaseOrphanLane {
      *  `null` = 父还活着。 */
     read: () => EngineOrphanState | null;
 }
-/** 自退缘由闭集:`"idle"` = 没人用了(owned 态);另两个词 = 看门狗判的孤儿那两支。
- *  `orphan === (reason !== "idle")` 是不变量 —— 两者在**同一处**铸出(见 {@link createEngineLeaseTracker}),
- *  不存在各算一次的可能。 */
+/**
+ * [ref] 首次附着车道 —— 窗长与读口**捆在一起**(与 {@link EngineLeaseOrphanLane} 同理:平行的两只 dep 会让「配了首窗、却没有
+ * 首触读口」成为一个可表达的状态)。装配层恒给(旋钮恒有值);`windowMs` 为 `0` 即不给额外宽限。
+ */
+export interface EngineLeaseFirstAttachLane {
+    /** 旋钮值(`config.engineFirstAttachMs`;`0` = 关)。生效窗 = `max(lingerMs, windowMs)` —— 由本模块一处算,不在装配层算。 */
+    windowMs: number;
+    /** 首个**非探针** HTTP 触点的单调时刻(`drainState.firstActivityAt`;与 `now` 同为 `performance.now()` 域)。`null` = 还没有过。
+     *  属主 = 活性时钟的写者(写一次就定):本腿只读,不锁存、不另算 —— 首触的判据(探针律)只有那一处。 */
+    firstTouchAt: () => number | null;
+}
+/**
+ * [ref] 交接车道 —— 窗长与后台 shell 计数读口**捆在一起**(与孤儿车道同理:「配了交接窗、却数不了后台 shell」不可表达)。
+ * 装配层只在「非多租户」时给;缺席 ⇒ 把手上没有交接门,handover 车道结构上不可达。
+ */
+export interface EngineLeaseHandoverLane {
+    /** 交接车道的窗(`config.engineHandoverLingerMs`,缺省 30 min)。 */
+    lingerMs: number;
+    /** 此刻运行中、引擎一退就会被收掉的后台 shell 行数(装配层给退出边界的 `shellsExitWouldKill`:与硬收面同一只 `includeRetained`,读不出按 1 计、不抛)。 */
+    backgroundShells: () => number;
+}
+/** 交接的缘由闭集(交接口体的 `reason`)。 */
+export declare const HANDOVER_REASONS: readonly ["background_exit"];
+export type HandoverReason = (typeof HANDOVER_REASONS)[number];
+/** `engine_lane_changed` 的缘由闭集(只由交接门铸:孤儿已有 `parent_watch_orphaned`,首触今天无日志)。 */
+export type EngineLaneChangeReason = "handover_requested" | "attached";
+/** 自退缘由闭集:`"idle"` = 不在孤儿车道;另两个词 = 看门狗判的孤儿那两支。
+ *  不变量 `reason !== "idle"` ⟺ `lane === "orphan"` —— 两者在**同一处**铸出(见 {@link createEngineLeaseTracker})。 */
 export type EngineLeaseExitReason = "idle" | ParentOrphanReason;
 /**
  * 自退那一刻的**判据读数**(一个对象,三个消费者:`engine_lease_auto_exit` 日志行、数据根上的
  * `exit-last.json` 留痕、以及 drain 本身)。一处铸出 ⇒ 日志与留痕永远不会各说各话。
  */
 export interface EngineLeaseExitReport {
-    /** 父已经不在了那一路退的吗(壳的 exit watch 读这一键把 pid 归入**预期**退出)。 */
-    orphan: boolean;
+    /** [ref]:自退那一拍的车道(窗就是按它选的)。 */
+    lane: EngineLane;
     reason: EngineLeaseExitReason;
     /** 真实空闲时长(不是配置的窗长 —— 见顶注 8)。 */
     idleForMs: number;
     attached: number;
     inflight: number;
-    /** 本次**生效**的窗长(孤儿态 = 孤儿窗)。 */
+    /** 本次**生效**的窗长(= 那一拍车道的窗)。 */
     lingerMs: number;
-    /** 成孤儿到自退之间隔了多久;非孤儿退出时键缺席(不编 0)。 */
+    /** 成孤儿到自退之间隔了多久;非孤儿车道退出时键缺席(不编 0)。 */
     orphanedForMs?: number;
 }
 /**
  * [ref] —— 租约窗的 wire 读数(`GET /health` 的 `engineLease`;壳持租约的触点节拍据此定,别处起的短窗引擎不再让第二句失败)。
  *
  * ## 报的是什么
- *  · `lingerMs` = 本腿**会执行的最短静默窗**:父还活着的窗({@link EngineLeaseDeps.lingerMs})与孤儿窗({@link EngineLeaseOrphanLane.lingerMs},只在看门狗装了时存在)取小。
+ *  · `lingerMs` = 本腿**会执行的最短静默窗**:父还活着的窗({@link EngineLeaseDeps.lingerMs})、孤儿窗({@link EngineLeaseOrphanLane.lingerMs},只在看门狗装了时存在)、
+ *    交接窗({@link EngineLeaseHandoverLane.lingerMs},只在交接车道装了时存在)取小。
  *    取**最短**而不是「此刻生效」:此刻生效的窗在父死那一拍从 owned 窗掉到孤儿窗,按旧读数定节拍的壳会在下一次读 `/health` 之前被拆台;
  *    最短窗是配置的性质、不随状态变,壳的触点只要比它密,在任何状态下都留得住引擎。
  *  · `tickMs` = 自退检查的采样拍。自退发生在**生效窗**满之后、至多再晚一拍(顶注 8);生效窗恒 ≥ `lingerMs`(`lingerMs` 是各窗里最短的一个),所以触点比 `lingerMs` 密 ⇒ 在任何状态下都先于自退。
  *    读数**不预言**自退时刻:父还活着时生效的是 owned 窗,自退只会更晚。
+ *  · `lane`([ref])= 此刻的车道(与自退判据同一只派生函数,每次现读)。
  *
  * ## 一源
  * 与租约腿自己的行为同一处铸出:`engine_lease_armed` 日志、自退判据用的窗、拍频推导(`tickMs = min(15s, 最短窗)`)和本读数读的是同一组数 ——
- * 不存在第二处去「算一遍租约窗」。一个永远不到期的窗(owned 窗 = `Infinity` 且没有孤儿车道)不是租约:读数整个缺席,不补 0、不把 `Infinity` 送进 JSON。
+ * 不存在第二处去「算一遍租约窗」。一个永远不到期的窗(owned 窗 = `Infinity` 且没有孤儿 / 交接车道)不是租约:读数整个缺席,不补 0、不把 `Infinity` 送进 JSON。
  */
 export interface EngineLeaseFacts {
     readonly lingerMs: number;
     readonly tickMs: number;
+    /** [ref]:此刻的车道。 */
+    readonly lane: EngineLane;
+    /** [ref] 首窗格({@link EngineLeaseFirstAttachFacts}):候首触窗有限(owned 窗有限)才在场 —— 永不到期的窗不上 wire(同上一段那条律)。 */
+    readonly firstAttach?: EngineLeaseFirstAttachFacts;
+    /** [ref] 交接格({@link EngineHandoverFacts}):只在 handover 车道在场。 */
+    readonly handover?: EngineHandoverFacts;
+}
+/**
+ * [ref] —— `GET /health` 的 `engineLease.firstAttach`:首次附着前的宽限窗。
+ *
+ *  · `windowMs` = **生效**的候首触窗 `max(owned 窗, ENGINE_FIRST_ATTACH_MS)`(解析后的真值,不是旋钮回声;旋钮 `0` ⇒ 等于 owned 窗)。
+ *  · `since` = 窗开始的时刻(装配那一拍,epoch ms)。父一直活着且一直没人碰时,`since + windowMs` 是「最早何时自退」的**下界**,不是预言 —— 父死之后孤儿窗优先、可以更早退
+ *    (那一态的窗看同一格的 `lingerMs`:最短窗已含孤儿窗;本格在孤儿态照旧在场,codex 对抗审 F2 成文);
+ *    候首触期间有在飞会让它后移,另有至多一拍的采样滞后(顶注 8)。没有单列 `until` —— 它可由这两格推出(一个事实一处读)。
+ *  · `attachedAt` = 首个非探针触点的时刻(epoch ms);`null` = 还在候首触。非 null ⇒ 首窗已永久关闭(单向)。
+ *  · 两个时刻是**同一只单调钟**的投影:装配时只采一次挂钟作锚,`epoch = since + (单调时刻 − 装配单调时刻)`。不跑第二只钟;系统改钟之后它与真实期限会漂开(成文)。
+ */
+export interface EngineLeaseFirstAttachFacts {
+    readonly windowMs: number;
+    readonly since: number;
+    readonly attachedAt: number | null;
+}
+/**
+ * [ref] —— 交接格(`GET /health` 的 `engineLease.handover`;交接口 200 体 = 其中 `since` / `lingerMs` / `backgroundShells` 三键加 `lane`)。
+ *  · `since` = 进入交接车道的时刻(epoch ms,与首窗格同一只单调钟投影);幂等的再次交接回同一个值。
+ *  · `lingerMs` = 交接窗;`backgroundShells` = 退出边界此刻会硬收的后台 shell 行数(现读)。窗只在它为 0、阻断集在飞为 0、且无附着与触点时起算。
+ *  · 不带在飞数:阻断集在同一份 `/health` 里已由 `inflightBreakdown.http + leader` 读出(一个事实一处读);交接口 200 体若带它,读到的恒含这次请求自己。
+ */
+export interface EngineHandoverFacts {
+    readonly since: number;
+    readonly reason: HandoverReason;
+    readonly lingerMs: number;
+    readonly backgroundShells: number;
+}
+/** 交接口的应答(200 体):`lane` 恒 `"handover"` + 交接格里的三键。 */
+export interface EngineHandoverEntry {
+    readonly lane: "handover";
+    readonly since: number;
+    readonly lingerMs: number;
+    readonly backgroundShells: EngineHandoverFacts["backgroundShells"];
+}
+/** attach 口的应答(200 体):清位之后的车道;`handedOverForMs` 只在这一次 attach 真的清掉了交接位时在场。 */
+export interface EngineAttachAnswer {
+    readonly lane: EngineLane;
+    readonly handedOverForMs?: number;
+}
+/**
+ * [ref] 交接门 —— 本腿交给装配层(经排空盒子到两只 HTTP 口)的**唯一**写口。只在交接车道装了时存在。
+ * `observing` = 腿还在观察(停了 ⇒ 能力事实答不可用;两口不再写)。
+ */
+export interface EngineHandoverDoor {
+    readonly observing: boolean;
+    /** 置交接位(幂等:已在 handover ⇒ 回同一个 `since`,不再打日志)。 */
+    enter(reason: HandoverReason): EngineHandoverEntry;
+    /** 清交接位(不在 handover ⇒ 照回此刻车道)。 */
+    attach(): EngineAttachAnswer;
 }
 /** {@link createEngineLeaseTracker} 的把手:`stop()` 收摊;`facts` 现读 —— **腿还在观察**时才有(收摊 / 自退触发之后缺席,says-yes ⟺ 腿在转)。 */
 export interface EngineLeaseHandle {
     stop(): void;
     readonly facts: EngineLeaseFacts | undefined;
+    /** [ref]:此刻的车道(腿在观察才有;SIGHUP 读者经它读同一只车道函数)。 */
+    lane(): EngineLane | undefined;
+    /** [ref]:交接门(交接车道装了才有)。 */
+    readonly handover?: EngineHandoverDoor;
 }
 export interface EngineLeaseDeps {
     /** 活附着数 = 本副本当前**打开着的 SSE 流**条数(`drainState.attachedStreams`,由 `createHttpServer` 自赋)。 */
     attachedStreams: () => number;
-    /** 在飞腿数 —— **`/health` 的 `inflight` 同一只 getter**(`drainState.inflight`)。不自建第二套计数:
-     *  两套计数迟早分叉,而分叉的那一侧恰好是「以为没 run 了」就把引擎关掉。 */
+    /** 必须等完的活的数 —— **阻断集** `drainState.blockingInflight`(`http + leader`;与排空等的、SIGHUP 空闲窗同一只 getter。会话驻留的后台 shell / monitor 在
+     *  `/health.inflight` 的总数里、不在这里,见顶注「已知收窄」)。不自建第二套计数:两套计数迟早分叉,而分叉的那一侧恰好是「以为没 run 了」就把引擎关掉。 */
     inflight: () => number;
     /** 最后一次**非探针** HTTP 触点的单调时刻(`drainState.lastActivityAt`)。
      *  ⚠️ 时基契约:必须与本模块的 `now` 同为 `performance.now()` 单调域(`server.ts` 的打点即该域)——
@@ -180,8 +345,12 @@ export interface EngineLeaseDeps {
     /** owned 态(父还活着 / 没被监视)下三合取**持续**满这么久才触发(`config.engineLingerMs`,默认 60s)。
      *  **`Infinity`** = 永不自退(`ENGINE_AUTO_EXIT` 关着的 owned 引擎;窗永远追不上 ⇒ 无需第二条分支)。 */
     lingerMs: number;
-    /** 孤儿车道(`SEMA_PARENT_PID` 在场才给)。缺席 ⇒ 这台引擎不可能成孤儿,窗恒为 `lingerMs`。 */
+    /** 孤儿车道(`SEMA_PARENT_PID` 在场才给)。缺席 ⇒ 这台引擎不可能成孤儿。 */
     orphan?: EngineLeaseOrphanLane;
+    /** [ref] 首次附着车道(恒给;见 {@link EngineLeaseFirstAttachLane})。 */
+    firstAttach: EngineLeaseFirstAttachLane;
+    /** [ref] 交接车道(非多租户才给;见 {@link EngineLeaseHandoverLane})。缺席 ⇒ 把手上没有交接门。 */
+    handover?: EngineLeaseHandoverLane;
     log: (event: string, fields: Record<string, unknown>) => void;
     /** 检查拍频 seam(测试)。缺省 = 顶注 9 的推导(`min(ENGINE_LEASE_TICK_MS, 本腿可能执行的每个窗)`)。 */
     tickMs?: number;
@@ -189,6 +358,9 @@ export interface EngineLeaseDeps {
      *  拉长 linger 窗 —— 前跳把窗直接跳过去 = 在一只还有人用的引擎底下提前关停。 */
     now?: () => number;
 }
+/** 后台 shell 计数在没有交接车道时**结构上读不到**(只有 handover 那一格读它,而 handover 车道只经交接门进入,门只在车道装了时建)。
+ *  真被读到 = 不变量破了 —— 响亮抛,不回一个看起来合理的 0([ref])。 */
+export declare const backgroundShellsUnreachable: () => number;
 /** 装配并**立刻**起自退检查(装配即 `engine_lease_armed`)。返回停机链用的 `stop()`。 */
 export declare function createEngineLeaseTracker(deps: EngineLeaseDeps): EngineLeaseHandle;
 //# sourceMappingURL=engine-lease.d.ts.map

package/dist/boot/engine-lease.js

@@ -1,20 +1,86 @@
 export const ENGINE_LEASE_TICK_MS = 15_000;
+export const ENGINE_LANES = ["handover", "orphan", "awaitingFirstAttach", "owned"];
+export const ENGINE_LANE_TABLE = Object.freeze({
+    handover: { countsBackgroundShells: true, sighupYieldsToLease: true },
+    orphan: { countsBackgroundShells: false, sighupYieldsToLease: false },
+    awaitingFirstAttach: { countsBackgroundShells: false, sighupYieldsToLease: false },
+    owned: { countsBackgroundShells: false, sighupYieldsToLease: false },
+});
+export function deriveEngineLane(s) {
+    if (s.handedOver)
+        return "handover";
+    if (s.orphaned)
+        return "orphan";
+    return s.touched ? "owned" : "awaitingFirstAttach";
+}
+export function laneWork(lane, s, reader) {
+    const row = lane === undefined ? undefined : ENGINE_LANE_TABLE[lane];
+    switch (reader) {
+        case "sighup":
+            if (row?.sighupYieldsToLease === true)
+                return true;
+            break;
+        case "lease":
+            break;
+        default: {
+            const unhandled = reader;
+            throw new Error(`laneWork: unknown reader ${String(unhandled)}`);
+        }
+    }
+    return s.attached > 0 || s.inflight > 0 || (row?.countsBackgroundShells === true && s.backgroundShells() > 0);
+}
+export const HANDOVER_REASONS = ["background_exit"];
+export const backgroundShellsUnreachable = () => {
+    throw new Error("engine lease: background-shell count read on a lane table row that counts it, but no handover lane is armed (invariant broken)");
+};
 export function createEngineLeaseTracker(deps) {
     const orphanLane = deps.orphan;
-    const shortestLingerMs = Math.min(deps.lingerMs, orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY);
+    const handoverLane = deps.handover;
+    const shortestLingerMs = Math.min(deps.lingerMs, orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY, handoverLane?.lingerMs ?? Number.POSITIVE_INFINITY);
     const tickMs = deps.tickMs ?? Math.min(ENGINE_LEASE_TICK_MS, shortestLingerMs);
-    const leaseFacts = Number.isFinite(shortestLingerMs) ? Object.freeze({ lingerMs: shortestLingerMs, tickMs }) : undefined;
+    const firstAttachWindowMs = Math.max(deps.lingerMs, deps.firstAttach.windowMs);
     const now = deps.now ?? (() => performance.now());
     let stopped = false;
-    let idleSince = now();
+    const armedAt = now();
+    const armedEpochMs = Date.now();
+    const epochOf = (mono) => Math.round(armedEpochMs + (mono - armedAt));
+    let idleSince = armedAt;
+    let handedOver = null;
+    const backgroundShells = handoverLane?.backgroundShells ?? backgroundShellsUnreachable;
+    function windowOf(lane) {
+        switch (lane) {
+            case "handover":
+                return handoverLane?.lingerMs ?? Number.POSITIVE_INFINITY;
+            case "orphan":
+                return orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY;
+            case "awaitingFirstAttach":
+                return firstAttachWindowMs;
+            case "owned":
+                return deps.lingerMs;
+            default: {
+                const unhandled = lane;
+                throw new Error(`engine lease: unknown lane ${String(unhandled)}`);
+            }
+        }
+    }
+    function laneNow() {
+        const orphaned = orphanLane ? orphanLane.read() : null;
+        const lane = deriveEngineLane({ handedOver: handedOver !== null, orphaned: orphaned !== null, touched: deps.firstAttach.firstTouchAt() !== null });
+        return { lane, orphaned };
+    }
     deps.log("engine_lease_armed", {
         lingerMs: Number.isFinite(deps.lingerMs) ? deps.lingerMs : null,
         orphanLingerMs: orphanLane?.lingerMs ?? null,
+        firstAttachMs: deps.firstAttach.windowMs,
+        firstAttachWindowMs: Number.isFinite(firstAttachWindowMs) ? firstAttachWindowMs : null,
+        handoverLingerMs: handoverLane?.lingerMs ?? null,
         tickMs,
         note: "engine self-exits once NO shell session is attached AND no run is in flight AND no HTTP touch, " +
-            "continuously for the linger window — via the same graceful drain as SIGTERM. The window is " +
-            "ENGINE_LINGER_MS while the parent is alive (or the watch is not armed) and ENGINE_ORPHAN_LINGER_MS " +
-            "once SEMA_PARENT_PID's process is gone. Set ENGINE_AUTO_EXIT=false and unset SEMA_PARENT_PID to disable.",
+            "continuously for the linger window — via the same graceful drain as SIGTERM. The window is chosen by lane: " +
+            "ENGINE_HANDOVER_LINGER_MS after POST /v1/engine/handover (until the next POST /v1/engine/attach; running background " +
+            "shells count as work only there); ENGINE_ORPHAN_LINGER_MS once SEMA_PARENT_PID's process is gone; otherwise " +
+            "max(ENGINE_LINGER_MS, ENGINE_FIRST_ATTACH_MS) until the first non-probe HTTP request ever arrives, and ENGINE_LINGER_MS after it. " +
+            "Set ENGINE_AUTO_EXIT=false and unset SEMA_PARENT_PID to disable.",
     });
     const timer = setInterval(() => {
         if (stopped)
@@ -25,7 +91,8 @@ export function createEngineLeaseTracker(deps) {
         }
         const attached = deps.attachedStreams();
         const inflight = deps.inflight();
-        if (attached > 0 || inflight > 0) {
+        const { lane, orphaned } = laneNow();
+        if (laneWork(lane, { attached, inflight, backgroundShells }, "lease")) {
             idleSince = null;
             return;
         }
@@ -34,8 +101,7 @@ export function createEngineLeaseTracker(deps) {
             idleSince = t;
             return;
         }
-        const orphaned = orphanLane ? orphanLane.read() : null;
-        const linger = orphanLane && orphaned !== null ? orphanLane.lingerMs : deps.lingerMs;
+        const linger = windowOf(lane);
         if (t - deps.lastActivityAt() < linger)
             return;
         if (t - deps.lastAttachEndedAt() < linger)
@@ -43,22 +109,17 @@ export function createEngineLeaseTracker(deps) {
         if (t - idleSince < linger)
             return;
         stop();
+        const orphanedNow = lane === "orphan" ? orphaned : null;
         const report = {
-            orphan: orphaned !== null,
-            reason: orphaned?.reason ?? "idle",
+            lane,
+            reason: orphanedNow?.reason ?? "idle",
             idleForMs: Math.round(t - Math.max(idleSince, deps.lastActivityAt(), deps.lastAttachEndedAt())),
             attached,
             inflight,
             lingerMs: linger,
-            ...(orphaned !== null ? { orphanedForMs: Math.round(t - orphaned.since) } : {}),
+            ...(orphanedNow !== null ? { orphanedForMs: Math.round(t - orphanedNow.since) } : {}),
         };
-        deps.log("engine_lease_auto_exit", {
-            ...report,
-            note: orphaned !== null
-                ? "the parent that spawned this engine is gone AND nobody is attached, no run is in flight and no HTTP touch " +
-                    "for the full orphan linger window — entering the SIGTERM graceful drain path (exit code 0; see exit-last.json)"
-                : "no attached shell session, no in-flight run and no HTTP touch for the full linger window — entering the SIGTERM graceful drain path",
-        });
+        deps.log("engine_lease_auto_exit", { ...report, note: AUTO_EXIT_NOTES[lane] });
         deps.selfExit(report);
     }, tickMs);
     timer.unref?.();
@@ -68,11 +129,76 @@ export function createEngineLeaseTracker(deps) {
         stopped = true;
         clearInterval(timer);
     }
+    function firstAttachFacts() {
+        if (!Number.isFinite(firstAttachWindowMs))
+            return undefined;
+        const touchedAt = deps.firstAttach.firstTouchAt();
+        return Object.freeze({ windowMs: firstAttachWindowMs, since: armedEpochMs, attachedAt: touchedAt === null ? null : epochOf(touchedAt) });
+    }
+    function handoverFacts() {
+        if (handedOver === null || handoverLane === undefined)
+            return undefined;
+        return Object.freeze({
+            since: epochOf(handedOver.since),
+            reason: handedOver.reason,
+            lingerMs: handoverLane.lingerMs,
+            backgroundShells: handoverLane.backgroundShells(),
+        });
+    }
+    const door = handoverLane === undefined
+        ? undefined
+        : {
+            get observing() {
+                return !stopped;
+            },
+            enter(reason) {
+                if (handedOver === null) {
+                    const from = laneNow().lane;
+                    handedOver = { since: now(), reason };
+                    deps.log("engine_lane_changed", { from, to: "handover", reason: "handover_requested", since: epochOf(handedOver.since) });
+                }
+                const facts = handoverFacts();
+                if (facts === undefined)
+                    throw new Error("engine lease: handover facts absent right after entering the handover lane (invariant broken)");
+                return { lane: "handover", since: facts.since, lingerMs: facts.lingerMs, backgroundShells: facts.backgroundShells };
+            },
+            attach() {
+                if (handedOver === null)
+                    return { lane: laneNow().lane };
+                const t = now();
+                const handedOverForMs = Math.round(t - handedOver.since);
+                handedOver = null;
+                const to = laneNow().lane;
+                deps.log("engine_lane_changed", { from: "handover", to, reason: "attached", since: epochOf(t) });
+                return { lane: to, handedOverForMs };
+            },
+        };
     return {
         stop,
         get facts() {
-            return stopped ? undefined : leaseFacts;
+            if (stopped || !Number.isFinite(shortestLingerMs))
+                return undefined;
+            const firstAttach = firstAttachFacts();
+            const handover = handoverFacts();
+            return Object.freeze({
+                lingerMs: shortestLingerMs,
+                tickMs,
+                lane: laneNow().lane,
+                ...(firstAttach !== undefined ? { firstAttach } : {}),
+                ...(handover !== undefined ? { handover } : {}),
+            });
         },
+        lane: () => (stopped ? undefined : laneNow().lane),
+        ...(door !== undefined ? { handover: door } : {}),
     };
 }
+const AUTO_EXIT_NOTES = {
+    handover: "this engine was handed over to the background (POST /v1/engine/handover) and nobody attached, no run and no background shell " +
+        "was running and no HTTP touch for the full ENGINE_HANDOVER_LINGER_MS window — entering the SIGTERM graceful drain path",
+    orphan: "the parent that spawned this engine is gone AND nobody is attached, no run is in flight and no HTTP touch " +
+        "for the full orphan linger window — entering the SIGTERM graceful drain path (exit code 0; see exit-last.json)",
+    awaitingFirstAttach: "no non-probe HTTP request EVER reached this engine within the first-attach window (max(ENGINE_LINGER_MS, ENGINE_FIRST_ATTACH_MS)) " +
+        "and nothing is attached or in flight — entering the SIGTERM graceful drain path",
+    owned: "no attached shell session, no in-flight run and no HTTP touch for the full linger window — entering the SIGTERM graceful drain path",
+};
 //# sourceMappingURL=engine-lease.js.map

package/dist/boot/execution-env.d.ts

@@ -55,6 +55,9 @@ export interface SessionScopedRegistries {
      * 请求放宽凭据面)。
      */
     setSessionInheritEnv(sid: string, policy: TaskInheritEnv | undefined): void;
+    /** 本进程见过的会话 → 属主(围栏表本身,只读视图;`null` = 匿名)。**会话驻留后台行的枚举源**:`session-resident-background.ts` 逐会话问注册表
+     *  (core 的访问元组要带 scope,没有进程总数的读口),读的就是这一张 —— 每次提交写一笔、`dropSession` 清一笔、LRU 有界,不另立第二张会话名册。 */
+    readonly sessionOwners: ReadonlyMap<string, string | null>;
     /** 记录/对拍本会话的主人。与上次不同 ⇒ **先清两张表**再记新主(换主即清)。`null` = 匿名会话,
      *  它同样是一个**稳定**的身份值(不是「未知」),所以匿名重入不会被判成换主。 */
     fenceSessionOwner(sid: string, owner: string | null): void;
@@ -171,6 +174,7 @@ export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
     setSessionInheritEnv: (sid: string, policy: TaskInheritEnv | undefined) => void;
     fenceSessionOwner: (sid: string, owner: string | null) => void;
     dropSessionScoped: (sid: string) => void;
+    sessionResidentBackground: () => number;
     executionEnvFactory: import("@sema-agent/core").ExecutionEnvFactory | undefined;
     worktreeReap: (() => Promise<void>) | undefined;
     sendUserFileTaskEnvs: TaskEnvRegistry | undefined;

package/dist/boot/execution-env.js

@@ -40,6 +40,7 @@ import { createLaneHomeAbsenceReporter } from "../lane-home-probe.js";
 import { REMOTE_EXEC_PROVIDER_WORDS, buildLaneHomeBootNote, buildLaneHomeClaim, capabilitiesFor, executionLaneOf, laneBindsReads, laneIsolated, laneSandboxReadFloorState } from "../execution-lane-caps.js";
 import { warnReadDenyFloorUnkept } from "./execution-lane.js";
 import { seatText } from "../trace/exit-seat.js";
+import { countSessionResidentBackground } from "../session-resident-background.js";
 function boundedSessionSetter(map, maxEntries) {
     return (sid, value) => {
         map.delete(sid);
@@ -79,6 +80,7 @@ export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
     return {
         perSessionCwd,
         perSessionShellEnv,
+        sessionOwners: owners,
         setSessionCwd: (sid, cwd) => {
             perSessionCwd.set(sid, cwd);
             touch(sid, undefined);
@@ -506,10 +508,20 @@ export function createExecutionEnv(ctx) {
                 : undefined;
     if (lspManager)
         logger.info("lsp_enabled", { provider: lspProvider });
+    const unreadableReported = new Set();
+    const sessionResidentBackground = () => countSessionResidentBackground(sessionScoped.sessionOwners, {
+        onUnreadable: (sessionId, err) => {
+            if (unreadableReported.has(sessionId))
+                return;
+            unreadableReported.add(sessionId);
+            logger.warn("session_resident_background_unreadable", { sessionId, counted: 1, err: seatText("operator-log-text", String(err)) });
+        },
+    });
     return {
         perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, setSessionInheritEnv,
         fenceSessionOwner: sessionScoped.fenceSessionOwner,
         dropSessionScoped: sessionScoped.dropSession,
+        sessionResidentBackground,
         executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer, sandboxSecretSeatGate, sandboxPodReaper, sandboxGitPlane,
     };
 }

package/dist/boot/exit-boundary.d.ts

@@ -1,4 +1,49 @@
+/**
+ * [ref] —— **进程退出边界**的装配器:全进程**一只**,两条车道(HTTP 服务 / `run-local` 一次性 CLI)同走。
+ *
+ * 不变量 = **本进程拥有的东西不得活过本进程**(自起的前台子进程组 + 自铸的 ephemeral host 工作区)。
+ * 它是**进程**的性质,不属于某一条退出路径,也不属于某一个入口 —— 所以收割挂 `process.once("exit")`,
+ * 而这只钩的**装配**从 `boot/shutdown.ts`(只有 HTTP 车道装得起:它的 ctx 绑着 server / backend / runner…)
+ * 抽到这里,变成一条只要一只 {@link Logger} 的函数。
+ *
+ * ── [ref] 的病(test 7.93.3 复验实测)────────────────────────────────────────────────────────────────
+ * [ref] 之后 HTTP 车道零孤儿,而 `src/run-local.ts` **一只 `process.on/once` 都没有** —— 它却经
+ * `hostExecutionEnvFactory` 走同一条 host exec 腿、同一本前台簿(`trackHostForegroundChild`)。Ctrl-C ⇒
+ * 进程在 12ms 内被信号**默认终止**,簿上的组留 `ppid=1` 跑满。用户面:一次 `sema run` 被 Ctrl-C 之后,
+ * 机器上留着它起的 `npm run build` / `sleep`,没有任何人会再去 kill。
+ *
+ * ── 为什么不是「run-local 也补一份」──────────────────────────────────────────────────────────────────
+ * 同一句不变量在两个入口各写一份 = 两个写者、两份会各自腐烂的注(CLAUDE.md 以点改面:修一个类,不是
+ * 修一个出口)。所以是**抽出**而不是复制:钩体、两条腿、哨兵读数、`dispose` 全在本文件,两条车道各自
+ * 只剩一行调用。HTTP 车道的行为**逐字不变**(函数体整段搬运,缩进外无一字改动)。
+ *
+ * 🔴 **光有本装配器治不了 run-local**:`exit` 事件在进程被信号**默认终止**时**不触发**。前台 CLI 的
+ * Ctrl-C 是常态 ⇒ run-local 必须同时装 SIGINT / SIGTERM 处理器,让信号落到一条显式 `process.exit` 上
+ * (见 `run-local.ts` 的 {@link installRunLocalExitBoundary} 注:退出码取 128+signo 的理由写在那里)。
+ * HTTP 车道的三只信号处理器留在 `boot/shutdown.ts`(它们承载的是 drain / SIGHUP 空闲窗这些**车道语义**,
+ * 不是退出边界)。
+ */
+import { type TaskRegistry } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
+/**
+ * 退出边界的硬收面**此刻**会收掉的后台 shell 行数(`background_bash` + `monitor`,在跑,整张进程级注册表,retain 行按
+ * {@link PROCESS_EXIT_INCLUDES_RETAINED} 跳过)—— 「引擎现在退,会不会把一条在跑的后台 shell 一起收掉」这一问的**唯一**读法。
+ *
+ * 一问一源:数与收读同一只 `includeRetained` 常量,core 的 `countRunningBackgroundShells` 与 `killAllBackgroundShellsNow` 又按同一只访问函数选行
+ * (core 注:the count and the walk cannot drift)⇒ 这只数就是硬收面会交出的 `killed` 收据数。
+ * **不是** `/health.inflightBreakdown.sessionResident`(`session-resident-background.ts`):那一项回答「引擎托管着多少会话驻留的活」,是总数里的一个分项 ——
+ * 只数围栏表里会话的、会话驻留的行(挂在 run 腿上的行算在 http 项里,数它是第二次;围栏外的会话它看不见);本函数整表数、不分会话,
+ * 腿上的行、围栏外会话的行都在内。两问的关系 = 读得出时本数 ≥ 驻留项(驻留项的每一行都是本数的一行)。
+ *
+ * 读不出(core:某行 env 的 retain 声明读抛 ⇒ 计数抛)⇒ 按 **1** 计并经 `onUnreadable` 报出 —— 读不出 ⇒ 非空闲,与驻留项同一条律;
+ * 本函数在租约拍(定时器回调)、`/health` 与交接口里被调,**不许抛**(定时器里一抛就是 uncaught,一台交接出去的引擎会因此崩掉并收掉它本该留着的 shell)——
+ * 报口自己再抛(抛出物转不成文本之类)也一样:落 `console.error`(不回同一只报口),读数照返 1。
+ * `registry` 只供测试换桩(只用到 `countRunningBackgroundShells`)。
+ */
+export declare function countShellsExitWouldKill(opts: {
+    readonly registry?: Pick<TaskRegistry, "countRunningBackgroundShells">;
+    readonly onUnreadable: (err: unknown) => void;
+}): number;
 /** {@link installProcessExitBoundary} 的把手。 */
 export interface ProcessExitBoundary {
     /**
@@ -8,6 +53,11 @@ export interface ProcessExitBoundary {
      * 返回本次软停的后台行数(core `reapAllSessionBackground` 的返回;腿抛错 ⇒ 0,warn 已记)—— 调用方据此决定欠不欠宽限。
      */
     reapChildProcessesEarly(): number;
+    /**
+     * 硬收面此刻会收掉的后台 shell 行数({@link countShellsExitWouldKill},进程级注册表)。读不出 ⇒ 按 1 计,运维行
+     * `engine_handover_shell_count_unreadable` 本装配**只响一次**(这只读口在租约拍里被调,逐次响会刷屏)。附着租约交接车道那一格工作谓词读它。
+     */
+    shellsExitWouldKill(): number;
     /** 摘掉本次装配的 `exit` 钩。幂等(同进程内反复装配的调用方=测试必须用它收尾)。 */
     dispose(): void;
 }