@sema-agent/server 7.15.0 → 7.16.0-rc.2

package/dist/http/server.js

@@ -3,7 +3,7 @@ import { once } from "node:events";
 import { createHash } from "node:crypto";
 import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, CheckpointError, HAND_TOOL_EFFECTS, RETIRED_TOOL_NAMES, defaultTaskRegistry, validatePendingSteer, subscribeWorkflow, GLOBAL_USAGE_KEY, usageRetryAfterMs } from "@sema-agent/core";
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
-import { matchCatalogModel } from "../model-select.js";
+import { isModelAllowlisted, matchCatalogModel } from "../model-select.js";
 import {} from "../config-center/facade.js";
 import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, isDestructiveSessionWrite, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
 import { verifyDirectDoorProof } from "../principal-jwt.js";
@@ -117,6 +117,13 @@ const MAX_IMAGE_BASE64_BYTES = 6 * 1024 * 1024; // a single inline image's base6
 // name is never mounted, so keeping it here would let the pre-check claim satisfiability for a tool that
 // cannot exist (same derivation hygiene as hands-lane.ts HANDS_BAND_TOOL_NAMES).
 const HAND_TOOL_NAMES = Object.keys(HAND_TOOL_EFFECTS).filter((n) => !RETIRED_TOOL_NAMES.has(n));
