@sema-agent/server 1.322.0 → 2.0.0

package/dist/parked-decide.d.ts

@@ -1,8 +1,31 @@
+/**
+ * 件3d `/decide` 消费 parked 后台子代——server 半场辅件(设计稿:sema-internal
+ * server/docs/DECIDE-PARKED-DESIGN.md;黑板 [1587];core 裁定 [1574]/[1584])。
+ *
+ * 本模块先落判别器:`POST /v1/approvals/:sessionId/decide` 路由在既有 session→token 映射拿到
+ * pending checkpoint 后,用它判定该 cp 是否属于一个 parked 后台子代——命中则走 claim →
+ * 裸 `ToolSpec.execute`(ctx.reviveClaim)赎回腿,不中则零回归走既有任务级 resumeCheckpoint 腿。
+ * 判别必须 parked-first:legacy 腿的 `resumeStream` 会绕开 bg registry(无 consumeParkedFlip、
+ * 行永 parked、生命周期分叉)。
+ */
 import type { BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, TaskRegistry, ToolSpec } from "@sema-agent/core";
 export interface ParkedAgentMatch {
     handle: string;
     row: BackgroundAgentRecord;
 }
+/**
+ * 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 declare function findParkedAgentForCheckpoint(agentStore: BackgroundAgentStore, cp: {
     token: string;
     scope: string;
@@ -11,9 +34,19 @@ export declare function findParkedAgentForCheckpoint(agentStore: BackgroundAgent
 export interface ParkedDecideDeps {
     agentStore: BackgroundAgentStore;
     checkpointStore: Pick<CheckpointStore, "get">;
+    /** 与 reaper/scenarios 同一个 registry(claim/rollback 的 CAS 与 in-memory handle 收敛在同处)。 */
     registry: Pick<TaskRegistry, "claimParkedAgent" | "rollbackParkedClaim">;
+    /** boot 期从生产装配(buildScenarios)取的裸 Agent ToolSpec——与 spawn 用同一装配路径,
+     *  subRunner/bg opts/checkpointStore 同实例天然成立([1587] 设计稿 §4)。 */
     reviveTool: ToolSpec;
+    /** revive args 的 `subagent_type` 成员性判定集([1588] Q1 修正:非 roster 成员必须省略,否则
+     *  unknown subagent_type 拒;字面比对 general-purpose 在 roster 撞名时会错省)。缺省空集=恒省略。 */
     knownAgentTypes?: ReadonlySet<string>;
+    /** [1596]/[1597] 跨进程父约束重供席:按部署配置**重建的同语义**父策略链工厂(host 任务的 toolPolicy
+     *  解析槽一条,单层链;exempt 探针锚= row.rootSessionId,与 remember grant 锚同键)。core 1.396 起
+     *  `parkedResume.inheritedGate` 席位把它透传进 resume 的官方重供通道——不供 = 重启后带
+     *  requiresParentConstraint 的 checkpoint 恒被 pre-CAS 门拒(retryable 假话,永不可赎回)。链长形状
+     *  校验在 core(fail-closed,供错链长照拒)。 */
     rebuildInheritedGate?: (row: BackgroundAgentRecord) => unknown;
     warn?: (event: string, fields: Record<string, unknown>) => void;
 }
