@sema-agent/server 7.101.0 → 7.102.0

package/dist/fleet/fleet-reconciler.d.ts

@@ -33,10 +33,17 @@
  * 「**静默满一个对账周期**」(本腿订阅总线自记每行的最后帧时刻):还在出帧 = 活着的证据。
  * durable 行**在场**的那三格没有这个歧义(`getRun` 命中 = 它就是一条 run 行),故照矩阵即时处置。
  *
- * ## 子代行(§1)
- * 随父:父行退休/退场时**同扫**(与 `onTerminal` 的 removal 集同姿势)。子代**不读 durable** ——
- * bg 子代的 durable 真源在 core 侧 registry,server 不越界重判。无父可循的孤儿子行(父行已不在 bus)
- * 按「bus 内滞留超一个对账周期且无新帧」陈述级退场。
+ * ## 子代行(§1;🔴 S-751 起改为「活性由属主说了算」)
+ * 子代行**不读 durable run 店**(它不是 run 行)。它的活性属主有两只,都在本仓可读 —— 读它们**不是**越界重判,
+ * 是问属主(S-751 之前此处写「bg 子代的 durable 真源在 core 侧 registry,server 不越界重判」,于是判据里只剩
+ * 「静默」这一条,而 registry 的读半场 `RunnerDeps.backgroundAgentStore` 一直就在本仓):
+ *  ① core bg registry(`BackgroundAgentStore` 行 `status` 非终态 = `running` / `parked`);
+ *  ② 本副本审批面的待决卡(子代发起、没人答的 ask —— 子代卡在那儿,当然不出帧)。
+ * **一条规则**:无父可循(父从未在 / 父本周期刚退休或退场)∧ 静默满一个对账周期 ∧ 两只属主都不作保 ⇒
+ * 陈述级退场。父离场**不再无条件同扫**子代(那是报案的一半病:父轮结束、子代一次工具调用 ≥60s 或审批卡
+ * 60s 没人答 ⇒ 活子代被扫);父离场只让子代「无父可循」,子代与既有孤儿走**同一只**判据、同一个循环。
+ * 同一问也挂在「durable 无行」那一格上:父链接未解析的 `a*` 行与顶层行同形(见上方收窄段),run 账不认识它
+ * ≠ 它死了。另一半病(陈述级退场立了代际墓碑、吞掉活子代之后的同代帧)的修在 `fleet-bus.ts` `removeTask`。
  *
  * ## workflow 行(§1)
  * 只做同款「durable 终局投影」([ref] 的 snapshot pull 腿 + reapers 的 workflow recover 腿已在场),
@@ -77,7 +84,7 @@
  * 与 `fleet-terminal-window.ts` 同一论证:两侧边界都由语义定死(比周期短 = 幽灵行仍在面板上,比周期长 =
  * 拿对账腿当历史列表),旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
  */
-import { type WorkflowRun, type WorkflowRunStore } from "@sema-agent/core";
+import { type BackgroundAgentRecord, type WorkflowRun, type WorkflowRunStore } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
 import { type RunRecord } from "../plugins/store-contracts.js";
