@sema-agent/server 7.145.0 → 7.146.0

package/dist/rules-consent.js

@@ -5,7 +5,7 @@ import { createLogger } from "./observability/logger.js";
 import { ABSOLUTE_HOST_PATH_MAX, hasControlOrBidi } from "@sema-agent/settings-schema";
 import { isDirectWritableRuleBehavior } from "./permission-rule-vocab.js";
 import { hasBidiControls } from "./text-bidi.js";
-import { confirmRuleApproval, RULE_BEHAVIORS, parseRuleText, ruleReachesProgramRun, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, isValidDurableScope, effectiveOrThrow, readRowBehavior, readRuleOwner, } from "@sema-agent/core";
+import { confirmRuleApproval, RULE_BEHAVIORS, RULE_REFUSAL_CODES, parseRuleText, ruleReachesProgramRun, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, isValidDurableScope, effectiveOrThrow, readRowBehavior, readRuleOwner, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
@@ -21,7 +21,7 @@ const ImportOutcomeSchema = z
         .object({
         key: z.object({ behavior: z.preprocess((v) => readRowBehavior(v) ?? v, z.enum(RULE_BEHAVIORS)), rule: z.string().min(1), scope: z.string().min(1) }).strict(),
         outcome: z.enum(["persisted", "no-op", "refused", "indeterminate"]),
-        reason: z.literal("store_refused").optional(),
+        reason: z.enum(RULE_REFUSAL_CODES).optional(),
         detail: z.string().optional(),
     })
         .strict()),
@@ -137,6 +137,52 @@ function confirmRefusalWord(reason) {
         }
     }
 }