@@ -21,21 +54,49 @@ export interface ParkedDecideRequest {
     token: string;
     scope: string;
     sessionId: string;
+    /** cp.pendingAction 原样(outcome 铸造的 persisted 回落源,与 legacy 腿 D-1 姿势逐字同形)。 */
     pendingAction: unknown;
     decision: "approve" | "deny";
     reason?: string;
+    /** D-1 decision-binding echo(操作员在 GET 看到的 boundCallId/boundInputHash 原样透传;server
+     *  绝不重算,core resume 侧做 fail-closed 等值校验——与 legacy 腿同姿势)。 */
     binding?: {
         boundCallId?: string;
         boundInputHash?: string;
         updatedInput?: unknown;
     };
+    /** body 带了 `remember:"session"` 时路由传入的 grant 执行器([1591] 候裁② 的 server 侧修,经两轮
+     *  行为探针实证):豁免必须锚在**行的 root/host 会话 id**——部署侧三个豁免探针(policy 层/fs-write
+     *  门/workflow 门)的闭包统一捕获 host 会话键且签名不携身份(1.393 seam 亲读:`sourceTaskId` 只在
+     *  onAsk 层的 AskRequest,durable 车道无 onAsk),grant 落子代会话则键永不相交(G-F4 原案);落
+     *  root 会话则宿主键闭包立即命中,复活子代的后续同工具 ask 被短路(探针 v2 实证),语义与同步车道/
+     *  宿主任务的「本会话不再询问」一致(= host 会话树全域)。行无 root 锚(病态形)⇒ claim 前诚实 400。 */
     grantRemember?: (rootSessionId: string) => Promise<void>;
+    /** body 带了 `answer`(复审 F6):parked 腿无 onQuestion 挂点,显式 400 与 legacy 腿对同一
+     *  畸形输入的拒绝姿势对齐(legacy:「answer 仅在 approve AskUserQuestion 时合法」),不静默吞。 */
     answerPresent?: boolean;
+    /** claim CAS 赢了(≈ legacy 腿的 markResuming 赢)之后、execute 之前触发——remember 豁免 grant
+     *  的挂点(调用方自吞错,绝不抛落赎回)。claim 败/判别 miss 恒不触发。 */
     onDecideCommitted?: () => Promise<void>;
 }
 export interface ParkedDecideResult {
     status: number;
     body: Record<string, unknown>;
 }
+/**
+ * `/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 declare function decideParkedAgent(deps: ParkedDecideDeps, req: ParkedDecideRequest): Promise<ParkedDecideResult | undefined>;
 //# sourceMappingURL=parked-decide.d.ts.map

package/dist/parked-decide.js

@@ -1,3 +1,16 @@
+/**
+ * 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) {
     const parked = await agentStore.listByScope(cp.scope, { status: "parked" });
     for (const s of parked) {
@@ -12,6 +25,9 @@ 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",
@@ -21,16 +37,34 @@ 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;
     }
@@ -39,16 +73,22 @@ 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 } };
     }
     if (req.answerPresent === true) {
+        // 复审 F6:与 legacy 腿同姿势显式拒,不静默丢弃操作员的输入。
         return { status: 400, body: { error: "body.answer is not supported when deciding a parked background agent (no question hookpoint on the revive path)", errorCode: "decide.parked_answer_unsupported", taskId: match.handle } };
     }
     const pendingTool = req.pendingAction?.toolName;
     if (pendingTool === "AskUserQuestion" && req.decision === "approve") {
+        // 复审 F1:只拦 approve(approve 必须携 answer 才有意义,而 parked 腿无 onQuestion 挂点);
+        // deny 放行走赎回(deny outcome 不需要 answer),决策面不留死角。claim 之前拒,claim 不被消费。
         return { status: 400, body: { error: "pending action is AskUserQuestion — approve is not supported for a parked background agent (deny it, stop the agent, or let the gate expire)", errorCode: "decide.parked_question_unsupported", 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 } };
     }
     const stores = { agentStore: deps.agentStore, checkpointStore: deps.checkpointStore };
@@ -58,11 +98,13 @@ 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:
+            default: // not_found | not_parked——行在判别与 claim 之间被 stop/另一 decide 抢走
                 return { status: 409, body: { error: "the parked agent moved under this decide (stopped or already decided)", errorCode: "decide.not_parked", taskId: match.handle } };
         }
     }
@@ -71,12 +113,17 @@ 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;
@@ -98,15 +145,20 @@ export async function decideParkedAgent(deps, req) {
             parkedResume: {
                 ticket,
                 outcome,
+                // [1597] 席位:重建父约束链(同进程时 core 的内存 registry 也能自动重供,席位供了也无害
+                // ——core 侧 count 校验对得上即用;跨进程/重启形全靠这里)。
                 ...(deps.rebuildInheritedGate ? { inheritedGate: deps.rebuildInheritedGate(row) } : {}),
             },
         },
     };
+    // 复审 F7:warn 回调自身故障(duck-typed logger 缺方法/日志面抖动)绝不能改写 rollback 的结果面——
+    // 已成功的回滚若因 warn 抛错逃逸成 500/reject,操作员会对着"失败"重试一个其实已回纯的行。
     const quietWarn = (event, fields) => {
         try {
             deps.warn?.(event, fields);
         }
         catch {
+            // 观测面故障不进结果面
         }
     };
     const rollback = async (why) => {
@@ -138,6 +190,11 @@ 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;
         return {

package/dist/per-task-image.d.ts

@@ -1,4 +1,20 @@
+/**
+ * §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 type { ImageViewer, ImageIndexEntry } from "./plugins/store-contracts.js";
+/** Minimal slice of the image index the per-task resolver needs (a testable seam — the real `imageIndex`'s
+ *  `latestPublished` returns the full {@link ImageIndexEntry}, which is assignable to this Pick). */
 export interface SandboxImageResolver {
     latestPublished(profile: string, viewer: ImageViewer): Promise<Pick<ImageIndexEntry, "repo" | "digest" | "capabilities"> | null>;
 }