+/** #233 / A-002.8 —— 未知模型 400 里 `available` 列表的**名单过滤**:不给用户广告他点不了的模型。
+ *  名单缺席/空 ⇒ 与本件之前逐字同集(全目录去 `default` 别名);名单在场 ⇒ 只留名单准的那些。
+ *  判定单源 `isModelAllowlisted`(与三个执法点同一只),所以"列出来的"与"点了不被拒的"恒为同一批。 */
+function mentionableNames(config, catalog) {
+    const allowlist = config.atModelAllowlist ?? [];
+    return Object.keys(catalog).filter((n) => n !== "default" && isModelAllowlisted(n, catalog, allowlist));
+}
 /** [1245] codex-3/4 — the REOPEN-class resume failures: core's runtask reopened the checkpoint (store.reopen,
  *  dist-read) BEFORE returning this failed result, so the park is STILL PENDING and decidable. Everything
  *  downstream must treat these as a re-park, never terminal: the durable event log writes `suspended` (not
@@ -125,6 +132,37 @@ const HAND_TOOL_NAMES = Object.keys(HAND_TOOL_EFFECTS).filter((n) => !RETIRED_TO
 function isCheckpointReopenedFailure(r) {
     return r.status === "failed" && (r.errorCode === "resume.env_failed" || r.errorCode === "resume.tool_unavailable");
 }
+/**
+ * 一条 verify/cascade 腿的结果**是不是嵌套 durable park**,以及 park 落在哪个词上(扫描P2 + codex 复审
+ * round1 [high] 一,2026-08-12 亲读 core 验真)。`undefined` = 不是 park(照常走终局)。
+ *
+ * 🔴 判据是 **errorCode**,不是 `verification.unverifiedReason` —— 后者**不覆盖修复轮**:
+ *  · `verify.js:201/208`(runWithVerification / resumeWithVerification 的**立即** park)铸的 outcome 带
+ *    `unverifiedReason: status === "needs_review" ? "needs_review" : "suspended"`;
+ *  · 但 `verify.js:191`(verifier 判 FAIL 后的**修复轮** `runTask` 又停在门上)返回的是
+ *    `{ ...mapNestedSuspend(current), verification: outcome }`,那个 `outcome` 是**上一轮验证器的
+ *    FAIL 判决** —— `verdict:"FAIL"` 的臂根本不填 `unverifiedReason`(`verify.js:166` 只在
+ *    no_verdict / PARTIAL 两种情况填)。于是「按 reason 判 park」对修复轮恒为假,而结果里
+ *    checkpointToken 还活着 ⇒ 写 `done` + setTerminal ⇒ 释放 task_active 锁 + 孤儿化那张卡。
+ *
+ * `mapNestedSuspend`(core `agents/suspend-guard.js`)是**每一条**嵌套 park 的必经点,它无条件盖这两个
+ * 码之一,并且码本身就带 park 的词 —— 所以它同时是「是不是 park」和「是哪个 park」的单一真源。
+ * 两个字面量在 core 的 index 里没有导出,只能照字面锚(与 `runs.ts` / `resource-suspend.ts` 顶注同姿势)。
+ *
+ * ⚠️ 边界:`checkpoint.reopen_failed` 与 `resume.*` 两类 reopen 失败**不在**这里(它们不是 gate 再停,
+ * 由 {@link isCheckpointReopenedFailure} + 店内复核那条腿处置);`verifier_paused` 也不在(那是验证器
+ * 自己的会话与凭据,本 run 的活已经做完)。
+ */
+function nestedParkStatusOf(r) {
+    switch (r.errorCode) {
+        case "unexpected.needs_review": // core UNEXPECTED_NEEDS_REVIEW —— 内层 status 是 needs_review 的 park
+            return "needs_review";
+        case "unexpected.suspended": // core UNEXPECTED_SUSPENDED —— 内层 status 是 suspended 的 park
+            return "suspended";
+        default:
+            return undefined;
+    }
+}
 /** The TRUSTED end-user principal for an owner-gated / per-tenant request. On a direct-door worker the
  *  trusted-header path is OFF (x-agent-principal is client-spoofable), so identity comes from the crypto-VERIFIED
  *  principal JWT (`x-approval-principal-token`, principal-only proof — no cnf.bnd action binding); otherwise the
@@ -1191,7 +1229,7 @@ export function createHttpServer(rawDeps) {
             const bare = deps.config.models ?? {}; // 防御:极简 stub deps 可无 models 域(真 loadConfig 恒有)
             const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
             if (matchCatalogModel(body.model, catalog) === undefined) {
-                sendError(res, 400, "request.unknown_reference", `unknown model "${body.model.slice(0, 120)}" — not in the configured catalog (name, tier word, or id)`, { available: Object.keys(catalog).filter((n) => n !== "default") });
+                sendError(res, 400, "request.unknown_reference", `unknown model "${body.model.slice(0, 120)}" — not in the configured catalog (name, tier word, or id)`, { available: mentionableNames(deps.config, catalog) });
                 return null;
             }
         }
@@ -1207,7 +1245,7 @@ export function createHttpServer(rawDeps) {
             const bare = deps.config.models ?? {};
             const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
             if (matchCatalogModel(body.compactionModel, catalog) === undefined) {
-                sendError(res, 400, "request.unknown_reference", `unknown compactionModel "${body.compactionModel.slice(0, 120)}" — not in the configured catalog (name, tier word, or id)`, { available: Object.keys(catalog).filter((n) => n !== "default") });
+                sendError(res, 400, "request.unknown_reference", `unknown compactionModel "${body.compactionModel.slice(0, 120)}" — not in the configured catalog (name, tier word, or id)`, { available: mentionableNames(deps.config, catalog) });
                 return null;
             }
         }
@@ -1384,9 +1422,15 @@ export function createHttpServer(rawDeps) {
         if (!isApprovalGateKind(decideGateKind)) { // A-002.1 单一属主
             // [2400] HITL-6(clay 裁 2026-08-03,不做兼容):补机读指路——与 [2255]① 的 409 材料同形
             // (pendingGate{kind, decidePath},resumeEntryForGate 单源表),客户端凭 decidePath 直达对的
-            // resume 入口,不再解析人话文案。taskId 源=cp.sourceTaskId;缺席 ⇒ 只带 kind,诚实不铸假路径。
-            const gnPath = decideGateKind && cp.sourceTaskId
-                ? resumeEntryForGate(decideGateKind, { sessionId, taskId: cp.sourceTaskId })
+            // resume 入口,不再解析人话文案。taskId 源=账本活行(getActiveTaskId,与 active-run-conflict.ts
+            // 的 409 材料同源)——cp.sourceTaskId 是 core 契约里 issuing worker 的 **session id**(ECHO-ONLY
+            // triage,checkpoint-store.d.ts),拿它当 run taskId 铸路径=打出去必 404([3683]-1 同病族,
+            // 扫描 P1 修)。账本无活行 ⇒ 只带 kind,诚实不铸假路径。
+            const activeForPath = decideGateKind
+                ? await deps.runStore?.getActiveTaskId(sessionId).catch(() => undefined)
+                : undefined;
+            const gnPath = decideGateKind && activeForPath
+                ? resumeEntryForGate(decideGateKind, { sessionId, taskId: activeForPath })
                 : null;
             return {
                 status: 409,
@@ -1811,11 +1855,20 @@ export function createHttpServer(rawDeps) {
                     const vr = await resumeWithVerification(legRunner, token, outcome, { ...taskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds); // 快审 F1:整对象直传
                     let safe = stripCheckpointToken(vr);
                     // 🔴 A re-suspend on a LATER gate is NOT terminal: core maps it to status:"failed" +
-                    // verification.unverifiedReason:"suspended" with the checkpoint token still live. Treat it exactly like
-                    // the stream path's suspended branch — write a "suspended" event and return status:"suspended" so the
-                    // outer block calls setSuspended (keeps the session lock + resumable row). Driving it terminal would
-                    // release the lock and orphan the second checkpoint (next /decide → 409, task abandoned).
-                    const reSuspended = vr.verification?.unverifiedReason === "suspended";
+                    // verification.unverifiedReason with the checkpoint token still live. Treat it exactly like
+                    // the stream path's park branches — write the matching park event and return the park status so the
+                    // outer block calls setSuspended/setNeedsReview (keeps the session lock + resumable row). Driving it
+                    // terminal would release the lock and orphan the second checkpoint (next /decide → 409, task abandoned).
+                    //
+                    // 🔴 park 是**两个词**(扫描P2,status/kind 同名词混淆病族),而且判据必须取 **errorCode** 而不是
+                    // `verification.unverifiedReason` —— 完整理由(含修复轮那条 reason 恒缺席的腿)见
+                    // {@link nestedParkStatusOf} 的顶注,它是这条判据的唯一属主。只认 `unverifiedReason === "suspended"`
+                    // 会漏掉两类真 park:plan_review / dry_run 的 `needs_review` 再停,以及 verifier 判 FAIL 后修复轮
+                    // 的**任一**再停 —— 两类都会被写成 `done` + setTerminal:锁被释放、活卡成孤儿。
+                    // ⚠️ `verifier_paused` 不进这个集合:那是**验证器自己**的会话/凭据(见 core `VerificationOutcome
+                    // .verifierPause`),本 run 的活已经做完,与「本 run 再停在自己的门上」是两件事。
+                    const reParkStatus = nestedParkStatusOf(vr);
+                    const reSuspended = reParkStatus !== undefined;
                     // [1245] codex-4: reopen-class twin of the stream path (store-confirmed, codex-5) — the checkpoint
                     // is pending again, so the durable log must record a park, never `done` (the outer row drive
                     // re-parks via checkpointReopened; the response keeps status:"failed"+retriable, unlike reSuspended
@@ -1834,7 +1887,8 @@ export function createHttpServer(rawDeps) {
                             await appendPromptManifest(ap, deps.promptManifests, taskId); // [998]②: the verified-resume leg has no stream — persist the re-fired manifest before its terminal/suspend event
                             if (reSuspended || vrReopened) {
                                 await appendModelUsageDelta(ap, deps.modelUsage, taskId); // E8: persist pre-re-suspend per-model usage
-                                await ap("suspended", { gate: vr.checkpointGate ?? null, ...(vrReopened ? { reopened: vr.errorCode ?? null } : {}) });
+                                // reopen 腿恒落 `suspended`(它不是 gate 再停,是同一张卡被重开);reSuspended 腿按真 park 词落名。
+                                await ap(reSuspended ? reParkStatus : "suspended", { gate: vr.checkpointGate ?? null, ...(vrReopened ? { reopened: vr.errorCode ?? null } : {}) });
                             }
                             else {
                                 // E8: this verified-resume leg is the run's final done → flush the last delta + SUM model_usage into stats.modelUsage
@@ -1848,7 +1902,7 @@ export function createHttpServer(rawDeps) {
                         }
                     }
                     if (reSuspended)
-                        return { ...safe, status: "suspended" };
+                        return { ...safe, status: reParkStatus };
                     // Count the gate verdict only when the verifier actually ran (a re-suspend never reached it).
                     if (vr.verification?.verdict)
                         deps.metrics?.inc("verifications_total", { verdict: vr.verification.verdict });

package/dist/leader/fanout.d.ts

@@ -98,6 +98,24 @@ export interface FanOutResult {
     /** True if the overall deadline fired and cancelAll ran. */
     cancelled: boolean;
 }
