@sema-agent/server 1.323.0 → 2.0.0

package/dist/session-titler.js

@@ -1,10 +1,30 @@
-export const TITLE_MAX_CHARS = 80;
-const OBJECTIVE_SNIPPET_CHARS = 600;
+/**
+ * Auto-generated session titles.
+ *
+ * SHAPE: fire-and-forget at FIRST task submit for a session (the objective is known then — no need to wait
+ * for the run to finish, and the web Recents gets the title sooner). Write-once (`setTitleIfNull`, store-side
+ * `WHERE title IS NULL`) — the USER-facing rename lives BFF-side as a label overlay (user label wins
+ * over engine title, two layers never fight). Generation = one cheap-model one-liner via the deployment's
+ * hookLlm face (summarize role → MODEL_CHEAP_ID when configured, else the main model; bounded + timed out).
+ *
+ * FAILURE POSTURE: everything is best-effort — a generation/store failure logs and leaves title null (the
+ * list falls back to objectivePreview). An in-process pending set dedupes concurrent submits on the same
+ * session; the store's IS NULL guard closes the cross-replica race (double generation costs one extra cheap
+ * call at worst, and exactly one title lands).
+ */
+export const TITLE_MAX_CHARS = 80; // display budget (column holds 120; leave headroom for future prefixing)
+const OBJECTIVE_SNIPPET_CHARS = 600; // prompt input bound — a title needs the gist, not the whole objective
 const LLM_TIMEOUT_MS = 15_000;
-const NO_ROW_RETRY_MS = 20_000;
+const NO_ROW_RETRY_MS = 20_000; // session_meta register lag grace (MED3) — one in-process retry before releasing
+/** 失败日志 per-cause 去重的归一窗口:取 error 文案前 N 字符当 cause 键(错误文案尾部常带
+ *  会话/请求级变量,前缀足以区分「凭据缺失」vs「超时」这类配置性差异)。 */
 const FAIL_CAUSE_KEY_CHARS = 80;
+/** cause 键集合上限——错误文案前缀本身含变量时防无界;满了整体清空,代价只是偶发多一条 warn。 */
 const FAIL_CAUSE_CAP = 100;
+/** Sessions already handled (titled, failed, or in flight) this process — one attempt per session per process.
+ *  Bounded: evict-oldest past the cap (a worker sees a bounded set of NEW sessions between restarts anyway). */
 const SEEN_CAP = 10_000;
