@sema-agent/server 7.101.0 → 7.102.0

package/dist/http/readiness.d.ts

@@ -0,0 +1,87 @@
+/**
+ * S-739 / S-740(车OE,7.102.0):**就绪判的唯一属主** —— 一只谓词 {@link readinessOf},全部读点经它:
+ *
+ *  ① `GET /readyz`(`dispatch.ts`,凭据门之前,与 `/health` 同位):200 `{ready:true}` / 503 `{ready:false, reasons}` ——
+ *     给**摘流**语义的探针(k8s readinessProbe / LB 健康检查);**重启**语义的探针(Docker HEALTHCHECK、k8s livenessProbe)
+ *     留在 `/health`:中心宕机时整队副本同卡 roster 未落,指 `/readyz` 就会一起重启打转(对抗复审 #6);
+ *  ② `GET /health` 的 `ready` / `readyReason` / `reasons` 三键({@link healthReadinessKeys});
+ *  ③ 计费提交门的 503(`dispatch.ts` 的 billable 门、`routes/a2a-serve.ts` 的 `message/send`、
+ *     `approval-sweeps.ts` 的 PARKED 赎回席 —— 三处同调 {@link billableRefusalOf},拒绝体只此一处铸);
+ *  ④ fleet 心跳 `InstanceAnnouncement.ready` / `draining`(`fleet-client.ts`;装配层接
+ *     `readinessOf(deployment)` —— 与 HTTP 面读的是同一个 deps 组)。
+ *
+ * 修前是四份手抄:`/health` 读 `modelReady`、计费门两道各读一只、a2a 与赎回席各抄一遍,心跳读
+ * `!isDraining()`(不含 roster)⇒ roster 未落时心跳说「就绪」而计费提交在 503,中心按心跳把它当可路由。
+ *
+ * **reasons 闭集 = `draining | model_roster_pending`,刻意不含 storeLive**(web-admin [ref] 要、[ref] 裁):
+ * DB 抖动是**共模**失效 —— 一次库抖若进就绪门,整队副本会在同一拍被 k8s / LB 摘出路由,比「打到一台库连不上
+ * 的副本」更坏。`storeLive:false` 留在 `/health` 体位 + 既有告警键,摘不摘流由读体的编排器裁(披露不代裁)。
+ * 加一个 reason = 改 {@link READINESS_REASONS} ⇒ 下面两只按 reason 穷举的表(`READY_REASON_PHRASE` 的
+ * 映射型 / `billableRefusalOf` 的 switch)当场编译红,逼你给出它的 `/health` 句与计费门拒绝体。
+ *
+ * 模块形:纯叶(只值 import `send.ts`)—— `fleet-client.ts` / `boot/` 都会读它,不许长出回环。
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * 就绪原因闭集,**数组序 = 优先序**:`/health.readyReason` 取首条的句、计费门取首条的拒绝码。
+ * draining 在前 —— 一台正在下线的副本「去找替补」(Retry-After 15)比「稍后重试本机」(5)更对。
+ */
+export declare const READINESS_REASONS: readonly ["draining", "model_roster_pending"];
+export type ReadinessReason = (typeof READINESS_REASONS)[number];
+/** 就绪判。未就绪时 `reasons` 非空(类型上就是非空元组 —— 空数组的未就绪判构造不出来)、按
+ *  {@link READINESS_REASONS} 序、无重复。 */
+export type ReadinessVerdict = {
+    readonly ready: true;
+} | {
+    readonly ready: false;
+    readonly reasons: readonly [ReadinessReason, ...ReadinessReason[]];
+};
+export type NotReadyVerdict = Extract<ReadinessVerdict, {
+    ready: false;
+}>;
+/**
+ * 谓词的输入 —— `ServiceDeps` 上的同名两键(`modelReady` / `drainState`),HTTP 面与心跳读的是**同一个对象**。
+ * 两键缺席 = 该输入恒就绪(纯 env 部署没有 roster 可等;嵌入宿主 / 测试夹具没有 drain 面)。
+ */
+export interface ReadinessInputs {
+    /** boot ready 门(b):false = 布防且 roster 未落(`CONFIG_REQUIRE_ROSTER=true`)。 */
+    readonly modelReady?: () => boolean;
+    /** 收尾链翻转的共享 drain 态。 */
+    readonly drainState?: {
+        readonly draining: boolean;
+    };
+}
+/** **唯一**的就绪谓词(活判,每次调用现读输入 —— 不是快照)。 */
+export declare function readinessOf(deps: ReadinessInputs): ReadinessVerdict;
+/**
+ * `/health` 的就绪三键(additive:就绪 ⇒ 空对象,`/health` 正常形状逐字不变)。
+ * `reasons` = 与 `/readyz` 逐字同一份闭集词;`readyReason` = 首条的人读句(旧消费端读的就是它)。
+ */
+export declare function healthReadinessKeys(v: ReadinessVerdict): Record<string, unknown>;
+/** `/readyz` 两形:200 `{ready:true}` / 503 `{ready:false, reasons}` + `Retry-After: 5`。体只这两键(不带身份字段:
+ *  就绪探针给 k8s readinessProbe / Traefik / LB 摘流用,不是 `/health` 的替身;`drainReason` 等运维自由文本也不上这一面)。 */
+export declare function sendReadyz(res: ServerResponse, v: ReadinessVerdict): void;
+/** 计费提交门的拒绝(首条 reason 定码)。`retryAfterSec` 由发送形(`sendBillableRefusal`)镜像成头;交回
+ *  `{status, body}` 的赎回席只取体(它的路由刻意不带头,见 `approval-sweeps.ts` 该臂注)。 */
+export interface BillableRefusal {
+    readonly status: 503;
+    readonly body: {
+        readonly error: string;
+        readonly errorCode: string;
+        readonly message: string;
+        readonly reason?: string;
+    };
+    readonly retryAfterSec: 15 | 5;
+}
+/**
+ * 计费提交门的拒绝体 —— **唯一铸点**(`error` 字面 `"draining"` / `"model_roster_pending"` 与 `message` 是冻结的
+ * wire 契约:SDK / 壳的 pre-stream 重试按它们判型;冻结在 `test/api-error-text-freeze.test.ts` 的
+ * `FROZEN_RESULT_BODY` 与 `test/api-notice-text-freeze.test.ts` §2)。`drainReason` = `POST /v1/admin/drain`
+ * 声明的停机因由([ref],additive 键 `reason`;未声明 = 键缺席)。
+ */
+export declare function billableRefusalOf(v: NotReadyVerdict, drainReason: string | undefined): BillableRefusal;
+/** 发送形:`Retry-After` + 体(`dispatch.ts` 的 billable 门与 a2a `message/send` 同调)。走 `sendError` —— errorCode
+ *  是它的必填位置参(对抗复审 #3:修前这里是 `sendJson(res, r.status, r.body)`,与 leader 口的豁免行逐字同文,
+ *  在 error-code-key-gate 上借了别人的豁免过门);体键序与修前逐字同(`error, errorCode, message, reason?`)。 */
+export declare function sendBillableRefusal(res: ServerResponse, refusal: BillableRefusal): void;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/http/readiness.js