+/**
+ * 「这条 worker 的 TaskResult 停在门上(durable park)了吗」——`TaskStatus` 的穷举判据。
+ *
+ * 🔴 park 是**两个词**(扫描P2,status/kind 同名词混淆病族):`suspended`(工具审批 / human /
+ * resource_limit 门)与 `needs_review`(`plan_review` 与 dry-run 拦截门)。真源 = core
+ * `agents/suspend-guard.js` 的 `isDurablePause`(逐字 `status === "suspended" || status === "needs_review"`),
+ * `mapNestedSuspend` / `verify.js` 的 `unverifiedReason` 两处都按这张表分词。
+ *
+ * 只认 `suspended` 的后果不是「少一个标签」:一条 plan_review 停下的 worker 会被报成 `failed` ⇒
+ * fanOut 的 C4 抢占({@link FanOutOptions.cancelOnSuspend})不触发(其余 worker 继续烧钱)、leader 的
+ * replan「suspended 波」看不见它、`suspendedSessions` 的豁免名单漏掉它 ⇒ 它那张还能被决议的 checkpoint
+ * 与暂停中的环境会被当失败清掉。带验证器的那条腿早已改用「还带着 checkpointToken 就是 park」的判据
+ * (leader.ts round-3 review BLOCKER),这里是它当时漏掉的另外半场。
+ *
+ * `never` 收敛 = core `TaskStatus` 增删成员的**编译期**执行点(同 `store-contracts.ts` 两条判据的姿势);
+ * 运行时未知词保守判**非 park**(与既有 `else → failed` 同行为,不静默扩大 park 面)。
+ */
+export declare function isDurablePauseStatus(s: TaskResult["status"]): boolean;
 /**
  * Fan out `subtasks` in parallel. Never throws — every worker resolves to a WorkerReport (failures captured).
  * The caller (Coordinator) merges only `status==="completed"` reports.

package/dist/leader/fanout.js

@@ -19,8 +19,41 @@ class Semaphore {
         }
     }
 }
+/**
+ * 「这条 worker 的 TaskResult 停在门上(durable park)了吗」——`TaskStatus` 的穷举判据。
+ *
+ * 🔴 park 是**两个词**(扫描P2,status/kind 同名词混淆病族):`suspended`(工具审批 / human /
+ * resource_limit 门)与 `needs_review`(`plan_review` 与 dry-run 拦截门)。真源 = core
+ * `agents/suspend-guard.js` 的 `isDurablePause`(逐字 `status === "suspended" || status === "needs_review"`),
+ * `mapNestedSuspend` / `verify.js` 的 `unverifiedReason` 两处都按这张表分词。
+ *
+ * 只认 `suspended` 的后果不是「少一个标签」:一条 plan_review 停下的 worker 会被报成 `failed` ⇒
+ * fanOut 的 C4 抢占({@link FanOutOptions.cancelOnSuspend})不触发(其余 worker 继续烧钱)、leader 的
+ * replan「suspended 波」看不见它、`suspendedSessions` 的豁免名单漏掉它 ⇒ 它那张还能被决议的 checkpoint
+ * 与暂停中的环境会被当失败清掉。带验证器的那条腿早已改用「还带着 checkpointToken 就是 park」的判据
+ * (leader.ts round-3 review BLOCKER),这里是它当时漏掉的另外半场。
+ *
+ * `never` 收敛 = core `TaskStatus` 增删成员的**编译期**执行点(同 `store-contracts.ts` 两条判据的姿势);
+ * 运行时未知词保守判**非 park**(与既有 `else → failed` 同行为,不静默扩大 park 面)。
+ */
+export function isDurablePauseStatus(s) {
+    switch (s) {
+        case "suspended":
+        case "needs_review":
+            return true;
+        case "completed":
+        case "failed":
+        case "blocked":
+            return false;
+        default: {
+            const unhandled = s;
+            void unhandled;
+            return false;
+        }
+    }
+}
 function mapStatus(s) {
-    return s === "completed" ? "completed" : s === "suspended" ? "suspended" : "failed";
+    return s === "completed" ? "completed" : isDurablePauseStatus(s) ? "suspended" : "failed";
 }
 /**
  * Fan out `subtasks` in parallel. Never throws — every worker resolves to a WorkerReport (failures captured).

package/dist/leader/leader.js

@@ -12,7 +12,7 @@
  * Deps injected → mock-tested; the real-infra wiring (E2B envs + deepseek runners + git push) lives in the
  * joint dogfood, which this generalizes.
  */
-import { fanOut } from "./fanout.js";
+import { fanOut, isDurablePauseStatus } from "./fanout.js";
 import { pullDiff } from "./diffout.js";
 import { mergeBranches } from "./merge.js";
 import { Runner, runWithVerification, resumeWithVerification, delimitUntrusted } from "@sema-agent/core";