@@ -11,17 +27,55 @@ export type SandboxImageResolution = {
     status: number;
     message: string;
 };
+/**
+ * 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 declare function resolveSandboxImageRef(opts: {
     profile: string;
     capabilitiesNeeded?: readonly string[];
     viewer: ImageViewer;
     index: SandboxImageResolver;
 }): Promise<SandboxImageResolution>;
+/**
+ * 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 declare class PerTaskImageRegistry {
     private readonly maxEntries;
     private readonly map;
     constructor(maxEntries?: number);
+    /** 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: string, ref: string): void;
+    /** 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: string | undefined): string | undefined;
 }
 //# sourceMappingURL=per-task-image.d.ts.map

package/dist/per-task-image.js

@@ -1,4 +1,19 @@
+/** 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) {
@@ -13,14 +28,38 @@ 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 {
     maxEntries;
     map = new Map();
     constructor(maxEntries = 4096) {
         this.maxEntries = 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.map.delete(sessionId);
         this.map.set(sessionId, ref);
@@ -30,6 +69,8 @@ export class PerTaskImageRegistry {
                 this.map.delete(oldest);
         }
     }
+    /** 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 sessionId === undefined ? undefined : this.map.get(sessionId);
     }

package/dist/plan-cache-probe.d.ts

@@ -1,21 +1,56 @@
+/**
+ * Plan-cache recurrence probe — INSTRUMENT-FIRST (search AI → service, 团队/给service-AI.md [1];
+ * core design/42). Zero-LLM, zero-dependency, pure in-memory.
+ *
+ * Measures the **per-scope recurrence rate of task objectives**: the unproven "省钱" premise behind a
+ * proposed core *plan-caching* feature (store a successful run's generalized plan → a similar new task
+ * retrieves it as a hint). The 2-juror review wanted real data before core builds the producer hook:
+ * does an agent's traffic actually re-pose near-duplicate objectives per tenant? (arXiv 2602.18922:
+ * heterogeneous queries can hit 0–12%.) We hold the real multi-tenant traffic, so this is ours to count.
+ *
+ * **The token criterion is copied verbatim from core `src/core/strategy-store.ts`** (`tokens()` /
+ * `significant()` / `find()` lines 46-52, 107-110) — otherwise we'd measure something other than what
+ * plan-cache retrieval would actually use. Note the **asymmetry**: a stored problem is matched on its
+ * full `tokens()` set, the query on its `significant()` set, and a hit = every significant query token
+ * is present in some stored problem (`significant(new) ⊆ tokens(historical)`).
+ *
+ * Fidelity choices (stated to search AI for confirmation): the history ring holds only **completed**
+ * tasks (plan-cache only stores plans from successful runs), while the hit test runs for **every**
+ * finished task; `qSig` length is bucketed so a hit can be told apart from a short-objective fluke
+ * (the juror's `qSig>=3` gate).
+ */
 import type { Metrics } from "./observability/metrics.js";
 import type { Logger } from "./observability/logger.js";
+/** Lowercased word tokens (core口径). */
 export declare function tokens(s: string): string[];
