@sema-agent/server 7.150.0 → 7.152.0

package/dist/http/owner-access.js

@@ -16,7 +16,7 @@ export function callerOf(req, w) {
     const subject = gatedSubject(req, w.config);
     return {
         subject,
-        operator: explicitOperatorOk(subject === undefined ? undefined : personOf(subject), w.config),
+        operator: explicitOperatorOk(subject === undefined ? undefined : personOf(subject), w.config, "operate"),
         fleet: actsForDeployment(req, w.config, () => subject),
         traceRead: traceTokenPresented(req, w.config),
         principalRequired: DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(w.config),
@@ -24,7 +24,7 @@ export function callerOf(req, w) {
     };
 }
 export function callerOfDecision(base, decider, roster) {
-    return { ...base, subject: deciderSubjectOf(base.subject, decider), operator: explicitOperatorOk(decider, roster), fleet: undefined, traceRead: false };
+    return { ...base, subject: deciderSubjectOf(base.subject, decider), operator: explicitOperatorOk(decider, roster, "operate"), fleet: undefined, traceRead: false };
 }
 export function deciderSubjectOf(requestSubject, decider) {
     return decider === undefined ? undefined : subjectOf(decider, requestSubject === undefined ? undefined : partsOf(requestSubject).scenario);
@@ -47,9 +47,8 @@ export const ROUTE_FACES = {
     "run-task-stop": "run.supervise",
     "elicitation-respond": null,
     "question-respond": null,
-    "tool-approval-respond": null,
-    "tool-approval-read": null,
     "task-ask-decision": null,
+    "task-ask-read": null,
     "run-permission-mode": "run.supervise",
     "run-memory-capture-optout": "run.drive",
     "session-init": null,
@@ -410,9 +409,24 @@ export async function readVisibleSession(entry, store, sessionId) {
     const verdict = await judgeSessionById(entry, store, sessionId);
     return verdict === undefined || verdict === "door" || verdict === "not_visible" ? undefined : verdict;
 }
-export async function sessionOwnerUnchanged(entry, store, sessionId, admittedOwner) {
+export async function sessionOccupantUnchanged(entry, store, sessionId, admitted) {
     const head = await readOwnerCell(entry, sessionId, () => store.headOf(sessionId));
-    return sessionRowPresent(head) && head.owner === admittedOwner;
+    return sessionRowPresent(head) && sameOccupant(admitted, head);
+}
+export async function recheckSyncGate(store, sessionId, admitted, port) {
+    const live = await store.headOf(sessionId);
+    switch (port) {
+        case "pull":
+            return rowRead(live) && sameOccupant(admitted, live);
+        case "push": {
+            const held = rowRead(live) ? live : await deletionHeadReadOf(store)(sessionId);
+            return rowRead(held) && sameOccupant(admitted, held);
+        }
+        default: {
+            const unknownPort = port;
+            throw new Error(`recheckSyncGate: no port ${JSON.stringify(unknownPort)}`);
+        }
+    }
 }
 export async function judgeSession(entry, store, sessionId, reading) {
     if (!sessionRowPresent(reading))
@@ -448,6 +462,15 @@ export function sessionFactsReadOf(store) {
         return rowRead(head) ? { get leafId() { return head.leafId; } } : undefined;
     };
 }
+export function sessionOccupantReadOf(store) {
+    const headOf = store?.headOf;
+    if (typeof headOf !== "function")
+        return undefined;
+    return async (sessionId) => {
+        const head = await headOf.call(store, sessionId);
+        return rowRead(head) ? sessionFaceOfHead(sessionId, head) : undefined;
+    };
+}
 export async function readSessionAgent(store, sessionId) {
     const placementOf = store?.placementOf;
     if (placementOf === undefined)
@@ -477,13 +500,17 @@ export async function readVisibleLatestRun(entry, store, sessionId) {
     const latest = await store.latestRunForSession(sessionId);
     return rowRead(latest) && seesRun(entry, latest.owner) ? latest : undefined;
 }
-export function runListOwnerOf(filter, named) {
+export function listOwnerOf(filter, named) {
     return filter.gateOwner ?? named;
 }
 export function listVisibleRuns(store, filter, named, query) {
-    const owner = runListOwnerOf(filter, named);
+    const owner = listOwnerOf(filter, named);
     return store.listRuns({ ...query, ...(owner ? { owner } : {}) });
 }
+export function listVisibleSessions(lister, filter, named, query) {
+    const owner = listOwnerOf(filter, named);
+    return lister({ ...query, ...(owner !== undefined ? { owner } : {}), ...(filter.includeUnowned ? { includeUnowned: true } : {}) });
+}
 export function listRunsOfScope(store, scope, limit) {
     return store.listRuns({ owner: ownerOfCheckpointScope(scope), limit });
 }
@@ -534,14 +561,17 @@ export const WORKFLOW_SESSION_ASSERTION = {
     "workflow-stream": { phase: "accept", label: "workflow.stream" },
     "workflow-agent-steer": { phase: "accept", label: "workflow.agent-steer" },
 };
+export function workflowScopeOf(subject) {
+    return engineScopeOf(subject);
+}
 export function listVisibleWorkflows(entry, store, opts) {
-    return store.listByScope(engineScopeOf(entry.caller.subject), opts);
+    return store.listByScope(workflowScopeOf(entry.caller.subject), opts);
 }
 export async function judgeWorkflowRun(entry, store, runId) {
     const row = await store.get(runId);
     if (!rowRead(row))
         return "missing";
-    const engineCaller = { ...entry.caller, subject: recoveredSubject(engineScopeOf(entry.caller.subject)) };
+    const engineCaller = { ...entry.caller, subject: recoveredSubject(workflowScopeOf(entry.caller.subject)) };
     const verdict = verdictOnQuals(entry, qualsOf(engineCaller, ownerCellOf(row.scope)));
     if (verdict === "door" || verdict === "not_visible")
         return verdict;

package/dist/http/principal-gate.d.ts

@@ -1,7 +1,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
+import { type NonPersonTier, type OperatorPower, type OperatorRoster } from "../operator-roster.js";
 import { type Person, type Subject } from "../owner-brands.js";
-import type { Caller } from "../owner-faces.js";
+import { type Caller } from "../owner-faces.js";
 import { type IdentitySource, type RunIdentity } from "../identity-source.js";
 import type { Logger } from "../observability/logger.js";
 /** Coerce a possibly-repeated request header to a single string (or undefined). */
@@ -126,23 +127,50 @@ export declare function actsForDeployment(req: IncomingMessage, config: ServiceC
  */
 export declare function serviceTokenDeclaredActsForDeployment(config: Pick<ServiceConfig, "serviceTokenActsForDeployment">): boolean;
 /**
- * 运维名册 —— 「谁是 operator」读的两格(都住在部署配置里):具名名单 `OPERATOR_PRINCIPALS` 与单用户形的显式声明 `OPERATOR_SINGLE_USER`。
- * 两者互斥(声明只在单用户形、名单为空时成立;否则拒启 —— 一个事实一个来源,`config-invariants.ts` 的 `operator-single-user`)。
- */
-export type OperatorRoster = Pick<ServiceConfig, "operatorPrincipals" | "operatorSingleUser">;
-/**
- * 🔴 **「谁是 operator」的唯一读法**([ref],[ref] ① 裁 A;IMAGE-API-DESIGN.md §P2.4a MUST-FIX 的那一只门)。
+ * 🔴 **「这位验过的人在这台部署上持不持这只运维权力」的唯一读法**([ref],[ref] ① 裁 A;IMAGE-API-DESIGN.md §P2.4a MUST-FIX 的那一只门)。
+ * 档表与人 → 档的读法住在叶子 `operator-roster.ts`(`ROSTER_TIERS` / `rosterTierOf`);本函数 = 「人落在某档 ∧ 那一档持 `power`」。
  *  · 名单为空 ⇒ **没人是**(没有任何形把「空名单」读成「人人是」—— 那条读法 `isOperator` 已删);
- *  · 名单非空 ⇒ 验过的主体在名单里才是;
- *  · 单用户形显式声明 `OPERATOR_SINGLE_USER=true` ⇒ 这台部署的**每个调用方**都是(单用户形只有一位用户,能到这台部署的就是他;边界是部署自己的
- *    凭据门 —— 没配凭据的部署上,能连上端口的都是)。声明只在单用户形成立(起服不变量)。
+ *  · 名单非空 ⇒ 验过的人在名单里才是;全运维档(`OPERATOR_PRINCIPALS`)持每一只权力,排空档(`OPERATOR_DRAIN_PRINCIPALS`)只持 `drain`;
+ *  · 单用户形显式声明 `OPERATOR_SINGLE_USER=true` ⇒ 这台部署的**每个调用方**落全运维档(单用户形只有一位用户,能到这台部署的就是他;边界是部署自己的
+ *    凭据门 —— 没配凭据的部署上,能连上端口的都是)。声明只在单用户形、且各档名单都空时成立(起服不变量)。
+ * `power` 必填、零缺省:运维面的门与放宽位传 `"operate"`,排空口传它声明行的 `power`(`routes/admin-drain.ts`)。
  * `person` 必须是验过的人(`gatedPerson` / `personOf(主体)`),绝不是自述头,也不是带场景的主体(名册登记的是人)。全部运维面(审批队列、steer / interrupt / wake 的属主门旁路、记忆运维口、bake 门……)读这一只 —— 只答授权;
  * 送话口的文本框架(`trusted`)从不读它(调用方的话恒 `trusted: false`,见 `routes/runs.ts` steer 口的注);
  * 🔴 SINGLE mint point (E1):不要再造兄弟。
  */
-export declare function explicitOperatorOk(person: Person | undefined, roster: OperatorRoster): boolean;
-/** 「这台部署**有没有**运维」的唯一读法(名单非空 ∨ 单用户声明在场)—— 能力事实 `operatorLane` 读这一只(整理阀门的可达性告警随本条退役)。单用户形上,装了运维面的进程里它恒真(`operator-declaration-required`:服务进程起服第 1 段、`createHttpServer` 对不声明的单用户形拒),多租形上空名单 ⇒ 假。 */
-export declare function operatorRosterPresent(roster: OperatorRoster): boolean;
+export declare function explicitOperatorOk(person: Person | undefined, roster: OperatorRoster, power: OperatorPower): boolean;
+/** 「这台部署上**有没有**人能持这只权力」的唯一读法(持它的某档名单非空 ∨ 单用户声明在场)—— 能力事实 `operatorLane` 读这一只(整理阀门的可达性告警随本条退役)。单用户形上,装了运维面的进程里它恒真(`operator-declaration-required`:服务进程起服第 1 段、`createHttpServer` 对不声明的单用户形拒),多租形上持它的各档名单都空 ⇒ 假。 */
+export declare function operatorRosterPresent(roster: OperatorRoster, power: OperatorPower): boolean;
+/**
+ * 🔴 **圈禁的唯一判官**(三个读点,同一只判:请求的人 —— {@link requestConfinedTier},分派层整次请求判一次;决定证明推出的决定者 —— 直连门决定口验过证明之后,
+ * `routes/approvals-assistant.ts` 的 `admitDirectDoorDecider`;设备行的属主 —— {@link deviceOwnerConfinedTier},设备 hello 准入,`device-ws-hub.ts`)。`person` 落在**非人档** ∧ 这一条路由没声明那一档持的权力(`power` = 路由声明行的 `power` 列,缺席 = 没声明)
+ * ⇒ 答那一档(调用方 403 `auth.principal_confined`,{@link sendPrincipalConfined});人档 / 不在名册 / 路由声明了它持的权力 ⇒ `undefined`(照常往下判)。
+ * 不是第二套鉴权:身份读法、名册来源都不新;它答的是「这只验过的身份在本请求上能不能用」——与 [ref] `auth.scope_mismatch` 同一位置的第二个原因。
+ */
+export declare function confinedTierOf(person: Person | undefined, roster: OperatorRoster, power: OperatorPower | undefined): NonPersonTier | undefined;
+/**
+ * 请求读点:这次请求的人在本路由上被不被圈禁。**只在名册里有非人档的名字时读人**(`rosterHasNonPersonNames`;没声明的部署零新读、逐字节同今天)。
+ * 读的是这次请求里**任一只验得过的人**(`verifiedPerson`:三来源按身份边界的序),**不**因同一请求另带了一枚验不过的 Bearer 而读成「没有人」——
+ * 那条律(`gatedSubject`)只收窄身份、从不授权;圈禁是收窄的另一面,请求里只要出示了一只被圈禁的身份就判它(读路凭据谓词照样会认那只身份,
+ * 例如直连门 principal 令牌 + 坏 Bearer 的 `/health`,所以这里不能比它少认)。**不判场景头**(不把「REQUIRE 401 先于场景头 400」的既有序提前改掉)。
+ * 读人只在人名坏形时抛(`assertPrincipalShape` 的 400):非人档的名字由起服 / 装配不变量 `operator-roster-well-formed` 保证都是合形的主体名,坏形的串
+ * 永远对不上任何一个 ⇒ 本请求没有可圈禁的身份 ⇒ 不判(下游每一次读人都抛同一只、同一处答 400)。这不是放宽臂:名单里的人永远读得出来。
+ */
+export declare function requestConfinedTier(req: IncomingMessage, config: ServiceConfig, power: OperatorPower | undefined): NonPersonTier | undefined;
+/**
+ * 设备读点:设备行的属主此刻被不被圈禁。设备车道不经 HTTP(`GET /v1/device/ws` 凭设备密钥对握手,不带任何一枚人的凭据),所以请求读点看不到它;设备行按**属主**绑定,
+ * 登记那一刻的属主是验过的人 —— `http/execution-context.ts` 的 `deviceOwnerDomainOf` 是复合身份 `{ tenant, subject }` 的唯一铸点,`subject` 格逐字节取自 `gatedPerson` ——
+ * 于是行里存的就是一只持久的属主串,按恢复管线(`recoveredSubject` → `personOf`;与组织信封的发件人同一条)读回那位人,再交同一只判官。设备车道上没有任何路由声明过权力
+ * (`power` 缺席):落在非人档的属主在这条车道上整个不算数 —— 它登记的设备不许连上、不许为它执行指令(HTTP 面同一位置已 403)。
+ * 读的是名册**现态**(`roster` 每次现读,不拍快照、不把「登记时在哪一档」记在设备行里)。名册只来自 env、起服冻结 ⇒ 进程内连着的设备不会被挪档;挪档后的重启,新进程的每一次 hello 按新名册判。
+ */
+export declare function deviceOwnerConfinedTier(owner: {
+    readonly subject: string;
+}, roster: OperatorRoster): NonPersonTier | undefined;
+/** 圈禁拒句(一档一句,模块级常量;冻结门按常量解引用逐字钉)。不回显主体名;点名名单所在的 env 与这一档能用的那一条路由。 */
+export declare const PRINCIPAL_CONFINED_DRAIN = "forbidden \u2014 this caller is a drain-only service principal on this deployment (it is named in OPERATOR_DRAIN_PRINCIPALS), and that identity counts only on POST /v1/admin/drain: every other endpoint refuses it; use an identity that is not on that list for anything else";
+/** `403 auth.principal_confined` 的唯一铸点(一档一句,穷举 switch:加一只非人档不接句子 = 编译红)。 */
+export declare function sendPrincipalConfined(res: ServerResponse, tier: NonPersonTier): void;
 /**
  * 起服一行:部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` ⇒ `service_token_posture { actsForDeployment: false }`(info);缺省不打。
  * 声明形让运维面板开位当天成片 401,而「位关了」与「token 错了」在 wire 上同体(反探测律),这一行是起服时唯一一处说清这台部署选了哪一读法的地方。
@@ -154,14 +182,14 @@ export declare function buildServiceTokenPostureNotice(config: Pick<ServiceConfi
         actsForDeployment: false;
     };
 } | undefined;
-/** operator 面族在「名单为空」这一形上的**唯一**拒发口:事实 `operatorLane`(`capability-facts.ts`)为假 ⇒ 这一面对任何
- *  身份都打不通 = 这台部署上不可用 ⇒ 501,不是鉴权拒(403 只留给「名单非空而你不在名单上」)。能力位读的是同一只事实。 */
-export declare function sendOperatorPrincipalsRequired(res: ServerResponse): void;
+/** operator 面族在「持这只权力的名单都空」这一形上的**唯一**拒发口:事实 `operatorLane(d, power)`(`capability-facts.ts`)为假 ⇒ 这一面对任何
+ *  身份都打不通 = 这台部署上不可用 ⇒ 501,不是鉴权拒(403 只留给「名单非空而你不在名单上」)。能力位读的是同一只事实。一只权力一句(穷举 switch)。 */
+export declare function sendOperatorPrincipalsRequired(res: ServerResponse, power: OperatorPower): void;
 /**
- * 「这台部署没有运维名册」时**唯一**的出路句 —— 与 {@link operatorRosterPresent} 同一对旋钮,所以句子不比事实少说一条出路:
- * 名单 `OPERATOR_PRINCIPALS`(具名运维;多租形只有这一条),或单用户形的显式声明 `OPERATOR_SINGLE_USER=true`(只在 `REQUIRE_PRINCIPAL` 未开且名单为空时成立,
- * 否则起服拒 —— 句子把它限定在单用户部署上)。拒发口 {@link sendOperatorPrincipalsRequired}、能力事实闭集 `operator_principals_empty` 的义、记忆整理阀门的起服告警
- * 都说这一句,别处不再各写一份。
+ * 「这台部署上没有人持这只权力」时**唯一**的出路句 —— 与 {@link operatorRosterPresent} 同一组旋钮(档表里持 `power` 的各档名单 + 单用户声明),所以句子不比事实少说一条出路:
+ * 持它的每一档名单(按档表的规范序列出;`operate` 只有 `OPERATOR_PRINCIPALS`,`drain` 另有 `OPERATOR_DRAIN_PRINCIPALS`),或单用户形的显式声明 `OPERATOR_SINGLE_USER=true`
+ * (只在 `REQUIRE_PRINCIPAL` 未开且各档名单都空时成立,否则起服拒 —— 句子把它限定在单用户部署上)。拒发口 {@link sendOperatorPrincipalsRequired}、能力事实闭集 `operator_principals_empty` 的义、
+ * 记忆整理阀门的起服告警都说这一句,别处不再各写一份。
  */
-export declare function buildOperatorRosterWayOut(): string;
+export declare function buildOperatorRosterWayOut(power: OperatorPower): string;
 //# sourceMappingURL=principal-gate.d.ts.map

package/dist/http/principal-gate.js

@@ -1,7 +1,9 @@
 import { timingSafeEqual } from "node:crypto";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
-import { PRINCIPAL_TOKEN_HEADER, verifiedPerson, verifiedSubject, scenarioHeaderOf, scenarioWithoutPrincipalError, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope } from "../security.js";
+import { HttpError, PRINCIPAL_TOKEN_HEADER, verifiedPerson, verifiedSubject, scenarioHeaderOf, scenarioWithoutPrincipalError, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope } from "../security.js";
+import { ROSTER_TIERS, ROSTER_TIER_ORDER, rosterHasNonPersonNames, rosterNamesOf, rosterTierOf, tierHolds, tierIsPerson } from "../operator-roster.js";
 import { personOf } from "../owner-brands.js";
+import { recoveredSubject } from "../owner-faces.js";
 import { IDENTITY_SOURCES, runIdentityClaimOverflow } from "../identity-source.js";
 import { sendError } from "./send.js";
 import { canonicalAddress } from "../net-address.js";
@@ -159,23 +161,71 @@ export function actsForDeployment(req, config, subject) {
 export function serviceTokenDeclaredActsForDeployment(config) {
     return config.serviceTokenActsForDeployment === true;
 }
-export function explicitOperatorOk(person, roster) {
-    if (roster.operatorSingleUser === true)
-        return true;
-    return roster.operatorPrincipals.length > 0 && person !== undefined && roster.operatorPrincipals.includes(person);
+export function explicitOperatorOk(person, roster, power) {
+    const tier = rosterTierOf(person, roster);
+    return tier !== undefined && tierHolds(tier, power);
 }
-export function operatorRosterPresent(roster) {
-    return roster.operatorSingleUser === true || roster.operatorPrincipals.length > 0;
+export function operatorRosterPresent(roster, power) {
+    return roster.operatorSingleUser === true || ROSTER_TIER_ORDER.some((tier) => tierHolds(tier, power) && rosterNamesOf(tier, roster).length > 0);
+}
+export function confinedTierOf(person, roster, power) {
+    const tier = rosterTierOf(person, roster);
+    if (tier === undefined || tierIsPerson(tier))
+        return undefined;
+    if (power !== undefined && tierHolds(tier, power))
+        return undefined;
+    return tier;
+}
+export function requestConfinedTier(req, config, power) {
+    if (!rosterHasNonPersonNames(config))
+        return undefined;
+    let person;
+    try {
+        person = verifiedPerson(req, config);
+    }
+    catch (e) {
+        if (e instanceof HttpError)
+            return undefined;
+        throw e;
+    }
+    return confinedTierOf(person, config, power);
+}
+export function deviceOwnerConfinedTier(owner, roster) {
+    return confinedTierOf(personOf(recoveredSubject(owner.subject)), roster, undefined);
+}
+export const PRINCIPAL_CONFINED_DRAIN = "forbidden — this caller is a drain-only service principal on this deployment (it is named in OPERATOR_DRAIN_PRINCIPALS), and that identity counts only on POST /v1/admin/drain: every other endpoint refuses it; use an identity that is not on that list for anything else";
+export function sendPrincipalConfined(res, tier) {
+    switch (tier) {
+        case "drain":
+            sendError(res, 403, "auth.principal_confined", PRINCIPAL_CONFINED_DRAIN);
+            return;
+        default: {
+            const unknownTier = tier;
+            throw new Error(`sendPrincipalConfined: unknown confined tier ${String(unknownTier)}`);
+        }
+    }
 }
 export function buildServiceTokenPostureNotice(config) {
     if (serviceTokenDeclaredActsForDeployment(config))
         return undefined;
     return { event: "service_token_posture", fields: { actsForDeployment: false } };
 }
-export function sendOperatorPrincipalsRequired(res) {
-    sendError(res, 501, "capability.operator_principals_required", `this endpoint is operator-only and this deployment has no operator roster (OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not declared), so no caller can be an operator; ${buildOperatorRosterWayOut()}`);
+export function sendOperatorPrincipalsRequired(res, power) {
+    switch (power) {
+        case "operate":
+            sendError(res, 501, "capability.operator_principals_required", `this endpoint is operator-only and this deployment has no operator roster (OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not declared), so no caller can be an operator; ${buildOperatorRosterWayOut(power)}`);
+            return;
+        case "drain":
+            sendError(res, 501, "capability.operator_principals_required", `this endpoint is open to this deployment's operators and its drain-only service principals, and it names neither (OPERATOR_PRINCIPALS and OPERATOR_DRAIN_PRINCIPALS are empty and OPERATOR_SINGLE_USER is not declared), so no caller can call it; ${buildOperatorRosterWayOut(power)}`);
+            return;
+        default: {
+            const unknownPower = power;
+            throw new Error(`sendOperatorPrincipalsRequired: unknown power ${String(unknownPower)}`);
+        }
+    }
 }
-export function buildOperatorRosterWayOut() {
-    return "configure OPERATOR_PRINCIPALS with the named operator principals, or — on a single-user deployment (REQUIRE_PRINCIPAL off) — declare OPERATOR_SINGLE_USER=true";
+export function buildOperatorRosterWayOut(power) {
+    const rosters = ROSTER_TIER_ORDER.filter((tier) => tierHolds(tier, power)).map((tier) => `${ROSTER_TIERS[tier].env} with the named ${ROSTER_TIERS[tier].holders}`);
+    return `configure ${rosters.join(" or ")}, or — on a single-user deployment (REQUIRE_PRINCIPAL off) — declare OPERATOR_SINGLE_USER=true`;
 }
 //# sourceMappingURL=principal-gate.js.map

package/dist/http/request-channel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * **通道事实**(纯叶,只依赖 `node:http` 的型):一条请求从本服务的哪一只监听口进来。
+ *
+ * ## 律(一条)
+ * 闭集 {@link REQUEST_CHANNELS} = `tcp`(TCP 监听口)· `control-socket`(本机控制 socket,`control-socket.ts`)。
+ * 唯一写者 = 控制 socket 那只 `http.Server` 的请求监听器({@link markControlSocketRequest},`http/server.ts` 里恰一处调用);唯一读法 = {@link requestChannelOf}。
+ * **缺标 ⇒ `tcp`**(fail-closed):没被那只监听器标过的请求一律按 TCP 读。不按 `req.socket.remoteAddress` 缺席反推 —— TCP 连接断开之后它同样缺席,反推形是 fail-open。
+ *
+ * ## 通道换来什么(不换来什么)
+ * 控制 socket 证明的是「对端是引擎的 OS 用户(或 root)」—— 能穿过私有目录的只有他们。宿主车道上模型跑的命令也是这个用户,所以**通道不是凭据**:
+ * 它不进读路谓词(`dispatch.ts` 的 `readCredentialOk`)、不进全局凭据门、不进身份来源闭集(`identity-source.ts` 的 `IDENTITY_SOURCES`);
+ * 它只换来 `/health` 的读者档 `engine-user`(引擎自描述的全键,`health-reader.ts`)、诊断面远程来源门的「本机」一读、限流的地址回落键。
+ * 读它的每一处都**穷举**本闭集(`switch` + `never`),没有一处写「等于某一词」的比较 —— 加一种通道不接 ⇒ 编译红,而不是默认得到某一档。
+ */
+import type { IncomingMessage } from "node:http";
+/** 请求通道的闭集(顺序无语义)。 */
+export declare const REQUEST_CHANNELS: readonly ["tcp", "control-socket"];
+export type RequestChannel = (typeof REQUEST_CHANNELS)[number];
+/** **唯一写者**:控制 socket 那只 `http.Server` 的请求监听器在把请求交给共享监听器之前调一次。别处调用 = 把 TCP 请求读成本机用户(源码门钉调用点恰一处)。 */
+export declare function markControlSocketRequest(req: IncomingMessage): void;
+/** 这条请求从哪一只监听口进来 —— 唯一读法;缺标 ⇒ `tcp`。 */
+export declare function requestChannelOf(req: IncomingMessage): RequestChannel;
+//# sourceMappingURL=request-channel.d.ts.map

package/dist/http/request-channel.js

@@ -0,0 +1,9 @@
+export const REQUEST_CHANNELS = ["tcp", "control-socket"];
+const controlSocketRequests = new WeakSet();
+export function markControlSocketRequest(req) {
+    controlSocketRequests.add(req);
+}
+export function requestChannelOf(req) {
+    return controlSocketRequests.has(req) ? "control-socket" : "tcp";
+}
+//# sourceMappingURL=request-channel.js.map

package/dist/http/request-guards.js

@@ -9,6 +9,7 @@ import { escapedStatementBytes, packetWallStatementBytes, rowWallPayloadBytes }
 import { MAX_JSON_BODY_BYTES } from "../json-body-limit.js";
 import { deliverVia } from "../submission-exit.js";
 import { canonicalAddress } from "../net-address.js";
+import { requestChannelOf } from "./request-channel.js";
 export function refuseSubmitBody(walls, body) {
     const rowWall = walls.maxRowBytes;
     const packetWall = walls.maxPacketBytes;
@@ -171,8 +172,7 @@ export function createRequestGuards(ctx) {
     function rateLimited(req, res) {
         if (!deps.rateLimiter)
             return false;
-        const peer = req.socket.remoteAddress;
-        const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? (peer === undefined ? "anon" : (canonicalAddress(peer) ?? peer));
+        const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? rateLimitAddressKeyOf(req);
         const d = deps.rateLimiter.check(key);
         if (d.allowed)
             return false;
@@ -220,4 +220,19 @@ export function createRequestGuards(ctx) {
     }
     return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, readJson, readRawBody };
 }
+function rateLimitAddressKeyOf(req) {
+    const channel = requestChannelOf(req);
+    switch (channel) {
+        case "tcp": {
+            const peer = req.socket.remoteAddress;
+            return peer === undefined ? "anon" : (canonicalAddress(peer) ?? peer);
+        }
+        case "control-socket":
+            return "control-socket";
+        default: {
+            const unknownChannel = channel;
+            throw new Error(`rate limit: request channel ${String(unknownChannel)} has no address key`);
+        }
+    }
+}
 //# sourceMappingURL=request-guards.js.map

package/dist/http/resume-ctx-read.js

@@ -2,6 +2,8 @@ import { openCheckpointCtx } from "./checkpoint-ctx.js";
 import { storeFaultClassOf } from "../plugins/store-fault.js";
 import { refusalBody } from "./refusal-body.js";
 import { frozenProjectContextOf } from "../project-context.js";
+import { frozenMemorySeedOf } from "../project-registry.js";
+import { permissionModeWriteOf } from "../permission-mode-admission.js";
 export async function readResumeCtx(load, opening) {
     const read = await readStoredCtx(load);
     if (read.kind !== "ok")
@@ -9,19 +11,56 @@ export async function readResumeCtx(load, opening) {
     const opened = openCheckpointCtx(read.ctx, opening.opener, opening.sessionId);
     if (opened.kind !== "ok")
         return { kind: "unsealable", field: opened.field, reason: opened.reason };
+    const where = (key) => ({ kind: "corrupt", where: `checkpoint ctx for session ${JSON.stringify(opening.sessionId)}: ${key}` });
+    const { memorySeed: _storedSeed, projectContext: _storedContext, permissionModeWrite: _storedWrite, ...rest } = opened.ctx;
+    const seed = frozenMemorySeedOf(opened.ctx.memorySeed);
     const frozen = frozenProjectContextOf(opened.ctx.projectContext);
+    const written = permissionModeWriteOf(opened.ctx.permissionModeWrite);
+    let seedPart;
+    switch (seed.kind) {
+        case "absent":
+            seedPart = {};
+            break;
+        case "none":
+            seedPart = { memorySeed: null };
+            break;
+        case "malformed":
+            return where("memorySeed");
+        case "ok":
+            seedPart = { memorySeed: seed.seed };
+            break;
+        default: {
+            const unhandled = seed;
+            throw new Error(`resume-ctx-read: unplaced frozen memory seed reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+    let contextPart;
     switch (frozen.kind) {
         case "absent":
-            return { kind: "ok", ctx: opened.ctx };
+            contextPart = {};
+            break;
         case "malformed":
-            return { kind: "corrupt", where: `checkpoint ctx for session ${JSON.stringify(opening.sessionId)}: projectContext` };
+            return where("projectContext");
         case "ok":
-            return { kind: "ok", ctx: { ...opened.ctx, projectContext: frozen.context } };
+            contextPart = { projectContext: frozen.context };
+            break;
         default: {
             const unhandled = frozen;
             throw new Error(`resume-ctx-read: unplaced frozen project context reading ${JSON.stringify(unhandled)}`);
         }
     }
+    switch (written.kind) {
+        case "absent":
+            return { kind: "ok", ctx: { ...rest, ...seedPart, ...contextPart } };
+        case "malformed":
+            return where("permissionModeWrite");
+        case "ok":
+            return { kind: "ok", ctx: { ...rest, ...seedPart, ...contextPart, permissionModeWrite: written.write } };
+        default: {
+            const unhandled = written;
+            throw new Error(`resume-ctx-read: unplaced permission-mode write reading ${JSON.stringify(unhandled)}`);
+        }
+    }
 }
 async function readStoredCtx(load) {
     let stored;

package/dist/http/resume-legs.d.ts

@@ -21,7 +21,7 @@ import type { HostDecision } from "../host-decision.js";
 import { type GateSighting } from "../approval-gate-currency.js";
 import { type CancelRunReader } from "../run-cancel-card.js";
 import { type PlanApprovePermissionModeAfter } from "../task-settings.js";
-import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview, RememberSessionRequest, ResumeCheckpointOutcome, ResumeLegOutcome, WorkflowDecisionDelivery } from "./route-ctx.js";
+import type { RouteCtxBase, DriveResumeArgs, PersistRuleRequest, PreparedPlanReview, RememberSessionRequest, ResumeCheckpointOutcome, ResumeLegOutcome, WorkflowDecisionDelivery } from "./route-ctx.js";
 import type { RunRegistry, RouteHelpers, RouteLegs } from "./route-ctx.js";
 import type { createRequestGuards } from "./request-guards.js";
 import type { FlatServiceDeps } from "./server.js";
@@ -121,7 +121,7 @@ export declare function createResumeLegs(ctx: {
     runnerFor: FlatServiceDeps["runnerFor"];
 } & RunRegistry & RouteHelpers & Pick<RouteLegs, "prepareSpec" | "finalizeTaskResult"> & Pick<ReturnType<typeof createRequestGuards>, "ownerCostQuotaDenied" | "ownerFleetLeaseDenied" | "usageWindowDenialFor">): {
     routeCtxBase: RouteCtxBase;
-    resumeCheckpoint: (sessionId: string, decision: "approve" | "deny", reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, answer: QuestionAnswer | undefined, binding: DecideBinding, remember?: RememberSessionRequest, acceptEarly?: boolean, decider?: KeyCaller, restatement?: ResumeRestatement) => Promise<ResumeCheckpointOutcome>;
+    resumeCheckpoint: (sessionId: string, decision: "approve" | "deny", reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, answer: QuestionAnswer | undefined, binding: DecideBinding, remember?: RememberSessionRequest, acceptEarly?: boolean, decider?: KeyCaller, restatement?: ResumeRestatement, persistRule?: PersistRuleRequest) => Promise<ResumeCheckpointOutcome>;
     driveResumeIntoRunLog: (args: DriveResumeArgs) => Promise<ResumeLegOutcome>;
     driveResumeLeg: (args: DriveResumeArgs, onAccepted?: (receipt: {
         status: number;
@@ -129,7 +129,7 @@ export declare function createResumeLegs(ctx: {
     }) => void) => Promise<ResumeLegOutcome>;
     decisionRowAdmits: (cs: CheckpointStoreFull, token: CheckpointToken, who: KeyCaller | undefined, bodyScope: string | undefined) => Promise<boolean>;
     resumePreempted: (sessionId: string, req: IncomingMessage | undefined, acceptEarly?: boolean, decider?: KeyCaller, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
-    startFreshHostTurn: (sessionId: string, objective: string, subject: string | undefined, req: IncomingMessage, workflowDecision: WorkflowDecisionDelivery, runId: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
+    startFreshHostTurn: (sessionId: string, objective: string, subject: string | undefined, req: IncomingMessage | undefined, workflowDecision: WorkflowDecisionDelivery, runId: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
     resumeWake: (sessionId: string, message: PendingSteerInput | undefined, caller: Subject | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, workflowDecision?: WorkflowDecisionDelivery, ownerLeaseAdmittedFor?: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
     preparePlanReview: (sessionId: string, log?: {
         taskId?: string;
@@ -146,6 +146,7 @@ export declare function createResumeLegs(ctx: {
     }>;
     drivePlanReview: (prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, acceptEarly?: boolean, permissionModeAfter?: PlanApprovePermissionModeAfter) => Promise<ResumeLegOutcome>;
     sessionNotifyDoor: import("../session-notify-door.js").SessionNotifyDoor;
+    handOverRunEndedDecisions: (runId: string) => Promise<void>;
 };
 export {};
 //# sourceMappingURL=resume-legs.d.ts.map