@@ -105,10 +105,14 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                         }
                         return {
                             ...base,
-                            // Map the TaskResult status directly (like fanOut's own mapStatus) — a `suspended` result that the
-                            // auto-resume left unresumed (a non-resource gate, e.g. human-approval) stays `suspended` so the
-                            // leader's C4 surface/cancel reaction still fires; only completed/timeout pass through, else failed.
-                            status: r.status === "completed" ? "completed" : r.status === "suspended" ? "suspended" : "failed", // core 5.8.0:TaskResult 无 "timeout"(内部词表的 timeout 仍由 fanout 墙钟臂生产)
+                            // Map the TaskResult status directly (like fanOut's own mapStatus) — a durably PARKED result that
+                            // the auto-resume left unresumed (a non-resource gate, e.g. human-approval or a plan review) stays
+                            // `suspended` so the leader's C4 surface/cancel reaction still fires; only completed/timeout pass
+                            // through, else failed. 🔴 park 的判据取自 `fanout.ts` 的 `isDurablePauseStatus`(扫描P2):
+                            // 原地手抄的 `=== "suspended"` 漏掉 `needs_review`(plan_review / dry-run 门),会把一条还
+                            // 拿着 checkpoint、环境还暂停着的 worker 报成 failed —— 与本文件带验证器那条腿早就修过的
+                            // 是同一个缺陷(round-3 review BLOCKER),当时只修了那半场。
+                            status: r.status === "completed" ? "completed" : isDurablePauseStatus(r.status) ? "suspended" : "failed", // core 5.8.0:TaskResult 无 "timeout"(内部词表的 timeout 仍由 fanout 墙钟臂生产)
                             stats: r.stats,
                             ...(r.status === "completed" ? {} : { error: r.errorMessage ?? r.blockedReason ?? `worker ${r.status}` }),
                             ...(r.checkpointGate ? { checkpointGate: r.checkpointGate } : {}),

package/dist/leader/wire.js

@@ -25,6 +25,7 @@ import { pullDiff, safeRev } from "./diffout.js";
 import { runLeaderTask } from "./leader.js";
 import { attachRepairLoopDeps } from "./repair-wire.js";
 import { routePlanWithFallback, validateSubtasks } from "./planner.js";
+import { createEngineNoticeSeat } from "../boot/runner-deps.js";
 /** The single-agent `runRepairLoop` is now WIRED LIVE (the canary-enable slice): when `LEADER_REPAIR_LOOP=true`
  *  the wire provisions a DEDICATED oracle-seeded grader sandbox per solo worker and attaches a real async
  *  `resolve` to `attachRepairLoopDeps` (below). With this `true`, flipping `LEADER_REPAIR_LOOP` engages BOTH the
@@ -245,6 +246,16 @@ export function createLeaderRunner(cfg) {
     const ident = cfg.git ?? { name: "leader", email: "leader@local" };
     const { leaderTimeoutMs, workerLimits, presignTtlSec, resourceSuspend: resourceCfg } = leaderResourceConfig();
     const { repairRounds, repairBudgetUsd, conflictRounds, repairLoopOn, measureGatesOn, repairLoopAttempts, oracleFlakyK, replanBudgetUsd, } = leaderLoopConfig({ repairRounds: cfg.repairRounds, conflictRounds: cfg.conflictRounds });
+    // #240② onNotice 席(合并码重扫):本车道的每一只 Runner 都要带,否则 core 的引擎通告在这条腿上落回
+    // 裸 `console.warn`(主车道进结构化 `engine_notice` 行)—— 同一部署两条通告通道,按 code 采集的运维面
+    // 只看得见一半。转发体取共享基座的**那一个**具名导出,禁在这里另写一份(两份必漂)。
+    // ⚠️ 判据是 `warn` **在场**,不是 `cfg.logger` 在场:leader 的 logger 两格都可选,只装了 `info` 的部署
+    // 铸这一席等于把通告吞掉 —— 那比不铸还坏(不铸时 core 至少还打自己的 `console.warn`)。
+    // 🔴 这条判据现在**整条住在** `createEngineNoticeSeat` 里(codex 复审 R1-[medium],验真后修):此前它是
+    // 这里的一行三元,于是只能靠「扫这段源码文本里有没有 `warn`」去守,而 `cfg.logger ? ((m,x)=>cfg.logger?.warn?.(m,x)) : undefined`
+    // 这一族变异**文本上照样有 `warn`**、值上却是 truthy 闭包(info-only 部署照铸席、通告被可选链吞掉)。
+    // 搬进函数之后判据可被**行为**测,门不再是关键字搜索。
+    const onNoticeSeat = createEngineNoticeSeat(cfg.logger);
     // worker resource bounds (limits/maxCostUsd) + presign ttl are derived in leaderResourceConfig(), above.
     // Bounded integration-repair (search 2026-06-14): when the merged tree compiles-clean-but-fails, run a strong
     // agent WITH HANDS in the live merged sandbox to fix the cross-worker integration, then mergeBranches re-runs
@@ -271,7 +282,7 @@ export function createLeaderRunner(cfg) {
                     // rootPath: repoDir (Codex review #4) — without it core roots the file tools at executionEnv.cwd
                     // (/workspace on Kata), one level above the repo (/workspace/repo). bash can cd, but the dedicated
                     // read/edit tools would start too high + lose containment.
-                    const runner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, executionEnv: rawEnv, rootPath: repoDir });
+                    const runner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...onNoticeSeat, executionEnv: rawEnv, rootPath: repoDir });
                     const objective = [
                         `The integrated project at ${repoDir} fails its build/test. Make the MINIMAL change to the working tree so this command exits 0 (cd into the repo and run it yourself to confirm):`,
                         `  ${testCmd}`,
@@ -327,7 +338,7 @@ export function createLeaderRunner(cfg) {
                         throw new Error(`oracle still present after remove (${f.path}) — refusing conflict-resolve (measurement integrity)`);
                 }
                 try {
-                    const runner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, executionEnv: rawEnv, rootPath: repoDir });
+                    const runner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...onNoticeSeat, executionEnv: rawEnv, rootPath: repoDir });
                     const objective = [
                         `A parallel worker '${workerId}' ported a module on its own branch, but applying its patch onto the already-integrated tree at ${repoDir} produced a MERGE CONFLICT (git apply --3way). The OTHER workers' patches already applied cleanly — integrate THIS worker's changes too, resolving the overlap.`,
                         `Resolve EVERY conflict in the working tree: open each file containing conflict markers (<<<<<<< / ======= / >>>>>>>) and merge BOTH sides' real intent (keep both workers' behaviour — never drop one side just to make it apply). Then apply any rejected hunks recorded in *.rej files by hand, and DELETE every *.rej and *.orig file.`,
@@ -415,7 +426,7 @@ export function createLeaderRunner(cfg) {
                 // the Coordinator's parallel merge relies on. Was a straight map() that skipped all of it.
                 return validateSubtasks(body.subtasks);
             }
-            const planRunner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing });
+            const planRunner = new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...onNoticeSeat });
             const runRoute = async (prompt) => {
                 const res = await planRunner.runTaskStream({
                     objective: prompt,
@@ -566,7 +577,7 @@ export function createLeaderRunner(cfg) {
                     workerId: sub.workerId, sessionId, branch: sub.branch,
                     baseSha, // seedCmd reproduces the durable base — same sha for every worker
                     runner: keepCtxWarm(new Runner({
-                        brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing,
+                        brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...onNoticeSeat,
                         ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}),
                         ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}),
                         executionEnvFactory: (ctx) => withStaging(envFactory(ctx), stage, async (e) => {
@@ -589,7 +600,7 @@ export function createLeaderRunner(cfg) {
             const baseSha = await sh(env)(`cd ${repo} && git rev-parse HEAD`);
             return {
                 workerId: sub.workerId, sessionId, branch: sub.branch, baseSha,
-                runner: keepCtxWarm(new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env })),
+                runner: keepCtxWarm(new Runner({ brain: cfg.brain, models: cfg.models, roles: cfg.roles, pricing: cfg.pricing, ...onNoticeSeat, ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env })),
                 diffEnv: env,
                 destroy: () => env.destroy().then(() => { }),
                 spec: { ...workerLimits, ...sub.spec, ...durableSpec, ...resourceSpec },

package/dist/main.js

@@ -443,6 +443,7 @@ async function main() {
         // 基座只有一份)。差异键在展开后显式列出,每个都有为何不同的理由(见 boot/runner-deps.ts 头注)。
         ...createSharedRunnerDeps({
             config,
+            logger, // #240②:onNotice 席落共享基座 ⇒ 两 Runner 同源(EngineNotice→logger.warn)
             hands: commitHands, // 交接件⑤:与主 runner 同一个值(基座保证同源)
             brain,
             pricing,

package/dist/model-select.d.ts

@@ -23,11 +23,53 @@
  * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
  * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
  */
-export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>): {
+export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, allowlist?: readonly string[]): {
     model: string;
     cleanedObjective: string;
     unknownExplicit?: string;
+    notAllowed?: ModelNotAllowed;
 };