+/** Meaningful tokens: ≥3 chars, not a stopword (core口径). */
 export declare function significant(s: string): string[];
+/** Per-scope view for the 2-week handoff back to search AI. */
 export interface ScopeRecurrence {
     tasks: number;
     hits: number;
     hitRate: number;
+    /** qSig-length histogram (index 0..QSIG_CAP; last bucket = QSIG_CAP+). */
     qsig: number[];
 }
 export declare const QSIG_CAP = 12;
+/**
+ * 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).
+ */
 export declare class PlanCacheProbe {
     private readonly metrics?;
     private readonly logger?;
     private readonly byScope;
     constructor(metrics?: Metrics | undefined, logger?: Logger | undefined);
+    /**
+     * 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: string | undefined, objective: string, completed: boolean): void;
+    /** Per-scope recurrence snapshot for the handoff (token-gated dump endpoint). */
     dump(): Record<string, ScopeRecurrence>;
+    /** LRU get-or-create: re-insert on access so the oldest-touched scope is evicted past the cap. */
     private touch;
 }
 //# sourceMappingURL=plan-cache-probe.d.ts.map

package/dist/plan-cache-probe.js

@@ -1,18 +1,25 @@
+// Verbatim from core strategy-store.ts (keep in sync if core changes its stopword set).
 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口径). */
 export function tokens(s) {
     return s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
 }
+/** Meaningful tokens: ≥3 chars, not a stopword (core口径). */
 export function significant(s) {
     return tokens(s).filter((t) => t.length >= 3 && !STOP.has(t));
 }