@@ -111,6 +118,12 @@ export interface FleetReconcileRunPort {
 export interface FleetReconcileWorkflowPort {
     get(id: string): Promise<WorkflowRun | null | undefined>;
 }
+/** S-751:core bg registry 账(`BackgroundAgentStore`)的只读窄口 —— 与 {@link FleetReconcileRunPort} 同一条
+ *  单写者纪律(接口上没有写方法)。生产 = `RunnerDeps.backgroundAgentStore` **同实例**(结构上就是它的 `get`
+ *  一面);`null` = 账上没有这一行。 */
+export interface FleetReconcileAgentPort {
+    get(handle: string, scope: string): Promise<Pick<BackgroundAgentRecord, "status"> | null>;
+}
 export interface FleetReconcilerDeps {
     bus: FleetEventBus;
     /**
@@ -130,6 +143,14 @@ export interface FleetReconcilerDeps {
     subscribeRunTerminal?: (fn: (rec: RunTerminalRecord) => void) => () => void;
     runs?: FleetReconcileRunPort;
     workflows?: FleetReconcileWorkflowPort | WorkflowRunStore;
+    /** S-751:子代活性的属主①(bg registry 账)。缺席 = 没有 bg 店的部署(纯内存 dev),这一问问不了。 */
+    agents?: FleetReconcileAgentPort;
+    /**
+     * S-751:子代活性的属主②:这只子代此刻有没有**待决**审批卡。只问是非(与 {@link isLiveOnThisReplica} 同姿势,
+     * 不搬 Map)。入参是 ask 发起者域(子代自己的 core session id,= 卡上的 `originTaskId`),**不是**行 id ——
+     * 行 id → 该域的换算只在 `FleetEventBus.childOwnerKeys`。生产 = `ToolApprovalCoordinator.hasLivePendingFrom`。
+     */
+    hasPendingAsk?: (originTaskId: string) => boolean;
     /** 本副本 id(与 `RunRecord.instanceId` 同域)。只进日志/读数 —— 两条 `running` 臂的**处置相同**
      *  (都是陈述级退场),分不分得出 claim 属谁不改变行为,故它不是判据。 */
     instanceId?: string;
@@ -150,8 +171,10 @@ export interface FleetReconcileTally {
     retired: number;
     /** 陈述级退场的行数(顶层 + 孤儿子行)。 */
     orphaned: number;
-    /** 随父同扫的子行数。 */
+    /** 父本周期刚离场、自己又判成孤儿而陈述级退场的子行数(S-751 前 = 随父无条件同扫的数)。 */
     childrenSwept: number;
+    /** S-751:静默满一周期、无父可循(或 run 账不认识),但属主作保而**留行**的子行数。 */
+    childrenKeptAlive: number;
     /** durable 终局 ⇒ 投影退休的 workflow 行数。 */
     workflowsRetired: number;
     /** 本周期实际发出的 durable 点读次数。 */

package/dist/fleet/fleet-reconciler.js

@@ -11,7 +11,7 @@ export const FLEET_RECONCILE_COOLDOWN_MS = 60_000;
 export const FLEET_RECONCILE_WATCH_MAX = 200;
 export const FLEET_RECONCILE_WATCH_TTL_MS = 30 * 60_000;
 const emptyTally = () => ({
-    scanned: 0, skippedLive: 0, skippedParked: 0, retired: 0, orphaned: 0, childrenSwept: 0, workflowsRetired: 0, reads: 0, cooling: false, failOpen: false,
+    scanned: 0, skippedLive: 0, skippedParked: 0, retired: 0, orphaned: 0, childrenSwept: 0, childrenKeptAlive: 0, workflowsRetired: 0, reads: 0, cooling: false, failOpen: false,
 });
 function rotate(rows, cursor) {
     if (cursor === undefined || rows.length === 0)
@@ -22,6 +22,22 @@ function rotate(rows, cursor) {
     return [...rows.slice(at), ...rows.slice(0, at)];
 }
 const SILENT_FOR_A_CYCLE = FLEET_RECONCILE_INTERVAL_MS;
+function bgAgentVouches(status) {
+    switch (status) {
+        case "running":
+        case "parked":
+            return true;
+        case "completed":
+        case "failed":
+        case "killed":
+            return false;
+        default: {
+            const unhandled = status;
+            recordFailOpen("server.fleet.agent-status-unmapped", String(unhandled));
+            return true;
+        }
+    }
+}
 export function createFleetReconciler(deps) {
     const now = deps.now ?? (() => Date.now());
     const lastFrameAt = new Map();
@@ -86,11 +102,11 @@ export function createFleetReconciler(deps) {
         coolingUntil = undefined;
         const deadline = now() + FLEET_RECONCILE_READ_BUDGET_MS;
         const budgetLeft = () => tally.reads < FLEET_RECONCILE_MAX_ROWS && now() < deadline;
-        const readRun = async (id) => {
+        const budgetedRead = async (read) => {
             tally.reads++;
             let t;
-            const rec = await Promise.race([
-                deps.runs.getRun(id),
+            return await Promise.race([
+                read(),
                 new Promise((_r, reject) => {
                     t = setTimeout(() => reject(new ReadAborted(`fleet reconcile read exceeded ${FLEET_RECONCILE_READ_BUDGET_MS}ms`)), Math.max(0, deadline - now()));
                     if (typeof t.unref === "function")
@@ -100,30 +116,43 @@ export function createFleetReconciler(deps) {
                 if (t !== undefined)
                     clearTimeout(t);
             });
-            return rec;
         };
+        const readRun = (id) => budgetedRead(() => deps.runs.getRun(id));
         const snap = deps.bus.snapshot();
         for (const r of snap.tasks)
             if (!lastFrameAt.has(r.id))
                 lastFrameAt.set(r.id, nowMs);
         const idle = (id) => nowMs - (lastFrameAt.get(id) ?? nowMs) >= SILENT_FOR_A_CYCLE;
         const present = new Set(snap.tasks.map((r) => r.id));
-        const kids = new Map();
-        for (const r of snap.tasks) {
-            if (r.parentId === undefined)
-                continue;
-            const bucket = kids.get(r.parentId);
-            if (bucket)
-                bucket.push(r);
-            else
-                kids.set(r.parentId, [r]);
-        }
-        const sweepChildren = (parentId) => {
-            for (const c of kids.get(parentId) ?? []) {
-                deps.bus.removeTask(c.id, { removeReason: "orphaned", ...(c.cycleSeq !== undefined ? { cycleSeq: c.cycleSeq } : {}) });
-                lastFrameAt.delete(c.id);
-                tally.childrenSwept++;
+        const parentsOnBus = new Set(present);
+        const stillSilent = (row) => {
+            const cur = deps.bus.taskRow(row.id);
+            return cur !== undefined && cur.cycleSeq === row.cycleSeq && idle(row.id);
+        };
+        const keptAlive = (row, why) => {
+            tally.childrenKeptAlive++;
+            deps.logger?.info("fleet_row_reconciled", { taskId: row.id, disposition: "child_kept_alive", why, instanceId: deps.instanceId ?? null });
+        };
+        const judgeSilentRow = async (row, exit) => {
+            const handle = deps.bus.childOwnerKeys(row).handle;
+            if (handle !== undefined && deps.agents !== undefined && row.scope !== undefined) {
+                if (!budgetLeft())
+                    return "over_budget";
+                const scope = row.scope;
+                const rec = await budgetedRead(() => deps.agents.get(handle, scope));
+                if (rec !== null && bgAgentVouches(rec.status)) {
+                    keptAlive(row, "bg_registry");
+                    return "settled";
+                }
+            }
+            const hasPendingAsk = deps.hasPendingAsk;
+            if (hasPendingAsk !== undefined && deps.bus.childOwnerKeys(row).sessionIds.some((id) => hasPendingAsk(id))) {
+                keptAlive(row, "pending_ask");
+                return "settled";
             }
+            if (stillSilent(row))
+                exit();
+            return "settled";
         };
         const retire = (row, rec) => {
             deps.bus.publishTask({
@@ -132,14 +161,14 @@ export function createFleetReconciler(deps) {
                 retiredBy: "reconcile",
                 ...fleetRunResiduals(rec.result),
             });
-            sweepChildren(row.id);
+            parentsOnBus.delete(row.id);
             deps.bus.removeTask(row.id, { ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
             lastFrameAt.delete(row.id);
             tally.retired++;
             deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "retired" });
         };
         const orphanExit = (row, why) => {
-            sweepChildren(row.id);
+            parentsOnBus.delete(row.id);
             deps.bus.removeTask(row.id, { removeReason: "orphaned", ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
             lastFrameAt.delete(row.id);
             if (deps.runs && watch.size < FLEET_RECONCILE_WATCH_MAX)
@@ -148,6 +177,61 @@ export function createFleetReconciler(deps) {
             deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "orphaned" });
             deps.logger?.info("fleet_row_reconciled", { taskId: row.id, disposition: "orphaned", why, instanceId: deps.instanceId ?? null });
         };
+        const childExit = (row, parentId) => {
+            deps.bus.removeTask(row.id, { removeReason: "orphaned", ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
+            lastFrameAt.delete(row.id);
+            parentsOnBus.delete(row.id);
+            if (present.has(parentId)) {
+                tally.childrenSwept++;
+            }
+            else {
+                tally.orphaned++;
+                deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "orphaned_child" });
+            }
+        };
+        const judgeTopLevel = async (row) => {
+            tally.scanned++;
+            if (deps.isLiveOnThisReplica(row.id)) {
+                tally.skippedLive++;
+                return "settled";
+            }
+            if (!deps.runs)
+                return "settled";
+            if (!budgetLeft())
+                return "over_budget";
+            const rec = await readRun(row.id);
+            if (deps.isLiveOnThisReplica(row.id)) {
+                tally.skippedLive++;
+                return "settled";
+            }
+            const nowRow = deps.bus.taskRow(row.id);
+            if (nowRow === undefined)
+                return "settled";
+            if (nowRow.cycleSeq !== row.cycleSeq)
+                return "settled";
+            if (rec === undefined) {
+                if (!idle(row.id))
+                    return "settled";
+                return judgeSilentRow(row, () => orphanExit(row, "durable_row_absent"));
+            }
+            if (isTerminalRunStatus(rec.status)) {
+                retire(row, rec);
+                return "settled";
+            }
+            if (isParkedRunStatus(rec.status)) {
+                tally.skippedParked++;
+                return "settled";
+            }
+            orphanExit(row, runProvenElsewhere(rec, deps.instanceId) ? "durable_running_other_replica" : "durable_running_no_local_leg");
+            return "settled";
+        };
+        const judgeChild = async (row, parentId) => {
+            if (parentsOnBus.has(parentId))
+                return "settled";
+            if (!idle(row.id))
+                return "settled";
+            return judgeSilentRow(row, () => childExit(row, parentId));
+        };
         try {
             for (const [id, w] of [...watch]) {
                 if (nowMs - w.at > FLEET_RECONCILE_WATCH_TTL_MS) {
@@ -171,53 +255,11 @@ export function createFleetReconciler(deps) {
                     tally.retired++;
             }
             for (const row of rotate(snap.tasks, taskCursor)) {
-                if (row.parentId !== undefined)
-                    continue;
-                tally.scanned++;
-                if (deps.isLiveOnThisReplica(row.id)) {
-                    tally.skippedLive++;
-                    continue;
-                }
-                if (!deps.runs)
-                    continue;
-                if (!budgetLeft()) {
+                const step = row.parentId === undefined ? await judgeTopLevel(row) : await judgeChild(row, row.parentId);
+                if (step === "over_budget") {
                     taskCursor = row.id;
                     break;
                 }
-                const rec = await readRun(row.id);
-                if (deps.isLiveOnThisReplica(row.id)) {
-                    tally.skippedLive++;
-                    continue;
-                }
-                const nowRow = deps.bus.taskRow(row.id);
-                if (nowRow === undefined)
-                    continue;
-                if (nowRow.cycleSeq !== row.cycleSeq)
-                    continue;
-                if (rec === undefined) {
-                    if (idle(row.id))
-                        orphanExit(row, "durable_row_absent");
-                    continue;
-                }
-                if (isTerminalRunStatus(rec.status)) {
-                    retire(row, rec);
-                    continue;
-                }
-                if (isParkedRunStatus(rec.status)) {
-                    tally.skippedParked++;
-                    continue;
-                }
-                orphanExit(row, runProvenElsewhere(rec, deps.instanceId) ? "durable_running_other_replica" : "durable_running_no_local_leg");
-            }
-            for (const row of snap.tasks) {
-                if (row.parentId === undefined || present.has(row.parentId))
-                    continue;
-                if (!idle(row.id))
-                    continue;
-                deps.bus.removeTask(row.id, { removeReason: "orphaned", ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
-                lastFrameAt.delete(row.id);
-                tally.orphaned++;
-                deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "orphaned_child" });
             }
             if (wfGet) {
                 for (const wf of rotate(snap.workflows, wfCursor)) {
@@ -227,19 +269,7 @@ export function createFleetReconciler(deps) {
                         wfCursor = wf.id;
                         break;
                     }
-                    tally.reads++;
-                    let wfTimer;
-                    const run = await Promise.race([
-                        wfGet(wf.id),
-                        new Promise((_r, reject) => {
-                            wfTimer = setTimeout(() => reject(new ReadAborted("fleet reconcile workflow read over budget")), Math.max(0, deadline - now()));
-                            if (typeof wfTimer.unref === "function")
-                                wfTimer.unref();
-                        }),
-                    ]).finally(() => {
-                        if (wfTimer !== undefined)
-                            clearTimeout(wfTimer);
-                    });
+                    const run = await budgetedRead(() => wfGet(wf.id));
                     if (!run || !isTerminalWorkflowStatus(run.status))
                         continue;
                     if (wf.scope !== undefined && run.scope !== wf.scope)

package/dist/fleet-client.d.ts

@@ -4,16 +4,25 @@
  *  - **可选分层(D3)**:仅当 center 已配置(sema-registry lane 的 baseUrl+token+worker)∧ `FLEET_ADVERTISE_ADDRESS`
  *    显式声明时才启动 —— 不配 center 的部署零行为变化。address 不自猜(k8s pod IP / docker alias / 127.0.0.1:port
  *    只有部署环境自己知道,故用显式 env)。
- *  - **announce=注册=心跳同形状幂等 upsert**:boot 后 POST 一次 + 每 heartbeatMs 续;`ready` 今 = `!draining`(实现只读
- *    `isDraining()`,announce 本身在 boot 之后才起;S-740 起与 /health 就绪同一只谓词 —— 车OC 6b 注释改真,实现归 S-740)。
- *  - **draining 翻转即刻再 announce**(第一时间自摘流,比任何观测都快);退出前 DELETE(显式注销,幂等)。
+ *  - **announce=注册=心跳同形状幂等 upsert**:boot 后(listen 之后)POST 一次 + 每 heartbeatMs 续。
+ *    `ready` / `draining` 两字段由**同一只**就绪谓词的同一次读铸(S-740:`http/readiness.ts` 的 `readinessOf`,
+ *    与 `/health.ready`、`GET /readyz`、计费提交门同源):`ready = verdict.ready`(= roster 已落 ∧ ¬draining),
+ *    `draining = reasons ∋ "draining"`。修前 `ready = !isDraining()`,不含 roster ⇒ roster 未落时心跳说「就绪」
+ *    而计费提交在 503。
+ *  - **`restart?`(S-741)**:在场 ⇔ 本副本必须重启才能应用配置 —— 取自 `/health.restart` **同一只**取值口(装配层接
+ *    `deployment.restartState`,config-center 的 `restartState()`),同一个对象,形 = settings-schema `RestartSignal`;
+ *    缺席即键缺席(中心按行整体替换,不合并 —— 一条不带它的心跳就是「不再需要」)。
+ *  - **自报状态翻转即刻再 announce**(第一时间自摘流 / 自挂流 / 报重启,比任何观测都快):draining 翻转由收尾链直调
+ *    `announceNow`;roster 落地与 restart 信号变化由装配层把 config-center 的 `onSelfReportChange` 接到 `announceNow`
+ *    (两处 = 两类输入各自的唯一写者,触发都是 `announceNow`)。退出前 DELETE(显式注销,幂等)。
  *  - **usage 批报**:tracer 的 `brain.call` 已带 ALS principal —— FleetUsageAccumulator 按 principal×model
  *    累计,每窗口(默认 60s,半开 [windowStartMs, windowEndMs))POST /api/fleet/usage。幂等键
  *    (worker,instanceId,windowStartMs) 重发安全;**发送失败 → merge 回累计器**,并入下一窗(失败窗从未入账,
  *    向前合并不会双计 —— 只延迟,不丢量)。
  *  - 全部 fire-and-forget + swallow-guarded:fleet 面是运维旁路,绝不影响任务面;网络错误只 warn 一次/连败类。
  */
-import { UsageReport } from "@sema-agent/settings-schema/fleet";
+import { UsageReport, type RestartSignal } from "@sema-agent/settings-schema/fleet";
+import type { ReadinessVerdict } from "./http/readiness.js";
 import { type CenterEndpoint } from "./config-center/center-request.js";
 /** Bound on distinct principal×model keys per window — a runaway/multi-tenant burst collapses into
  *  `__other__` instead of growing unbounded (same posture as budget.ts cardinalityGuard). */
@@ -65,8 +74,12 @@ export interface FleetClientOpts {
     /** Reachable base URL of THIS instance — the operator's explicit declaration (`FLEET_ADVERTISE_ADDRESS`). */
     advertiseAddress: string;
     version: string;
-    /** Live drain flag (drainState) — read at every announce. */
-    isDraining: () => boolean;
+    /** S-740:就绪判(装配层接 `readinessOf(deployment)` —— HTTP 面读的同一个 deps 组)。每条公告现读**一次**,
+     *  `ready` 与 `draining` 两字段都由这一次读铸(不会撕裂成 `ready:true` + `draining:true`)。 */
+    readiness: () => ReadinessVerdict;
+    /** S-741:restart 信号(装配层接 `/health` 同一只取值口 `deployment.restartState`)。每条公告现读一次;`undefined` ⇒ 公告不带
+     *  `restart` 键。必填:心跳面没有「不知道要不要重启」这一形。 */
+    restart: () => RestartSignal | undefined;
     usage?: FleetUsageAccumulator;
     heartbeatMs?: number;
     usageWindowMs?: number;
@@ -78,7 +91,8 @@ export interface FleetClientOpts {
     fetchImpl?: typeof fetch;
 }
 export interface FleetClient {
-    /** Immediate out-of-cycle announce — call when `draining` flips (self-remove from routing FIRST). */
+    /** Immediate out-of-cycle announce — call when a self-reported input flips (draining: self-remove from routing FIRST;
+     *  roster landed: become routable without waiting a heartbeat; restart signal changed: S-741). */
     announceNow: () => Promise<void>;
     /** Stop timers + best-effort DELETE deregistration (bounded; never throws). */
     stop: () => Promise<void>;

package/dist/fleet-client.js

@@ -81,17 +81,22 @@ export function startFleetClient(opts) {
     const send = (route, method, json) => centerFetch(opts.center, { kind: route }, { method, json, timeoutMs: FLEET_CLIENT_FETCH_TIMEOUT_MS, fetchImpl: f });
     let stopped = false;
     let failStreak = 0;
-    const announceNow = async () => {
-        const body = {
-            instanceId: opts.instanceId,
-            worker: opts.center.worker,
-            address: opts.advertiseAddress,
-            version: opts.version,
-            ready: !opts.isDraining(),
-            draining: opts.isDraining(),
-            heartbeatMs,
-        };
+    const announceOnce = async () => {
+        if (stopped)
+            return;
         try {
+            const verdict = opts.readiness();
+            const restart = opts.restart();
+            const body = {
+                instanceId: opts.instanceId,
+                worker: opts.center.worker,
+                address: opts.advertiseAddress,
+                version: opts.version,
+                ready: verdict.ready,
+                draining: !verdict.ready && verdict.reasons.includes("draining"),
+                heartbeatMs,
+                ...(restart !== undefined ? { restart } : {}),
+            };
             const { res } = await send("fleet-instances", "POST", body);
             if (!res.ok)
                 throw new Error(`announce ${res.status}${await rejectionSnippet(res)}`);
@@ -105,6 +110,26 @@ export function startFleetClient(opts) {
                 opts.logger?.warn("fleet_announce_failed", { error: err instanceof Error ? err.message : String(err) });
         }
     };
+    let inFlight;
+    let again = false;
+    const announceNow = () => {
+        if (inFlight !== undefined) {
+            again = true;
+            return inFlight;
+        }
+        inFlight = (async () => {
+            try {
+                do {
+                    again = false;
+                    await announceOnce();
+                } while (again && !stopped);
+            }
+            finally {
+                inFlight = undefined;
+            }
+        })();
+        return inFlight;
+    };
     let windowStartMs = Date.now();
     const flushUsage = async () => {
         if (!opts.usage)
@@ -131,13 +156,17 @@ export function startFleetClient(opts) {
     hb.unref?.();
     const uw = opts.usage ? setInterval(() => void flushUsage(), usageWindowMs) : undefined;
     uw?.unref?.();
+    let stopping = false;
     const stop = async () => {
-        if (stopped)
+        if (stopping)
             return;
-        stopped = true;
+        stopping = true;
         clearInterval(hb);
         if (uw)
             clearInterval(uw);
+        while (inFlight !== undefined)
+            await inFlight;
+        stopped = true;
         await flushUsage();
         try {
             await send("fleet-instances", "DELETE", { instanceId: opts.instanceId, worker: opts.center.worker });

package/dist/fleet-lease.d.ts

@@ -116,7 +116,7 @@ export declare class FleetLeaseManager {
 /**
  * Env/config gate(与 startFleetClientFromEnv 同 D3 分层姿势,但 lease 不需要 FLEET_ADVERTISE_ADDRESS ——
  * 它是出站消费面,不是入站可达性声明):sema-registry lane 配齐(baseUrl + **声明了**凭证 + worker)即启;任一缺失 →
- * undefined,非 fleet 部署零行为变化。S-651:按**声明**装、不按内容装 —— `SEMA_REGISTRY_TOKEN_FILE` 在场而
+ * undefined,非 fleet 部署零行为变化。S-651:按**声明**装、不按内容装 —— `SEMA_REGISTRY_TOKEN_FILE`(`CENTER_CREDENTIAL_ENV.tokenFile`)在场而
  * 文件此刻不可读,管理器照样装上(每次协商取值,失败走响亮的鉴权失败臂;文件恢复即恢复)。
  */
 export declare function createFleetLeaseFromEnv(cfg: {

package/dist/http/approval-sweeps.js

@@ -6,6 +6,7 @@ import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
 import { hasServiceAuth } from "./dispatch.js";
 import { gatedPrincipal } from "./principal-gate.js";
+import { readinessOf, billableRefusalOf } from "./readiness.js";
 export function createApprovalSweeps(ctx) {
     const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
     const denySweepClockGuard = createWallClockJumpGuard({
@@ -71,26 +72,10 @@ export function createApprovalSweeps(ctx) {
         if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
             return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
         }
-        if (deps.drainState?.draining) {
-            return {
-                status: 503,
-                body: {
-                    error: "draining",
-                    errorCode: "draining",
-                    message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
-                    ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
-                },
-            };
-        }
-        if (deps.modelReady && !deps.modelReady()) {
-            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",
-                },
-            };
+        const readiness = readinessOf(deps);
+        if (!readiness.ready) {
+            const refusal = billableRefusalOf(readiness, deps.drainState?.reason);
+            return { status: refusal.status, body: refusal.body };
         }
         if (deps.costQuota && req.httpReq) {
             const quotaPrincipal = gatedPrincipal(req.httpReq, deps.config);

package/dist/http/dispatch.js

@@ -3,8 +3,9 @@ import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessio
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
-import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute } from "./route-table.js";
+import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath } from "./route-table.js";
 import { sendJson, sendError, isSseResponse } from "./send.js";
+import { readinessOf, healthReadinessKeys, sendReadyz, billableRefusalOf, sendBillableRefusal } from "./readiness.js";
 import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function hasServiceAuth(config) {
@@ -67,7 +68,7 @@ export function createDispatch(ctx) {
         const search = qMark === -1 ? "" : rawUrl.slice(qMark);
         const allow = { pre: [], post: [] };
         noteActivity(url);
-        const admitted = method !== "OPTIONS" && url !== "/health" && !url.startsWith("/metrics");
+        const admitted = method !== "OPTIONS" && !isProbePath(url);
         if (admitted)
             counters.admittedInflight++;
         if (admitted)
@@ -89,7 +90,7 @@ export function createDispatch(ctx) {
             const status = aborted ? "499" : String(res.statusCode);
             deps.metrics?.inc("http_requests_total", { route, method, status });
             deps.metrics?.observe("http_request_duration_seconds", seconds, { route });
-            const log = route === "/health" || route === "/metrics" ? deps.logger?.debug : deps.logger?.info;
+            const log = route === "/health" || route === "/readyz" || route === "/metrics" ? deps.logger?.debug : deps.logger?.info;
             log?.call(deps.logger, "request", { method, route, status, ms: Date.now() - startedAt, ...(reqState.runStatus !== undefined ? { runStatus: reqState.runStatus } : {}), ...(reqState.runErrorCode !== undefined ? { errorCode: reqState.runErrorCode } : {}), ...(aborted ? { aborted: true, ...(reqState.streamTaskId ? { taskId: reqState.streamTaskId } : {}), ...(reqState.streamDetached ? { detached: true } : {}) } : {}) });
         };
         res.on("finish", () => record(false));
@@ -112,7 +113,7 @@ export function createDispatch(ctx) {
                 ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}), ...(deps.drainState.reason ? { drainReason: deps.drainState.reason } : {}) } : {}),
                 ...(deps.drainState?.inflight ? { inflight: deps.drainState.inflight() } : {}),
                 ...(deps.storeDegraded ? { durable: false, storeDegraded: true } : {}),
-                ...(deps.modelReady && !deps.modelReady() ? { ready: false, readyReason: "model roster pending (first effective-config pull)" } : {}),
+                ...healthReadinessKeys(readinessOf(deps)),
                 model: deps.config.model.id,
                 sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
                 sessions: deps.runner.sessions.size,
@@ -123,7 +124,7 @@ export function createDispatch(ctx) {
                 startedAt: PROCESS_STARTED_AT_MS,
                 port: deps.config.port,
                 ...(deps.config.directDoorActive ? { directDoorActive: true } : {}),
-                ...(restart ? { restartRequired: true, restart: { reasons: restart.reasons, version: restart.version, since: restart.since } } : {}),
+                ...(restart ? { restartRequired: true, restart } : {}),
                 ...(() => {
                     const stuck = deps.planeDeferredState?.();
                     return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
@@ -140,6 +141,10 @@ export function createDispatch(ctx) {
                         ...(gen.configApplyStaleMs !== undefined ? { configApplyStaleMs: gen.configApplyStaleMs } : {}),
                     };
                 })(),
+                ...(() => {
+                    const credential = deps.centerCredentialState?.();
+                    return credential ? { centerCredential: credential } : {};
+                })(),
                 ...(() => {
                     const probe = deps.storeLiveState?.();
                     if (!probe)
@@ -152,6 +157,10 @@ export function createDispatch(ctx) {
             });
             return;
         }
+        if (req.method === "GET" && url === "/readyz") {
+            sendReadyz(res, readinessOf(deps));
+            return;
+        }
         if (req.method === "GET" && (url === "/metrics" || url === "/metrics/summary" || url === "/metrics/plan-cache")) {
             if (!deps.metrics) {
                 sendError(res, 404, "feature.metrics_disabled", "metrics disabled");
@@ -218,15 +227,12 @@ export function createDispatch(ctx) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions");
             return;
         }
-        if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
-            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;
-        }
-        if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
-            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;
+        if (req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
+            const verdict = readinessOf(deps);
+            if (!verdict.ready) {
+                sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+                return;
+            }
         }
         if (isDestructiveSessionWrite(req.method ?? "", url) && !anyServiceAuth && !deps.config.allowUnauthedWrites) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting destructive session writes (policy / sync-import / fork / delete)");