+/** #233 判别式拒因:名单在场且这次**用户选择**落在名单外。`resolved` 已是目录 name 形(归一后)。 */
+export interface ModelNotAllowed {
+    /** 调用方发来的原始 ref(name / 档位词 / 别名 / id / `@name`),已做过日志安全的 repr 归一。 */
+    requested: string;
+    /** 归一到的目录 name(即这次真会跑的模型)。 */
+    resolved: string;
+    /** 走的是哪条用户通道:`explicit`=body.model/settings.model,`mention`=objective 内联 `@name`。 */
+    source: "explicit" | "mention";
+}
+/**
+ * #233 / A-002.8 —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
+ *
+ * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
+ * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 绕过一张按 name 写的名单
+ * (同一只模型,两个键)。所以两边(ref 与每个名单条目)都先经 {@link matchCatalogModel} 解到目录条目,
+ * 再按 **引用相等** 判同。id 形的 ref 不需要特别处理:`matchCatalogModel` 本身就是 name+id 双键索引,
+ * 它会把 id 解成目录键,引用相等接着就对上了。
+ *
+ * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high],已采纳):目录**允许两条不同 name 的条目共享
+ * 同一个上游 `Model.id`,却各自带不同的 `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 那正是多网关、
+ * 多账号部署形。按 id 判同会把 `safe` 与 `premium` 合并,于是一张只含 `safe` 的名单会放行 `premium`,
+ * 而真正执行的是 `premium` 那份坐标与计费。判据只认**目录条目本身**:两条条目就是两只模型,哪怕上游
+ * id 撞车。(引用相等因此不是"优化",是唯一正确的判据;它天然覆盖 tier 词/别名/id 三形。)
+ *
+ * 缺席/空名单 ⇒ 恒 `true`(ship-dark:缺省 = 旧行为,全放行)。
+ * 目录里根本没有的 ref ⇒ 恒 `true`:那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),
+ * 本门只答「在目录里,但准不准点」——两道门同码同拒会让消费端分不清"没这模型"和"不让你点"。
+ *
+ * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator
+ * 配置自己走,**不经本门**——那不是一次用户选择,如实声明,不假装是运行时执法。
+ */
+export declare function isModelAllowlisted(ref: string, catalog: Record<string, unknown>, allowlist: readonly string[] | undefined): boolean;
+/**
+ * #233 —— ref → **终端 catalog name**(拒因/日志的可读形)。
+ *
+ * 为什么不是 `matchCatalogModel` 的返回值:增广目录里 `pro`/`opus`/`default` 都是**真实存在的键**,
+ * 于是 `matchCatalogModel("pro")` 回的就是 `"pro"` —— 那是用户点的那个别名,不是他真会跑的模型。
+ * 取条目自己的 `Model.name`(applyEffective 建目录时 `models[m.name].name === m.name`,env lane 同)
+ * 才是终端名;拿不到时如实退回匹配键(诚实缺席,不猜)。
+ */
+export declare function terminalCatalogName(ref: string, catalog: Record<string, unknown>): string | undefined;
 /**
  * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
  *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸

package/dist/model-select.js

@@ -24,7 +24,7 @@ import { parseModelMention } from "@sema-agent/core";
  * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
  * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
  */