-const RING = 1000;
-const MAX_SCOPES = 2000;
-export const QSIG_CAP = 12;
+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).
+ */
 export class PlanCacheProbe {
     metrics;
     logger;
@@ -21,10 +28,16 @@ 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.
+        // qSig empty → never a hit (mirrors find()'s `qSig.length===0 → []`, no injection).
         let hit = false;
         if (qSig.length > 0) {
             for (const hist of st.ring) {
@@ -47,6 +60,7 @@ 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) {
@@ -59,6 +73,7 @@ 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) {

package/dist/plugins/approval-exemption-store.d.ts

@@ -6,10 +6,15 @@ export interface ApprovalExemptionRow {
     createdAt: number;
 }
 export interface ApprovalExemptionStore {
+    /** Record the exemption (idempotent upsert; a re-grant refreshes grantedBy, createdAt keeps the FIRST grant). */
     grant(sessionId: string, toolName: string, grantedBy: string | null): Promise<void>;
+    /** The ask-gate probe. Callers MUST fail-closed on a rejected promise (ask anyway). */
     has(sessionId: string, toolName: string): Promise<boolean>;
+    /** All exemptions for a session (the GET /v1/approvals UI surface). */
     list(sessionId: string): Promise<ApprovalExemptionRow[]>;
+    /** Revoke one exemption; false = nothing to revoke (idempotent). */
     revoke(sessionId: string, toolName: string): Promise<boolean>;
+    /** E21 — purge ALL exemptions for a session (session delete wiring). Idempotent (affected count). */
     deleteBySession(sessionId: string): Promise<number>;
 }
 export declare class TiDBApprovalExemptionStore implements ApprovalExemptionStore {
@@ -44,6 +49,7 @@ export declare class FileApprovalExemptionStore implements ApprovalExemptionStor
     private readonly logs;
     constructor(root: string);
     private pathFor;
+    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. */
     private hydrate;
     private logFor;
     grant(sessionId: string, toolName: string, grantedBy: string | null): Promise<void>;
@@ -51,6 +57,7 @@ export declare class FileApprovalExemptionStore implements ApprovalExemptionStor
     list(sessionId: string): Promise<ApprovalExemptionRow[]>;
     revoke(sessionId: string, toolName: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
+    /** Release every open append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose(): void;
 }
 //# sourceMappingURL=approval-exemption-store.d.ts.map

package/dist/plugins/approval-exemption-store.js

@@ -1,6 +1,22 @@
+/**
+ * Per-session per-toolName approval exemption ("本会话不再询问",
+ * design: docs/design/APPROVAL-SESSION-EXEMPTION.md).
+ *
+ * SEMANTICS (the boundary that keeps this an APPROVAL MEMORY, not a policy loosen): a granted row makes the
+ * F4 ask-gate SKIP the human ask for that (sessionId, canonicalToolName) — it is consulted ONLY after
+ * `APPROVAL_DENY` and `APPROVAL_NEVER_AUTO` (both always win), and never touches the session-policy layer
+ * (tighten-only stays intact). Keyed in CANONICAL tool-name space (the same rename-smuggling discipline as
+ * the require/deny sets). Lifecycle = session-bound: E21 session DELETE purges via deleteBySession.
+ *
+ * Four twins behind one interface (the resume-anchor pattern): TiDB/PG = durable cross-replica SQL rows
+ * (idempotent upsert on the (session_id, tool_name) PK); File = per-session JSONL append log (fsync — a
+ * lost grant re-asks, but a torn log must not FABRICATE one), hydrated on boot, torn-tail-safe; Memory =
+ * tests / ephemeral. Consumers treat store FAILURE as fail-closed (ask anyway) — enforced at the call site.
+ */
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { AppendLog, ensureDir, readJsonlRecords, sanitizePathComponent } from "@sema-agent/core";
+// ─── TiDB / MySQL twin ───────────────────────────────────────────────────────────────────────────────────
 export class TiDBApprovalExemptionStore {
     pool;
     constructor(pool) {
@@ -8,7 +24,8 @@ export class TiDBApprovalExemptionStore {
     }
     async grant(sessionId, toolName, grantedBy) {
         await this.pool.query("INSERT INTO approval_exemption (session_id, tool_name, granted_by, created_at) VALUES (?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE granted_by = VALUES(granted_by)", [sessionId, toolName, grantedBy, new Date()]);
+            "ON DUPLICATE KEY UPDATE granted_by = VALUES(granted_by)", // created_at keeps the first grant
+        [sessionId, toolName, grantedBy, new Date()]);
     }
     async has(sessionId, toolName) {
         const [rows] = await this.pool.query("SELECT 1 FROM approval_exemption WHERE session_id = ? AND tool_name = ?", [sessionId, toolName]);
@@ -31,6 +48,7 @@ export class TiDBApprovalExemptionStore {
         return r.affectedRows;
     }
 }
+// ─── PG twin (dialect twin of the TiDB store — same contract, $n placeholders + ON CONFLICT) ─────────────
 export class PgApprovalExemptionStore {
     pool;
     constructor(pool) {
@@ -67,6 +85,7 @@ export class PgApprovalExemptionStore {
         return res.rowCount ?? 0;
     }
 }
+// ─── Memory twin (tests / ephemeral) ─────────────────────────────────────────────────────────────────────
 export class MemoryApprovalExemptionStore {
     bySession = new Map();
     async grant(sessionId, toolName, grantedBy) {
@@ -110,6 +129,7 @@ export class FileApprovalExemptionStore {
     pathFor(sessionId) {
         return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
     }
+    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. */
     hydrate() {
         let names;
         try {
@@ -191,9 +211,13 @@ export class FileApprovalExemptionStore {
             log.close();
             this.logs.delete(key);
         }
+        // 🔴 unlink BEFORE dropping the index, and FAIL LOUD if the file survives: a
+        // swallowed rm would let hydrate() resurrect purged exemptions after a restart — an E21 right-to-delete
+        // violation with PRIVILEGE attached (auto-approve rights), unlike the inert anchor-store twin. Throwing
+        // here aborts the caller's session purge before it deletes the session metadata (fail-loud, retryable).
         const path = this.pathFor(sessionId);
         try {
-            rmSync(path, { force: true });
+            rmSync(path, { force: true }); // force: missing file is fine (idempotent delete)
         }
         catch (e) {
             if (existsSync(path))
@@ -202,12 +226,14 @@ export class FileApprovalExemptionStore {
         this.bySession.delete(key);
         return removed;
     }
+    /** Release every open append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose() {
         for (const log of this.logs.values()) {
             try {
                 log.close();
             }
             catch {
+                /* best-effort */
             }
         }
         this.logs.clear();