@sema-agent/server 7.133.0 → 7.135.0

package/dist/http/resume-legs.js

@@ -3,9 +3,10 @@ import { createHash } from "node:crypto";
 import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY, PAUSE_REGISTRY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParkForked, denyWorkflowParksUnreadable, findParkOrigin, heldWorkflowParkDecisions, planWorkflowParkedDecide } from "../parked-decide.js";
 import { parkDecisionFingerprint } from "../orchestration/workflow-park-decision.js";
+import { headReadOf } from "../session-incarnation.js";
 const DELIVERY_NOT_RECORDED = "workflow park decide: this delivery no longer holds the host session (its claim was released) — the decision was not recorded and this delivery was not started";
-const sessionFaceUnavailable = async (sessionId) => {
-    throw new Error(`parked decide cannot verify which occupant session ${sessionId} belongs to: this deployment's session store has no sessionFaceOf read (every built-in store has one) — refusing rather than resuming unverified`);
+const headUnavailable = async (sessionId) => {
+    throw new Error(`parked decide cannot verify which occupant session ${sessionId} belongs to: this deployment's session store has no head read (headOf; every built-in store has one) — refusing rather than resuming unverified`);
 };
 import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import { parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
@@ -17,7 +18,8 @@ import { recordResumeResourceWindow } from "../resource-window.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "../fleet/subagent-tail-bus.js";
-import { APPROVAL_GATE_KINDS, createApprovalCardEmitter, isApprovalGateKind, parkRowStandingAnswerFacts, resolveApprovalLeg, resolveStreamApprovalGate, standingAnswerDurablyRecordable } from "../tool-approval.js";
+import { currentApprovalGateToken } from "../approval-gate-currency.js";
+import { createApprovalCardEmitter, declaredApprovalFrameFamilies, parkRowStandingAnswerFacts, resolveApprovalLeg, resolveStreamApprovalGate, standingAnswerDurablyRecordable } from "../tool-approval.js";
 import { buildCheckpointAnchorHash } from "../approval-ask-audit-store.js";
 import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
 import { serviceVersion } from "../service-version.js";
@@ -45,11 +47,11 @@ import { gatedPrincipal, explicitOperatorOk } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
 import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
-import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
+import { ASK_USER_QUESTION_TOOL_NAME, isApprovalGateKind } from "../approval-content-kind.js";
 import { deploymentListAsks } from "../approval.js";
-import { readResumeCtx, resumeCtxCorruptAnswer } from "./resume-ctx-read.js";
-import { buildCheckpointVersionKeys, resumeBlockedByPolicyAnswer, resumeRefusalWithCard, storedBodyReplayAnswer, storedBodyReplayLogFields, withPermissionModeRewritten } from "./checkpoint-ctx.js";
-import { refusalBody } from "./refusal-body.js";
+import { readResumeCtx, resumeCtxCorruptAnswer, resumeCtxUnsealableAnswer } from "./resume-ctx-read.js";
+import { buildCheckpointVersionKeys, resumeBlockedByPolicyAnswer, resumeRefusalWithCard, sealCheckpointCtx, storedBodyReplayAnswer, storedBodyReplayLogFields, withPermissionModeRewritten } from "./checkpoint-ctx.js";
+import { refusalBody, resumeRefusalFacts } from "./refusal-body.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
 import { httpErrorRefusal } from "./send.js";
 import { createRunAcceptance } from "../run-acceptance.js";
@@ -91,6 +93,7 @@ const WORKER_SWAP_REDEEMABLE = {
     registry_occupied: true,
     unknown_model_ref: true,
     not_a_model_ref: true,
+    unknown_role_word: true,
 };
 function checkpointRowRedeemableElsewhere(reason) {
     return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
@@ -125,6 +128,9 @@ const CHECKPOINT_ERROR_DISPOSITION = {
     "steering.invalid_content": "terminal",
     "steering.queue_full": "terminal",
 };
+function windowZeroSeatOf(toolApproval) {
+    return (identity) => toolApproval.boundUnattendedAsk(identity, { arm: "window_zero" });
+}
 export function resumeRefusalDisposition(e) {
     const word = Object.hasOwn(CHECKPOINT_ERROR_DISPOSITION, e.code) ? CHECKPOINT_ERROR_DISPOSITION[e.code] : undefined;
     switch (word) {
@@ -149,6 +155,7 @@ const CHECKPOINT_ERROR_FIELD_ROLE = {
     answer: "answer",
     hostDecision: "outcome_cell",
     approver: "outcome_cell",
+    feedback: "outcome_cell",
     taskConfig: "config",
     deps: "config",
     inheritedGate: "config",
@@ -186,9 +193,7 @@ export function checkpointRefusalAnswer(e, at) {
             errorCode: e.code === "checkpoint.invalid_outcome" ? (refusalCause !== undefined ? WIRE_CODE_OF_DECISION_REFUSAL[refusalCause] : UNCLASSIFIED_INVALID_OUTCOME_CODE) : e.code,
             facts: {
                 ...(at.taskId !== undefined ? { taskId: at.taskId } : {}),
-                ...(detail?.code !== undefined ? { blockedBy: detail.code } : {}),
-                ...(detail?.field ? { field: detail.field } : {}),
-                ...(detail?.reason !== undefined ? { reason: detail.reason } : {}),
+                ...resumeRefusalFacts(detail),
                 ...((e.code === "resume.usage_window_exhausted" || e.code === "resume.preflight_rejected") && typeof detail?.retryAfterMs === "number" && Number.isFinite(detail.retryAfterMs) && detail.retryAfterMs > 0
                     ? { retryAfterSec: Math.max(1, Math.ceil(detail.retryAfterMs / 1000)) }
                     : {}),
@@ -198,11 +203,12 @@ export function checkpointRefusalAnswer(e, at) {
     }, at.retriable);
 }
 export function createResumeLegs(ctx) {
-    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const ctxOpening = (sessionId) => ({ sessionId, opener: deps.checkpointCtxSealing });
     const resumeFleetScope = (req, auth) => req ? (gatedPrincipal(req, deps.config) ?? "default") : (auth.principal ?? "default");
     async function resumeCheckpoint(sessionId, decision, reason, hostDecision, req, answer, binding, onResumeCommitted, acceptEarly, decider) {
         const cs = deps.checkpointStore;
-        const token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? (await cs.findPendingTokenBySession(sessionId));
+        const token = await currentApprovalGateToken(cs, sessionId);
         if (binding?.checkpointToken && binding.checkpointToken !== token) {
             let seenUnreadable = false;
             const seen = await cs.get(binding.checkpointToken).catch((e) => {
@@ -386,7 +392,7 @@ export function createResumeLegs(ctx) {
             const parkedReq = {
                 token, scope: cp.scope, sessionId: cp.sessionId, pendingAction: cp.pendingAction,
                 decision, hostDecision, ...(reason !== undefined ? { reason } : {}),
-                ...(binding !== undefined ? { binding: { ...(binding.boundCallId !== undefined ? { boundCallId: binding.boundCallId } : {}), ...(binding.boundInputHash !== undefined ? { boundInputHash: binding.boundInputHash } : {}), ...(binding.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}) } } : {}),
+                ...(binding !== undefined ? { binding: (({ checkpointToken: _staleGuardOnly, ...rest }) => rest)(binding) } : {}),
                 ...(answer !== undefined ? { answer } : {}),
                 ...(boundGrant ? { grantRemember: (rootSessionId) => boundGrant(rootSessionId) } : {}),
             };
@@ -396,10 +402,10 @@ export function createResumeLegs(ctx) {
                     checkpointStore: cs,
                     registry: defaultTaskRegistry,
                     reviveSurface: parkedSurface,
-                    sessionFaceOf: deps.sessionStorage?.sessionFaceOf ? deps.sessionStorage.sessionFaceOf.bind(deps.sessionStorage) : sessionFaceUnavailable,
+                    headOf: headReadOf(deps.sessionStorage) ?? headUnavailable,
                     ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
                     ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
-                    ...(deps.toolApproval ? { approverSeatFor: deps.toolApproval.boundUnattendedAsk } : {}),
+                    ...(deps.toolApproval ? { approverSeatFor: windowZeroSeatOf(deps.toolApproval) } : {}),
                     ...(deps.logger ? { warn: parkWarn } : {}),
                 }, parkedReq, { handle: origin.handle, row: origin.row }));
                 void ctxPromise.catch(() => { });
@@ -463,9 +469,11 @@ export function createResumeLegs(ctx) {
                 return out;
             }
         }
-        const ctxRead0 = await readResumeCtx(ctxPromise);
+        const ctxRead0 = await readResumeCtx(ctxPromise, ctxOpening(sessionId));
         if (ctxRead0.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead0.where);
+        if (ctxRead0.kind === "unsealable")
+            return resumeCtxUnsealableAnswer(ctxRead0);
         const ctx = ctxRead0.kind === "ok" ? ctxRead0.ctx : null;
         if (!ctx)
             return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
@@ -492,6 +500,7 @@ export function createResumeLegs(ctx) {
             decision: decision === "approve" ? "allow" : "deny",
             ...(decision === "approve" && binding?.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}),
             ...(reason ? { reason } : {}),
+            ...(binding?.feedback !== undefined ? { feedback: binding.feedback } : {}),
             ...(answer !== undefined ? { answer } : {}),
             hostDecision,
         };
@@ -554,7 +563,7 @@ export function createResumeLegs(ctx) {
         const resumeLegStartedAt = Date.now();
         const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds, resumeCtx } = args;
         const reparkStatus = outcome.gate === "plan_review" ? "needs_review" : "suspended";
-        const commitResumeCtx = () => deps.checkpointStore.putCtx(resumeCtx.sessionId, { ...resumeCtx.ctx, writerVersion: serviceVersion() }).catch((e) => {
+        const commitResumeCtx = () => Promise.resolve().then(() => deps.checkpointStore.putCtx(resumeCtx.sessionId, sealCheckpointCtx({ ...resumeCtx.ctx, writerVersion: serviceVersion() }, deps.checkpointCtxSealing, resumeCtx.sessionId))).catch((e) => {
             deps.metrics?.inc("resume_ctx_not_persisted_total");
             deps.logger?.warn?.("resume_ctx_not_persisted", { sessionId: resumeCtx.sessionId, gate: outcome.gate, error: errorText(e), note: "this continuation runs with the body it was given; the durable rebuild input still holds the PREVIOUS body, so the NEXT continuation of this session rebuilds from that one (never wider than this leg's)" });
         });
@@ -563,7 +572,7 @@ export function createResumeLegs(ctx) {
             toolApprovalEnabled: Boolean(deps.toolApproval),
             streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
             backend: deps.backend,
-            parkFacility: deps.checkpointStore !== undefined,
+            checkpointStore: deps.checkpointStore,
         }).active;
         const approvalLeg = resolveApprovalLeg({
             streamApprovalOn,
@@ -571,6 +580,7 @@ export function createResumeLegs(ctx) {
             windowMarginMs: deps.config.streamAskWindowMarginMs,
             ...(typeof taskConfig.limits?.maxWalltimeMs === "number" ? { legWalltimeMs: taskConfig.limits.maxWalltimeMs } : {}),
             nowMonotonicMs: performance.now(),
+            declaredFamilies: declaredApprovalFrameFamilies(resumeCtx.ctx.body.settings),
         });
         const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
         const ownerQuotaDenial = args.callerInitiated === true ? ownerCostQuotaDenied(principal) : undefined;
@@ -609,8 +619,8 @@ export function createResumeLegs(ctx) {
         const resumeTaskConfig = taskId ? { ...taskConfig, taskId } : taskConfig;
         if (deps.toolApproval && taskId) {
             const toolApproval = deps.toolApproval;
-            resumeTaskConfig.onAsk = approvalLeg.windowZero
-                ? toolApproval.boundUnattendedAsk({ owner: principal ?? null, taskId, sessionId })
+            resumeTaskConfig.onAsk = approvalLeg.unattended
+                ? toolApproval.boundUnattendedAsk({ owner: principal ?? null, taskId, sessionId }, approvalLeg.unattended)
                 : toolApproval.boundAsk({
                     owner: principal ?? null,
                     taskId,
@@ -849,9 +859,9 @@ export function createResumeLegs(ctx) {
                 if (deps.userInputLedger && taskId)
                     await deps.userInputLedger.announceUndrained({ sessionId, taskId });
                 const anchorOwner = principal ?? null;
-                const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
-                const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
-                    ? async (eventId) => { const leaf = await getLeafId(sessionId); if (leaf)
+                const headOf = headReadOf(deps.sessionStorage);
+                const captureTurnAnchor = deps.resumeAnchorStore && headOf
+                    ? async (eventId) => { const leaf = (await headOf(sessionId))?.leafId; if (leaf)
                         await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner); }
                     : undefined;
                 const captureUserMessageAnchor = deps.resumeAnchorStore && taskId
@@ -1097,7 +1107,7 @@ export function createResumeLegs(ctx) {
                     const { type, ...rest } = frame;
                     return append(type, rest);
                 };
-                const withApproval = () => deps.toolApproval && taskId && approvalLeg.active && !approvalLeg.windowZero
+                const withApproval = () => deps.toolApproval && taskId && approvalLeg.active && approvalLeg.unattended === undefined
                     ? deps.toolApproval.runWithContext({
                         taskId,
                         owner: principal ?? null,
@@ -1274,9 +1284,11 @@ export function createResumeLegs(ctx) {
         if (gateKind !== RESUMABLE_GATE_KIND) {
             return { status: 409, body: refusalBody({ errorCode: "gate_not_resumable", message: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a resumable resource/preempt suspension — an approval gate must be decided via POST /v1/approvals/:id/decide` }) };
         }
-        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId), ctxOpening(sessionId));
         if (ctxRead.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "unsealable")
+            return resumeCtxUnsealableAnswer(ctxRead);
         if (ctxRead.kind === "absent")
             return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
         const ctx = ctxRead.ctx;
@@ -1294,9 +1306,11 @@ export function createResumeLegs(ctx) {
         if (!deps.runStore) {
             return { status: 501, body: refusalBody({ errorCode: "capability.run_store_required", message: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)" }) };
         }
-        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId), ctxOpening(sessionId));
         if (ctxRead.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "unsealable")
+            return resumeCtxUnsealableAnswer(ctxRead);
         const ctx = ctxRead.kind === "ok" ? ctxRead.ctx : null;
         if (!ctx) {
             return {
@@ -1385,9 +1399,11 @@ export function createResumeLegs(ctx) {
                 throw e;
             }
         }
-        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId), ctxOpening(sessionId));
         if (ctxRead.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "unsealable")
+            return resumeCtxUnsealableAnswer(ctxRead);
         if (ctxRead.kind === "absent")
             return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
         const ctx = ctxRead.ctx;
@@ -1474,9 +1490,11 @@ export function createResumeLegs(ctx) {
                 }),
             });
         }
-        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId), ctxOpening(sessionId));
         if (ctxRead.kind === "corrupt")
             return refuse(resumeCtxCorruptAnswer(ctxRead.where));
+        if (ctxRead.kind === "unsealable")
+            return refuse(resumeCtxUnsealableAnswer(ctxRead));
         if (ctxRead.kind === "absent")
             return refuse({ status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) });
         const replay = storedBodyReplayRefusal(ctxRead.ctx, deps.config);
@@ -1514,7 +1532,7 @@ export function createResumeLegs(ctx) {
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters },
-        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
+        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal(), capabilities: createCapabilitiesLocal() },
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, preparePlanReview, drivePlanReview },
     };

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

@@ -30,7 +30,7 @@ import type { PlanApprovePermissionModeAfter } from "../task-settings.js";
 import type { VerifyRoundsSpec } from "./verify-rounds.js";
 import type { RunAbort } from "../run-cancel-context.js";
 /** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。
- *  S-947:`cancelledViaVerb`(按 taskId 键控的「这次是取消动词」旁表)删除 —— 中止成因改挂在每条腿自己的
+ *  [ref]:`cancelledViaVerb`(按 taskId 键控的「这次是取消动词」旁表)删除 —— 中止成因改挂在每条腿自己的
  *  {@link RunAbort} 句柄上(`inflightRuns` 的值),同寿同删,不再有一张与腿不同寿的旁表。 */
 export interface RunRegistry {
     idemCache: IdempotencyCache<SubmitOutcome>;
@@ -73,21 +73,12 @@ export interface RouteHelpers {
     /** [ref]-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
     usageWindowDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
     safeDecode(seg: string): string | null;
-    isFleetWide(req: IncomingMessage): boolean;
     /** run 面的属主门(谓词 `runOwnerReadable`;非属主 ⇒ 404 `not_found.run` + 长文,与 run 读口的 unknown 臂同码同串,[ref])。 */
     runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;
-    /** 会话面的属主门(谓词 `sessionOwnerReadable`,S-1452:没有身份边界的部署不钉人,与会话列表同读;非属主 ⇒ 404 `not_found.session` +
-     *  {@link SESSION_NOT_FOUND_MESSAGE},与会话读口的 unknown 臂同码同串 —— G52 [ref] / S-989)。每一个按会话寻址的属主判都走它。
-     *  `cell` = 调用点经 `security.ts` 的 `sessionOwnerCellOf` 读出的那一格(S-1770:无主的委派子代 placed 行只对 fleet 调用方放行,判据 `ownerlessRowOpen`)。 */
+    /** 会话面的属主门(谓词 `sessionOwnerReadable`,[ref]:没有身份边界的部署不钉人,与会话列表同读;非属主 ⇒ 404 `not_found.session` +
+     *  {@link SESSION_NOT_FOUND_MESSAGE},与会话读口的 unknown 臂同码同串 —— G52 [ref] / [ref])。每一个按会话寻址的属主判都走它。
+     *  `cell` = 调用点经 `security.ts` 的 `sessionOwnerCellOf` 读出的那一格([ref]:无主的委派子代 placed 行只对 fleet 调用方放行,判据 `ownerlessRowOpen`)。 */
     sessionOwnerOk(req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell): boolean;
-    sessionOwnerScope(req: IncomingMessage): {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
-    sessionOwnerScopeForWrite(req: IncomingMessage): {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
     runSessionAcceptOk(req: IncomingMessage, res: ServerResponse, run: {
         sessionId: string | null;
     }, face: string, notFoundError?: string): boolean;
@@ -96,7 +87,7 @@ export interface RouteHelpers {
  *  (模块级会把 rate-limiter / 缓存跨实例串味,测试里一个进程建几十个 server)。 */
 export interface RouteLocals {
     images: ImagesLocal;
-    /** S-481:`GET /v1/capabilities/mcp` / `POST /v1/capabilities/mcp/probe` 的 TTL 缓存与每 principal 限速窗。 */
+    /** [ref]:`GET /v1/capabilities/mcp` / `POST /v1/capabilities/mcp/probe` 的 TTL 缓存与每 principal 限速窗。 */
     capabilities: CapabilitiesLocal;
     sessions: SessionsLocal;
     sessionSync: SessionSyncLocal;
@@ -131,7 +122,7 @@ export interface PreparedTaskSubmission {
     cascade?: boolean;
     jobId?: string;
     body: TaskRequestBody;
-    /** L-167:**装配期**铸下的、这条会话的用户面 `EngineNotice`(今天两族:请求腿 MCP 注入被丢弃;入口地板钳制 `permission.entry_mode_clamped`)。
+    /** [ref]:**装配期**铸下的、这条会话的用户面 `EngineNotice`(今天两族:请求腿 MCP 注入被丢弃;入口地板钳制 `permission.entry_mode_clamped`)。
      *  装配跑在这条腿的通告口开张之前,所以铸点交不出去 —— 由腿在 `registerEngineNoticeLeg` 那一拍
      *  经 `pending` 一起投(投递单点仍是那一只注册助手,不新开第二条机制)。缺席 = 本次装配没铸下任何通告。 */
     engineNotices?: readonly EngineNotice[];
@@ -142,7 +133,7 @@ export interface PreparedTaskSubmission {
      */
     warnings?: readonly EntryProblem[];
     /**
-     * S-470(device lane 首绑写协议,design §4.3.2 两阶段 placement)—— **已校验、未写库**的 placement 意图。
+     * [ref](device lane 首绑写协议,design §4.3.2 两阶段 placement)—— **已校验、未写库**的 placement 意图。
      *
      * 缺席的两种含义都等价于「本腿没有 placement 要提交」:①本部署不是 device 车道(绝大多数);
      * ②本腿不是 fresh 根提交(resume 家族根本不经 `prepareSpec`)。在场 ⇒ 每个 `runStore.createRun(`
@@ -159,7 +150,7 @@ export interface PreparedTaskSubmission {
 /**
  * 一条会话的**续跑重建输入**(`checkpoint_ctx` 的行体)—— 提交腿写一次,续跑腿读它重建 spec。
  *
- * S-433 F2 起命名化(此前是五处结构等价的内联字面 `{ body: TaskRequestBody; memoryScope?: string }`):
+ * [ref] F2 起命名化(此前是五处结构等价的内联字面 `{ body: TaskRequestBody; memoryScope?: string }`):
  * 它同时是 {@link DriveResumeArgs.resumeCtx} 的形,而那一位是**写回**口 —— 读形与写形是同一件东西这句话
  * 得由类型说,不能靠五处手抄碰巧一致。
  */
@@ -168,9 +159,9 @@ export interface CheckpointCtx {
     /** 提交时这条会话绑定的记忆域(重建 `RequestAuth` 用);缺席 = 没有记忆面。 */
     memoryScope?: string;
     /**
-     * 🔴 S-877 候裁 18(codex r3 F1)—— 这条会话的 run 是**无人值守腿**铸的(今天唯一的写者 = leader worker 的 durable 块,
+     * 🔴 [ref] 候裁 18(codex r3 F1)—— 这条会话的 run 是**无人值守腿**铸的(今天唯一的写者 = leader worker 的 durable 块,
      * `leader/wire.ts`),**服务端写、不来自请求体**(`body` 是提交体;本位是它的兄弟键,客户端够不着)。
-     * 续跑家族据此请 `resolveSpec` 带 `unattendedLeg: true`,由它经首跑同一只合并口 `withUnattendedLeg` 重挂整条腿(S-934 ①:`default` +
+     * 续跑家族据此请 `resolveSpec` 带 `unattendedLeg: true`,由它经首跑同一只合并口 `withUnattendedLeg` 重挂整条腿([ref] ①:`default` +
      * 按类作答的 onAsk)—— onAsk 是活闭包、进不了 checkpoint,而 core 在 spec 不说模式时取 checkpoint 记下的那一个(`seat ?? recorded`),
      * 不重挂 = 续跑落 checkpoint 记下的旧模式(7.106.0–7.108.0 的行记 `bypassPermissions`)而按类作答缺席。写回口(`DriveResumeArgs.resumeCtx`)
      * 传原 ctx / 其展开 ⇒ 标随行。缺席 = 不是无人值守腿(HTTP 提交腿;7.106.0 前落盘的行 —— 那时这些腿不铸模式,checkpoint 里也没有)。
@@ -192,7 +183,7 @@ export interface CheckpointCtx {
      */
     permissionModeReading?: import("./checkpoint-ctx.js").PermissionModeReading;
     /**
-     * 🔴 S-1365 —— **写这份上下文的服务版本**(`package.json` 的 `version`),**服务端写、不来自请求体**(与 {@link unattendedLeg} 同为 `body` 的兄弟键)。
+     * 🔴 [ref] —— **写这份上下文的服务版本**(`package.json` 的 `version`),**服务端写、不来自请求体**(与 {@link unattendedLeg} 同为 `body` 的兄弟键)。
      * 写点两个:`buildCheckpointCtx`(每一次新的持久化写)与续跑腿的写回({@link DriveResumeArgs.resumeCtx} 的唯一写点,CAS 赢点盖本进程的版本 —— 接下来写下一张停车行的就是它)。
      * 读者:`checkpoint.unsupported_version` 的 409 体 —— 原样带出 `writerVersion`,与本引擎的 `readerVersion` 并列(运维据此知道该回哪一版去决);
      * 两键唯一铸法 `checkpoint-ctx.ts` `buildCheckpointVersionKeys`,本码每个铸点同调。它是**上下文**,不是拒因:成因与码都不读它。
@@ -226,9 +217,9 @@ export interface WorkflowDecisionDelivery {
 export interface DriveResumeArgs {
     token: CheckpointToken;
     /**
-     * 🔴 **S-433 合并复审 F2 [high] —— 「本次续跑真正用的那个体」,由本腿在赢下 CAS 之后写回耐久层**
+     * 🔴 **[ref] 合并复审 F2 [high] —— 「本次续跑真正用的那个体」,由本腿在赢下 CAS 之后写回耐久层**
      * (验真后修;必填 —— `driveResumeIntoRunLog` 今天恰有**四个**调用点:legacy `/decide`(`resumeCheckpoint`)、
-     * `resumePreempted`、`resumeWake`、`drivePlanReview`(S-609 前名 `resumePlanReview`),四条一视同仁)。
+     * `resumePreempted`、`resumeWake`、`drivePlanReview`([ref] 前名 `resumePlanReview`),四条一视同仁)。
      *
      * 病(修前):`resumePlanReview` 在 `driveResumeIntoRunLog` **受理(2xx)之后**才 `putCtx(sessionId,
      * {...ctx, body})`,而 `ctx` 是请求**开头** `getCtx` 读到的那一份,两个店的 `putCtx` 又都是按
@@ -270,7 +261,7 @@ export interface DriveResumeArgs {
     outcome: ResumeOutcome;
     verifyRounds: VerifyRoundsSpec | undefined;
     /**
-     * **R-1**(车CJ 收车档 §10 R-1;S-185 批落地)—— 本条 resume 腿**装配期**铸下的用户面通告
+     * **R-1**(车CJ 收车档 §10 R-1;[ref] 批落地)—— 本条 resume 腿**装配期**铸下的用户面通告
      * (`PreparedTaskSubmission.engineNotices` 的 resume 孪生;今天唯一一族:`mcp.injection_dropped`)。
      *
      * 为什么 resume 腿也要投:一条 park 任务的 body 是**存量**的,它自己那几条丢弃在首跑那一拍确实已经
@@ -329,7 +320,7 @@ export interface DriveResumeArgs {
      * 为什么系统腿必须豁免(亲核后改的判据,首版曾一并拦下 sweep):sweep 的活是把过了 SLA 的卡**结算掉**
      * (graceful deny → 行收敛 → 释放 `task_active` claim)。拦住它并不能省钱,只会让超顶租户的卡**挂着**
      * —— 而挂多久的兜底**比首版注释里写的差得多**:`checkpoint-store-sql.ts` 的 `reapExpired` 在
-     * **deadline 分支**上逐字排除了 `APPROVAL_GATE_KINDS`(`gate_kind NOT IN (…) OR tool_name='AskUserQuestion'`),
+     * **deadline 分支**上排除了读作 facet `A` 的审批门行(7.135.0 起是由 core 两张表生成的谓词;更早是门型 IN 字面 + 问答工具名臂),
      * 所以一张过期的 human / irreversible_ask 卡根本不走那条腿;真正兜住它的只有绝对 backstop
      * `terminal_at_ms`(`TERMINAL_BACKSTOP_MS` 默认 **30 天**)。于是「拦 sweep」= 把一个由
      * `APPROVAL_TIMEOUT_SEC` 界定的 SLA 换成「等成本窗滚过(`COST_QUOTA_WINDOW_SEC` 默认 24h)、最坏等 30 天」,
@@ -367,7 +358,7 @@ export interface DriveResumeArgs {
     ownerLeaseAdmitted?: boolean;
 }
 /**
- * S-609(7.97.0):plan_review 纯读段全部过关后交给驱动段的那一份 —— **选中的那张卡**(token + 载入的行)与**它那一刻**
+ * [ref](7.97.0):plan_review 纯读段全部过关后交给驱动段的那一份 —— **选中的那张卡**(token + 载入的行)与**它那一刻**
  * 的续跑上下文。三者一起走:驱动段只认这张卡,ctx 读绑在它上面(读在选卡之后;之后任何 ctx 写都得先赢这张卡的
  * CAS,于是一份过期的读只会让驱动段在 CAS 上败,不会被配给别的卡)。
  */
@@ -407,12 +398,12 @@ export interface RouteLegs {
      *  `hostDecision` = **这次结算的事实**(谁结束了这次等待 + 通道自报的归属),必填:本腿有两个调用方
      *  (HTTP `/decide` = 人;内部 D-D SLA deny-sweep = 窗到期),而函数内部分辨不出谁在叫它 —— 必填参数把
      *  「漏报出处」变成编译错,不是一条下游把「没人答」渲染成「有人拒」的静默假出处。
-     *  🔴 S-136(core 7.6.0 S6-A):宿主报事实、core 铸词 —— server 不再传结算词(旧形传 core 的三词之一,
+     *  🔴 [ref](core 7.6.0 S6-A):宿主报事实、core 铸词 —— server 不再传结算词(旧形传 core 的三词之一,
      *  于是「哪个词配哪个 decision」这条相容规则要 server 自己记,而记错的方向恰是上面那句要防的)。 */
     resumeCheckpoint(sessionId: string, decision: "approve" | "deny", reason: string | undefined, hostDecision: HostDecision, req?: IncomingMessage, answer?: QuestionAnswer, binding?: DecideBinding, 
     /** [ref] codex R4(验真后修):remember 豁免的 grant 挂点。**工具名不再由路由自己读**(那是与本函数
      *  载入行分歧的第三次 scope-less 读,三读分歧下会给他人工具落豁免=提权)——由本函数把**已属主校验的
-     *  载入 cp** 的可记工具名(`rememberableToolName`,非 tool_approval / AskUserQuestion / legacy null / S-663 强制卡 ⇒ `null`
+     *  载入 cp** 的可记工具名(`rememberableToolName`,非 tool_approval / AskUserQuestion / legacy null / [ref] 强制卡 ⇒ `null`
      *  = 无可记)一并回传,路由只对这个逐字落店。`overrideSessionId` = parked 腿的 root/host 会话 grant 锚。 */
     onResumeCommitted?: (grant: {
         overrideSessionId?: string;
@@ -451,7 +442,7 @@ export interface RouteLegs {
      *  而两条腿共用这一条驱动路径正是 `notify-wake.ts` 那条「wake 会烧模型,所以复用 resume 家族的同一条腿」的成文纪律。 */
     workflowDecision?: WorkflowDecisionDelivery): Promise<HostLegOutcome>;
     /**
-     * assistant plan_review 三态腿的**纯读段**(S-609,7.97.0):选卡 → 属主轻读 → 载入 → 行级 scope → 门类 → 这条决断
+     * assistant plan_review 三态腿的**纯读段**([ref],7.97.0):选卡 → 属主轻读 → 载入 → 行级 scope → 门类 → 这条决断
      * 唯一的一次 ctx 读。任何一步拒 ⇒ `{ok:false, answer}`(不改任何状态;端点在消费一次性 nonce **之前**把它答出去);
      * 全部过关 ⇒ `{ok:true, prepared}`,交给 {@link RouteLegs.drivePlanReview}。语义属主 = `resume-legs.ts` 同名函数顶注。
      */
@@ -476,13 +467,13 @@ export interface RouteLegs {
         readonly ok: true;
         readonly prepared: PreparedPlanReview;
     }>;
-    /** plan_review 三态腿的**驱动段**(S-609):只吃 prepare 的结果,用它选定的 token,不再选卡、不再读 ctx。 */
+    /** plan_review 三态腿的**驱动段**([ref]):只吃 prepare 的结果,用它选定的 token,不再选卡、不再读 ctx。 */
     drivePlanReview(prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, 
-    /** core 7.49.0 #1396:决策事实(谁决定的 + 归属),语义属主 = `resume-legs.ts` 的同名形参顶注。 */
+    /** core 7.49.0 [ref]:决策事实(谁决定的 + 归属),语义属主 = `resume-legs.ts` 的同名形参顶注。 */
     hostDecision: HostDecision, req: IncomingMessage | undefined, 
     /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
     acceptEarly?: boolean, 
-    /** S-433:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在把计划带出 plan 的决定
+    /** [ref]:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在把计划带出 plan 的决定
      *  —— `approve` / `edit` —— 上有意义,缺席 ⇒ `"default"`)。语义与判据的唯一属主 = `resume-legs.ts` 的同名形参顶注。 */
     permissionModeAfter?: PlanApprovePermissionModeAfter): Promise<{
         status: number;
@@ -557,7 +548,7 @@ export interface RouteCtx extends RouteCtxBase {
     req: RouteRequestState;
 }
 /**
- * 域入口的签名(S-146 第三刀 车②)。
+ * 域入口的签名([ref] 第三刀 车②)。
  *
  * 🔴 **`url` 与「已处理」布尔一并删掉**,零别名([ref] 硬 breaking):分派器已经**匹配过一次**并把
  * 结果整个交进来(`match`),所以一只 handler 既不需要再判路,也不可能「没匹配上」——「返回 false
@@ -620,7 +611,7 @@ export interface RouteDeclFacts {
      *  503 照旧罩着(它判的是「这台机能不能收写」,与方法无关,且必须在解析请求体之前)。 */
     readonly methodDispatched?: true;
 }
-/** **可分派行**多出来的列(S-146 第三刀):身份 + 它真认的方法(+ S-1281 的订阅类)。纯门行一列都没有(见下)。 */
+/** **可分派行**多出来的列([ref] 第三刀):身份 + 它真认的方法(+ [ref] 的订阅类)。纯门行一列都没有(见下)。 */
 interface RouteDeclIdentity {
     /** **全表唯一**的行名(kebab 闭集词)。这是声明行的身份:域 handler 用
      *  `switch (match.decl.id)` 闭集分派(漏一口 = 编译红),所以它必须稳定、唯一、且与路径解耦
@@ -636,7 +627,7 @@ interface RouteDeclIdentity {
      *     tasks 的 POST;`/v1/memory/export` = memory-policy 的 GET + memory-bundle 的 POST)。 */
     readonly methods: readonly RouteMethod[];
     /**
-     * 「这条 GET 开的是一条**只读订阅**」—— 一条 SSE 读面(推送队列 / 账本 tail),它看着别人干活,自己不是活(S-1281)。
+     * 「这条 GET 开的是一条**只读订阅**」—— 一条 SSE 读面(推送队列 / 账本 tail),它看着别人干活,自己不是活([ref])。
      * 在场 ⇒ 分派器不把它记进在飞(`drainState.inflight()`:排空等的、`/health` 报的、SIGHUP 空闲窗与附着租约读的那一只),只记进附着
      * (`attachedStreams()`:壳还挂在这只引擎上);排空进入那一拍(以及硬停起点)由分派器发一帧 `draining` 终帧后关掉它
      * (`drainState.endSubscriptions`)。闭集 = 八条 GET SSE 读面,逐行理由见各行注;**唯一**一条「在飞腿的流」`POST /v1/tasks/stream`
@@ -684,7 +675,7 @@ export type RouteDecl = RouteDispatchDecl | RouteGateDecl;
  * 「中止抛穿」臂、一切 4xx / 拒绝出口一律**不铸**(缺席 ⇒ 证不出提交,读者按「没提交」读 —— fail-closed)。
  *
  * 读者:`/decide` 的两道「这次决定提交了没有」门 —— [ref] 迟到结算留痕(`noteLateSettleIfAccepted`)与 remember 豁免落店
- * (`routes/approvals-assistant.ts`)。它们原先只读 wire 体的 `errorCode !== "cancelled"`(「取消 = 决定没提交」),S-947 给续跑腿补了
+ * (`routes/approvals-assistant.ts`)。它们原先只读 wire 体的 `errorCode !== "cancelled"`(「取消 = 决定没提交」),[ref] 给续跑腿补了
  * 「引擎受理之后才被取消」的取消终局之后,`cancelled` 不再等价「没提交」⇒ 两门改读本位:`200 ∧ (errorCode≠cancelled ∨ decisionCommitted)`。
  * 🔴 为什么不放进 `result.cancelContext`(主会话初稿的落点):那只快照的契约是「分诊材料,不是状态机输入:任何门 / CAS / resume 判定都不许
  * 读它」(`plugins/store-contracts.ts` `RunCancelContext` 顶注)—— 这两道门正是判定;而且门读的是 `/decide` 的平面体、看不到结果对象。
@@ -696,7 +687,7 @@ export interface EngineLegOutcome {
     decisionCommitted?: true;
 }
 /**
- * **workflow 宿主腿的结局(wake / fresh)—— 型上就没有 `decisionCommitted`**(S-992 ②,7.113.0;`never` 让「这条路径不铸」成为**编译事实**,不是靠人记)。
+ * **workflow 宿主腿的结局(wake / fresh)—— 型上就没有 `decisionCommitted`**([ref] ②,7.113.0;`never` 让「这条路径不铸」成为**编译事实**,不是靠人记)。
  *
  * 为什么这条路径不该有该位:`/decide` 的 workflow 第三条车道(`resumeCheckpoint` 的 parked 分流,`planWorkflowParkedDecide` 之后)与 `POST /v1/sessions/:id/wake`
  * 把决定 / 消息交给**宿主会话的下一跑**(`resumeWake` / `startFreshHostTurn`)。它们的 200 只到「已交给宿主的下一跑」—— 子代 checkpoint 的 resolve CAS 发生在
@@ -719,7 +710,7 @@ export declare function buildHostLegOutcome(out: {
     body: object;
 }): HostLegOutcome;
 /**
- * **「决定/续跑已受理」那一枚 200 收据的单一铸点**(S-218)。
+ * **「决定/续跑已受理」那一枚 200 收据的单一铸点**([ref])。
  *
  * 两条腿投同一份体:①resume 家族的受理点(`driveResumeLeg`,宿主停在 park 上时);②`/decide` 的
  * workflow 第三条车道在宿主**不在** park 上时新铸的那一跑。契约上这两条腿说的是同一句话 ——
@@ -743,7 +734,7 @@ export declare const RUN_NOT_FOUND_MESSAGE = "run not found \u2014 the id belong
  * 会话资源面 404 的**唯一一句**(与 {@link RUN_NOT_FOUND_MESSAGE} 同一冻结纪律,常量锚在 `test/api-error-text-freeze.test.ts`)。
  *
  * 为什么是常量不是各点字面量:这句话要在**每一个**会话面的「不存在」臂与「非属主」臂上逐字节同串(G52 [ref] /
- * S-989 —— 两臂差一个码或一个字就是单端点内的存在性 oracle)。十余个出站点各抄一份,漂开的那天没有任何东西会说话;
+ * [ref] —— 两臂差一个码或一个字就是单端点内的存在性 oracle)。十余个出站点各抄一份,漂开的那天没有任何东西会说话;
  * 走一只常量 + `runOwnerOk(..., "session")` 的会话拼法,「改一处」就是改全域。
  */
 export declare const SESSION_NOT_FOUND_MESSAGE = "session not found";

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

@@ -1,7 +1,7 @@
 /**
- * **路由声明表**(S-146,[ref] 波 2 第二刀)—— 「这是什么路由」这件事在本仓的**唯一属主**。
+ * **路由声明表**([ref],[ref] 波 2 第二刀)—— 「这是什么路由」这件事在本仓的**唯一属主**。
  *
- * ## 病(S-146 债行原文的读数)
+ * ## 病([ref] 债行原文的读数)
  * 同一件事此前有五份写法、两道扫源码文本的对账门,而那两道门已经**反向塑形了源码**:表里必须写
  * 字面量不许引常量(否则门的正则抓不到)、注释里不许出现某两个字符(否则门的非贪婪捕获提前收尾)。
  *  ① 分派序 = `handle()` 里 37 只 `if (await handleX(...)) return;`,鉴权/排空/破坏性写三道门按**行号**
@@ -18,13 +18,13 @@
  *  · `ROUTES` —— **行序 = 分派序**,`position` 说它在全局服务凭据门的哪一侧。门不再「按行号插在链中间」,
  *    而是在 `pre` 段与 `post` 段之间**恒定一处**执行 ⇒ ① 与 ② 合一(名册就是分派序本身,两者再不可能漂),
  *    那道「从 handle() 源码抽序对拍」的门随之删掉 —— 不是放松,是它守的事变成了结构上不可违反。
- *    🔴 S-146 第三刀 车②:**matcher 落地**。一行多了 `decls` 一列(本域真应答的口集合),而
+ *    🔴 [ref] 第三刀 车②:**matcher 落地**。一行多了 `decls` 一列(本域真应答的口集合),而
  *    `ROUTE_DECLARATIONS` 就是这一列按行序摊平 ⇒「分派表」与「声明表」从此是同一份数据的两个投影,
  *    不再是两份要对拍的名单;域 handler 不再看 url / method(见 route-ctx.ts `RouteHandler` 头注)。
  *  · `ROUTE_DECLARATIONS` —— ③④⑤ 合成一张;一行声明它的 `id`(全表唯一身份)、匹配式、它**真被响应**
  *    的 `methods`、以及它**真有**的性质(`billable` / `credentialGated` / `methodDispatched`),
  *    没有该性质就不写那一列(零默认值)。
- *    🔴 S-146 第三刀 车①:这 115 行的**行本体搬回各域**(`routes/x.ts` 的 `X_ROUTES`)—— 路径的
+ *    🔴 [ref] 第三刀 车①:这 115 行的**行本体搬回各域**(`routes/x.ts` 的 `X_ROUTES`)—— 路径的
  *    单一属主与 `*_PATH` 常量今天的属主对齐,本文件只做拼接与查找结构。`RouteDecl` / `RouteMethod`
  *    两个类型住在 `route-ctx.js`(域模块本来就 import 的那只接缝模块),理由见那里的行注。
  *    车②:行分两族 —— **可分派行**(`path` / `pattern`,带 `id` + `methods`)与**纯门行**
@@ -57,7 +57,7 @@ import type { RouteDecl, RouteDispatchDecl, RouteMatch, RouteCtx, RouteMethod }
 import type { BillableKind } from "./readiness.js";
 /** 一只域 handler 相对**全局服务凭据门**的位置。门前 = 未鉴权可达(每一只都要单独论证),门后 = 先过凭据。 */
 /**
- * 一行路由在全局服务凭据门的哪一侧、吃哪道门(闭集,三员;S-672 起由两员拆成三员):
+ * 一行路由在全局服务凭据门的哪一侧、吃哪道门(闭集,三员;[ref] 起由两员拆成三员):
  *  · `"read-credential"` —— 门**之前**,但过**一只**读路谓词(`dispatch.ts` 的 `readCredentialOk`:部署配了 service
  *    凭据时要「服务凭据(含只读 TRACE_TOKEN)∨ 已验 principal」,没配时与全局门同样放行)。只读路才能坐这一段:
  *    它们在门前只为收只读 TRACE_TOKEN 单凭据的调用方,不是为了对端口全开;
@@ -75,7 +75,7 @@ export interface RouteRow {
      *  自己的窄 union 判穷尽。窄↔宽的**绑定**由 {@link row} 工厂在编译期钉死:`decls` 与 `handler` 配错
      *  (把 B 域的表配给 A 域的入口)就是红,不是运行期的静默全不命中。 */
     handler(req: IncomingMessage, res: ServerResponse, match: RouteMatch, ctx: RouteCtx): Promise<void>;
-    /** 本域**真应答的那些口**(S-146 第三刀 车②)—— 一行 ROUTES = 一只域入口 = 它的口集合。
+    /** 本域**真应答的那些口**([ref] 第三刀 车②)—— 一行 ROUTES = 一只域入口 = 它的口集合。
      *  `ROUTE_DECLARATIONS` 就是这一列按行序摊平,所以「声明表」与「分派表」再不可能是两份名单:
      *  一只域忘了挂自己的声明 = 它一个口都分派不到,当场全红,而不是静默漂一行。 */
     readonly decls: readonly RouteDecl[];
@@ -99,7 +99,7 @@ export declare const POST_CREDENTIAL_ROUTES: readonly RouteRow[];
 /**
  * **探针路径**(k8s / 编排器 / 抓取器的常态高频采样):不计 admission inflight、不推活性时钟(`http/server.ts`
  * 的 `noteActivity`)、不入附着租约集 —— 常态采样噪音不许把 SIGHUP 空闲窗 / 引擎租约的「无人使用」判据永远撑开。
- * 两处消费(`dispatch.ts` 的 admission 门、`server.ts` 的活性时钟)读这一只;S-739 前是两份手抄
+ * 两处消费(`dispatch.ts` 的 admission 门、`server.ts` 的活性时钟)读这一只;[ref] 前是两份手抄
  * (`url === "/health" || url.startsWith("/metrics")`),加 `/readyz` 时漏一份 = k8s 每 5-10s 一探就让副本永不空闲。
  */
 export declare function isProbePath(url: string): boolean;
@@ -123,7 +123,7 @@ export declare function isProbePath(url: string): boolean;
  */
 export declare const ROUTE_DECLARATIONS: readonly RouteDecl[];
 /**
- * **匹配一次**(S-146 第三刀 车②)—— 一条可分派行对一条 url:命中 ⇒ 具名捕获组表,不命中 ⇒ `null`。
+ * **匹配一次**([ref] 第三刀 车②)—— 一条可分派行对一条 url:命中 ⇒ 具名捕获组表,不命中 ⇒ `null`。
  *
  * 🔴 `null` 与 `{}` 是**两件事**(`{}` = 命中且无参),所以返回值不是 `Record | undefined`。
  * 没参与匹配的可选组不入表(`m.groups` 里它们是 `undefined`,原样留着 —— 域内判「这一段在不在」
@@ -141,7 +141,7 @@ export declare function billableKindOf(url: string): BillableKind | undefined;
  *  `billable=false`(零模型工作),塞进那张名单会让它们连带吃 drain 与 roster-pending 两道 503 ——
  *  而收编与规则读写在排空期/roster 未落时做完全无害。 */
 export declare function isCredentialGatedRewrite(method: string, url: string): boolean;
-/** S-1281:这次请求是不是一条**只读订阅**(`RouteDeclFacts.subscription` 那一列;方法也要对上 —— 订阅行恒只认 GET)。
+/** [ref]:这次请求是不是一条**只读订阅**(`RouteDeclFacts.subscription` 那一列;方法也要对上 —— 订阅行恒只认 GET)。
  *  分派器在 admission 那一拍(第一个 await 之前)同步判它:订阅不进在飞计数,只进附着集与订阅集。 */
 export declare function isSubscriptionRequest(method: string, url: string): boolean;
 /** 见 `RouteDeclFacts.methodDispatched` 的头注(单 URL 多方法端点)。 */

package/dist/http/routes/agents-roster.d.ts

@@ -32,7 +32,7 @@ import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare const ROSTER_SCAN_LIMIT = 500;
 /**
  * 后台子代在 wire 上的 **id 投影**(唯一一只):名册行的 `handle` 与 `DELETE /v1/sessions/:id` 的 409
- * `conflict.session_children_alive` 体里 `remaining[]` 的每一项都经它出门(S-790,裁定 2026-09-28)—— 两个面上
+ * `conflict.session_children_alive` 体里 `remaining[]` 的每一项都经它出门([ref],裁定 2026-09-28)—— 两个面上
  * 「同一只子代」必须是同一个串,消费方拿删除答复里的 id 才对得上名册里的行、才能去它运行的地方停它。
  */
 export declare function rosterAgentId(row: Pick<BackgroundAgentRowSummary, "handle">): string;

package/dist/http/routes/agents-roster.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { sendUnauthorized } from "../principal-gate.js";
+import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 export const ROSTER_SCAN_LIMIT = 500;
@@ -56,10 +56,9 @@ function decodeCursor(raw) {
 }
 export async function handleAgentRoster(req, res, match, ctx) {
     const { deps } = ctx;
-    const { sessionOwnerScope } = ctx.helpers;
     switch (match.decl.id) {
         case "agents-roster": {
-            const { fleetWide, gateOwner } = sessionOwnerScope(req);
+            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;