-export function resolveTaskModel(bodyModel, objective, catalog) {
+export function resolveTaskModel(bodyModel, objective, catalog, allowlist) {
     const mention = parseModelMention(objective, Object.keys(catalog));
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog) : undefined;
     // 未匹配的「在场」ref 一律透出(codex L1:历史 checkpoint 里的空串/非字符串 model 在 RESUME 重放也不许
@@ -32,12 +32,80 @@ export function resolveTaskModel(bodyModel, objective, catalog) {
     const present = bodyModel !== undefined && bodyModel !== null;
     const unknown = present && explicit === undefined;
     const repr = typeof bodyModel !== "string" ? `<non-string:${typeof bodyModel}>` : bodyModel === "" ? "<empty-string>" : bodyModel;
+    const model = explicit ?? mention.model ?? "default";
+    // #233 / A-002.8:名单只裁**用户逐 turn 选择通道**——显式 ref(body.model / settings.model)与 objective
+    // 内联 `@name`。两者都缺席时落 `default`(operator 配置通道),本门**不碰**:名单管"用户可点什么",
+    // 不管"operator 配什么"(registry-core 也只校验名单 ⊆ catalog,从不要求 default ∈ 名单)。
+    // 不 throw:resume 重放持久化 body 不过 HTTP 门,砖死 resume 比降级糟(本文件 [865]② 同判据)——
+    // 判别式拒因交给调用点按 leg 分流(fresh 400 / resume warn 续跑)。
+    const picked = explicit !== undefined ? { ref: explicit, source: "explicit", requested: repr } : mention.model !== undefined ? { ref: mention.model, source: "mention", requested: mention.model } : undefined;
+    const notAllowed = picked !== undefined && !isModelAllowlisted(picked.ref, catalog, allowlist)
+        ? { requested: picked.requested, resolved: terminalCatalogName(picked.ref, catalog) ?? picked.ref, source: picked.source }
+        : undefined;
     return {
-        model: explicit ?? mention.model ?? "default",
+        model,
         cleanedObjective: mention.cleanedText || objective,
         ...(unknown ? { unknownExplicit: repr } : {}),
+        ...(notAllowed ? { notAllowed } : {}),
     };
 }
+/**
+ * #233 / A-002.8 —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
+ *
+ * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
+ * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 绕过一张按 name 写的名单
+ * (同一只模型,两个键)。所以两边(ref 与每个名单条目)都先经 {@link matchCatalogModel} 解到目录条目,
+ * 再按 **引用相等** 判同。id 形的 ref 不需要特别处理:`matchCatalogModel` 本身就是 name+id 双键索引,
+ * 它会把 id 解成目录键,引用相等接着就对上了。
+ *
+ * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high],已采纳):目录**允许两条不同 name 的条目共享
+ * 同一个上游 `Model.id`,却各自带不同的 `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 那正是多网关、
+ * 多账号部署形。按 id 判同会把 `safe` 与 `premium` 合并,于是一张只含 `safe` 的名单会放行 `premium`,
+ * 而真正执行的是 `premium` 那份坐标与计费。判据只认**目录条目本身**:两条条目就是两只模型,哪怕上游
+ * id 撞车。(引用相等因此不是"优化",是唯一正确的判据;它天然覆盖 tier 词/别名/id 三形。)
+ *
+ * 缺席/空名单 ⇒ 恒 `true`(ship-dark:缺省 = 旧行为,全放行)。
+ * 目录里根本没有的 ref ⇒ 恒 `true`:那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),
+ * 本门只答「在目录里,但准不准点」——两道门同码同拒会让消费端分不清"没这模型"和"不让你点"。
+ *
+ * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator
+ * 配置自己走,**不经本门**——那不是一次用户选择,如实声明,不假装是运行时执法。
+ */
+export function isModelAllowlisted(ref, catalog, allowlist) {
+    if (allowlist === undefined || allowlist.length === 0)
+        return true;
+    const entry = catalogEntryOf(ref, catalog);
+    if (entry === undefined)
+        return true;
+    for (const name of allowlist) {
+        const allowed = catalogEntryOf(name, catalog);
+        if (allowed === undefined)
+            continue; // 悬空/不可解名单条目(apply 期已 warn):它准不了任何东西
+        if (allowed === entry)
+            return true; // 引用相等 —— 增广目录里 tier 词/别名/id 最终都落到这同一只条目
+    }
+    return false;
+}
+/** ref(name / 档位词 / 别名 / id)→ 它在目录里的**条目对象**;未知 ⇒ undefined。 */
+function catalogEntryOf(ref, catalog) {
+    const name = matchCatalogModel(ref, catalog);
+    return name === undefined ? undefined : catalog[name];
+}
+/**
+ * #233 —— ref → **终端 catalog name**(拒因/日志的可读形)。
+ *
+ * 为什么不是 `matchCatalogModel` 的返回值:增广目录里 `pro`/`opus`/`default` 都是**真实存在的键**,
+ * 于是 `matchCatalogModel("pro")` 回的就是 `"pro"` —— 那是用户点的那个别名,不是他真会跑的模型。
+ * 取条目自己的 `Model.name`(applyEffective 建目录时 `models[m.name].name === m.name`,env lane 同)
+ * 才是终端名;拿不到时如实退回匹配键(诚实缺席,不猜)。
+ */
+export function terminalCatalogName(ref, catalog) {
+    const key = matchCatalogModel(ref, catalog);
+    if (key === undefined)
+        return undefined;
+    const name = catalog[key]?.name;
+    return typeof name === "string" && name.length > 0 ? name : key;
+}
 /**
  * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
  *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸

package/dist/observability/fail-open.d.ts

@@ -49,6 +49,14 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "CC 规则导入票的**认领回滚**失败(认领之后的某一步没成 ⇒ 本该把认领放回去,而这次放回本身也抛了)。放行的最坏后果 = 这张票留在已认领态、属主这一轮不能重试 —— 恰好等于加认领回滚**之前**的行为,不是新损失;票随 TTL 自然消失,属主重走一次 prepare 即可拿新票(导入按 core 的设计幂等:同一条规则再兑付只是同一个 dot 的重放)。方向上没有任何权限被放宽(规则**没有**落地才走到这条臂),故 F 类;必须留痕,否则「票为什么突然不能用了」在遥测里没有任何痕迹。";
     };
+    readonly "server.approvals.rule-suggestions-cell-unreadable": {
+        readonly cls: "F";
+        readonly note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.rule_suggestions` 这一格**不是合法 JSON 文本**(手改过的行 / 未来列语义漂了 / 回滚残留)。放行的最坏后果 = **这一行**的「不再询问」候选缺席(展示/分诊材料,永不参与 resume、也不是任何判据),队列其余部分照常;不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空)。故 F 类,但必须留痕:静默吞掉之后「候选为什么消失了」在遥测里没有任何痕迹,而本键存在的全部理由就是「缺席 = 真的没有候选」。";
+    };
+    readonly "server.approvals.risk-descriptor-cell-unreadable": {
+        readonly cls: "F";
+        readonly note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.risk_descriptor` 这一格**不是合法 JSON 文本**(手改过的行 / 回滚残留 / 列语义漂;与同一 `rows.map` 里的 `rule_suggestions` 是同族坏法,两方言都是 TEXT 列)。放行的最坏后果 = **这一行**的分诊 descriptor 落 null:severity 折 0 排到有 descriptor 的行之后、`shadowedRule` 无可脱敏、读面派生的 `governanceForced` 徽章不亮 —— 三者都是**展示/分诊**,不是执法判据(门早已 park,真按 `shellGateDoctrine` 判的 `active-run-conflict.ts` 读的是 checkpoint blob 的 `get()`,不经本读面),且 `governanceForced` 的成文语义本就是「缺席 = 没有治理来源的**证据**」。不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空),连同其余所有行一起消失。故 F 类;tag 与候选那格**分开计**,并计会让「哪一格在坏」在遥测里读不出来。";
+    };
     readonly "server.parked-revive.ancestor-classifier-unreachable": {
         readonly cls: "P-DEBT";
         readonly note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。";

package/dist/observability/fail-open.js

@@ -72,6 +72,14 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "CC 规则导入票的**认领回滚**失败(认领之后的某一步没成 ⇒ 本该把认领放回去,而这次放回本身也抛了)。放行的最坏后果 = 这张票留在已认领态、属主这一轮不能重试 —— 恰好等于加认领回滚**之前**的行为,不是新损失;票随 TTL 自然消失,属主重走一次 prepare 即可拿新票(导入按 core 的设计幂等:同一条规则再兑付只是同一个 dot 的重放)。方向上没有任何权限被放宽(规则**没有**落地才走到这条臂),故 F 类;必须留痕,否则「票为什么突然不能用了」在遥测里没有任何痕迹。",
     },
+    "server.approvals.rule-suggestions-cell-unreadable": {
+        cls: "F",
+        note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.rule_suggestions` 这一格**不是合法 JSON 文本**(手改过的行 / 未来列语义漂了 / 回滚残留)。放行的最坏后果 = **这一行**的「不再询问」候选缺席(展示/分诊材料,永不参与 resume、也不是任何判据),队列其余部分照常;不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空)。故 F 类,但必须留痕:静默吞掉之后「候选为什么消失了」在遥测里没有任何痕迹,而本键存在的全部理由就是「缺席 = 真的没有候选」。",
+    },
+    "server.approvals.risk-descriptor-cell-unreadable": {
+        cls: "F",
+        note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.risk_descriptor` 这一格**不是合法 JSON 文本**(手改过的行 / 回滚残留 / 列语义漂;与同一 `rows.map` 里的 `rule_suggestions` 是同族坏法,两方言都是 TEXT 列)。放行的最坏后果 = **这一行**的分诊 descriptor 落 null:severity 折 0 排到有 descriptor 的行之后、`shadowedRule` 无可脱敏、读面派生的 `governanceForced` 徽章不亮 —— 三者都是**展示/分诊**,不是执法判据(门早已 park,真按 `shellGateDoctrine` 判的 `active-run-conflict.ts` 读的是 checkpoint blob 的 `get()`,不经本读面),且 `governanceForced` 的成文语义本就是「缺席 = 没有治理来源的**证据**」。不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空),连同其余所有行一起消失。故 F 类;tag 与候选那格**分开计**,并计会让「哪一格在坏」在遥测里读不出来。",
+    },
     "server.parked-revive.ancestor-classifier-unreachable": {
         cls: "P-DEBT",
         note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。",

package/dist/observability/metrics.js

@@ -253,6 +253,9 @@ export function createMetrics() {
     m.counter("budget_exceeded_total", "Tasks failed by a budget/limit ceiling, by errorCode");
     m.counter("cost_quota_rejected_total", "Tasks refused because the principal is over its cumulative cost quota");
     m.counter("degraded_total", "Tasks degraded to a cheaper model (1.40), by reason (budget/rate_limit/breaker_open)");
+    // #233 / A-002.8:名单外的模型选择在 **resume 腿**被放行(fresh 提交是 400)。读法:非零 = 还有存量
+    // 会话跑在 @-mention 名单之外 —— 那是刻意的(砖死 resume 比降级糟),但治理面必须看得见它有多少。
+    m.counter("task_model_not_allowlisted_resume_total", "Resumed legs whose model/compactionModel is outside the @-mention allowlist (allowed to keep running by design — the allowlist gates fresh picks only)");
     m.counter("prompt_constitution_total", "Prompt assembly constitution mode per task (core 1.243 提示词主权): steady state = core; provider-assembled/replaced/legacy warrant eyes");
     m.counter("rewind_snapshot_failed_total", "Per-turn rewind file snapshots that failed, by code (too_large = big working tree, expected/benign; other codes warrant eyes)");
     m.counter("verifications_total", "Tasks run through the verification gate (1.44), by final verdict");

package/dist/parent-watch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * #219(黑板 [3617]):引擎 **parent 监视**。
+ *
+ * ## 防的是什么
+ *
+ * 壳(cli/TUI/桌面)自 spawn 引擎的**同机形**里,壳被 SIGKILL(崩溃、`kill -9`、OOM killer)之后没有
+ * 任何清理钩子跑得起来:引擎被 reparent 到 init,**继续活着** —— 占端口、占库连接池、占模型配额,而且
+ * 再没有人会给它发 SIGTERM(T11 的"骑进程组"腿只覆盖信号送得到的形;SIGKILL 那一路本来就无钩)。
+ * 于是引擎给自己装一只**自查**腿:定期问一句"当年生我的那个 pid 还在吗",不在就**自己**走正常停机。
+ *
+ * ## 机制(逐条都是契约)
+ *
+ *  1. **opt-in**:`SEMA_PARENT_PID` 缺席 ⇒ 整件不装配(`boot/shutdown.ts` 连 `createParentWatch` 都不调)。
+ *     存量部署逐字零变化。坏值拒启在 `config.ts` 的 `parentPidEnv()`。
+ *  2. **探活 = `process.kill(pid, 0)`**:0 号信号不投递任何信号,只做"这个 pid 存在吗 + 我能不能给它
+ *     发信号"的检查。两种失败方向**语义相反**,写反了后果不对称:
+ *       · `ESRCH` = 没有这个进程 ⇒ 父**不在**(这是我们要抓的);
+ *       · `EPERM` = 进程**在**,只是本进程无权给它发信号(父跑在另一个 uid 下 —— systemd/su/容器里
+ *         很常见)⇒ **算活着**。把 EPERM 当"不在",每台这种机器上的引擎会在开机后两拍内自杀。
+ *  3. **连续两拍才判死**:单拍抖动(探活恰好撞上一次瞬时错误)不误杀。任何一拍看到"活着"就清零。
+ *  4. **判死后走 `drain`**,即 `boot/shutdown.ts` 里 SIGTERM 用的那一条 `drainThenShutdown` —— in-flight
+ *     run 的结算 / park 语义与人工停机**逐字一致**。本模块自己**从不** `process.exit`。
+ *  5. **interval 必须 unref**:监视腿不得成为"进程本该退出却退不掉"的理由(与 drain tick 刻意不 unref
+ *     的取向相反 —— 那一只 tick 就是停机驱动,这一只只是观察者)。
+ *
+ * ## 已知残余(成文,现版不收窄)
+ *
+ *  · **pid 复用**:两拍窗口(≤30s)内父 pid 被系统复用,探活看到的是新进程,监视会判"父还活着"而不自退。
+ *  · **僵尸父进程**(codex 复审 H,本机 perl fork 实测证实):`kill(pid, 0)` 只证明 **pid 表项**在,不证明
+ *    进程还在跑 —— 父退出但**没被它自己的父进程 wait 回收**时留下 zombie(`ps STAT=Z`),表项还在,于是
+ *    每一拍都判"活着",监视永不触发。触发条件是壳的**上级**不回收子进程(容器里的朴素 PID 1 是典型),
+ *    终端 / launchd / systemd 起的壳不在此列。
+ *
+ * 两条都源于同一个根:`kill(pid, 0)` 是**弱身份**判据。收窄需要一个真身份锚(`process.ppid` 变化、
+ * starttime、pidfd、或壳侧持有型管道),那是**机制换代**而不是参数微调,归设计属主裁。本件在定稿里
+ * 就是**尽力自愈**、不是强一致的父子生命周期绑定 —— 要强一致,该由壳侧开一条持有型管道并在断开时收尸。
+ */
+/** 探活拍频。**固定值,不开 env 旋钮**(设计定稿:有真需求再议,防旋钮增殖)。 */
+export declare const PARENT_WATCH_INTERVAL_MS = 15000;
+export interface ParentWatchDeps {
+    /** 被监视的父 pid(`config.parentPid`,已在 config 层校验为正整数)。 */
+    pid: number;
+    /** 探活 seam:抛错 = 探活失败(`.code` 携 errno)。缺省 = `process.kill(pid, 0)`。
+     *  存在的理由不是"可配置",是 `ESRCH`/`EPERM` 两支在测试里没有确定性的自然触发法。 */
+    probe?: (pid: number) => void;
+    /** 已有停机属主(`closing || draining`)时监视腿站下:一次正在进行的优雅 drain 不该被"父也没了"
+     *  升级成第二信号硬停(那会斩掉 in-flight leg —— 与本件"和人工停机逐字一致"的取向相反)。 */
+    isStopped: () => boolean;
+    /** 判死出口 = SIGTERM 那条 graceful drain。 */
+    drain: () => void;
+    log: (event: string, fields: Record<string, unknown>) => void;
+}
+/** 装配并**立刻**起监视(装配即 `parent_watch_armed`)。返回停机链用的 `stop()`。 */
+export declare function createParentWatch(deps: ParentWatchDeps): {
+    stop(): void;
+};
+//# sourceMappingURL=parent-watch.d.ts.map