@sema-agent/server 7.43.0 → 7.44.0

package/dist/org-memory-admission.js

@@ -2,12 +2,6 @@ import { PrincipalOrgMemoryWire } from "@sema-agent/registry-core";
 import { assertPrincipalShape } from "./security.js";
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const ORG_SCOPE_RE = /^org:\S+$/;
-/**
- * 单机腿:装载 `MEMORY_ORG_DIRECTORY_JSON`(`Record<principal, Record<orgScope, {write?}>>`)。启动期调用,
- * **fail-loud**——任何非法直接 throw 且消息点名坏在哪个键(响亮拒是正确方向:一张半坏的授权表比拒绝
- * 启动更危险)。principal 键复用 {@link assertPrincipalShape}(拒保留哨兵/超长租户名,与所有其它
- * principal 入口同一道闸);scope 键必须是 `org:` 前缀、值必须是仅含可选 `write: boolean` 的 plain object。
- */
 export function parseOrgDirectoryStatic(json) {
     let parsed;
     try {
@@ -21,7 +15,7 @@ export function parseOrgDirectoryStatic(json) {
     }
     const table = new Map();
     for (const [principal, scopesRaw] of Object.entries(parsed)) {
-        assertPrincipalShape(principal); // reserved sentinel / oversized tenant name → throws (same gate as every other principal entry point)
+        assertPrincipalShape(principal);
         if (!isPlainObject(scopesRaw)) {
             throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] must be an object of org scopes`);
         }
@@ -47,10 +41,6 @@ export function parseOrgDirectoryStatic(json) {
     }
     return table;
 }
-/**
- * 建目录:远程腿(fetchSection,per-principal TTL 缓存 + in-flight 去重 + 退避窗 + gen 高水位)或单机腿
- * (staticTable,恒同步成功、无 TTL/退避语义——operator 自证配置面)。两腿互斥,装配点必须恰好给一个。
- */
 export function createOrgMemoryDirectory(opts) {
     if ((opts.fetchSection !== undefined) === (opts.staticTable !== undefined)) {
         throw new Error("createOrgMemoryDirectory requires exactly one of fetchSection or staticTable (both given or both missing)");
@@ -64,8 +54,6 @@ export function createOrgMemoryDirectory(opts) {
         };
     }
     if (opts.fetchSection === undefined) {
-        // Unreachable given the xor guard above (staticTable was undefined, so fetchSection must not be) — this
-        // check exists ONLY so the type checker narrows fetchSection to a function without a cast.
         throw new Error("createOrgMemoryDirectory: fetchSection missing (invariant violated)");
     }
     const fetchSection = opts.fetchSection;
@@ -76,7 +64,6 @@ export function createOrgMemoryDirectory(opts) {
     const inflight = new Map();
     function markUnavailable(state, reason) {
         state.unavailable = { until: now() + backoffMs, reason };
-        // C6: retryAfterMs never 0/negative — the window just opened, so its remaining time IS backoffMs.
         return { kind: "unavailable", reason, retryAfterMs: Math.max(backoffMs, 1000) };
     }
     async function doFetch(principal, state) {
@@ -91,17 +78,14 @@ export function createOrgMemoryDirectory(opts) {
             return markUnavailable(state, "section_absent");
         const parsed = PrincipalOrgMemoryWire.safeParse(raw);
         if (!parsed.success) {
-            // malformed: does NOT touch state.grant — a bad shape must not refresh (or clear) an existing granted entry's
-            // timestamp; a still-fresh old grant keeps serving from cache on the NEXT lookup (checked before we ever get here).
             return markUnavailable(state, "malformed");
         }
         if (state.highWaterGen !== undefined && parsed.data.gen < state.highWaterGen) {
-            // LB stale-replica defense: an older generation than one we've already seen is NEVER adopted.
             return markUnavailable(state, "stale_generation");
         }
         state.highWaterGen = parsed.data.gen;
         state.grant = { scopes: parsed.data.scopes, at: now() };
-        delete state.unavailable; // a real success clears any prior backoff window
+        delete state.unavailable;
         return { kind: "granted", scopes: parsed.data.scopes };
     }
     return {
@@ -112,15 +96,12 @@ export function createOrgMemoryDirectory(opts) {
                 states.set(principal, state);
             }
             const t = now();
-            // 1. Fresh grant (positive OR negative/empty result) always wins — no fetch, no backoff check.
             if (state.grant && state.grant.at + grantTtlMs > t) {
                 return { kind: "granted", scopes: state.grant.scopes };
             }
-            // 2. Inside an open backoff window → answer from the window WITHOUT re-fetching.
             if (state.unavailable && state.unavailable.until > t) {
                 return { kind: "unavailable", reason: state.unavailable.reason, retryAfterMs: Math.max(state.unavailable.until - t, 1000) };
             }
-            // 3. Grant expired (or never existed) and no active backoff → fetch, deduping concurrent callers.
             const dup = inflight.get(principal);
             if (dup)
                 return dup;
@@ -130,9 +111,6 @@ export function createOrgMemoryDirectory(opts) {
         },
     };
 }
-/** core 侧「瞬时不可用，重试」契约的载体：一个带 `retryAfterMs`（ms）属性的真 Error 子类，core 据此铸
- *  **瞬时**码 memory.admission_required（503，重试可改判——与终局的 memory.admission_denied 恰好相对）
- *  并透传该值。子类而非事后挂属性——避免任何宽松断言就能拿到正确类型。 */
 export class OrgMemoryAdmissionRetryError extends Error {
     retryAfterMs;
     constructor(message, retryAfterMs) {
@@ -141,28 +119,15 @@ export class OrgMemoryAdmissionRetryError extends Error {
         this.name = "OrgMemoryAdmissionRetryError";
     }
 }
-/**
- * `RunnerDeps.memoryScopeAdmission` 的 server 实装。deployment-origin 的 requested 项一律放行（operator
- * 自证——v1 不做中央收窄部署声明）；request-origin 项查 `directory.lookup(principal)`：granted 时逐项核
- * 对是否在授权集里（任何一项缺席 = 整体终局拒绝，不做部分放行——reason 只点名调用方自己请求过的 scope
- * 串，不逐 scope 展开「为什么」，避免变成成员探针）；unavailable 时 throw 一个带 `retryAfterMs` 的
- * {@link OrgMemoryAdmissionRetryError}。write 面独立收窄：deployment-origin 恒授，request-origin 仅当目录
- * 条目 `write === true` 才授，否则收窄为 null（即使读侧整体放行）。
- */
 export function createMemoryScopeAdmission(directory, opts) {
     const emit = (outcome, details) => {
         try {
             opts.onOutcome?.(outcome, details);
         }
         catch {
-            /* an observability hook must never break admission */
         }
     };
     return async ({ principal, requested, requestedWriteScope }) => {
-        /** 复审 D-3(7.1.0 后修):归因面。判决记录若不带 principal,运维只看得到「某个 org scope 被拒」而
-         *  无从知道**谁**被拒——「per-principal 归因走日志」这句设计承诺(与 CHANGELOG 7.0.0 同款公开陈述)
-         *  此前在代码里没有落点。principal 缺席时**不**塞键:干净 admit 那一路必须保持 `details === undefined`
-         *  (装配点据此判「无事发生不打日志」;塞个 `principal: undefined` 会把每个成功任务变成一行 warn)。 */
         const attributed = (details) => principal === undefined ? details : { principal, ...details };
         const requestOriginRequested = requested.filter((r) => r.origin === "request");
         const writeIsRequestOrigin = requestedWriteScope?.origin === "request";
@@ -171,18 +136,14 @@ export function createMemoryScopeAdmission(directory, opts) {
         const fullWriteScope = requestedWriteScope?.scope ?? null;
         const admitFull = () => ({ ok: true, scopes: fullScopes, writeScope: fullWriteScope });
         async function decide() {
-            // deployment-only requests (no request-origin item anywhere, including the write slot): nothing to
-            // look up — v1 does not centrally narrow operator-declared deployment scopes.
             if (!hasRequestOrigin)
                 return { kind: "admit", verdict: admitFull() };
             if (principal === undefined) {
-                // Defensive arm: core already refuses this shape itself when a request-origin org scope is present
-                // with no principal, but the resolver must not assume that guard always ran first.
                 return { kind: "deny", reason: "principal absent", outcome: "principal_missing" };
             }
             const lookup = await directory.lookup(principal);
             if (lookup.kind === "unavailable") {
-                const outcome = lookup.reason === "stale_generation" ? "directory_stale" : lookup.reason === "malformed" ? "directory_malformed" : "directory_absent"; // fetch_failed | section_absent
+                const outcome = lookup.reason === "stale_generation" ? "directory_stale" : lookup.reason === "malformed" ? "directory_malformed" : "directory_absent";
                 return { kind: "unavailable", retryAfterMs: lookup.retryAfterMs, outcome, lookupReason: lookup.reason, details: { reason: lookup.reason } };
             }
             const deniedScopes = requestOriginRequested.filter((r) => !(r.scope in lookup.scopes)).map((r) => r.scope);
@@ -205,9 +166,6 @@ export function createMemoryScopeAdmission(directory, opts) {
         }
         const decision = await decide();
         if (decision.kind === "admit") {
-            // C10(audit=纯观察**零**行为变化):write 收窄也是行为变化(enforce 下 harvest 静默零提交)——
-            // audit 模式对「读面通过但 write 未显式授」的判决只记 would-narrow,返回未收窄的全额;
-            // enforce 照常收窄。ok:true 分支的 writeScope 恒为 fullWriteScope 或 null(decide 只做这两值)。
             if (opts.mode === "audit" && decision.verdict.ok && decision.verdict.writeScope !== fullWriteScope) {
                 emit("ok", attributed({ audited: true, wouldNarrowWriteScope: true }));
                 return admitFull();
@@ -216,8 +174,6 @@ export function createMemoryScopeAdmission(directory, opts) {
             return decision.verdict;
         }
         if (opts.mode === "audit") {
-            // Zero behavior change: a would-deny (terminal or transient) is overridden to a full, UNNARROWED admit —
-            // the real decision is only ever recorded via onOutcome, never enforced.
             emit(decision.outcome, attributed({ ...decision.details, audited: true, wouldDeny: true, ...(decision.kind === "unavailable" ? { retryAfterMs: decision.retryAfterMs } : { reason: decision.reason }) }));
             return admitFull();
         }

package/dist/parent-watch.js

@@ -1,43 +1,4 @@
-/**
- * #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 const PARENT_WATCH_INTERVAL_MS = 15_000;
-/** 装配并**立刻**起监视(装配即 `parent_watch_armed`)。返回停机链用的 `stop()`。 */
 export function createParentWatch(deps) {
     const probe = deps.probe ?? ((pid) => void process.kill(pid, 0));
     let firstMissAtMs;
@@ -52,7 +13,7 @@ export function createParentWatch(deps) {
         if (stopped)
             return;
         if (deps.isStopped()) {
-            stop(); // 另一个停机属主已接管 —— 观察者退场,别把它的 drain 升级成硬停
+            stop();
             return;
         }
         let alive = true;
@@ -60,14 +21,8 @@ export function createParentWatch(deps) {
             probe(deps.pid);
         }
         catch (err) {
-            // ⚠️ 方向:只有 ESRCH 才是"父不在"。EPERM(无权发信号)与任何其它 errno 都算**活着** ——
-            // 这一支的保守方向是"继续服务",因为误判的代价是把一台**正常**引擎连同它的 in-flight run 关掉。
             const code = err?.code;
             alive = code !== "ESRCH";
-            // 🔴 不静默(codex 复审 M):`kill(pid, 0)` 正常只给 ESRCH/EPERM 两个 errno,出现第三种意味着
-            // **探活这条腿自己坏了**(例:pid 越出 int32 ⇒ `ERR_INVALID_ARG_TYPE`),而它的落点恰是"判活",
-            // 于是监视会 armed 之后永久失效、零信号。判死方向不变(保守),但必须留下一条带 errno 的线索;
-            // 一次性 —— 每 15s 刷一行会把真信号淹掉。
             if (code !== "ESRCH" && code !== "EPERM" && !probeErrorReported) {
                 probeErrorReported = true;
                 deps.log("parent_watch_probe_error", {
@@ -79,7 +34,7 @@ export function createParentWatch(deps) {
             }
         }
         if (alive) {
-            firstMissAtMs = undefined; // 活着的证据把窗口清零(连续性判据,不是累计计数)
+            firstMissAtMs = undefined;
             return;
         }
         if (firstMissAtMs === undefined) {
@@ -95,7 +50,6 @@ export function createParentWatch(deps) {
         });
         deps.drain();
     }, PARENT_WATCH_INTERVAL_MS);
-    // 观察者绝不是进程存活的理由(与 drain tick 刻意不 unref 的取向相反)。
     timer.unref?.();
     function stop() {
         if (stopped)

package/dist/parked-decide.js

@@ -1,40 +1,11 @@
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { backgroundScopesForCheckpointScope, decodeCheckpointScope } from "./security.js";
-/**
- * pending checkpoint → parked bg 行匹配。
- *
- * 键链(core 1.390 事实):park 时 cp 落 `sourceTaskId: sessionId`(子会话 id,**不是** bg handle),
- * 而 bg 行同样存该子会话 id(`row.sessionId`)与绑定 token(`row.parkedCheckpointToken`)。
- * `listByScope` 只回 summary(含 handle/sessionId、不含 token),故两步:summary.sessionId 初筛 →
- * `get(handle, scope)` 全行复核 token。
- *
- * token 复核是硬门,不是优化:行 REOPENED 后可在**新** token 下 re-park,旧 cp 的 decide 不得
- * 匹配到它(后续 `claimParkedAgent` 的 CAS/binding_broken 是兜底,不是第一道门)。同理,list 与
- * get 之间行被 stop/decide 抢走(离开 parked)时诚实 miss——调用方拿 undefined 走 legacy 腿,
- * 该腿对已消失的 pending cp 有自己的 404/409 处置。
- */
 export async function findParkedAgentForCheckpoint(agentStore, cp) {
-    // 🔴 A-057.44 [PARTIAL high](2026-08-19)—— **匿名部署上两套 scope 哨兵不同源**,分区查询恒落空。
-    // 病链:bg 行的 scope 写侧 = core `treeScope = reviveClaim?.row.scope ?? ctx.principal ??
-    // opts.background?.scope`,`ctx.principal` 在未开 REQUIRE_PRINCIPAL 的部署上恒 undefined ⇒ 落到本仓
-    // `capabilities/scenarios.ts` 填的 `"default"`;而 cp.scope 是 `encodeCheckpointScope(auth?.principal)`
-    // = `"_"`。店层是硬 `WHERE scope_key = ?`(MySQL/PG 双实现同形)⇒ 恒 miss ⇒ /decide 退回 legacy 腿 ⇒
-    // `getCtx(子代会话)` 必 null(全仓五个 putCtx 无一写 bg 子会话)⇒ 恒 409
-    // `conflict.resume_context_unavailable`,人的批准无处兑付、错误码还对真因有误导性。同一判别器被
-    // `server.ts` 的 deny-sweep `isParkedOwned` 复用,匿名下同样 miss ⇒ [1591] 那条静默跳过臂失效。
-    // 受害集 = REQUIRE_PRINCIPAL 未开 ∧ SQL 后端 ∧ DURABLE_APPROVAL=true。
-    //
-    // 归一**只能在读侧**(施工证伪了台账首选的「铸点改走 encodeCheckpointScope」——见
-    // `security.ts` 的 {@link backgroundScopesForCheckpointScope} 顶注:那个铸点的值同时喂进程内
-    // `defaultTaskRegistry`,而全仓读侧是一整族 `principal ?? "default"`,改铸点会把它们一起打瞎,
-    // 本车实测 subagent tail 建连当场 404)。所以这里按**别名集**查,别名表是单一属主。
     for (const scope of backgroundScopesForCheckpointScope(cp.scope)) {
         const parked = await agentStore.listByScope(scope, { status: "parked" });
         for (const s of parked) {
             if (s.sessionId !== cp.sessionId)
                 continue;
-            // ⚠️ 复核与下游(claim/rollback)都用**找到它的那个分区**,不是 cp.scope —— `decideParkedAgent`
-            // 之后取的是 `row.scope`/`row.owner` 双轴镜像([1588] Q3),故行自带的键就是权威。
             const row = await agentStore.get(s.handle, scope);
             if (row === null || row.status !== "parked")
                 continue;
@@ -45,9 +16,6 @@ export async function findParkedAgentForCheckpoint(agentStore, cp) {
     }
     return undefined;
 }
-/** [1588] Q1 裁定的 revive args 铸法:占位 prompt(objective 在 driveParkedResume 被丢弃,仅过非空门)、
- *  `run_in_background: true` 必须(revive.no_background 拒)、`name` 必传承重(名门校验+下游 park 资格
- *  谓词吃 agentName)、`subagent_type` 按 roster 成员性判。 */
 function mintReviveArgs(row, knownAgentTypes) {
     return {
         prompt: row.description ?? "resume parked agent",
@@ -57,34 +25,16 @@ function mintReviveArgs(row, knownAgentTypes) {
         ...(row.agentType !== undefined && knownAgentTypes.has(row.agentType) ? { subagent_type: row.agentType } : {}),
     };
 }
-/**
- * `/decide` parked 赎回腿(design/153 件3d server 半场;[1574]/[1584]/[1588] core 裁定形)。
- *
- * 返回 `undefined` = 该 pending checkpoint 不属于任何 parked 后台子代——调用方走既有任务级
- * resumeCheckpoint 腿(零回归);返回结果对象 = 赎回腿已受理/已拒,调用方直接回 HTTP。
- *
- * 链:判别(findParkedAgentForCheckpoint)→ `claimParkedAgent`(access = 行镜像双轴
- * `{scope: row.scope, owner: row.owner}`,[1588] Q3)→ outcome 铸造(D-1 echo/persisted 回落)
- * → 裸 `reviveTool.execute(args, ctx.reviveClaim)`。execute 一旦发起 drive,rollback 全在 core 内
- * (driveParkedResume);server 只在「claim 成功但 drive 从未发起」窗口补 `rollbackParkedClaim`
- * ([1588] Q2:isError 入参级早退 + throw 两形,已核幂等/双滚=无害 lost)。
- *
- * 200 是**受理**语义(drive 是 core 内 fire-and-forget):失败经行/notification 面 + REOPENED
- * re-park 诚实可见,操作员可再决。
- */
 export async function decideParkedAgent(deps, req) {
     let match;
     try {
         match = await findParkedAgentForCheckpoint(deps.agentStore, { token: req.token, scope: req.scope, sessionId: req.sessionId });
     }
     catch (e) {
-        // 复审 F2:bg 店瞬态读故障绝不能把(含任务级在内的)decide 变裸 500——诚实按 miss 处理,
-        // legacy 腿对 parked cp 有自己的 409 处置(retriable),任务级 cp 照常 resume。
         try {
             deps.warn?.("parked_decide_probe_failed", { error: e instanceof Error ? e.message : String(e) });
         }
         catch {
-            // warn 自身故障不改变结果面
         }
         return undefined;
     }
@@ -93,40 +43,15 @@ export async function decideParkedAgent(deps, req) {
     const row = match.row;
     const rememberRoot = req.grantRemember !== undefined ? (row.rootSessionId ?? row.parentSessionId) : undefined;
     if (req.grantRemember !== undefined && rememberRoot === undefined) {
-        // remember 的 grant 必须锚在 root/host 会话(探针闭包键);行无任何会话锚 = 无处可落,claim 前诚实拒。
         return { status: 400, body: { error: "remember cannot be applied: this parked agent row carries no root/parent session anchor for the exemption", errorCode: "decide.parked_remember_unsupported", taskId: match.handle } };
     }
     const pendingTool = req.pendingAction?.toolName;
     if (pendingTool === "AskUserQuestion" && req.decision === "approve" && req.answer === undefined) {
-        // RB-459(core 5.7.0,F1/F6 翻案后唯一剩下的 claim 前拒):问题门的 approve 必须携 answer——
-        // parked 腿无 live answering face,消费 claim 后只会空跑一次 revive;claim 前拒是免损前置。带 answer 的
-        // approve 与任何 deny 都放行透传,core 是语义权威(header 逐字匹配等)。
-        // 🔴 #152 当年写这条时的机制理由是:core 的 pre-CAS 拒条件(「`taskConfig.onQuestion ??
-        // deps.onQuestion` 为 undefined 或 QUESTION_AWAITS_RESUME」)在 ASK_QUESTION_ENABLED 部署上恒不成立
-        // ⇒ core 放行,而赎回腿会拿 coordinator 的**空答**当人答并消费掉 checkpoint。
-        // ⚠️ 那个理由已被后续两处证伪,别再据它推理:①#166 起 QuestionCoordinator 的每一条无人应答臂(无
-        // ALS ctx / abort / 限流 / 呈现不了 / TTL)一律返 `{kind:"unavailable"}`,类头逐字承诺「It NEVER
-        // synthesizes an empty answer set」——赎回腿无 ctx,拿到的是 unavailable 而不是空答;②core 5.16 对
-        // 赎回中的 ask 走 redeemsApproval 臂返 isError(「will not silently self-answer」)。
-        // 本判据**保留**,理由换成免损前置:放过去也只会空跑一次 revive(claim 已被消费),claim 前拒是
-        // 更便宜、错误信息也更准的那一手(任务级孪生:src/http/server.ts 的 decide 路由)。
         return { status: 400, body: { error: "pending action is AskUserQuestion — approve requires body.answer (the operator's answers[]); deny needs none", errorCode: "decide.parked_answer_required", taskId: match.handle } };
     }
     if (row.name === undefined) {
-        // forwardDurableApproval 只对具名子代成立,parked 行理应恒有 name;缺 = 行受损,claim 前诚实拒
-        // ([1588] Q1:name 必传承重——省略会把 revive 降级成匿名形)。
         return { status: 409, body: { error: "parked row carries no agent name — the revive path requires a named agent (row damaged?)", errorCode: "decide.row_unrevivable", taskId: match.handle } };
     }
-    // [1597]/A-010.1:席位重建**在 claim 之前**解开(codex 对抗复审 R1-中 的真 finding)。
-    // 🔴 位置即正确性:claim 之后到下面那道 try/catch(它才挂 `rollbackParkedClaim`)之间是一段
-    // **无回滚保护区**。工厂现在是 async(要现解 entitlement),把 await 放进那一段 = 任何 rejection
-    // 都带着一个已认领的 claim 逃逸,行上的 `parkClaimId` 要等 stale-claim 清算窗(默认可达一小时)
-    // 才放开,这期间该审批**再决不动**。搬到 claim 前:此刻还没有任何东西需要回滚,抛错就是干净地抛错。
-    // (工厂本身只读 row 的 scope/handle/sessionId/rootSessionId —— claim 不改这四个字段,搬位零语义差。)
-    // 🔴 A-057.44 第二半(codex 对抗复审 medium):席位收的是**权威 principal**,不是行上那个有损的
-    // `row.scope`。checkpoint 的 scope 列由 `encodeCheckpointScope(auth?.principal)` 铸,与 core 喂给
-    // `runtimeCapsResolver` 的是同一个值;`row.scope` 在 `principal ?? "default"` 约定下匿名与真名叫
-    // `default` 的租户同形(匿名别名匹配让这一格第一次真的可达,见 findParkedAgentForCheckpoint 顶注)。
     const inheritedGate = deps.rebuildInheritedGate ? await deps.rebuildInheritedGate(row, { principal: decodeCheckpointScope(req.scope) }) : undefined;
     const stores = { agentStore: deps.agentStore, checkpointStore: deps.checkpointStore };
     const claim = await deps.registry.claimParkedAgent(stores, match.handle, { scope: row.scope, owner: row.owner });
@@ -135,13 +60,11 @@ export async function decideParkedAgent(deps, req) {
             case "store_unreachable":
                 return { status: 503, body: { error: "the durable agent store is unreachable — retry", errorCode: "decide.store_unreachable", taskId: match.handle } };
             case "claim_lost":
-                // 复审 F8:claim_lost 也覆盖「上一轮 rollback 落 retry(claim 悬挂)」的形——那时要等 reaper 的
-                // stale-claim 清算窗(BG_AGENT_PARK_CLAIM_STALE_MS)过后才能再决,文案如实给出两种可能。
                 return { status: 409, body: { error: "the parked agent is already claimed — either a concurrent decide won (re-check the pending list), or a stale claim is pending automatic cleanup (retry after the stale-claim window)", errorCode: "decide.claim_lost", taskId: match.handle } };
             case "binding_broken":
             case "checkpoint_not_pending":
                 return { status: 409, body: { error: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", errorCode: "decide.gate_moved", taskId: match.handle } };
-            default: // not_found | not_parked——行在判别与 claim 之间被 stop/另一 decide 抢走
+            default:
                 return { status: 409, body: { error: "the parked agent moved under this decide (stopped or already decided)", errorCode: "decide.not_parked", taskId: match.handle } };
         }
     }
@@ -150,17 +73,12 @@ export async function decideParkedAgent(deps, req) {
         await req.onDecideCommitted?.();
     }
     catch {
-        // remember-grant 类挂点自吞错(与 legacy 腿 grantOnCommit 同姿势):绝不让豁免记账故障打断赎回。
     }
     if (req.grantRemember !== undefined && rememberRoot !== undefined) {
         try {
-            // claim 赢(≈ legacy 腿 markResuming CAS 赢)后、drive 前落店——复活腿自己的下一个同工具 ask
-            // 即可命中豁免(与 legacy 腿 1.294 grant-timing 裁定同向)。grant 失败由路由闭包自记 warn 并
-            // 让 rememberApplied 如实为 false,不阻断赎回。
             await req.grantRemember(rememberRoot);
         }
         catch {
-            // 同上:豁免记账故障不进赎回结果面
         }
     }
     const pa = req.pendingAction;
@@ -172,13 +90,8 @@ export async function decideParkedAgent(deps, req) {
         boundInputHash: req.binding?.boundInputHash ?? persistedHash,
         decision: req.decision === "approve" ? "allow" : "deny",
         ...(req.decision === "approve" && req.binding?.updatedInput !== undefined ? { updatedInput: req.binding.updatedInput } : {}),
-        // RB-459:answer 原样透传(核不预判、不改写——header 逐字匹配/合法组合全在 core 的 resume 校验)。
         ...(req.answer !== undefined ? { answer: req.answer } : {}),
-        // B10:存在性判定,不是真值判定 —— reason 可以是空串("运维显式选择不写理由"),这与"没传 reason"
-        // 是两件不同的事(姊妹 approval-hmac.ts `env.reason ?? null` 同判据:`??` 只在 null/undefined 时落
-        // null,空串照样入签名载荷)。真值判定会把显式 "" 与缺席折成同一个结果,审计/签名面丢了这个区分。
         ...(req.reason !== undefined ? { reason: req.reason } : {}),
-        // #204 件6③:结算出处逐字上 outcome(见 `ParkedDecideRequest.settledBy` 顶注)。
         settledBy: req.settledBy,
     };
     const ctx = {
@@ -189,20 +102,15 @@ export async function decideParkedAgent(deps, req) {
             parkedResume: {
                 ticket,
                 outcome,
-                // [1597] 席位:重建父约束链(同进程时 core 的内存 registry 也能自动重供,席位供了也无害
-                // ——core 侧 count 校验对得上即用;跨进程/重启形全靠这里)。
                 ...(deps.rebuildInheritedGate ? { inheritedGate } : {}),
             },
         },
     };
-    // 复审 F7:warn 回调自身故障(duck-typed logger 缺方法/日志面抖动)绝不能改写 rollback 的结果面——
-    // 已成功的回滚若因 warn 抛错逃逸成 500/reject,操作员会对着"失败"重试一个其实已回纯的行。
     const quietWarn = (event, fields) => {
         try {
             deps.warn?.(event, fields);
         }
         catch {
-            // 观测面故障不进结果面
         }
     };
     const rollback = async (why) => {
@@ -216,13 +124,6 @@ export async function decideParkedAgent(deps, req) {
             return "retry";
         }
     };
-    // [3911] per-agent tail 的**内容帧供给形**必须随赎回周期作废(codex 复审 round3 high)。
-    // 本车道是第四条腿:上面这只 ctx 是**裸的**(只有 toolCallId + reviveClaim),没有宿主
-    // forward / notification sink —— 于是 ①park 是非终态,三条 run 腿的终态撤销手够不到它;
-    // ②赎回周期是否有帧供给取决于**进程内 retain 条目还在不在**(在 ⇒ core 用 spawn 期的
-    // internalsSnapshot 继续转发;不在 ⇒ 这一周期结构上一帧都不会有)。两种都不是本处能断言的事,
-    // 所以把上一周期的答案作废成「不知道」:新周期真有帧时首帧会重新登记真相,没有帧时 meta 也不会
-    // 拿旧周期的 `on` 骗订阅方去等一个永远不来的转录(那正是本批要消灭的静默形)。
     defaultSubagentTailBus.forgetHandleContentMode(match.handle);
     let receipt;
     try {
@@ -242,19 +143,10 @@ export async function decideParkedAgent(deps, req) {
     }
     const isErr = typeof receipt === "object" && receipt !== null && receipt.isError === true;
     if (isErr) {
-        // execute 的入参级早退臂(revive.no_background/name 门/type 门等)return 于任何 registry 动作之前,
-        // core 不代滚([1588] Q2 核定)——这仍在「drive 未发起」窗口,server 补滚。
-        // 复审 G-F5 口径补充:isError 不恒等于「早退未滚」——core 的 parked_resume.startup_failed 臂是
-        // drive 已发起且 core 已自滚后的 isError;此处补滚在 rollbackParkedClaim 的 claimId CAS 下退化为
-        // 无害 "lost"([1588] Q2 幂等核定),结果面仍诚实(操作员重查 pending 列表即可自愈)。
         const disp = await rollback("execute_rejected");
         const content = receipt.content;
         const receiptError = receipt.details?.error;
         if (receiptError === "parked_resume.startup_failed") {
-            // RB-459([2458] 裁定形):resume 已发起但启动即败(含 core 对 outcome.answer 的语义拒——
-            // header 不匹配/answer 配错门,invalid_outcome field:"answer" 在 drive 内抛)——422 透传 core
-            // 的码,不塌 409 revive_rejected(那是入参级早退的形)。core 已自滚,上面的补滚在 claimId CAS
-            // 下退化无害 lost(G-F5 口径),行回 parked 可再决。
             return {
                 status: 422,
                 body: {

package/dist/per-task-image.js

@@ -1,34 +1,5 @@
-/**
- * §7 P0.5 — per-task sandbox image binding (門B "用户按需选像"). IMAGE-API-DESIGN §7.
- *
- * The caller sends a PROFILE (intent) on the run body — NEVER a digest. The trusted control plane (this service,
- * with the caller's principal) resolves the profile → a pullable `repo@digest`, FAIL-CLOSED, re-admitting by the
- * SAME per-principal visibility the `/v1/images/select` admission uses. Why profile-not-digest: a digest is a
- * stable, enumerable sha256 with no caller-binding — trusting a caller-supplied digest is fail-OPEN (a user could
- * pass another tenant's digest to pull an image they can't see). Resolving inside the trust boundary closes that.
- *
- * The resolved ref reaches the worker-global {@link import("@sema-agent/core").ExecutionEnvFactory} (which
- * only receives core's deliberately-minimal `{sessionId}` context) via {@link PerTaskImageRegistry} — core's own
- * doctrine: "richer routing is captured in the factory closure by the trusted control plane". This module is that
- * capture, kept narrow + unit-testable.
- */
 import { BoundedSessionMap } from "./bounded-session-map.js";
-/** Boolean capability keys a caller may require. `nestedBuildMode` is a posture string, not a boolean gate, so it
- *  is intentionally NOT requestable here (capability admission is allow-on-true only). */
 const REQUESTABLE_CAPS = new Set(["browser", "db", "nestedBuild"]);
-/**
- * Resolve a requested sandbox image PROFILE to a pullable `repo@digest`, FAIL-CLOSED, re-admitting by `viewer`:
- *  - `latestPublished(profile, viewer)` applies the SAME `visibilityClause` + `status='published'` filter the
- *    select admission uses. Not visible / not published ⇒ `{ok:false, 404}` (never silent-allow).
- *  - each `capabilitiesNeeded` entry must be a known boolean capability AND true on the resolved image, else fail.
- * Pure over the injected `index` ⇒ unit-testable with a fake resolver.
- *
- * NOTE (review LOW — error-code asymmetry, DELIBERATE): a not-visible / capability-miss here returns 404, whereas
- * the operator-facing `POST /v1/images/select` returns 409 + `missing`. That is intentional: task admission is an
- * UNTRUSTED-caller gate that must NOT distinguish "profile exists but you can't see it" from "doesn't exist"
- * (revealing that leaks the existence of other tenants' images), so it collapses both to 404. The select catalog
- * is the operator's own scoped view, where the richer 409 + `missing` detail is safe.
- */
 export async function resolveSandboxImageRef(opts) {
     const entry = await opts.index.latestPublished(opts.profile, opts.viewer);
     if (!entry) {
@@ -43,44 +14,16 @@ export async function resolveSandboxImageRef(opts) {
             return { ok: false, status: 404, message: `sandbox image for profile "${opts.profile}" does not provide capability "${cap}"` };
         }
     }
-    // capabilities ride along for RFC A1 envFacts (the resolved entry is already in hand — no second query).
     return { ok: true, ref: `${entry.repo}@${entry.digest}`, capabilities: entry.capabilities };
 }
-/**
- * The trusted-control-plane bridge from `resolveSpec` (resolves the per-task image with the caller's principal) to
- * the worker-global `ExecutionEnvFactory` (gets only core's minimal `{sessionId, taskId?}`). NOT a durable store
- * and NOT a cache: `resolveSpec` REPOPULATES it on EVERY call — initial AND resume, on whichever replica runs
- * resolveSpec immediately before the factory — so a cross-replica resume re-resolves LIVE (the resume re-admit
- * discipline: a stale persisted digest can never bypass admission), and there is nothing durable to go stale.
- *
- * KEYED BY sessionId — the ONLY identifier stable across the factory `ctx` on every path (adversarial-review
- * round-2): `/v1/runs` mints its OWN durable taskId that clobbers `spec.taskId`, so keying by taskId misses on the
- * primary path; `sessionId` survives the spec spread on every path. `get()` is NON-removing (the factory may be
- * invoked >once per logical task). Cleanup is by bounded eviction (oldest-first) — each entry is a tiny string; an
- * evicted task is long finished.
- *
- * ⚠️ KNOWN narrow edge (same-principal correctness, NOT a security breach): two CONCURRENT requests for the SAME
- * session (necessarily the same owner — session ownership is enforced) race `set()`; a request the run-claim later
- * rejects (409) can leave its image bound for the active run. Both images are the same principal's own admitted
- * images, so the worst case is the user's run using the user's OTHER selected image. The hardening
- * (register-after-claim, keyed by the durable run id) needs the registry threaded into the server claim path —
- * tracked as a follow-up. cascade/verify + a profile are rejected up front (they strip/replace the session).
- */
 export class PerTaskImageRegistry {
-    // #97 R11: the sessionId-keyed bounded-eviction map is the shared BoundedSessionMap basis (this class was
-    // its original verbatim form); the composition below keeps THIS class's own ctor/method surface unchanged.
     bounded;
     constructor(maxEntries = 4096) {
         this.bounded = new BoundedSessionMap(maxEntries);
     }
-    /** Register the resolved `repo@digest` for a session. A re-set (resume / a later same-session task) overwrites;
-     *  on overflow the oldest insertion is evicted so an orphaned entry (a resolveSpec not followed by a factory
-     *  call, e.g. a rejected/pre-exec-failed request) stays bounded. */
     set(sessionId, ref) {
         this.bounded.set(sessionId, ref);
     }
-    /** Read the ref for a session (NON-removing — the factory may be invoked more than once per logical task).
-     *  `undefined` ⇒ no per-task image for this session ⇒ the factory uses its worker-global default image. */
     get(sessionId) {
         return this.bounded.get(sessionId);
     }

package/dist/plan-cache-probe.js

@@ -1,17 +1,9 @@
-// Verbatim from core strategy-store.ts. 🔴 「keep in sync」不是靠这句话 —— lockstep 活钉在
-// test/plan-cache-probe.test.ts(真读 core 的 dist strategy-store.js 做 set diff + 切词正则/阈值同源),
-// 任一侧改词表当场红。2026-07-30 之前这里只有声明没有钉:删掉一个词全量零红(实测)。
 const STOP = new Set([
     "the", "and", "for", "with", "from", "this", "that", "into", "your", "you", "are", "was", "were", "has",
     "have", "had", "not", "but", "all", "any", "can", "use", "using", "via", "then", "than", "out", "get",
     "got", "its", "it's", "their", "them", "they", "what", "when", "which", "who", "how", "why", "a", "an",
     "of", "to", "in", "on", "is", "it", "or", "as", "at", "by", "be", "do", "if", "so", "no", "up", "we",
 ]);
-/** Lowercased word tokens (core口径). */
-/** core 5.49 G2(CJK 检索修)同形:拉丁/数字按非字母数字切段 + CJK 按单字与相邻二元组入集
- *  (core `memory-vector.termSet` 逐字搬)。旧形 `match(/[a-z0-9]+/g)` 对纯中文任务名恒空 ⇒
- *  probe 测出的 recurrence 与 plan-cache 真命中脱钩——同源钉(plan-cache-probe.test.ts)就是
- *  为这次换形红的。 */
 const CJK_RUN = /[぀-ヿㇰ-ㇿ㐀-䶿一-鿿가-힣豈-﫿]+/g;
 export function tokens(s) {
     const lower = s.toLowerCase();
@@ -28,18 +20,13 @@ export function tokens(s) {
     }
     return [...out];
 }
-/** CJK 词条豁免长度/停词判(core 5.49 `CJK_LEAD` 同形:单字即显著);拉丁保持 ≥3 且非停词。 */
 const CJK_LEAD = /^[぀-ヿㇰ-ㇿ㐀-䶿一-鿿가-힣豈-﫿]/;
 export function significant(s) {
     return tokens(s).filter((t) => (CJK_LEAD.test(t) ? true : t.length >= 3 && !STOP.has(t)));
 }
-const RING = 1000; // most-recent completed tasks per scope (= search AI's N=1000)
-const MAX_SCOPES = 2000; // LRU cap on tracked scopes — bounds memory under high tenant cardinality
-export const QSIG_CAP = 12; // qSig-length histogram cap (>=12 collapses into the last bucket)
-/**
- * In-memory recurrence tracker. One per process (single replica per worker in prod; cross-replica
- * aggregation is unnecessary for a 2-week instrument — each instance reports its own slice).
- */
+const RING = 1000;
+const MAX_SCOPES = 2000;
+export const QSIG_CAP = 12;
 export class PlanCacheProbe {
     metrics;
     logger;
@@ -48,19 +35,10 @@ export class PlanCacheProbe {
         this.metrics = metrics;
         this.logger = logger;
     }
-    /**
-     * Record one finished task. `completed` = it succeeded (only those enter the history ring). Pure
-     * in-memory + a counter/histogram + a debug log line; never throws into the caller.
-     */
     record(scopeRaw, objective, completed) {
         const scope = scopeRaw && scopeRaw.length > 0 ? scopeRaw : "anon";
         const qSig = significant(objective);
         const st = this.touch(scope);
-        // Hit = some historical (completed) task's full token set ⊇ this task's significant tokens,
-        // OR(core 5.49 compileStrategyQuery 的 legacy acceptance 臂,合并窗重扫 medium)⊇ 其拉丁/数字
-        // 子集 qAlnum(非空时)——changelog 原句 "old hits preserved via a legacy acceptance arm"。
-        // 少这条臂时「CJK 团不全匹配但拉丁标识符全匹配」的真命中被判 miss ⇒ recurrence 系统性低估。
-        // qSig empty → never a hit (mirrors find()'s `qSig.length===0 → []`, no injection).
         let hit = false;
         if (qSig.length > 0) {
             const qAlnum = qSig.filter((t) => !CJK_LEAD.test(t));
@@ -84,7 +62,6 @@ export class PlanCacheProbe {
         this.metrics?.observe("plan_cache_qsig", qSig.length);
         this.logger?.debug("plan-cache recurrence probe", { scope, qSig: qSig.length, hit, completed });
     }
-    /** Per-scope recurrence snapshot for the handoff (token-gated dump endpoint). */
     dump() {
         const out = {};
         for (const [scope, st] of this.byScope) {
@@ -97,7 +74,6 @@ export class PlanCacheProbe {
         }
         return out;
     }
-    /** LRU get-or-create: re-insert on access so the oldest-touched scope is evicted past the cap. */
     touch(scope) {
         let st = this.byScope.get(scope);
         if (st) {