+/** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */
 export function sanitizeTitle(raw) {
     const oneLine = raw.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").trim();
     const unquoted = oneLine.replace(/^["'「『]+/, "").replace(/["'」』]+$/, "").trim();
@@ -12,6 +32,10 @@ export function sanitizeTitle(raw) {
 }
 export function buildTitlePrompt(objective) {
     const snippet = objective.length > OBJECTIVE_SNIPPET_CHARS ? `${objective.slice(0, OBJECTIVE_SNIPPET_CHARS)}…` : objective;
+    // The task text is DATA here, not instructions — fence it (with the closing tag DEFUSED inside the data so
+    // the objective cannot terminate the fence early) and pin the output contract. A prompt-injection attempt
+    // can at worst produce a weird title, which the sanitizer bounds to one line; titles are display-only and
+    // never re-enter any model context.
     const fenced = snippet.replace(/<(\/?)request>/gi, "<\u200b$1request>");
     return ("Write a short title (at most 8 words) summarizing the user request below. " +
         "Reply with ONLY the title on a single line — no quotes, no preamble. " +
@@ -21,6 +45,12 @@ export function buildTitlePrompt(objective) {
 }
 export function createSessionTitler(deps) {
     const seen = new Set();
+    // [854]⑤ 失败日志锐化:titler 失败本是 fail-soft(标题留空、列表回退 objectivePreview,零用户面),
+    // 但同一部署级配置性失败(凭据缺失/模型面不可达)会随每次 trial/每个新会话反复触发——per-session
+    // warn 在评测跑批时是纯噪音。取舍=「首条 warn + 后续同 cause 全 debug」:完全静默会让运维发现不了
+    // 配置问题(违背 fail-loud),每条都 warn 又淹日志;同 cause 每进程恰好 warn 一次是两全。观测面不靠
+    // 日志靠 metrics(session_title_total outcome 族照常逐次记账)。cause=error 文案前缀归一(见常量注释);
+    // 集合挂在 titler 实例上,部署里每进程恰建一只 titler ⇒ 等价 per-process。
     const warnedCauses = new Set();
     const logFailure = (sessionId, error) => {
         const cause = error.slice(0, FAIL_CAUSE_KEY_CHARS);
@@ -39,7 +69,7 @@ export function createSessionTitler(deps) {
             if (!sessionId || !objective.trim())
                 return;
             if (seen.has(sessionId))
-                return;
+                return; // one attempt per session per process (resubmits/turns don't re-fire)
             if (seen.size >= SEEN_CAP) {
                 const oldest = seen.values().next().value;
                 if (oldest !== undefined)
@@ -47,12 +77,14 @@ export function createSessionTitler(deps) {
             }
             seen.add(sessionId);
             void (async () => {
-                let state = await deps.probeTitle(sessionId).catch(() => "untitled");
+                // pre-LLM probe: a point-read is orders cheaper than an LLM call (MED2 — restarts/evicted seen/other
+                // replicas must not re-pay), and it detects the register-lag "no row yet" window (MED3).
+                let state = await deps.probeTitle(sessionId).catch(() => "untitled"); // probe error ⇒ optimistic (IS NULL still guards)
                 if (state === "none") {
                     await new Promise((r) => setTimeout(r, NO_ROW_RETRY_MS));
                     state = await deps.probeTitle(sessionId).catch(() => "untitled");
                     if (state === "none") {
-                        seen.delete(sessionId);
+                        seen.delete(sessionId); // release: the NEXT submit on this session retries (no permanent miss)
                         deps.metrics?.inc("session_title_total", { outcome: "row_not_yet" });
                         return;
                     }
@@ -74,6 +106,8 @@ export function createSessionTitler(deps) {
                 }
                 const landed = await deps.setTitleIfNull(sessionId, title);
                 if (!landed) {
+                    // distinguish "another writer titled it" (fine) from "row STILL absent" (UPDATE-0 on a missing row —
+                    // release the seen slot so a later submit retries; never leave the session permanently untitled).
                     const after = await deps.probeTitle(sessionId).catch(() => "titled");
                     if (after === "none")
                         seen.delete(sessionId);
@@ -81,7 +115,7 @@ export function createSessionTitler(deps) {
                     return;
                 }
                 deps.metrics?.inc("session_title_total", { outcome: "set" });
-                deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length });
+                deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length }); // content stays OUT of logs (R10 posture) — it's user-derived data
             })().catch((e) => {
                 deps.metrics?.inc("session_title_total", { outcome: "error" });
                 logFailure(sessionId, String(e));

package/dist/session-watch.d.ts

@@ -1,28 +1,80 @@
+/**
+ * Session-watch registry — the server half of the session-level SSE subscription
+ * (design: sema-internal `server/docs/SESSION-SSE-DESIGN.md`, 黑板 [1164]①/[1196]).
+ *
+ * One entry per watched session; N subscribers SHARE one probe loop (this is the whole point:
+ * it converts web-side per-client polling into one per-replica probe). Two change channels:
+ *  - fast path: `notifyLocal(sessionId, leafId)` — an append that lands on THIS replica fans out
+ *    synchronously (zero latency on single-replica deployments, the common TOC/local shape);
+ *  - slow path: the probe loop reads leafId through the SAME storage face the /head probe uses.
+ *
+ * codex 复审(1.230 一轮)后的三条硬语义:
+ *  - **revision 守卫**:notifyLocal 每次推进 bump `rev`;探针起读前抓拍 rev,读回后 rev 变=结果作废
+ *    (陈旧慢读不得把 B 倒退回 A——latest-wins 的机制保证,不靠时序运气)。
+ *  - **replay-on-subscribe**:已有条目携带 `last` 时,新订阅者同步补发一帧(「join 与基线原子化」的
+ *    registry 半场;连接层再配 lastSent 去重,乱序/重复帧对下游不可见)。
+ *  - **冷启动 warm**:新条目 lastChangeAt=0(没观测到变化就不算热)——首拍一次 hotMs 快确认后即落
+ *    warm 拍距,直到真观测到跳变才进热窗(codex:重连风暴下 256 会话×200ms=对存储的自造尖峰)。
+ *
+ * Deliberately backend-agnostic (tidb|pg|local all go through getLeafId — the seamless-local-cloud
+ * invariant): no PG LISTEN/NOTIFY specialization, no shared bus. Latest-wins semantics: subscribers
+ * converge on the newest leafId; intermediate hops may be dropped (content still comes from tail faces).
+ */
+/** [1196] 二轮复审:SSE 资源旋钮的 env 解析——有界正整数,坏形(NaN/0/负/超界)一律回缺省并可观测
+ *  (坏 `SESSION_EVENTS_MAX_PROBES=foo` 若直进 Number() 会把帽谓词变恒假=无帽,拍距 NaN 进 setTimeout
+ *  =0ms 紧循环打爆存储)。 */
 export declare function posIntEnv(raw: string | undefined, fallback: number, max?: number): number;
 export interface SessionWatchOptions {
+    /** Probe interval while a change was OBSERVED within `hotWindowMs` (default 200ms). */
     hotMs?: number;
+    /** Probe interval otherwise (default 2000ms). */
     warmMs?: number;
+    /** How long after the last observed change the probe stays hot (default 60s). */
     hotWindowMs?: number;
+    /** Cap on concurrently-probed sessions per replica (default 512). Exceeding = subscribe refused. */
     maxWatchedSessions?: number;
 }
 export declare class SessionWatchRegistry {
+    /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
+     *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
+     *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
     private readonly getHead;
     private readonly entries;
     private readonly hotMs;
     private readonly warmMs;
     private readonly hotWindowMs;
     private readonly maxWatched;
-    constructor(getHead: (sessionId: string) => Promise<{
+    constructor(
+    /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
+     *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
+     *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
+    getHead: (sessionId: string) => Promise<{
         leafId: string | null | undefined;
         owner: string | null | undefined;
     }>, opts?: SessionWatchOptions);
+    /** Number of sessions currently probed (observability + the cap predicate). */
     watchedCount(): number;
+    /**
+     * Subscribe to head changes. Returns undefined when the per-replica probe cap is reached
+     * (caller answers 503 + Retry-After — the client falls back to /head polling).
+     * If the shared entry already knows a head (`last`), it is REPLAYED synchronously into
+     * `onHead` before returning — a subscriber joining an advanced entry can never miss the
+     * newest value (connection-level dedupe absorbs any overlap with the caller's own read).
+     */
     subscribe(sessionId: string, owner: string | null, onHead: (leafId: string | null) => void, onEnd?: () => void): (() => void) | undefined;
+    /** [1196] 三轮复审(租户轮转围栏,同副本半场):session 删除即终结条目——通知全部订阅者(onEnd,
+     *  路由据此断流)+ 停探针 + 弃缓存 head(新租户同键重订阅=全新世代,旧 replay 不可能渗入)。 */
     dropSession(sessionId: string): void;
+    /** S2 fast path: an append that landed on THIS replica. Safe to call for unwatched sessions (no-op).
+     *  `owner` 给了就 owner-限定(五轮复审):不符=条目属旧世代 ⇒ drop(断旧流),值不投——S2 接线时
+     *  append 落点必然知道 session owner,应当传。 */
     notifyLocal(sessionId: string, leafId: string | null, owner?: string | null, leafSeq?: number): void;
+    /** 立即压缩下一拍到 0ms(owner 疑云的权威核验)。探针自身 probing 串行 + 世代守卫照旧;urgent 旗
+     *  保证「疑云到达时已有读在飞(其快照摄于 reclaim 前=陈旧)」也必有一次**疑云后开始**的权威读。 */
     private probeNow;
     private arm;
     private probe;
+    /** 对**给定世代**应用一次推进(fan-out 恒按 rev 单调序)。 */
     private applyAdvance;
 }
 //# sourceMappingURL=session-watch.d.ts.map

package/dist/session-watch.js

@@ -1,3 +1,28 @@
+/**
+ * Session-watch registry — the server half of the session-level SSE subscription
+ * (design: sema-internal `server/docs/SESSION-SSE-DESIGN.md`, 黑板 [1164]①/[1196]).
+ *
+ * One entry per watched session; N subscribers SHARE one probe loop (this is the whole point:
+ * it converts web-side per-client polling into one per-replica probe). Two change channels:
+ *  - fast path: `notifyLocal(sessionId, leafId)` — an append that lands on THIS replica fans out
+ *    synchronously (zero latency on single-replica deployments, the common TOC/local shape);
+ *  - slow path: the probe loop reads leafId through the SAME storage face the /head probe uses.
+ *
+ * codex 复审(1.230 一轮)后的三条硬语义:
+ *  - **revision 守卫**:notifyLocal 每次推进 bump `rev`;探针起读前抓拍 rev,读回后 rev 变=结果作废
+ *    (陈旧慢读不得把 B 倒退回 A——latest-wins 的机制保证,不靠时序运气)。
+ *  - **replay-on-subscribe**:已有条目携带 `last` 时,新订阅者同步补发一帧(「join 与基线原子化」的
+ *    registry 半场;连接层再配 lastSent 去重,乱序/重复帧对下游不可见)。
+ *  - **冷启动 warm**:新条目 lastChangeAt=0(没观测到变化就不算热)——首拍一次 hotMs 快确认后即落
+ *    warm 拍距,直到真观测到跳变才进热窗(codex:重连风暴下 256 会话×200ms=对存储的自造尖峰)。
+ *
+ * Deliberately backend-agnostic (tidb|pg|local all go through getLeafId — the seamless-local-cloud
+ * invariant): no PG LISTEN/NOTIFY specialization, no shared bus. Latest-wins semantics: subscribers
+ * converge on the newest leafId; intermediate hops may be dropped (content still comes from tail faces).
+ */
+/** [1196] 二轮复审:SSE 资源旋钮的 env 解析——有界正整数,坏形(NaN/0/负/超界)一律回缺省并可观测
+ *  (坏 `SESSION_EVENTS_MAX_PROBES=foo` 若直进 Number() 会把帽谓词变恒假=无帽,拍距 NaN 进 setTimeout
+ *  =0ms 紧循环打爆存储)。 */
 export function posIntEnv(raw, fallback, max = 3_600_000) {
     if (raw === undefined || raw === "")
         return fallback;
@@ -11,19 +36,33 @@ export class SessionWatchRegistry {
     warmMs;
     hotWindowMs;
     maxWatched;
-    constructor(getHead, opts) {
+    constructor(
+    /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
+     *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
+     *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
+    getHead, opts) {
         this.getHead = getHead;
         this.hotMs = opts?.hotMs ?? 200;
         this.warmMs = opts?.warmMs ?? 2000;
         this.hotWindowMs = opts?.hotWindowMs ?? 60_000;
         this.maxWatched = opts?.maxWatchedSessions ?? 512;
     }
+    /** Number of sessions currently probed (observability + the cap predicate). */
     watchedCount() {
         return this.entries.size;
     }
+    /**
+     * Subscribe to head changes. Returns undefined when the per-replica probe cap is reached
+     * (caller answers 503 + Retry-After — the client falls back to /head polling).
+     * If the shared entry already knows a head (`last`), it is REPLAYED synchronously into
+     * `onHead` before returning — a subscriber joining an advanced entry can never miss the
+     * newest value (connection-level dedupe absorbs any overlap with the caller's own read).
+     */
     subscribe(sessionId, owner, onHead, onEnd) {
         let e = this.entries.get(sessionId);
         if (e && e.owner !== owner) {
+            // 四轮复审跨副本围栏:同键不同 owner=本副本条目属被删/被 reclaim 的旧世代——整体作废
+            // (旧订阅者 onEnd 断流),新 owner 拿全新条目,旧租户缓存 head 绝不 replay。
             this.dropSession(sessionId);
             e = undefined;
         }
@@ -32,7 +71,7 @@ export class SessionWatchRegistry {
                 return undefined;
             e = { subs: new Set(), ends: new Map(), owner, last: undefined, rev: 0, lastChangeAt: 0, probing: false };
             this.entries.set(sessionId, e);
-            this.arm(sessionId, e, this.hotMs);
+            this.arm(sessionId, e, this.hotMs); // one fast confirmation tick, then warm until a REAL change
         }
         e.subs.add(onHead);
         e.ends.set(onHead, onEnd);
@@ -41,21 +80,24 @@ export class SessionWatchRegistry {
                 onHead(e.last);
             }
             catch {
+                /* subscriber callback must not break subscribe */
             }
         }
         return () => {
             const cur = this.entries.get(sessionId);
             if (cur !== e)
-                return;
+                return; // entry already replaced/removed
             e.subs.delete(onHead);
             e.ends.delete(onHead);
             if (e.subs.size === 0) {
                 if (e.timer)
                     clearTimeout(e.timer);
-                this.entries.delete(sessionId);
+                this.entries.delete(sessionId); // cold: last subscriber gone → probe stops, entry dies
             }
         };
     }
+    /** [1196] 三轮复审(租户轮转围栏,同副本半场):session 删除即终结条目——通知全部订阅者(onEnd,
+     *  路由据此断流)+ 停探针 + 弃缓存 head(新租户同键重订阅=全新世代,旧 replay 不可能渗入)。 */
     dropSession(sessionId) {
         const e = this.entries.get(sessionId);
         if (!e)
@@ -68,17 +110,27 @@ export class SessionWatchRegistry {
                 end?.();
             }
             catch {
+                /* 单个订阅者收尾失败不挡其余 */
             }
         }
     }
+    /** S2 fast path: an append that landed on THIS replica. Safe to call for unwatched sessions (no-op).
+     *  `owner` 给了就 owner-限定(五轮复审):不符=条目属旧世代 ⇒ drop(断旧流),值不投——S2 接线时
+     *  append 落点必然知道 session owner,应当传。 */
     notifyLocal(sessionId, leafId, owner, leafSeq) {
         const e = this.entries.get(sessionId);
         if (!e)
             return;
         if (owner !== undefined && owner !== e.owner) {
+            // codex-4(S2 批):owner 不符的帧**绝不凭帧行刑**——leaf_seq 随行删建归零,跨世代序不可比:
+            // 迟到的旧租户高序帧会假装「新于」新租户的 seq 1(凭帧 drop=误杀新流);反向新租户低序真帧也
+            // 会被旧条目的高水位吞掉。裁决交给**立即权威探针**(owner 原子 getHead,本就是围栏权威):
+            // 真 reclaim=探针 dropSession(零等待,不再候 warm 拍),误报=条目安然。值不投。
             this.probeNow(sessionId, e);
             return;
         }
+        // codex-3:同 owner 内的乱序守卫——post-commit continuation 不保序,迟到低序=忽略不倒退。
+        // (同 owner 的 delete/recreate 归零序被高水位吞=良性新鲜度问题,探针自纠——条目头注既有口径。)
         if (leafSeq !== undefined && e.lastLocalSeq !== undefined && leafSeq <= e.lastLocalSeq)
             return;
         if (leafSeq !== undefined)
@@ -87,8 +139,12 @@ export class SessionWatchRegistry {
             return;
         this.applyAdvance(e, leafId);
     }
+    /** 立即压缩下一拍到 0ms(owner 疑云的权威核验)。探针自身 probing 串行 + 世代守卫照旧;urgent 旗
+     *  保证「疑云到达时已有读在飞(其快照摄于 reclaim 前=陈旧)」也必有一次**疑云后开始**的权威读。 */
     probeNow(sessionId, e) {
         e.urgent = true;
+        // codex-6:读在飞时**只置旗不排拍**——0ms 拍撞 probing 会跳读后又按旗补 0ms=事件环忙转直到慢读落定
+        // (存储降级时整副本被搅)。在飞读的拍尾独占排拍权,旗在那里兑现。
         if (e.probing)
             return;
         if (e.timer)
@@ -101,40 +157,47 @@ export class SessionWatchRegistry {
     }
     async probe(sessionId, e) {
         if (this.entries.get(sessionId) !== e)
-            return;
+            return; // entry died while the timer was pending
         if (e.probing)
-            return;
+            return; // 撞上在飞读:不读不排拍(其拍尾独占排拍权,urgent 旗在那兑现——codex-6)
         {
             e.probing = true;
-            e.urgent = false;
+            e.urgent = false; // 本读始于旗后=消费旗(读期间新疑云会重新置旗)
             const revAtStart = e.rev;
             try {
                 const head = await this.getHead(sessionId);
+                // 世代守卫(二轮复审):读期间末订阅者退出+重连=同键**新条目**——陈旧读绝不许经按键查找
+                // 渗入新世代;只对抓拍的旧条目本体应用(旧条目已无订阅者=自然无害)。
                 if (this.entries.get(sessionId) !== e)
                     return;
+                // 五轮复审跨副本围栏(探针拍级):session 被删(owner undefined)或被 reclaim(owner 变)
+                // ⇒ 条目作废+订阅者断流,leaf **不应用不 fan-out**——新租户的 leafId 绝不流向旧 owner 的流。
                 if (head.owner === undefined || head.owner !== e.owner) {
                     this.dropSession(sessionId);
                     return;
                 }
                 const leafId = head.leafId ?? null;
+                // revision 守卫:读期间 notifyLocal 推进过(rev 变)=本读陈旧,丢弃——绝不把新值倒退回旧值。
                 if (e.rev === revAtStart && leafId !== e.last)
                     this.applyAdvance(e, leafId);
             }
             catch {
+                /* transient storage error: keep probing — the SSE stream stays up */
             }
             finally {
                 e.probing = false;
             }
         }
         if (this.entries.get(sessionId) !== e)
-            return;
+            return; // last subscriber left during the read
         if (e.urgent) {
-            this.arm(sessionId, e, 0);
+            this.arm(sessionId, e, 0); // codex-5:in-flight 吞掉的急拍在拍尾补上——欠的权威读绝不滑到 warm 拍
             return;
         }
         const hot = e.lastChangeAt !== 0 && Date.now() - e.lastChangeAt < this.hotWindowMs;
         this.arm(sessionId, e, hot ? this.hotMs : this.warmMs);
     }
+    /** 对**给定世代**应用一次推进(fan-out 恒按 rev 单调序)。 */
     applyAdvance(e, leafId) {
         const wasKnown = e.last !== undefined;
         e.last = leafId;
@@ -146,6 +209,7 @@ export class SessionWatchRegistry {
                 fn(leafId);
             }
             catch {
+                /* one broken subscriber must not break the fan-out */
             }
         }
     }

package/dist/sighup-idle.d.ts

@@ -1,13 +1,43 @@
+/**
+ * B3(壳侧 [771]② 取证):SIGHUP 的 hup-pending 空闲窗。
+ *
+ * SIGHUP(壳窗口关闭打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,引擎按
+ * T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)且窗内
+ * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——`inflight()`(bg/resume
+ * legs + live streams)连续 idleGraceMs 为 0 才 shutdown,任何在飞 leg 重置窗口。真孤儿(最后一窗关掉)
+ * 有界自灭=T11 保留;第二个 SIGHUP 升级 escalate(既有 drain 路径,操作员硬梯子)。
+ *
+ * 诚实边界:idle-but-live 的 peer(两 turn 之间静默超过窗口)会碰到引擎已退→壳 dead-respawn 1-2s 自愈
+ * (伤害面从 mid-turn 斩降级为冷启动)。若壳侧确认每活会话对引擎持长连,可把连接数并入 inflight 判据。
+ */
 export interface SighupIdleDeps {
+    /** This replica's in-flight legs (drainState.inflight). */
     inflight: () => number;
+    /** MONOTONIC-clock ms of the last non-probe HTTP request (drainState.lastActivityAt). Covers what inflight
+     *  can't: admitted-but-not-yet-registered requests (auth/prepare/claim phases) and sub-tick short requests —
+     *  and keeps an idle-but-live peer (still listing/browsing) alive. Absent ⇒ inflight-only semantics.
+     *  ⚠️ 时基契约(三路复审修3,seam 对齐 D 组):lastActivityAt() 必须与本模块的 `now` 同为
+     *  performance.now() 单调域(server.ts 的 lastActivityAt 由 D 组切 performance.now())——混用 Date.now()
+     *  域会让 `now() - lastActivity` 差出 epoch 量级,活性判据恒真/恒假。 */
     lastActivityAt?: () => number;
+    /** True once another shutdown owner is active (closing || draining) — the watch stands down. */
     isStopped: () => boolean;
+    /** Second SIGHUP → the normal drain path. */
     escalate: () => void;
+    /** Idle window expired → hard shutdown. */
     shutdown: () => void;
     idleGraceMs: number;
     log: (event: string, fields: Record<string, unknown>) => void;
+    /** Watch poll period (test seam). Default 1s. */
     tickMs?: number;
+    /** 时钟 seam(三路复审修3):armedAt/idleSince/去抖判定全走它,缺省 `() => performance.now()`(单调)。
+     *  之前用 Date.now():NTP/手动前跳 > grace 会让 idle-elapsed 与 activity-quiet 两个检查同 tick 通过 →
+     *  过早关停 peer;后跳让窗口等墙钟追回才到期;回拨还可能把操作员真第二信号误判进 1s 去抖窗。
+     *  本文件不对外报告 epoch 时间戳,故 Date.now() 一律不再出现。 */
     now?: () => number;
 }
+/** Returns the SIGHUP handler. Call it on every SIGHUP; it arms the idle watch on the first signal and
+ *  escalates on the second. The interval is deliberately NOT unref'd — in the orphan case it IS the
+ *  shutdown driver (same posture as the drain tick). */
 export declare function createSighupIdleHandler(deps: SighupIdleDeps): () => void;
 //# sourceMappingURL=sighup-idle.d.ts.map

package/dist/sighup-idle.js

@@ -1,15 +1,24 @@
+/** Returns the SIGHUP handler. Call it on every SIGHUP; it arms the idle watch on the first signal and
+ *  escalates on the second. The interval is deliberately NOT unref'd — in the orphan case it IS the
+ *  shutdown driver (same posture as the drain tick). */
 export function createSighupIdleHandler(deps) {
     const tickMs = deps.tickMs ?? 1_000;
-    const now = deps.now ?? (() => performance.now());
+    const now = deps.now ?? (() => performance.now()); // 单调时钟(修3)——绝不用 Date.now()
     let watch;
     let idleSince = null;
     let armedAt = 0;
     return () => {
         if (deps.isStopped()) {
+            // A drain/shutdown owner is already active. Do NOT escalate: escalating during a graceful SIGTERM
+            // drain would hard-kill every in-flight leg because one terminal window closed — the exact harm B3
+            // exists to prevent. The operator's hard ladder stays SIGTERM×2 / SIGINT (复审 M5b).
             deps.log("sighup_ignored_shutdown_in_progress", {});
             return;
         }
         if (watch !== undefined) {
+            // Debounce (复审 M5a): a window close can deliver SIGHUP twice within milliseconds (kernel pty hangup
+            // + shell forwarding) — treating the echo as the operator's deliberate second signal would flip
+            // draining and 503 the peers B3 protects. A human double-press is comfortably > 1s.
             if (now() - armedAt < 1_000) {
                 deps.log("sighup_duplicate_ignored", {});
                 return;
@@ -39,6 +48,8 @@ export function createSighupIdleHandler(deps) {
                 idleSince = now();
                 return;
             }
+            // Activity clock: a request between ticks (or one still in its pre-registration phase) resets the
+            // window even though inflight sampled 0 — both clocks must be quiet for a full grace period.
             const lastActivity = deps.lastActivityAt?.() ?? 0;
             if (now() - lastActivity < deps.idleGraceMs)
                 return;

package/dist/spec-fields.d.ts

@@ -1,23 +1,102 @@
+/**
+ * Request-body → TaskSpec field normalizers (shell-host contract). Kept out of main.ts (which auto-runs the service
+ * on import) so they are unit-testable in isolation. Each is DEFENSIVE: a RESUME re-runs resolveSpec from the stored
+ * body WITHOUT the HTTP-layer 400 validation, so a malformed value must fall back to a safe default, never throw.
+ */
 import { type AgentDefinition, type TaskSpec } from "@sema-agent/core";
+/**
+ * E12 — normalize `body.suggestNextPrompts` → `TaskSpec.suggestNextPrompts`. `true` = on with core defaults
+ * (count 3, cheap role); an object tunes `count` (clamped 1..10) / `role` (a free string — core validates it against
+ * `ModelRole`, an unknown role falls back to the task model). `false` / absent / non-object / garbage ⇒ undefined (off).
+ */
 export declare function normalizeSuggestNextPrompts(v: unknown): TaskSpec["suggestNextPrompts"];
+/**
+ * design/131 (core 1.246) — normalize `body.resilience` → `TaskSpec.resilience`. INTENT flags only:
+ * `allowDegrade:false` / `allowFailover:false` let a bench/eval or critical task say "fail rather than fall back".
+ * `bypassBreaker` is OPERATOR-FACING (不给 wire 用户直开 — it punches through a shared circuit breaker,
+ * which exists to protect the provider): honored only when the request principal is an explicit operator; silently
+ * dropped otherwise (not a 4xx — resume re-runs this without HTTP validation, and a stripped intent flag degrades
+ * to today's behavior, core's own "all absent = byte-compat" posture). Only literal booleans pass; all-empty ⇒
+ * undefined (never an empty object — keeps the spec byte-identical for non-users).
+ */
 export declare function normalizeResilience(v: unknown, operator: boolean): TaskSpec["resilience"];
+/**
+ * design/133 (core 1.251) — normalize `body.attachments` → `TaskSpec.attachments`. Core's contract is
+ * literal-true unions ("关闭=删 key,勿传 false"): only `true` (or, for changedFiles, an object with a sane
+ * `maxFiles`) survives; `false`/garbage per key is DROPPED, not forwarded. maxFiles clamped 1..100 (core caps its
+ * own stat cost at 20 by default; the clamp only guards against a resume replaying a wild persisted value).
+ * All-empty ⇒ undefined. NB resume audit: our persisted body is the FULL request JSON and resolveSpec
+ * is the single translation point, so consuming the field here IS the whitelist inclusion — nothing else to add.
+ */
 export declare function normalizeAttachments(v: unknown): TaskSpec["attachments"];
+/**
+ * [833] rewind exclusive mode (core 1.292) — normalize `body.resumeAtMode` → `TaskSpec.resumeAtMode`. DEFENSIVE
+ * (the resume path re-runs resolveSpec WITHOUT the HTTP 400 gate): only the two enum values survive, and only when
+ * the resume-at handle actually RESOLVED (core ignores the field without `resumeAt`; keep the spec tight instead of
+ * shipping a dangling qualifier). Absent/garbage ⇒ undefined = core default "at" (zero regression).
+ */
 export declare function normalizeResumeAtMode(v: unknown, resumeAtResolved: boolean): "at" | "before" | undefined;
+/** [876] 防御上限:一份请求最多带多少个 agent 定义。core 侧无上限;这里封一个防御值 —— 每个定义都进
+ *  系统提示(whenToUse/skills/systemPrompt 全是 prompt 载荷),不设界就是 per-turn token 成本洞(与
+ *  MAX_USER_SKILLS 同轴)。32 足够覆盖 CC 式 `.claude/agents/` 全家桶还有余量。 */
 export declare const MAX_TASK_AGENTS = 32;
+/** [876] 单条 agent 定义的形状裁决:null=合法;否则一句可 400 的英文错误(不带索引,调用方自己加)。
+ *  白名单外键 fail-loud —— 与 resilience/limits 的「容忍未知键」相反:agents 是能力定义,静默丢字段 =
+ *  定义被悄悄削(一个丢掉的 isolation 就是放宽),比 400 更危险,故整条拒。⚠️ 已知残账(core 半场):
+ *  core 只对 allowTools 未知项 fail-loud,denyTools 未知项(如 typo)静默失效 —— 已上板请 core 镜像。
+ *  ⚠️ 键判断必须 Object.hasOwn:`in` 走原型链,JSON 里的 "toString"/"constructor"/"__proto__" 键会被
+ *  误判为白名单字段,随后 SHAPES[k].ok 不是函数 ⇒ TypeError(fresh 500 / resume 砖;cross-review 复现)。 */
 export declare function taskAgentIssue(item: unknown): string | null;
+/** [876] HTTP 门(fresh submit,server.ts prepareSpec):body.agents 在场必须是非空数组、每条过
+ *  {@link taskAgentIssue}、name 数组内唯一、条数 ≤ {@link MAX_TASK_AGENTS}。返回 400 错误串或 null。
+ *  RESUME 重放不过这道门 —— {@link taskAgentsFromBody} defensive(按条 DROP+warn,不砖 resume)。 */
 export declare function validateTaskAgents(v: unknown): string | null;
+/** [876] body.agents → `TaskSpec.agents`(resolveSpec 的唯一装配点;main.ts 只 spread)。两层门:
+ *   - 🔒 TOB 租户门:多租户(requirePrincipal===true)暂不放行 —— [876] 原文「TOB 面按租户 caps 门」,
+ *     当前没有 per-tenant caps 面可挂,先 fail-closed 关多租(warn `task_agents_ignored`,capabilities
+ *     的 `taskAgents` 同步 advertise false);单机/单用户直通(caller 是自己 worker 的 super-admin,
+ *     与 mcpInjection/hooks 同一姿势)。
+ *   - defensive 归一化(RESUME 重放持久化 body 不过 HTTP 400 门):非法项按条 DROP + warn
+ *     `task_agent_dropped`(绝不 throw 砖 resume);重名后到者 DROP;超上限截断。幸存字段按白名单拷贝
+ *     (不透传未知键 —— 非法项已整条 drop,这里只是让持久化 body 的杂键不上 spec)。全空 ⇒ undefined。 */
 export declare function taskAgentsFromBody(raw: unknown, requirePrincipal: boolean | undefined, warn: (event: string, fields: Record<string, unknown>) => void): AgentDefinition[] | undefined;
+/** [876] main.ts resolveSpec 的 agents 装配片段(可 import 真 fold,[1.211 codex L]:此前 main.ts 用内联
+ *  闭包,测试只能 SOURCE PIN 文本+重写同构表达式——文本锚可被「移出 resolveSpec 但保留同文」静默骗过;
+ *  现在行为测试直接调这个真出口,main.ts 只剩一次调用点可锚)。语义=taskAgentsFromBody 的条件 spread:
+ *  有幸存 agents 才挂键(absent/全 drop ⇒ 空对象,spec byte-compat)。 */
 export declare function taskAgentsSpecFragment(raw: unknown, requirePrincipal: boolean | undefined, warn: (event: string, fields: Record<string, unknown>) => void): {
     agents?: AgentDefinition[];
 };
+/** [854]② — body.retainBackgroundProcesses → `TaskSpec.retainBackgroundProcesses`。core 语义(1.295
+ *  runtask/task-registry dist 亲读):`=== true` 时任务收尾不主动收割 session 后台进程 —— host lane 上是
+ *  资源驻留授予,与 backgroundShell 同款单用户闸:多租户 warn 忽略(`task_retain_bg_ignored`,capability
+ *  同步 advertise false)。只 literal `true` 上 spec(false=core 缺省,不挂键保持 byte-compat);非 boolean
+ *  由 HTTP 门 400,resume 重放这里 defensive DROP(不 throw)。 */
 export declare function retainBackgroundProcessesFromBody(raw: unknown, requirePrincipal: boolean | undefined, warn: (event: string, fields: Record<string, unknown>) => void): true | undefined;
+/** [1052]② — body.{excludeTools,deferTools} → `TaskSpec.{excludeTools,deferTools}`(core 1.314 工具面
+ *  控制批)。语义:excludeTools=roster 真卸载(schema 字节不上 wire,manifest 如实收窄);deferTools=
+ *  design/36 延迟披露(占位上 wire,ToolSearch 激活 materialize)。两位 tighten-only(core 继承不变量:
+ *  union 进全部子 spawn 路径),per-run 工具面收窄无跨租户面 ⇒ 无租户门(interactiveTools 同姿势)。
+ *  DEFENSIVE(resume 重放不过 HTTP 400 门):非数组 ⇒ undefined;项非非空字符串 ⇒ 逐项 DROP;空数组 ⇒
+ *  undefined(不挂键=core 缺省,byte-compat)。HTTP 门另有 fail-loud 400(提交面邻居姿势)。 */
 export declare function toolNameListFromBody(raw: unknown): string[] | undefined;
+/** [1144]/[1146] — body.promptProfile → `TaskSpec.promptProfile`(core 1.328 R2 主件,CC LT(model_id)
+ *  同构双形轴)。语义:纯呈现轴不碰策略(simple=CC 212 短形面缺省;classic=长形面,可按任务/模型试分)
+ *  ⇒ 无租户门(deferTools 同姿势);全委托树继承由 core 管。缺省不挂键(引擎缺省 simple,byte-compat)。
+ *  DEFENSIVE(resume 重放不过 HTTP 400 门):非法值 ⇒ undefined;提交面另有 fail-loud 400(邻居姿势)。 */
 export declare function promptProfileFromBody(raw: unknown): "simple" | "classic" | undefined;
+/** [854]④ — 每键的运营方上限旋钮(env,缺省不设=不封顶)。 */
 export interface TaskLimitCaps {
-    timeoutSec?: number;
-    maxOutputTokens?: number;
-    maxTurns?: number;
+    /** TASK_TIMEOUT_MAX_SEC */ timeoutSec?: number;
+    /** TASK_MAX_OUTPUT_TOKENS_MAX */ maxOutputTokens?: number;
+    /** TASK_MAX_TURNS_MAX */ maxTurns?: number;
 }
+/**
+ * [854]④ — normalize `body.limits` → 请求方配速意图 {timeoutSec?, maxOutputTokens?, maxTurns?}。DEFENSIVE
+ * (resume 重放持久化 body 不过 HTTP 400 门):仅正的有限数字存活(floor 取整),0/负/垃圾按键 DROP —— core 侧
+ * `timeoutSec > 0` 才生效(0=不设墙,会绕过运营方封顶)、maxTurns/maxOutputTokens 的 0 无意义。每键各自被
+ * 运营方上限旋钮 clamp(Math.min;旋钮缺省不设=不封顶)。全空 ⇒ undefined。
+ */
 export declare function normalizeLimits(v: unknown, caps: TaskLimitCaps): {
     timeoutSec?: number;
     maxOutputTokens?: number;
@@ -26,5 +105,14 @@ export declare function normalizeLimits(v: unknown, caps: TaskLimitCaps): {
     callCapByDeadline?: false;
     gracefulFinalize?: false;
 } | undefined;
+/**
+ * [854]④ — body.limits 与 env 墙钟的合成规则(resolveSpec 的唯一 limits 装配点;run-local 无 body 车道不经此):
+ *  - `timeoutSec`:body 给了就用 body(caller 明确配速;已在 normalizeLimits 里被 TASK_TIMEOUT_MAX_SEC 封顶)。
+ *    body 缺席保持既有姿势 = tenancy 墙钟 + env `TASK_TIMEOUT_SEC` 只抬不降(taskWallClockSec 内 Math.max,
+ *    误配低值不能砍 council 预算)。注意两条纪律不叠加:「只抬不降」是 env 对内建缺省墙的规则,body 是
+ *    caller 的显式意图,直接生效(可低于 env 墙 —— 交互短任务要更紧的配速正是本件诉求)。
+ *  - `maxOutputTokens` / `maxTurns`:直透传(各自可选 env 上限已 clamp)。
+ * 全空 ⇒ undefined(spec 不挂 limits 键,byte-compat)。
+ */
 export declare function resolveTaskLimits(bodyLimits: unknown, caps: TaskLimitCaps, envTimeoutSec: number, requirePrincipal: boolean | undefined, big: boolean): TaskSpec["limits"];
 //# sourceMappingURL=spec-fields.d.ts.map