@@ -0,0 +1,54 @@
+import { sendJson, sendError } from "./send.js";
+export const READINESS_REASONS = ["draining", "model_roster_pending"];
+export function readinessOf(deps) {
+    const [first, ...rest] = READINESS_REASONS.filter((r) => holds(r, deps));
+    return first === undefined ? { ready: true } : { ready: false, reasons: [first, ...rest] };
+}
+function holds(reason, deps) {
+    switch (reason) {
+        case "draining":
+            return deps.drainState?.draining === true;
+        case "model_roster_pending":
+            return deps.modelReady !== undefined && !deps.modelReady();
+        default: {
+            const unhandled = reason;
+            throw new Error(`readiness reason without a predicate arm: ${String(unhandled)}`);
+        }
+    }
+}
+const READY_REASON_PHRASE = {
+    draining: "draining for shutdown or upgrade",
+    model_roster_pending: "model roster pending (first effective-config pull)",
+};
+export function healthReadinessKeys(v) {
+    if (v.ready)
+        return {};
+    return { ready: false, readyReason: READY_REASON_PHRASE[v.reasons[0]], reasons: [...v.reasons] };
+}
+export function sendReadyz(res, v) {
+    if (v.ready) {
+        sendJson(res, 200, { ready: true });
+        return;
+    }
+    res.setHeader("retry-after", "5");
+    sendJson(res, 503, { ready: false, reasons: [...v.reasons] });
+}
+export function billableRefusalOf(v, drainReason) {
+    const primary = v.reasons[0];
+    switch (primary) {
+        case "draining":
+            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance", ...(drainReason ? { reason: drainReason } : {}) }, retryAfterSec: 15 };
+        case "model_roster_pending":
+            return { status: 503, body: { error: "model_roster_pending", errorCode: "state.model_roster_pending", message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" }, retryAfterSec: 5 };
+        default: {
+            const unhandled = primary;
+            throw new Error(`readiness reason without a billable refusal: ${String(unhandled)}`);
+        }
+    }
+}
+export function sendBillableRefusal(res, refusal) {
+    const { error, errorCode, ...extra } = refusal.body;
+    res.setHeader("retry-after", String(refusal.retryAfterSec));
+    sendError(res, refusal.status, errorCode, error, extra);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/http/resume-legs.js

@@ -236,10 +236,10 @@ export function createResumeLegs(ctx) {
         const ownerLeaseAdmittedHere = req !== undefined;
         if (req !== undefined) {
             const parkedAgentStore = deps.backgroundAgentStore;
-            const parkedTool = deps.parkedReviveTool;
+            const parkedSurface = deps.parkedReviveSurface;
             const parkWarn = (event, fields) => deps.logger?.warn?.(event, fields);
             const origin = await findParkOrigin({
-                ...(parkedAgentStore !== undefined && parkedTool !== undefined ? { agentStore: parkedAgentStore } : {}),
+                ...(parkedAgentStore !== undefined && parkedSurface !== undefined ? { agentStore: parkedAgentStore } : {}),
                 ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
                     ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
                     : {}),
@@ -252,12 +252,13 @@ export function createResumeLegs(ctx) {
                 ...(answer !== undefined ? { answer } : {}),
                 ...(boundGrant ? { grantRemember: (rootSessionId) => boundGrant(rootSessionId) } : {}),
             };
-            if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedTool !== undefined) {
+            if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedSurface !== undefined) {
                 const parked = await withPrincipal(decodeCheckpointScope(cp.scope), () => decideParkedAgent({
                     agentStore: parkedAgentStore,
                     checkpointStore: cs,
                     registry: defaultTaskRegistry,
-                    reviveTool: parkedTool,
+                    reviveSurface: parkedSurface,
+                    ...(deps.sessionStorage?.ownerOf ? { sessionOwnerOf: deps.sessionStorage.ownerOf.bind(deps.sessionStorage) } : {}),
                     ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
                     ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
                     ...(deps.logger ? { warn: parkWarn } : {}),

package/dist/http/route-table.d.ts

@@ -83,6 +83,13 @@ export declare const ROUTES: readonly RouteRow[];
  *  「门前行不许出现在门后行之后」由 `test/route-order-freeze.test.ts` 钉住。 */
 export declare const PRE_CREDENTIAL_ROUTES: readonly RouteRow[];
 export declare const POST_CREDENTIAL_ROUTES: readonly RouteRow[];
+/**
+ * **探针路径**(k8s / 编排器 / 抓取器的常态高频采样):不计 admission inflight、不推活性时钟(`http/server.ts`
+ * 的 `noteActivity`)、不入附着租约集 —— 常态采样噪音不许把 SIGHUP 空闲窗 / 引擎租约的「无人使用」判据永远撑开。
+ * 两处消费(`dispatch.ts` 的 admission 门、`server.ts` 的活性时钟)读这一只;S-739 前是两份手抄
+ * (`url === "/health" || url.startsWith("/metrics")`),加 `/readyz` 时漏一份 = k8s 每 5-10s 一探就让副本永不空闲。
+ */
+export declare function isProbePath(url: string): boolean;
 /**
  * 全表 = 流水线四行 + **每一行 `ROUTES` 自己的 `decls`**,按行序摊平。
  *

package/dist/http/route-table.js

@@ -29,6 +29,7 @@ import { handleApprovalsAssistant, APPROVALS_ASSISTANT_ROUTES } from "./routes/a
 import { handleRuns, handleRunVerbs, RUNS_ROUTES, RUN_VERBS_ROUTES } from "./routes/runs.js";
 import { handleRunMemoryCapture, RUN_MEMORY_CAPTURE_ROUTES } from "./routes/run-memory-capture.js";
 import { handleMcpReconnect, MCP_RECONNECT_ROUTES } from "./routes/mcp-reconnect.js";
+import { handleBackground, BACKGROUND_ROUTES } from "./routes/background.js";
 import { handleSideQuery, SIDE_QUERY_ROUTES } from "./routes/side-query.js";
 import { handleTasks, TASKS_ROUTES } from "./routes/tasks.js";
 import { handleLeader, LEADER_ROUTES } from "./routes/leader.js";
@@ -50,6 +51,7 @@ export const ROUTES = [
     row({ handler: handleRunVerbs, decls: RUN_VERBS_ROUTES, position: "post-credential", label: "run-verbs" }),
     row({ handler: handleRunMemoryCapture, decls: RUN_MEMORY_CAPTURE_ROUTES, position: "post-credential", label: "run-memory-capture" }),
     row({ handler: handleMcpReconnect, decls: MCP_RECONNECT_ROUTES, position: "post-credential", label: "mcp-reconnect" }),
+    row({ handler: handleBackground, decls: BACKGROUND_ROUTES, position: "post-credential", label: "background" }),
     row({ handler: handleLeader, decls: LEADER_ROUTES, position: "post-credential", label: "leader", enabled: (deps) => Boolean(deps.leaderEndpoint) }),
     row({ handler: handleImages, decls: IMAGES_ROUTES, position: "post-credential", label: "images" }),
     row({ handler: handleApprovalsAssistant, decls: APPROVALS_ASSISTANT_ROUTES, position: "post-credential", label: "approvals-assistant", enabled: (deps) => Boolean(deps.checkpointStore) }),
@@ -80,10 +82,14 @@ export const PRE_CREDENTIAL_ROUTES = ROUTES.filter((r) => r.position === "pre-cr
 export const POST_CREDENTIAL_ROUTES = ROUTES.filter((r) => r.position === "post-credential");
 const PIPELINE_ROUTES = [
     { id: "health", path: "/health", methods: ["GET"] },
+    { id: "readyz", path: "/readyz", methods: ["GET"] },
     { id: "metrics", path: "/metrics", methods: ["GET"] },
     { id: "metrics-summary", path: "/metrics/summary", methods: ["GET"] },
     { id: "metrics-plan-cache", path: "/metrics/plan-cache", methods: ["GET"] },
 ];
+export function isProbePath(url) {
+    return url === "/health" || url === "/readyz" || url.startsWith("/metrics");
+}
 export const ROUTE_DECLARATIONS = [...PIPELINE_ROUTES, ...ROUTES.flatMap((r) => r.decls)];
 function declMatches(d, url) {
     if ("path" in d)

package/dist/http/routes/a2a-serve.js

@@ -6,6 +6,7 @@ import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-cont
 import { HttpError } from "../../security.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError } from "../send.js";
+import { readinessOf, billableRefusalOf, sendBillableRefusal } from "../readiness.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import { createDurableRun } from "./runs.js";
@@ -169,20 +170,11 @@ function rpcErrorFromTypedFailure(err, skillId) {
 }
 function submitUnavailable(res, ctx) {
     const { deps } = ctx;
-    if (deps.drainState?.draining) {
-        res.setHeader("retry-after", "15");
-        sendError(res, 503, "draining", "draining", {
-            message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
-            ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
-        });
-        return true;
-    }
-    if (deps.modelReady && !deps.modelReady()) {
-        res.setHeader("retry-after", "5");
-        sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
-        return true;
-    }
-    return false;
+    const verdict = readinessOf(deps);
+    if (verdict.ready)
+        return false;
+    sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+    return true;
 }
 function readBlocking(params) {
     if (params.configuration === undefined)

package/dist/http/routes/approvals-assistant.js

@@ -289,6 +289,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     ...(s.hasBidiControls === true ? { hasBidiControls: true } : {}),
                     ...(s.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     ...(s.mandated === true ? { mandated: true } : {}),
+                    ...(s.mandate !== undefined ? { mandate: s.mandate } : {}),
                     ...(s.denialLimitFallback !== undefined ? { denialLimitFallback: s.denialLimitFallback } : {}),
                     ...(s.origin !== undefined ? { origin: s.origin } : {}),
                     ...(s.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: s.ruleStoreUnreadable } : {}),

package/dist/http/routes/background.d.ts

@@ -0,0 +1,80 @@
+/**
+ * S-745(core 7.32.0 #1107 的 server 半场;wire 形 [ref] / [ref] / [ref] 定)—— **会话后台任务的两只读口**:
+ *
+ *   `GET  /v1/sessions/:id/background`        → 200 `{ rows: [{ id, description?, type, status, createdAt, sessionScoped, retained? }] }`
+ *   `POST /v1/sessions/:id/background/stop`   body `{ includeRetained: boolean }` → 200 `{ receipts: [{ id, outcome }] }`
+ *
+ * 消费方:cli L-694 ①(删前核登记)/ L-686(退出三选一:「Exit and stop tasks」= `includeRetained:true`,`sema kill` =
+ * `includeRetained:false`,两臂都等受据再退)/ client-core CC-194 B 半(对账谓词)。老 server 404 ⇒ 壳只出 Stay / 退出两臂。
+ *
+ * ── 读口:逐字投 core `list()` 行 ─────────────────────────────────────────────────────────────────
+ * 读的是**进程内**注册表(`defaultTaskRegistry.list`),访问元组 = 会话自己的 `{ owner: sid, sessionId: sid, scope }`
+ * (scope = 会话行属主 `owner ?? "default"`,与 core 注册铸值同源)⇒ 可见集完全由 core 的 `canAccess` 判(fail-closed:
+ * 缺轴即拒;本会话的会话驻留行、task id 即会话 id 的 run 行、本会话发起的 workflow、根会话是本会话的后台 agent)。
+ * 键逐个处置(下面的 {@link ROW_KEY_DISPOSITION},core 给行加键 ⇒ 编译红):`task_id` 改名 `id`;`retained` **真才带**
+ * (core:缺席 ⇒ 这一行在 `includeRetained:false` 的硬面上会停);`description` 是模型写的描述、缺席时是启动时的命令文本 ——
+ * 内容族 ⇒ `redactSecrets` + 截 {@link DESCRIPTION_MAX}(显示串;core 不另存原始命令)。多副本部署:只列**本副本**上的行。
+ *
+ * ── 停止口:会话级收敛同一只函数 ────────────────────────────────────────────────────────────────
+ * `reapSessionBackgroundHard`(`background-session-reap.ts`,与 `DELETE /v1/sessions/:id` 同一只):软面(会话的后台 agent /
+ * workflow 一并结算;`includeRetained:true` 时 retain 行也先收到 SIGTERM)→ 等一次 `HOST_BG_KILL_GRACE_MS` → 硬面(车OL O1 / O2);
+ * `includeRetained` **没有缺省**(core 同一条:调用方说明这是哪一种停),缺席 / 非布尔 ⇒ 400。
+ * 受据只含 shell 行(`background_bash` / `monitor`),`outcome` 四词逐字透传:`killed` / `already_gone` / `retained_skipped` /
+ * `no_pgid`(= 没有同步硬收落地、已派普通 kill,「可能还在跑」—— 远端 / 沙箱车道的常态,不是失败)。受据在 200 之前已齐(`await`
+ * 收敛函数;有后台行时应答慢一次宽限)。
+ *
+ * ── 鉴权与门 ────────────────────────────────────────────────────────────────────────────────────
+ * 与 `POST /v1/sessions/:id/mcp/reconnect` 同一套:会话属主面缺席 ⇒ 501;未知会话与他人会话**同码同串** 404(无存在性
+ * oracle);显式 operator 可读可停任何会话(监督动作)。零模型工作 ⇒ 不进 billable、不吃 drain 503;停止口是 mutating ⇒
+ * `rateLimited`。能力位 `background: { listFace, exitFaces }` 与两口的 501 从同一个谓词推导(会话属主面在场)。
+ *
+ * 🔴 **停止口在无凭据写门内**(`credentialGated: ["POST"]`;车OL F1 = 7.102.0 合并复审 gpt-6 腿 [high]):门的两个合取项它都中
+ *   —— ① 授权的唯一输入是 principal 头(属主判 `runOwnerOk` 与 operator 臂 `explicitOperatorOk` 读的都是 `gatedPrincipal`,
+ *   无 service 凭证的部署上它收调用方自报的头);② 不可撤销、爆炸半径跨租户(知道会话 id + 自报它的属主 ⇒ 停掉那个会话的后台
+ *   进程,`includeRetained:true` 连显式 retain 的活服务一起停)。于是无 service 凭证且未开 `ALLOW_UNAUTHED_WRITES` 的部署上它与
+ *   其余改写门同码同句 503 `auth.service_token_required`(在路由之前,`dispatch.ts` 那一道),同一只会话级收敛函数的另一个调用点
+ *   `DELETE /v1/sessions/:id` 早在同一形下被 `isDestructiveSessionWrite` 拒。读口 `GET …/background` 不进:它有属主门兜底、只读、
+ *   只列本会话,与 `GET /v1/rules` 同判。已知同族缺口(不在本口单独打补丁):能力位 `exitFaces` 不含「凭据就绪」这一项,见契约
+ *   附录 B.1 `memoryCompliance` 行的同族说明。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type TaskRegistry, type BackgroundShellHardKillReceipt } from "@sema-agent/core";
+import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+/** `description` 的显示截断(模型描述通常一句话;回落的命令文本可能是一整段脚本)。 */
+export declare const DESCRIPTION_MAX = 500;
+/** core `list()` 的行型(从唯一的消费位取,不抄结构)。 */
+type RegistryListRow = ReturnType<TaskRegistry["list"]>[number];
+/** 读口的一行(白名单显式构造;缺席的可选键不铸)。 */
+export interface SessionBackgroundRow {
+    id: string;
+    description?: string;
+    type: RegistryListRow["type"];
+    status: RegistryListRow["status"];
+    createdAt: number;
+    sessionScoped: boolean;
+    retained?: true;
+}
+/** 停止口的一条受据(`outcome` 逐字透传 core 闭集)。 */
+export interface SessionBackgroundReceipt {
+    id: string;
+    outcome: BackgroundShellHardKillReceipt["outcome"];
+}
+/** 能力位与两口 501 的**同一个**谓词:会话属主面在场(入站 owner 门 fail-closed,缺它两口都 501)。 */
+export declare function sessionBackgroundFacesAvailable(deps: Pick<RouteCtx["deps"], "sessionStorage">): boolean;
+export declare function handleBackground(req: IncomingMessage, res: ServerResponse, match: RouteMatch<BackgroundRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const BACKGROUND_ROUTES: readonly [{
+    readonly id: "session-background-list";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/background";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "session-background-stop";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/background/stop";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type BackgroundRouteId = RouteIdsOf<typeof BACKGROUND_ROUTES>;
+export {};
+//# sourceMappingURL=background.d.ts.map

package/dist/http/routes/background.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { reapSessionBackgroundHard } from "../../background-session-reap.js";
+import { redactSecrets } from "../../trace/redact.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import {} from "../route-ctx.js";
+import { assertNever } from "../route-ctx.js";
+const LIST_LIMIT = 500;
+export const DESCRIPTION_MAX = 500;
+const ROW_KEY_DISPOSITION = {
+    task_id: "keep",
+    type: "keep",
+    status: "keep",
+    createdAt: "keep",
+    sessionScoped: "keep",
+    retained: "keep",
+    description: "keep",
+    toolUseId: "strip",
+    updatedAt: "strip",
+};
+void ROW_KEY_DISPOSITION;
+function projectRow(r) {
+    return {
+        id: r.task_id,
+        ...(r.description !== undefined ? { description: redactSecrets(r.description).slice(0, DESCRIPTION_MAX) } : {}),
+        type: r.type,
+        status: r.status,
+        createdAt: r.createdAt,
+        sessionScoped: r.sessionScoped,
+        ...(r.retained === true ? { retained: true } : {}),
+    };
+}
+const StopBodySchema = z.object({ includeRetained: z.boolean() }).strict();
+export function sessionBackgroundFacesAvailable(deps) {
+    return Boolean(deps.sessionStorage?.ownerOf);
+}
+export async function handleBackground(req, res, match, ctx) {
+    const { deps } = ctx;
+    const id = match.decl.id;
+    if (id === "session-background-stop" && ctx.helpers.rateLimited(req, res))
+        return;
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && principal === undefined) {
+        sendPrincipalRefusal(res, req, deps.config);
+        return;
+    }
+    let includeRetained = false;
+    if (id === "session-background-stop") {
+        const parsed = StopBodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "body must be { includeRetained: boolean } — required, no default: true = also stop the background processes this session was asked to keep running (explicit retain), false = keep them (they are reported as retained_skipped)");
+            return;
+        }
+        includeRetained = parsed.data.includeRetained;
+    }
+    const sessionId = ctx.helpers.safeDecode(match.params.sessionId);
+    if (sessionId === null) {
+        sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
+        return;
+    }
+    if (!sessionBackgroundFacesAvailable(deps)) {
+        sendError(res, 501, "capability.session_ownership_required", "the session background faces require the session-ownership face (sessionStorage.ownerOf)");
+        return;
+    }
+    const owner = await deps.sessionStorage.ownerOf(sessionId);
+    if (owner === undefined) {
+        sendError(res, 404, "not_found.session", "session not found");
+        return;
+    }
+    const isOperator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+    if (!isOperator && !ctx.helpers.runOwnerOk(req, res, owner, "session"))
+        return;
+    const scope = owner ?? "default";
+    switch (id) {
+        case "session-background-list": {
+            const rows = defaultTaskRegistry.list({ owner: sessionId, sessionId, scope }, { limit: LIST_LIMIT }).map(projectRow);
+            sendJson(res, 200, { rows });
+            return;
+        }
+        case "session-background-stop": {
+            const { receipts } = await reapSessionBackgroundHard(sessionId, scope, { includeRetained, reason: includeRetained ? "session_background_stop_all" : "session_background_stop" }, deps.logger);
+            sendJson(res, 200, { receipts: receipts.map((r) => ({ id: r.taskId, outcome: r.outcome })) });
+            return;
+        }
+        default:
+            return assertNever(id);
+    }
+}
+export const BACKGROUND_ROUTES = [
+    { id: "session-background-list", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background$/, label: "/v1/sessions/:id/background", methods: ["GET"] },
+    { id: "session-background-stop", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background\/stop$/, label: "/v1/sessions/:id/background/stop", credentialGated: ["POST"], methods: ["POST"] },
+];
+//# sourceMappingURL=background.js.map

package/dist/http/routes/capabilities.js

@@ -25,6 +25,7 @@ import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import { judgeAutoModeArming } from "../../auto-mode-face.js";
 import { coercePermissionModeStrict, SETTINGS_PERMISSION_MODE_WORDS } from "../../task-settings.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { sessionBackgroundFacesAvailable } from "./background.js";
 function routePairingOf(deps, name, m) {
     if (isSealedKeyPoison(deps.config.modelApiKeys?.[name]))
         return "unknown";
@@ -92,6 +93,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 sessionBackgroundable: Boolean(deps.runStore),
                 runMemoryCaptureOptOut: Boolean(deps.runStore),
                 mcpReconnect: Boolean(deps.runStore) && Boolean(deps.sessionStorage?.ownerOf),
+                background: { listFace: sessionBackgroundFacesAvailable(deps), exitFaces: sessionBackgroundFacesAvailable(deps) },
                 sharedMemory: Boolean(deps.sharedMemoryStore && deps.orgMemoryDirectory),
                 adoption: Boolean(deps.backend?.adoptionLog) && deps.config.operatorPrincipals.length > 0,
                 memoryBundle: Boolean(deps.memoryBundleExport && deps.memoryBundleImport) && deps.config.operatorPrincipals.length > 0,

package/dist/http/server.d.ts

@@ -3,7 +3,8 @@ import type { IncomingMessage } from "node:http";
 import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry, type MemoryExportBundle, type MemoryImportReport, type EntryProvenanceAccount, type MemoryErasureAttestation, type MemoryEntryOrigin, type OriginClearanceRow, type SessionMemoryStatus, type ConsolidationRunReceipt, type ConsolidationDriverRunRow, type SideQuerySpec, type SideQueryResult, type Brain, type EngineNotice } from "@sema-agent/core";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
-import { type RestartSignal, type SessionMirrorRuling } from "../config-center/facade.js";
+import { type SessionMirrorRuling } from "../config-center/facade.js";
+import type { RestartSignal } from "@sema-agent/settings-schema/fleet";
 import { type OwnerAwareSessionStore } from "../security.js";
 import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ApprovalNonceStore, ServiceSessionPolicyStore, ServiceFileHistoryStore, ToolResultStoreFull, StoreBackend } from "../plugins/store-backend.js";
 import type { RuleConsentLane } from "../rules-consent.js";
@@ -549,7 +550,9 @@ export interface ServiceSeamDeps {
             };
         };
     }) => void;
-    parkedReviveTool?: import("@sema-agent/core").ToolSpec;
+    /** #1110(core 7.32.0):parked 赎回面工厂(按行解析驱动哪只 Agent 工具 + 同出一张列表的继承座;属主 `parked-revive-surface.ts`)。
+     *  缺席 = 这台部署没有 park 底座(checkpointStore / backgroundAgentStore 任一缺席),bg 赎回臂不接线。 */
+    parkedReviveSurface?: import("../parked-revive-surface.js").ParkedReviveSurfaceFactory;
     /** 可选第三件:revive args 的 `subagent_type` roster 成员集([ref] Q1 成员性规则)。当前生产装配
      *  **恒缺席**(boot 内建 default 无自定义 agents roster,per-request 的 spec.agents 不进 boot 工具)
      *  = 恒省略 subagent_type,typed 子代按 general-purpose 形复活(保真度 caveat 已报 core,[ref]
@@ -562,7 +565,7 @@ export interface ServiceSeamDeps {
      *  `rebuildInheritedGate` 头注。 */
     parkedReviveInheritedGate?: (row: import("@sema-agent/core").BackgroundAgentRecord, identity: {
         principal: string | undefined;
-    }) => Promise<unknown>;
+    }) => Promise<import("../boot/parked-revive-gate.js").RebuiltInheritedGate | undefined>;
 }
 /** **可观测面**:日志/指标/累加器。全体 fail-open——观测失败绝不改变业务面行为。 */
 export interface ServiceObservabilityDeps {
@@ -640,7 +643,8 @@ export interface ServiceDeploymentDeps {
      *    respond/subagent) stay open so the runs we are waiting on can still finish/interact.
      *  • `inflight` is ASSIGNED BY createServer (a live union of this replica's in-flight legs: durable bg/resume
      *    `inflightRuns` + live sync/resume streams `steerableRuns`) — main.ts polls it to know when drain is done.
-     *  • /health carries `draining:true` (k8s readiness 摘流信号) + `version` (build self-description).
+     *  • /health carries `draining:true` + `version` (build self-description); draining is a readiness reason
+     *    (`http/readiness.ts`) ⇒ `/readyz` 503 + `/health` `ready:false` (the k8s readiness 摘流信号).
      *  • [ref]:`attachedStreams` 同样 ASSIGNED BY createServer —— 本副本当前打开着的 SSE 流条数
      *    (= 引擎附着租约集的大小)。消费方是 `boot/engine-lease.ts` 的自退判据;与 `inflight` 同族,
      *    同一个共享盒子,不另开第二条 main↔server 的通道。
@@ -654,21 +658,28 @@ export interface ServiceDeploymentDeps {
         attachedStreams?: () => number;
         lastAttachEndedAt?: () => number;
     };
-    /** boot ready 门(b):false = registry 部署无显式 env 模型且首次 effective pull 尚未落 roster
-     *  (worker 只有占位模型)。计费提交 503 + /health 加性 `ready:false`。absent = 恒 ready(env 模型在/非
-     *  registry 部署),现有部署零影响。main.ts 在 applyEffective 落模型后翻 true(one-way latch)。 */
+    /** boot ready 门(b):false = 布防(`CONFIG_REQUIRE_ROSTER=true`)且首次 effective pull 尚未落 roster
+     *  (worker 只有占位模型)。就绪原因 `model_roster_pending`(`http/readiness.ts`):计费提交 503 + `/readyz` 503 +
+     *  /health 加性 `ready:false`。absent = 恒 ready(未布防 / 非 registry 部署),现有部署零影响。config-center 的
+     *  markRosterLanded 在落模型后翻 true(one-way latch)。 */
     modelReady?: () => boolean;
     /** Sema-registry restart signal: the refresh loop sets this when a pull carries restart-to-apply
      *  changes (skills/mcp/a2a/scenarios/… baked at boot — the `RestartSlice` closed set) that DIFFER from this process's boot config.
      *  Surfaced at GET /health as `restartRequired` + `restart{reasons,version,since}` so the orchestrator can
      *  auto rolling-restart the worker. Change-detected (not presence) — absent when nothing baked-at-boot
-     *  changed, so polling it never causes a restart loop. */
+     *  changed, so polling it never causes a restart loop. S-741:the fleet heartbeat reads THIS getter too
+     *  (`boot/stage-10-http-server.ts` → `restart: () => deployment.restartState?.()`), so `/health.restart` and the
+     *  announcement's `restart` are the same object — one mint point, two exits. */
     restartState?: () => RestartSignal | undefined;
     /** [ref] 世代账([ref] §2):本副本的配置收敛状态 —— `/health` 取三键
      *  (configTargetVersion / configAppliedVersion / configApplyStaleMs),`GET /v1/diagnostics/wiring` 取整份
      *  (按组的 appliedVersion / deferredKeys+铸因 / lastRejected 消毒形)。缺席 = 这个进程没有配置管道
      *  (纯 env 部署 / 测试夹具)⇒ 两个面的形状逐字不变(additive)。 */
     configApplyState?: () => import("../config-center/apply-ledger.js").ConfigApplyLedgerView | undefined;
+    /** S-698:中心凭证健康位(`/health.centerCredential`)—— 凭证来源的健康态 + 续签器状态(`center-credential-renewer.ts`
+     *  `buildCenterCredentialHealthView` 铸形,只有闭集词 / 时刻 / 计数,不带路径与令牌)。缺席 / 返回 undefined = 健康或没有中心
+     *  ⇒ `/health` 形状逐字不变(additive)。 */
+    centerCredentialState?: () => import("../center-credential-renewer.js").CenterCredentialHealthView | undefined;
     /** [ref] 追加件:`POST /v1/admin/config/refresh` 的实现面 —— 触发**一次既有**的 refresh 拍(在飞则 join)。
      *  缺席 / 回 `"not-wired"` = 本部署没有配置管道 ⇒ 该口诚实 4xx(绝不吞成 200)。 */
     configRefreshNow?: () => Promise<"triggered" | "not-wired" | "failed">;
@@ -798,6 +809,8 @@ export declare function flattenServiceDeps(deps: ServiceDeps): FlatServiceDeps;
 /**
  * Managed-Agents-style HTTP/SSE service surface.
  *   GET  /health
+ *   GET  /readyz              → readiness probe: 200 {ready:true} / 503 {ready:false, reasons} (S-739; same predicate
+ *                               as /health.ready, the billable-submit 503s and the fleet heartbeat — http/readiness.ts)
  *   POST /v1/tasks            → run to completion, TaskResult JSON (synchronous)
  *   POST /v1/tasks/stream     → SSE of TaskEvent, live tokens (synchronous, same instance)
  *   POST /v1/runs             → async: 202 {taskId, sessionId, status}, runs in background (S1)

package/dist/http/server.js

@@ -24,7 +24,7 @@ import { createRequestGuards } from "./request-guards.js";
 import { createAdmission, MAX_SKILL_CONTENT_CHARS, MAX_SYSTEM_PROMPT_CHARS, MAX_OUTPUT_SCHEMA_CHARS, validateUserSkills } from "./admission.js";
 import { createResumeLegs } from "./resume-legs.js";
 import { createDispatch, hasServiceAuth } from "./dispatch.js";
-import { routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath } from "./route-table.js";
+import { routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, isProbePath } from "./route-table.js";
 import { createApprovalSweeps } from "./approval-sweeps.js";
 export { routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, hasServiceAuth };
 export { MAX_SKILL_CONTENT_CHARS, MAX_SYSTEM_PROMPT_CHARS, MAX_OUTPUT_SCHEMA_CHARS, validateUserSkills };
@@ -49,7 +49,7 @@ export function createHttpServer(rawDeps) {
         deps.drainState.inflight = () => new Set([...inflightRuns.keys(), ...steerableRuns.keys()]).size + counters.uncountedBillableInflight + counters.admittedInflight + (deps.leaderEndpoint?.inflight?.() ?? 0);
     let lastBillableActivityAt = performance.now();
     const noteActivity = (url) => {
-        if (url === "/health" || url.startsWith("/metrics"))
+        if (isProbePath(url))
             return;
         lastBillableActivityAt = performance.now();
     };

package/dist/model-entry-refusal.d.ts

@@ -8,7 +8,7 @@ export declare const MODEL_ENTRY_REFUSAL_CODES: {
 export type ModelEntryRefusalCode = (typeof MODEL_ENTRY_REFUSAL_CODES)[ModelEntryRefusalReason];
 /** 「这张表没有缺省模型」的机读码(S-705;boot 拒启与热路径模型面组拒同一个码)。 */
 export declare const DEFAULT_MODEL_MISSING_CODE = "config.default_model_missing";
-/** 🔴 S-712「被拒的名字被档位 / 别名增广铸到了别的条目上(或读不出被丢条目的名字,无从证明没有)」的机读码
+/** 🔴 S-712「被拒的名字被档位 / 别名增广铸到了别的条目上(或被丢身份载体形不对、读不出名字,无从证明没有)」的机读码
  *  (不变量 `refused-names-not-minted`;热路径 / boot 首次 apply / dry-run 同一个码)。 */
 export declare const REFUSED_NAME_MINTED_CODE = "config.model_refused_name_minted";
 /**
@@ -47,20 +47,21 @@ export interface CatalogEntryLike {
  * 坐标,不取它的输出(输出会补缺省、剥扩展键,那是读腿的事)。
  */
 export declare function judgeCatalogEntry(m: CatalogEntryLike, ctx: CatalogEntryVerdictCtx): ModelEntryRefusal | undefined;
-/** 一批已启用条目的判决:可用的(保序)、不可用的(按 catalog name)、以及身份证明不了的被丢条目(坐标)。 */
+/** 一批已启用条目的判决:可用的(保序)、不可用的(按 catalog name)、以及形不对的被丢身份载体行(坐标)。 */
 export interface CatalogEntriesVerdict<M extends CatalogEntryLike> {
     readonly usable: readonly M[];
     readonly refused: Readonly<Record<string, ModelEntryRefusal>>;
-    /** S-712:读腿逐条丢掉、而身份证明不了的条目坐标(`models.3`;载体上不带 `name` 的那些 —— 读腿只在原文档对不上本次解析时
-     *  这样交出,见 `read-warnings.ts` `DroppedModelIdentity`)。非空 ⇒ 不变量 `refused-names-not-minted` 无从成立 ⇒ 模型面组拒。 */
-    readonly unreadable: readonly string[];
+    /** S-712:被丢身份**载体形不对**的行坐标(`models.3`;载体不是列表时是一个固定标记)。读腿只为有名的被丢条目铸载体行
+     *  (`read-warnings.ts` `DroppedModelIdentity`,`name` 必在),所以这一形只来自绕过读腿的输入被改过(盘上 LKG 被手改 / 手写
+     *  effective)。非空 ⇒ 读不出的名字无从证明它不被增广铸出 ⇒ 不变量 `refused-names-not-minted` 不成立 ⇒ 模型面组拒(fail-closed)。 */
+    readonly malformed: readonly string[];
 }
 /**
  * 批量形(模型面 stage 与 dry-run 共用这一只 —— 报数与真 apply 永不撕裂)。
  * S-712:`dropped` = 读腿交出的被丢条目身份(`EffectiveConfig.models.droppedIdentities`)—— 它们与逐条判据判出的 `entry_invalid`
- * 是**同一件事**(条目不合 `ModelEntry` 形),只是在第一道边界就被丢了;带名字的铸墓碑,不带名字的(读腿证明不了身份)进
- * `unreadable`。没有字符串名的坏行读腿已按停用处置、根本不进载体(7.101.0 验修轮 V-2:没有名字就没有可保留的名字)。
- * 入参按 `unknown` 判形:载体可能来自盘上 LKG(本仓写的,但文件可被改),形不对的一律按证明不了处置(fail-closed)。
+ * 是**同一件事**(条目不合 `ModelEntry` 形),只是在第一道边界就被丢了;每一行铸一块墓碑(拒因 provider 词空:告警身份不带它)。
+ * 入参按 `unknown` 判形:载体可能来自盘上 LKG(本仓写的,但文件可被改)。**规则一条**:载体要么缺席,要么是一列带字符串 `name`
+ * 的行;其余一律「载体形不对」进 `malformed`(fail-closed)—— 读腿自己从不铸这种形。
  * 与一条可用 / 已判不可用条目同名时不覆盖(可用条目仍可用;同名撞车由不变量 `refused-names-not-minted` 响亮拒)。
  */
 export declare function judgeCatalogEntries<M extends CatalogEntryLike>(enabled: readonly M[], ctx: CatalogEntryVerdictCtx, dropped?: unknown): CatalogEntriesVerdict<M>;
@@ -125,6 +126,6 @@ export interface RefusedNameView {
 export declare function mintedRefusedNames(view: RefusedNameView): MintedRefusedName[];
 /** 不变量 `refused-names-not-minted` 的拒因句(`undefined` = 成立)。warn 与世代账 / 拒因同一句;逐对明细另走 {@link mintedRefusedNames}。 */
 export declare function refusedNameMintedRefusal(view: RefusedNameView): string | undefined;
-/** 身份证明不了的被丢条目的拒因句(同一不变量同一个码:证明不了的名字无从证明它不被增广铸出)。 */
-export declare function unreadableDroppedRefusal(entries: readonly string[]): string;
+/** 被丢身份载体形不对的拒因句(同一不变量同一个码:读不出的名字无从证明它不被增广铸出)。 */
+export declare function malformedDroppedCarrierRefusal(entries: readonly string[]): string;
 //# sourceMappingURL=model-entry-refusal.d.ts.map