+function isRuleStoreFault(code) {
+    switch (code) {
+        case "store_read":
+        case "store_write":
+            return true;
+        case "unsupported.layer_root":
+        case "ticket_invalid":
+        case "record_missing":
+        case "wrong_principal":
+        case "record_schema_stale":
+        case "not_confirmed":
+        case "record_malformed":
+        case "not_chosen":
+        case "parse_rejected":
+        case "store_unavailable":
+        case "record_changed":
+        case "withheld":
+        case "session_ended":
+        case "occ":
+        case "dot_removed":
+            return false;
+        default:
+            return code;
+    }
+}
+class RuleStoreFaultError extends Error {
+    code;
+    constructor(refusal) {
+        super(refusal.reason);
+        this.name = "RuleStoreFaultError";
+        this.code = refusal.code;
+    }
+}
+function throwIfRuleStoreFault(refusal) {
+    const { code } = refusal;
+    if (!isRuleStoreFault(code))
+        return;
+    switch (refusal.committed) {
+        case "no":
+            throw new RuleStoreFaultError({ code, reason: refusal.reason });
+        case "unknown":
+            return;
+        default:
+            return refusal.committed;
+    }
+}
 function refusedMembersOf(members) {
     const refused = [];
     for (const m of members) {
@@ -250,7 +296,7 @@ function buildImportOutcomeMembers(members) {
             case "deduped":
                 return { key, outcome: "no-op" };
             case "refused":
-                return { key, outcome: "indeterminate", reason: "store_refused", detail: m.reason };
+                return { key, outcome: refusedOutcomeOf(m.committed), reason: m.code, detail: m.reason };
             default: {
                 const unknown = m;
                 throw new Error(`unknown redeemed-batch member status: ${JSON.stringify(unknown)}`);
@@ -258,6 +304,22 @@ function buildImportOutcomeMembers(members) {
         }
     });
 }
+function unsettledDetailOf(members) {
+    const open = members.find((m) => m.outcome === "indeterminate");
+    return open === undefined ? undefined : `the outcome of ${open.key.rule} is not known (${open.reason ?? "unknown"}): ${open.detail ?? ""}`;
+}
+function refusedOutcomeOf(committed) {
+    switch (committed) {
+        case "no":
+            return "refused";
+        case "unknown":
+            return "indeterminate";
+        default: {
+            const unknown = committed;
+            throw new Error(`unknown redeemed-batch member committed word: ${JSON.stringify(unknown)}`);
+        }
+    }
+}
 export function createRuleConsentLane(stores, opts) {
     const deps = { provider: stores.provider, approvals: stores.approvals, cardEdits: true };
     const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
@@ -300,10 +362,15 @@ export function createRuleConsentLane(stores, opts) {
                 if (!confirmed.ok)
                     return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
                 const result = await redeemRuleBatch({ approvalId: prepared.approvalId, principal: input.principal, deps });
-                if ("status" in result)
+                if ("status" in result) {
+                    throwIfRuleStoreFault(result);
                     return { ok: false, reason: "redeem-refused", detail: result.reason };
+                }
                 const refused = refusedMembersOf(result.members);
                 if (refused.length > 0) {
+                    if (refused.length === result.members.length && refused.every((m) => m.committed === "no"))
+                        for (const m of refused)
+                            throwIfRuleStoreFault(m);
                     return { ok: false, reason: "redeem-refused", detail: `partial batch: ${refused.length} member(s) refused (${refused.map((x) => x.reason).join("; ")})` };
                 }
                 return { ok: true, ...anchorBatchMembers(result.members, redemption.offer), rev: result.rev };
@@ -351,8 +418,10 @@ export function createRuleConsentLane(stores, opts) {
                 ticket = minted.ticket;
             }
             const redeemed = await redeemRuleTicket({ ticket, principal: input.principal, deps });
-            if (redeemed.status !== "redeemed")
+            if (redeemed.status !== "redeemed") {
+                throwIfRuleStoreFault(redeemed);
                 return { ok: false, reason: "redeem-refused", detail: redeemed.reason };
+            }
             return { ok: true, kind: "single", rule: redeemed.rule, rev: redeemed.rev, alreadyRedeemed: redeemed.alreadyRedeemed };
         },
         async prepareImport(principal, layers) {
@@ -449,7 +518,11 @@ export function createRuleConsentLane(stores, opts) {
                 if ("status" in result) {
                     return await indeterminate(result.reason);
                 }
-                return { ok: true, outcome: { members: buildImportOutcomeMembers(result.members), rev: result.rev } };
+                const members = buildImportOutcomeMembers(result.members);
+                const open = unsettledDetailOf(members);
+                if (open !== undefined)
+                    return await indeterminate(open);
+                return { ok: true, outcome: { members, rev: result.rev } };
             }
             catch (err) {
                 return await indeterminate(err instanceof Error ? err.message : String(err));
@@ -607,6 +680,9 @@ export function createRuleConsentLane(stores, opts) {
                     }
                     members = buildImportOutcomeMembers(result.members);
                     rev = result.rev;
+                    const open = unsettledDetailOf(members);
+                    if (open !== undefined)
+                        return await transient(open);
                 }
                 catch (err) {
                     return await transient(err instanceof Error ? err.message : String(err));

package/dist/run-cancel-context.d.ts

@@ -136,6 +136,9 @@ export declare function buildCancelledLedgerRow(c: PersistedTaskResult): {
  * `signal.reason`:那会改掉引擎与 provider 层收到的拒绝值,是在下游改上游接缝的输入(立宪禁区)。
  */
 export interface RunAbort {
+    /** 这条腿的**属主**(run 行的 `owner` 列;无主体 = `null`)—— 在飞集(`inflightRuns`)里「谁占着几条」的唯一读处:并发帽按主体数在飞腿时读它
+     *  (`http/run-concurrency-cap.ts`),不另起一张按 taskId 键控的旁表。句柄与腿同寿,换腿就是换句柄。 */
+    readonly owner: string | null;
     /** 交给引擎的那只信号(`spec.signal` / 审批 / 提问 ALS 的 `abortSignal` / 子代 stoppedBy 归因都用它)。 */
     readonly signal: AbortSignal;
     /** 以 `cause` 中止本腿。已中止 ⇒ no-op(成因不改写)。 */
@@ -143,6 +146,6 @@ export interface RunAbort {
     /** 让本腿停下来的那次中止的成因;未中止 ⇒ `undefined`。 */
     cause(): AbortCause | undefined;
 }
-export declare function createRunAbort(): RunAbort;
+export declare function createRunAbort(owner: string | null): RunAbort;
 export {};
 //# sourceMappingURL=run-cancel-context.d.ts.map

package/dist/run-cancel-context.js

@@ -51,10 +51,11 @@ export function buildCancelledLedgerRow(c) {
         ...(c.abortCause !== undefined ? { abortCause: c.abortCause } : {}),
     };
 }
-export function createRunAbort() {
+export function createRunAbort(owner) {
     const ctrl = new AbortController();
     let landed;
     return {
+        owner,
         signal: ctrl.signal,
         abort(cause) {
             if (ctrl.signal.aborted)

package/dist/runs.js

@@ -285,7 +285,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart();
-    const cancelCtrl = createRunAbort();
+    const cancelCtrl = createRunAbort(principal ?? null);
     inflight?.set(taskId, cancelCtrl);
     markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
     const preemptEligible = verify === undefined && cascade === undefined;

package/dist/sandbox-egress-policy.js

@@ -1,4 +1,5 @@
-import { BlockList, isIP } from "node:net";
+import { isIP } from "node:net";
+import { createCidrSet, parseCidr as readCidrText } from "./net-address.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { seatText } from "./trace/exit-seat.js";
 export const SANDBOX_IPV6_WORDS = ["enabled", "disabled"];
@@ -155,22 +156,16 @@ function nodeAddresses(json) {
     return out;
 }
 function parseCidr(cidr) {
-    const slash = cidr.indexOf("/");
-    const net = slash < 0 ? cidr : cidr.slice(0, slash);
-    const fam = isIP(net);
-    const max = fam === 6 ? 128 : 32;
-    const prefix = slash < 0 ? max : Number(cidr.slice(slash + 1));
-    if (fam === 0 || !/^\d+$/.test(slash < 0 ? String(max) : cidr.slice(slash + 1)) || prefix > max)
+    const r = readCidrText(cidr);
+    if (!r.ok)
         throw new Unjudgeable(`ipBlock cidr ${JSON.stringify(cidr)} does not parse`);
-    return { net, prefix, family: fam === 6 ? "ipv6" : "ipv4" };
+    return r.cidr;
 }
 function inCidr(address, cidr) {
     const c = parseCidr(cidr);
     if ((isIP(address) === 6 ? "ipv6" : "ipv4") !== c.family)
         return false;
-    const list = new BlockList();
-    list.addSubnet(c.net, c.prefix, c.family);
-    return list.check(address, c.family);
+    return createCidrSet([c]).has(address);
 }
 function ruleAllows(rule, address) {
     if (rule.to === undefined)

package/dist/sandbox-rbac-rules.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 沙箱车道(`REMOTE_EXEC=k8s`)的服务账号在沙箱命名空间 / 集群里需要哪些 RBAC 规则,以及每条规则由哪个引擎特性开关决定 ——
+ * 「引擎需要哪条规则由哪个开关决定」**只写在这一张表里**。
+ *
+ * ## 谁读它(都是读者,没有第二份)
+ *  · `scripts/gen-deploy-lanes.ts`:把本表渲成部署产物 —— chart `templates/sandbox-rbac.yaml` 的 Role / ClusterRole 规则区(开关条件规则包在 helm 条件里)、
+ *    chart `templates/_helpers.tpl` 里把同一个开关值写进引擎旋钮的助手体、cluster 静态清单的同两个规则区(静态清单不能条件渲,引擎 env 里两个旋钮都没设,
+ *    开关条件规则渲成注释掉的规则块)、`docs/DEPLOY-PREREQS.md` 的规则表区,以及给取用方的只读数据 `deploy/facts/sandbox-rbac.json`。
+ *    「入库文件 ≡ 生成物」由 `--check` 与 `test/deploy-lane-projections.test.ts` 钉;行为由 `test/sandbox-rbac-table.test.ts` 钉。
+ *  · secrets 那一行的动词**直接就是** {@link SANDBOX_SECRET_SEAT_VERBS}`.env`(起服门问的、适配器真发的同一张表)—— 不另抄一份。
+ *    pvc 那一行的动词 ⊇ 适配器对 `persistentvolumeclaims` 真发的每个调用(`test/sandbox-rbac-table.test.ts` 读 `remote-env-k8s.ts` 对拍)。
+ *
+ * ## 形
+ *  · `when`:`"always"`(恒授)或一个**特性开关词**({@link SANDBOX_RBAC_SWITCH_WORDS},闭集;加词必须同时给 {@link SANDBOX_RBAC_SWITCHES} 一行 —— 缺行是编译错)。
+ *  · 开关 = 引擎旋钮的一个状态:`bool` 形 = 旋钮取某个词时开(`WORKSPACE_CACHE=volume`),`names` 形 = 旋钮是 NAME,NAME 名单、非空时开(`K8S_SANDBOX_ENV`)。
+ *    随包 chart 里同一个值(`chartValue`)既写引擎旋钮、又决定 Role 带不带那几行规则。
+ *  · `need`:这一行的动词引擎适配器**真调**(`called`,`why` 里写着调用它的适配器方法〔`remote-env-k8s.ts#<方法名>`〕,源码钉对拍)还是只是**兼容保留**
+ *    (`retained`:chart 与静态清单一直授着、适配器源码里零调用)。同一个资源的动词按 `need` 拆成两行;chart 与静态清单把同资源的行并回一条规则照授(本版不删 `retained`)。
+ *  · 给取用方的数据 `deploy/facts/sandbox-rbac.json` = `{ schemaVersion, rules: [{ scope, apiGroups, resources, verbs, when, need, why }] }`(随包;npm 子路径同名),
+ *    形由本文件的 {@link SANDBOX_RBAC_FACTS_SCHEMA} 定义(和表放一起;生成器把它写成 `deploy/facts/sandbox-rbac.schema.json`)。
+ *    形变的加性 / 破坏性判法、登记与 `schemaVersion` 的派生是随包部署事实的统一规则,见 `src/deploy-facts.ts` 头注 —— 本表不另立一套。
+ */
+import type { WorkspaceCacheWord } from "./workspace-cache.js";
+import { type FactsRootSchema } from "./deploy-facts.js";
+/** `deploy/facts/sandbox-rbac.json` 的形版本(从形变登记表派生,见 `src/deploy-facts.ts` 的 `factsSchemaVersion`)。 */
+export declare const SANDBOX_RBAC_SCHEMA_VERSION: number;
+export declare const SANDBOX_RBAC_SCOPES: readonly ["Role", "ClusterRole"];
+export type SandboxRbacScope = (typeof SANDBOX_RBAC_SCOPES)[number];
+/** Kubernetes RBAC 动词闭集(规则只收这些词)。 */
+export declare const SANDBOX_RBAC_VERBS: readonly ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"];
+export declare const SANDBOX_RBAC_ALWAYS: "always";
+/** 特性开关词:引擎旋钮的一个状态。词表是闭集 —— {@link SANDBOX_RBAC_SWITCHES} 对它做穷尽映射(新增一个词而不给开关行 ⇒ 编译错)。 */
+export declare const SANDBOX_RBAC_SWITCH_WORDS: readonly ["WORKSPACE_CACHE=volume", "K8S_SANDBOX_ENV"];
+export type SandboxRbacSwitchWord = (typeof SANDBOX_RBAC_SWITCH_WORDS)[number];
+/** `when` 的全词表:恒授 + 开关词。 */
+export declare const SANDBOX_RBAC_WHEN_WORDS: readonly ["always", "WORKSPACE_CACHE=volume", "K8S_SANDBOX_ENV"];
+export type SandboxRbacWhen = (typeof SANDBOX_RBAC_WHEN_WORDS)[number];
+export type SandboxRbacSwitch = {
+    /** 旋钮取 {@link envValue} 时开。 */
+    readonly kind: "bool";
+    readonly env: string;
+    readonly envValue: WorkspaceCacheWord;
+    /** 随包 chart 的值路径,恒 `sandbox.<键>`;布尔。 */
+    readonly chartValue: string;
+    readonly meaning: string;
+} | {
+    /** 旋钮是 NAME,NAME 名单,非空时开。 */
+    readonly kind: "names";
+    readonly env: string;
+    /** 随包 chart 的值路径,恒 `sandbox.<键>`;名单字符串。 */
+    readonly chartValue: string;
+    readonly meaning: string;
+};
+export declare const SANDBOX_RBAC_SWITCHES: {
+    readonly [W in SandboxRbacSwitchWord]: SandboxRbacSwitch;
+};
+/** 一行动词的引擎用度:`called` = 适配器源码真调;`retained` = 兼容保留(chart 有、适配器零调用)。 */
+export declare const SANDBOX_RBAC_NEEDS: readonly ["called", "retained"];
+export type SandboxRbacNeed = (typeof SANDBOX_RBAC_NEEDS)[number];
+export interface SandboxRbacRule {
+    readonly scope: SandboxRbacScope;
+    readonly apiGroups: readonly string[];
+    readonly resources: readonly string[];
+    readonly verbs: readonly string[];
+    readonly when: SandboxRbacWhen;
+    readonly need: SandboxRbacNeed;
+    /** 这一行为什么在(渲成产物里规则上方的注释;也是 `deploy/facts/sandbox-rbac.json` 的 `why`);`called` 行写着调用方的 `remote-env-k8s.ts#<方法名>` 坐标。 */
+    readonly why: string;
+}
+/**
+ * 规则表(表序 = 产物里的规则序)。`called` 行的调用坐标 = `remote-env-k8s.ts` 里的方法名(不写行号,免得每改一行适配器就漂);
+ * `test/sandbox-rbac-table.test.ts` 读该文件逐方法核「这一行的动词 ⊆ 那些方法真发的调用」,并核 `retained` 行没有任何调用。
+ */
+export declare const SANDBOX_RBAC_RULES: readonly SandboxRbacRule[];
+/** 一份完整的表(生成器的输入;测试用变异夹具替换它)。 */
+export interface SandboxRbacModel {
+    readonly switches: {
+        readonly [W in SandboxRbacSwitchWord]: SandboxRbacSwitch;
+    };
+    readonly rules: readonly SandboxRbacRule[];
+}
+export declare const SANDBOX_RBAC_MODEL: SandboxRbacModel;
+/**
+ * `deploy/facts/sandbox-rbac.json` 的 Schema(随包方言,见 `src/deploy-facts.ts`)。闭集词表直接取本文件的常量:加一个 `when` / `need` / 范围 / 动词词
+ * = 闭集加词 = 破坏性形变(读方对闭集做穷尽判别),要登记、要抬版。一条规则的身份 = (范围, apiGroups, resources, need)—— 同一资源按 `need` 拆成两行。
+ */
+export declare const SANDBOX_RBAC_FACTS_SCHEMA: FactsRootSchema;
+//# sourceMappingURL=sandbox-rbac-rules.d.ts.map

package/dist/sandbox-rbac-rules.js

@@ -0,0 +1,80 @@
+import { SANDBOX_SECRET_SEAT_VERBS } from "./plugins/k8s-exec-protocol.js";
+import { FACTS_SCHEMA_DIALECT, factsSchemaVersion } from "./deploy-facts.js";
+export const SANDBOX_RBAC_SCHEMA_VERSION = factsSchemaVersion("sandbox-rbac");
+export const SANDBOX_RBAC_SCOPES = ["Role", "ClusterRole"];
+export const SANDBOX_RBAC_VERBS = ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"];
+export const SANDBOX_RBAC_ALWAYS = "always";
+export const SANDBOX_RBAC_SWITCH_WORDS = ["WORKSPACE_CACHE=volume", "K8S_SANDBOX_ENV"];
+export const SANDBOX_RBAC_WHEN_WORDS = [SANDBOX_RBAC_ALWAYS, ...SANDBOX_RBAC_SWITCH_WORDS];
+export const SANDBOX_RBAC_SWITCHES = {
+    "WORKSPACE_CACHE=volume": { kind: "bool", env: "WORKSPACE_CACHE", envValue: "volume", chartValue: "sandbox.workspaceCacheVolume", meaning: "按工作区空间的构建缓存卷开着" },
+    K8S_SANDBOX_ENV: { kind: "names", env: "K8S_SANDBOX_ENV", chartValue: "sandbox.sandboxEnv", meaning: "沙箱带外 env 名单非空(名单点到的值留在服务进程环境里)" },
+};
+export const SANDBOX_RBAC_NEEDS = ["called", "retained"];
+export const SANDBOX_RBAC_RULES = [
+    { scope: "Role", apiGroups: [""], resources: ["pods"], verbs: ["get", "list", "create", "delete"], when: "always", need: "called", why: "沙箱 pod 的生命周期:remote-env-k8s.ts#createPod 建(POST pods)并读就绪(GET pods/<名>)· remote-env-k8s.ts#listSandboxPods 按标签列(GET pods?labelSelector)· remote-env-k8s.ts#reconnect 读存活(GET pods/<名>)· remote-env-k8s.ts#deletePod 删(DELETE pods/<名>)" },
+    { scope: "Role", apiGroups: [""], resources: ["pods"], verbs: ["watch"], when: "always", need: "retained", why: "兼容保留:chart 一直授着,适配器没有 watch 调用" },
+    { scope: "Role", apiGroups: [""], resources: ["pods/exec"], verbs: ["create", "get"], when: "always", need: "called", why: "在沙箱 pod 里执行命令:remote-env-k8s.ts#execUrl 拼 pods/<名>/exec 的连接地址" },
+    { scope: "Role", apiGroups: [""], resources: ["pods/attach"], verbs: ["create", "get"], when: "always", need: "retained", why: "兼容保留:chart 一直授着,适配器没有 attach 调用" },
+    { scope: "Role", apiGroups: [""], resources: ["pods/log"], verbs: ["get"], when: "always", need: "retained", why: "兼容保留:chart 一直授着,适配器没有读日志的调用" },
+    {
+        scope: "Role",
+        apiGroups: [""],
+        resources: ["persistentvolumeclaims"],
+        verbs: ["get", "create", "deletecollection"],
+        when: "WORKSPACE_CACHE=volume",
+        need: "called",
+        why: "按工作区空间的构建缓存卷:remote-env-k8s.ts#ensureCacheClaim 按名读、没有就建(GET / POST persistentvolumeclaims)· remote-env-k8s.ts#cacheClaimBound 按名读 · remote-env-k8s.ts#reclaimSpaceCache 空间结束按标签回收(DELETE persistentvolumeclaims?labelSelector = deletecollection);缺它 ⇒ 缓存卷拿不到,适配器按 fail-open 照起、不挂卷(计数 server.workspace-cache.unavailable)",
+    },
+    { scope: "Role", apiGroups: [""], resources: ["persistentvolumeclaims"], verbs: ["delete"], when: "WORKSPACE_CACHE=volume", need: "retained", why: "兼容保留:chart 一直授着,适配器回收只发按标签的 deletecollection,没有按名 delete 的调用" },
+    {
+        scope: "Role",
+        apiGroups: [""],
+        resources: ["secrets"],
+        verbs: SANDBOX_SECRET_SEAT_VERBS.env,
+        when: "K8S_SANDBOX_ENV",
+        need: "called",
+        why: "沙箱秘密座:动词取自 SANDBOX_SECRET_SEAT_VERBS.env —— 起服门(boot/execution-env.ts ensureSandboxSecretSeat)问的与 remote-env-k8s.ts#createOwnedSecret 为 env Secret 真发的(POST secrets)是同一行;起服门只在有效转发集合非空(名单点到的键在服务进程环境里有值)时问:答 denied ⇒ server 起服拒,问不到 ⇒ 告警 sandbox_secret_seat_unverified 照起;名单非空而有效集合为空时本行是保守多授(安装器看不到服务进程的运行时环境,引擎此时既不问也不调)",
+    },
+    { scope: "Role", apiGroups: ["networking.k8s.io"], resources: ["networkpolicies"], verbs: ["list"], when: "always", need: "called", why: "起服的出网自检读本 ns 的 NetworkPolicy 集合:remote-env-k8s.ts#egressPolicyGaps(GET .../networkpolicies)" },
+    { scope: "Role", apiGroups: ["networking.k8s.io"], resources: ["networkpolicies"], verbs: ["get"], when: "always", need: "retained", why: "兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get" },
+    { scope: "ClusterRole", apiGroups: [""], resources: ["nodes"], verbs: ["list"], when: "always", need: "called", why: "出网自检读节点表(节点是集群级对象 ⇒ ClusterRole + Binding 给同一只服务账号):remote-env-k8s.ts#egressPolicyGaps(GET /api/v1/nodes)" },
+    { scope: "ClusterRole", apiGroups: [""], resources: ["nodes"], verbs: ["get"], when: "always", need: "retained", why: "兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get" },
+];
+export const SANDBOX_RBAC_MODEL = { switches: SANDBOX_RBAC_SWITCHES, rules: SANDBOX_RBAC_RULES };
+const nonEmptyNames = (description) => ({ type: "array", minItems: 1, uniqueItems: true, items: { type: "string" }, description });
+export const SANDBOX_RBAC_FACTS_SCHEMA = {
+    $schema: FACTS_SCHEMA_DIALECT,
+    description: "k8s 沙箱车道(REMOTE_EXEC=k8s)的服务账号在沙箱命名空间 / 集群里需要的 RBAC 规则;每条规则何时授、引擎适配器真调还是兼容保留。",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "rules"],
+    properties: {
+        schemaVersion: { type: "integer", const: SANDBOX_RBAC_SCHEMA_VERSION, description: "本份数据的形版本;读方不认识的版本整份拒读。" },
+        rules: {
+            type: "array",
+            minItems: 1,
+            "x-uniqueKey": ["scope", "apiGroups", "resources", "need"],
+            description: "规则行;同一资源的动词按 need 拆成两行,授权时并回一条规则(Kubernetes 对同一资源的多条规则取并集)。",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["scope", "apiGroups", "resources", "verbs", "when", "need", "why"],
+                properties: {
+                    scope: { type: "string", enum: SANDBOX_RBAC_SCOPES, description: "Role = 沙箱命名空间里的 Role;ClusterRole = 集群级对象(节点)要的 ClusterRole,绑给同一只服务账号。" },
+                    apiGroups: nonEmptyNames("API 组;核心组写空串。"),
+                    resources: nonEmptyNames("资源名(子资源写 pods/exec 这种形)。"),
+                    verbs: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", enum: SANDBOX_RBAC_VERBS }, description: "动词。" },
+                    when: {
+                        type: "string",
+                        enum: SANDBOX_RBAC_WHEN_WORDS,
+                        description: "always = 恒授;WORKSPACE_CACHE=volume = 引擎开着按工作区空间的缓存卷时授(引擎用到它的条件同一个);K8S_SANDBOX_ENV = 引擎的沙箱 env 名单非空时授 —— 这是保守的授权条件,引擎真正问 / 调用的条件是名单点到的键在服务进程环境里有值,两者之差写在该行 why 里。",
+                    },
+                    need: { type: "string", enum: SANDBOX_RBAC_NEEDS, description: "called = 引擎适配器源码真发这些调用;retained = 随包 chart 一直授着、适配器源码里零调用(兼容保留)。" },
+                    why: { type: "string", description: "这一行为什么在(called 行写着调用它的适配器方法)。" },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=sandbox-rbac-rules.js.map

package/dist/sealed-key-layout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 钥匙保管目录的布局常量 —— 引擎建目录、写钥匙文件、建停驻行封签子目录时用的**唯一**值(`src/sealed-key.ts` 读它们)。
+ *
+ * 单独成一只零依赖的叶子模块:随包部署事实 `deploy/facts/sealed-key.json`(`src/deploy-facts.ts` 投影、`scripts/gen-deploy-lanes.ts` 生成)
+ * 读的是同一份值,生成器不必为了三个常量把整只保管模块(libsodium / 中心上报)装载进来。
+ */
+/** 保管目录的权限位:每次建店都 `mkdir` + `chmod` 成它(目录预先存在时 `mkdir` 的 mode 不生效,所以另 `chmod` 一次)。 */
+export declare const SEALED_KEY_DIR_MODE = 448;
+/** 钥匙文件 `<publicKeyId>.json` 的权限位(`writeFile` 的 mode 受 umask 掩,所以另 `chmod` 一次)。 */
+export declare const SEALED_KEY_FILE_MODE = 384;
+/**
+ * 停驻行凭据封签那一域的保管子目录名(在模型钥匙保管目录之下:`<保管目录>/checkpoint-ctx-keys/`)。**一个域一对钥匙**:模型钥匙(`ModelEntry.sealedApiKey`,
+ * 浏览器对着 caps 公钥裸封)与停驻行封签各用自己目录里的钥匙对 —— 一边的开箱口在另一边的密文上恒「不持有那把钥匙」,不是靠哪一侧多判一句信封。
+ * 放在模型钥匙目录之下是为了「多副本共享 / 跨重启持久」只有一个目录要管(整个保管目录);模型钥匙店只读这一层的 `*.json`,子目录不进它的视野。
+ */
+export declare const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+//# sourceMappingURL=sealed-key-layout.d.ts.map

package/dist/sealed-key-layout.js

@@ -0,0 +1,4 @@
+export const SEALED_KEY_DIR_MODE = 0o700;
+export const SEALED_KEY_FILE_MODE = 0o600;
+export const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+//# sourceMappingURL=sealed-key-layout.js.map

package/dist/sealed-key.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import _sodium from "libsodium-wrappers";
+import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE, SEALED_KEY_FILE_MODE } from "./sealed-key-layout.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
@@ -61,8 +62,8 @@ export function judgeSealedKeyPublicKey(publicKeyB64) {
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
-    await mkdir(dir, { recursive: true, mode: 0o700 });
-    await chmod(dir, 0o700);
+    await mkdir(dir, { recursive: true, mode: SEALED_KEY_DIR_MODE });
+    await chmod(dir, SEALED_KEY_DIR_MODE);
     const keys = new Map();
     for (const name of (await readdir(dir)).filter((n) => n.endsWith(".json")).sort()) {
         const path = join(dir, name);
@@ -99,8 +100,8 @@ export async function ensureSealedKeyStore(dir, logger) {
             createdAt: new Date().toISOString(),
         };
         const path = join(dir, `${record.publicKeyId}.json`);
-        await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
-        await chmod(path, 0o600);
+        await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: SEALED_KEY_FILE_MODE });
+        await chmod(path, SEALED_KEY_FILE_MODE);
         keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
         logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
     }
@@ -120,7 +121,6 @@ export async function ensureSealedKeyStore(dir, logger) {
         },
     };
 }
-const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
 function mintCheckpointCtxKeyStore(store) {
     return store;
 }

package/dist/security.d.ts

@@ -4,10 +4,10 @@ import type { ServiceConfig } from "./config-types.js";
 import { type DeploymentShapeInput } from "./deployment-shape.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
-import type { ClientSessionRowWrite, ReplaySessionRowWrite, ReplaySessionRowWriteOutcome, SessionRowPatch, SessionRowWriteOutcome } from "./session-row.js";
+import type { ClientSessionRowWrite, ReplaySessionRowWrite, ReplaySessionRowWriteOutcome, SessionRowAnswer, SessionRowPatch, SessionRowWriteOutcome } from "./session-row.js";
 import type { ExecutionPlacementSeat } from "./execution-placement.js";
 import type { SessionUnreadable } from "./session-error-wire.js";
-import type { ForkTarget, ForkToOutcome } from "./plugins/session-fork.js";
+import type { ForkPlacement, ForkTarget, ForkToOutcome } from "./plugins/session-fork.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
  *  output (§0.5). Mirrors {@link RunStore}'s shipped `SessionSummary` shape so the wire response is unchanged. */
 export interface SessionListItem {
@@ -104,7 +104,7 @@ export type SessionOwnerCell = {
     readonly placed: boolean;
 };
 /** 会话行属主门的调用方:验过的主体(`gatedPrincipal`)+ 它是不是 **fleet 调用方**(dev-open 部署上的任何调用方,或出示了这台部署的 service 凭据、
- *  不报主体的调用方)。唯一铸点 `http/principal-gate.ts` 的 `sessionCallerOf`。 */
+ *  不报主体的调用方 —— 除非部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false`)。唯一铸点 `http/principal-gate.ts` 的 `sessionCallerOf`。 */
 export interface SessionCaller {
     readonly principal: Principal | undefined;
     readonly fleet: boolean;
@@ -114,7 +114,8 @@ export interface SessionCaller {
  * 审批豁免面、notify 面的无主臂都经它,不各写一份):
  *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
  *  · 无主的 **placed** 行(委派子代:属主 = 引擎判的委派树属主,三只持久会话店建行那一笔原样记 `placement.owner`,`null` = 根匿名;`delegated-session-owner.ts` 头注)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
- *    或出示了 service 凭据、不报主体的调用方 —— 只配 token 的单用户部署、BFF 的系统调用)。任何具名主体(含经 BFF 代发的)与没有 service 凭据的无身份调用方都不成立:
+ *    或出示了 service 凭据、不报主体的调用方 —— 只配 token 的单用户部署、BFF 的系统调用;部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时后者不是 fleet)。
+ *    任何具名主体(含经 BFF 代发的)与无身份调用方(没有 service 凭据的;声明形上不报主体的 service 凭据)都不成立:
  *    这一行要么属于一棵无身份调用方的树(引擎交的属主是 `null`),要么是属主从没被记下的行 —— 7.144.0 之前写下的存量(7.132.x 及更早建行不记属主;7.133.0–7.143.x 按本服务当年的推断写下,
  *    推断那一刻来源还没有属主的仍无主;SQL 两店由一次性迁移 M23 在它的窗内回填),以及 local 文件店上 7.144.x 及更早建行两笔之间崩溃留下的行(7.145.0 起建行格先、存档后,不再新生)、
  *    同一数据根上 run-local 腿经 core 店写下的 placed 存档(local 没有回填臂)
@@ -175,6 +176,20 @@ export declare function legacyUnownedSessionOk(deployment: DeploymentShapeInput<
  * 单实体读/写点(fork/delete/同步族/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
  */
 export declare function legacyUnownedAmnestyOpen(deployment: DeploymentShapeInput<"principal">, gateOwner: string | null): boolean;
+/** [ref] 存量哨兵窄互认的行属主字面量 —— cli ≤1.0.70 在本地单用户模式自发的 principal 头,存量会话的属主列就是它(引擎不发明这个字面量)。 */
+export declare const LEGACY_SHELL_SENTINEL_OWNER = "anon:shell-live";
+/**
+ * 🔴 **会话属主等价律 —— 「行上记下的属主」与「这一次的调用方 / 住客」是不是同一位,唯一判官**(两只窄互认臂收在这一处,读者不各写一份):
+ *  · 字面相等(含两边都无主 —— 单用户形无身份的调用方与无主的行);
+ *  · [ref] 窄互认第二臂的身份半支:单机形 ∧ 行无主 ∧ 对方恰为 `default`({@link legacyUnownedAmnestyOpen});
+ *  · [ref] 存量哨兵臂:非 `requirePrincipal` ∧ 行恰为 {@link LEGACY_SHELL_SENTINEL_OWNER} ∧ 对方没有主体。
+ * **有方向、不传递**:`rowOwner` 是行上记下的(或删前记下的)属主,`principal` 是这一次的调用方 / 住客(没有主体 = `null`);
+ * 两条臂各自只认它那一对,不由它们推出 `default` ≡ 哨兵、也不反过来认「`default` 的行 ≡ 无主体的调用方」。
+ * 读者:`createAuthorizer` 的会话属主门(有主的行)、`http/principal-gate.ts` 的 `runOwnerReadable`(有主的行)、`deleted-session-ids.ts` 的墓碑读点(删前属主 vs 本次住客)。
+ * 不在本判官里的两件(它们问的不是「是不是同一位」):无主的委派子代 placed 行只对 fleet 调用方开放(读面律 {@link ownerlessRowOpen});
+ * 删除 / fork / 同步族的放行另有 fleet 臂与 placed 判({@link legacyUnownedSessionOk} = 本判官的第二臂 ∧ {@link ownerlessRowOpen})。
+ */
+export declare function sameSessionOwner(deployment: DeploymentShapeInput<"principal">, rowOwner: string | null, principal: string | null): boolean;
 /**
  * 本仓会话店的面 = core `SessionStore` + 本仓的行面(登记 / 列表 / 换装 / 同步……)。
  * 🔴 **按 id 读一行只有一只**:core 的 `headOf(id)`(`{ owner, incarnation, leafId }`,同一行一次读;core 7.55.0 [ref] S2)。
@@ -203,6 +218,19 @@ export type OwnerAwareSessionStore = SessionStore & {
         limit: number;
         q?: string;
     }) => Promise<SessionListItem[]>;
+    /** The SAME list face as {@link listSessions} (same SELECT, same mapper, same predicate and keyset) with each row's occupant — the row's owner and
+     *  incarnation as read in that one read. The incarnation never enters the row (it is not a wire fact: `session-incarnation.ts`); this pair is for the
+     *  in-process reader that must address a row by occupant — the peer directory's `PeerSessionRecord.occupant`. `listSessions` is this face's rows. */
+    listSessionRows?: (opts: {
+        owner?: string;
+        includeUnowned?: boolean;
+        cursor?: {
+            lastActivityAt: string;
+            sessionId: string;
+        };
+        limit: number;
+        q?: string;
+    }) => Promise<Array<SessionRowAnswer<SessionListItem>>>;
     /** ONE session's list row — the SAME projection {@link listSessions} emits for it (same columns, same mapper). `undefined` = not a
      *  row of the list face (no such session, or a placed / delegation-transcript session, which never lists). Reader: the 2c
      *  manifest (`title` / `pinned`). */
@@ -217,8 +245,12 @@ export type OwnerAwareSessionStore = SessionStore & {
     writeSessionRowCells?: SessionRowCellsWriter;
     /** E17 — fork a session's whole history to a NEW session; null if the source is unknown. The fork row records `owner` when it is a
      *  string, else (`null`) the SOURCE row's owner — a copy of an owned history is never anonymous (core `SessionStore.fork`, 7.55.0 S2).
-     *  On the three stores it is the projection `forkTo(…, { id: uuidv7() })` of {@link forkTo} (one private body). */
-    fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
+     *  On the three stores it is the projection `forkTo(…, { id: uuidv7(), placement? })` of {@link forkTo} (one private body). `opts.placement`
+     *  (core `SessionStore.fork`; engine-internal: a background fork child's transcript) forks INTO the delegation partition — the creating write
+     *  lays the tuple down as a placed acquire does; a store that declares no partition ignores it. */
+    fork?: (sourceId: string, owner: string | null, opts?: {
+        placement?: ForkPlacement;
+    }) => Promise<string | null>;
     /** fork 续写的店契约(三店同一只私有体;规则与结果闭集在 `plugins/session-fork.ts`):把源会话整份历史拷进调用方给的目标 id;`target.key` 存进新行那一格 fork 键。
      *  `null` = 源不在;`created` / `replayed`(同属主同键)/ `occupied{sameOwner}`(撞上别的行)。目标行原子新建(SQL 主键排他、meta 先;local 两把写锁 + 格先)。 */
     forkTo?: (sourceId: string, owner: string | null, target: ForkTarget) => Promise<ForkToOutcome | null>;

package/dist/security.js

@@ -39,6 +39,14 @@ export function legacyUnownedSessionOk(deployment, caller, cell) {
 export function legacyUnownedAmnestyOpen(deployment, gateOwner) {
     return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(deployment) && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
 }
+export const LEGACY_SHELL_SENTINEL_OWNER = "anon:shell-live";
+export function sameSessionOwner(deployment, rowOwner, principal) {
+    if (rowOwner === principal)
+        return true;
+    if (rowOwner === null)
+        return legacyUnownedAmnestyOpen(deployment, principal);
+    return !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deployment) && rowOwner === LEGACY_SHELL_SENTINEL_OWNER && principal === null;
+}
 const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 export function isUuidV7(s) {
     return UUIDV7_RE.test(s);
@@ -111,8 +119,7 @@ export function createAuthorizer(config, sessionStore) {
                     await register(requested, principal);
                     owner = await readOwner(requested);
                 }
-                const legacyShellOwner = !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
-                if (!legacyShellOwner && owner != null && owner !== principal) {
+                if (owner != null && !sameSessionOwner(config, owner, principal ?? null)) {
                     throw principal
                         ? new HttpError(403, "session does not belong to this principal")
                         : new HttpError(401, `session is principal-owned; missing principal header '${config.principalHeader}'`);

package/dist/session-notify-door.d.ts

@@ -24,9 +24,11 @@
  *
  * ## 调用方(两只,都经 {@link SessionNotifyDoor.deliver},不各写一份臂)
  *  · `POST /v1/sessions/:id/notify`(`http/routes/notify-wake.ts`):入站鉴权、验型、属主门在路由;属主 = 会话行的属主。
- *  · **Runner 之外的后台子代完成**({@link createBackgroundCompletionRelay}):停驻赎回腿的复活、操作员 `handle.resume` —— 这些续跑不是哪一次 run 内的调用,
- *    没有调用车道(`ToolExecuteContext.onTaskNotification`),引擎把完成交给委派工具挂载期的 `background.notify`;那只 sink 在 `capabilities/scenarios.ts` 接一次,
- *    交到委派树根会话的这只门。Runner 之内的调用照旧走调用车道(引擎 `resolveCompletionSink` = 调用 ?? 挂载),这只门不经手。
+ *  · **Runner 之外的后台子代完成**({@link createBackgroundCompletionRelay}):操作员 `handle.resume`,与**停驻落在别的进程**(另一副本 / 重启之前)的停驻赎回腿复活 ——
+ *    这些续跑不是哪一次 run 内的调用,本进程也没有它们欠账的车道,引擎把完成交给委派工具挂载期的 `background.notify`;那只 sink 在 `capabilities/scenarios.ts`
+ *    接一次,交到委派树根会话的这只门(停驻赎回那一形引擎另说一次 `delegation.resume_lane_missing`,运维受众)。本进程持有停驻的赎回(core 7.63.0 起)是停驻
+ *    周期的延续:完成回到周期欠账的那条车道(父 run 的车道;父 run 已收场 ⇒ 根会话的活 run 或下一轮),这只门不经手。Runner 之内的调用照旧走调用车道
+ *    (引擎 `resolveCompletionSink` = 调用 ?? 停驻车道 ?? 挂载)。
  */
 import type { ExternalNotificationInput, SessionHead, SubagentToolOptions, TaskStream } from "@sema-agent/core";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";