@sema-agent/server 7.145.0 → 7.147.0

package/dist/runs.js

@@ -11,7 +11,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { withModelReachScope } from "./model-reach-scope.js";
 import { createInstructionSelectionLeg } from "./instruction-selection.js";
 import { redactSecrets } from "./trace/redact.js";
-import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
+import { taskNotificationEventData, appendModelUsageDelta, attachModelUsage, createPromptManifestSeat } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "./trace/engine-notice-wire.js";
 import { recordTurnActivity } from "./turn-activity.js";
@@ -78,6 +78,8 @@ const PREPARE_REFUSAL_HTTP_STATUS = {
     "rewind.child_scope_unsupported": 422,
     "rewind.capture_disabled": 422,
     "rewind.store_unconfigured": 409,
+    "rewind.session_busy": 409,
+    "rewind.files_env_unsupported": 409,
     "memory.capture_optout_unpersisted": 503,
     "config.memory_capture_spelling": 400,
     "config.invalid_checkpoint_store": 400,
@@ -174,17 +176,25 @@ export async function releaseKeyIfZeroWorkRefusal(runStore, taskId, result) {
         await runStore.releaseIdemKey(taskId);
 }
 export function createPromptCommitReader() {
-    let attachmentWindow;
+    const commits = [];
+    let frames = 0;
+    let appliedInputs = 0;
+    let settled = false;
     return (ev) => {
+        if (settled)
+            return undefined;
         if (ev.type === "human_input") {
             const h = ev;
             if (h.delivery !== "applied")
                 return undefined;
-            attachmentWindow = Array.isArray(h.attachments) && h.attachments.length > 0 ? { frames: h.attachments.length, commits: [] } : undefined;
+            appliedInputs += 1;
+            if (appliedInputs === 1)
+                frames = Array.isArray(h.attachments) ? h.attachments.length : 0;
             return undefined;
         }
         if (ev.type === "turn_end") {
-            attachmentWindow = undefined;
+            if (commits.length > 0)
+                settled = true;
             return undefined;
         }
         if (ev.type !== "message_committed")
@@ -192,17 +202,17 @@ export function createPromptCommitReader() {
         const c = ev;
         const entryId = typeof c.entryId === "string" && c.entryId.length > 0 ? c.entryId : undefined;
         if (c.role === "user") {
-            if (attachmentWindow !== undefined) {
-                attachmentWindow.commits.push(entryId);
-                return undefined;
-            }
-            return entryId;
+            commits.push(entryId);
+            return frames === 0 && commits.length === 1 ? entryId : undefined;
         }
-        const closed = attachmentWindow;
-        attachmentWindow = undefined;
-        if (closed === undefined || closed.commits.length < closed.frames + 1)
+        if (commits.length === 0)
+            return undefined;
+        settled = true;
+        if (frames === 0)
+            return commits.length > 1 ? commits[commits.length - 1] : undefined;
+        if (appliedInputs > 1 || commits.length < frames + 1)
             return undefined;
-        return closed.commits[closed.commits.length - 1 - closed.frames];
+        return commits[commits.length - 1 - frames];
     };
 }
 export async function settleResumeAnchor(write, where) {
@@ -285,7 +295,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;
@@ -385,8 +395,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const flushModelUsage = () => appendModelUsageDelta(append, modelUsage, taskId);
     const withModelUsage = (result) => attachModelUsage(result, { append, getEvents: (id, after) => runStore.getEvents(id, after), modelUsage, taskId });
     modelUsage?.register(taskId);
-    const manifestLease = promptManifests?.register(taskId) ?? 0;
-    const flushPromptManifest = () => appendPromptManifest(append, promptManifests, taskId);
+    const manifestSeat = createPromptManifestSeat(promptManifests, taskId);
+    const flushPromptManifest = () => manifestSeat.drain(append);
     const elicitEmit = (frame) => {
         const { type, ...rest } = frame;
         return append(type, rest);
@@ -652,7 +662,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             for (const evict of subagentHandleEvictions)
                 evict();
             modelUsage?.clear(taskId);
-            promptManifests?.clear(taskId, manifestLease);
+            manifestSeat.release();
             clearInterval(heartbeat);
         }
     }

package/dist/runtime-caps-resolver.d.ts

@@ -66,6 +66,11 @@
  * 人的授予、搭上一个人的在飞请求、带上一个人的 etag 去换 304。在飞期间换了人,答复由传输层丢弃
  * (`http-client.ts` `requestPrincipalView`),按这一次取数失败走下面的 fail-closed 臂(降级项落在发起那一箱)。
  *
+ * 🔐 场景面同一条故障律、另一种拒法:同一次硬失败把场景那一面记成 `"unavailable"`(读数第三态,见 `capabilities/scenarios.ts`
+ * `ScenarioRulingRead`),场景门据它拒这条 run(503 `state.scenario_assignment_unavailable`)—— 场景面没有「拒掉放大位、照跑」的中间形:
+ * 受限主体的指派与白名单此刻不可知,落部署缺省或照放点名都可能比他的指派更宽。治理两键形不对同记 `"unavailable"`(经 `onError` 一行)。
+ * 缺席(无 principal / 中心不发两键)仍是 `undefined`;没接中心的部署根本没有本客户端。
+ *
  * The resolver maps center's `EntitlementRuntimeCaps` → the SUBSET core enforces ({@link RuntimeCaps}): center
  * also carries `allowUltracode` (a shell/UX reasoning-tier cap the engine has no primitive for), which we DROP —
  * this seam feeds the ENGINE, and `allowUltracode` is enforced at the service settings-resolution layer, not here.
@@ -77,7 +82,7 @@ import type { RuntimeCaps } from "@sema-agent/core";
 import type { EntitlementRuntimeCaps } from "@sema-agent/settings-schema";
 import { fetchPrincipalCaps, type ExecutionRuling } from "./web-admin-client/facade.js";
 import type { CenterEndpoint } from "./web-admin-client/center-request.js";
-import type { ScenarioRuling } from "./capabilities/scenarios.js";
+import type { ScenarioRulingRead } from "./capabilities/scenarios.js";
 import type { ServiceConfig } from "./config-types.js";
 import { type Logger } from "./observability/logger.js";
 /** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
@@ -181,17 +186,18 @@ export interface PrincipalEntitlementsClient {
      * 都重抓,denyTtl 的界对提交腿失效)。让它升格的是一次真提交自己吃到的硬失败,不是那次读。
      */
     peekRuntimeCaps: (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
-    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest —
-     *  FAIL-OPEN on error / older center without scenario keys / no principal (undefined = no governance, legacy passthrough).
-     *  Scenario switching is not a privilege-amplifying face; a center blip must not pin users to `default`. */
-    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest — a three-state read
+     *  ({@link ScenarioRulingRead}): the ruling; `undefined` = absent (no principal ⇒ no center call; older center without
+     *  the scenario keys) = no governance; `"unavailable"` = the center could not answer (hard fetch failure — same error entry
+     *  as the caps face's fail-closed deny — or malformed ruling keys) ⇒ the gate refuses the run. */
+    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /**
      * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCaps} 的界):同一只缓存 / 同一条抓取 /
-     * 同一份 fail-open 判决(`undefined` = 无治理),唯一的差别是 center 硬失败时本腿铸的 fail-closed 降级项**只对读面自己算数**,提交腿不认、照常重抓。
+     * 同一份三态读数(故障 ⇒ `"unavailable"`,读面与提交腿同拒),唯一的差别是 center 硬失败时本腿铸的降级项**只对读面自己算数**,提交腿不认、照常重抓。
      * 读面(`GET /v1/capabilities/mcp?scenario=` 的场景门)问中心裁定时必须走这一只 —— 经 `scenarioRuling` 问,center 抖动的那一拍会替这个主体的**真提交**
      * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCaps` 的病灶同一类)。
      */
-    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /** (stage7 P5) The resolved per-principal execution-lane ruling for resolveSpec's
      *  gateExecutionLane. FAIL-OPEN + audit on error (this phase is "honest-but-bypassable";
      *  tightening to fail-closed is a future, separate decision) / older center without the execution key / no principal. */
@@ -215,7 +221,8 @@ export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, o
  * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight
  * (zero extra center RTT — center attaches the ruling to the caps body). Wire ONLY when a center is
  * configured (and not in dry-run) — absent ⇒ core sees `undefined` ⇒ NO per-principal restriction, and the
- * scenario gate sees `undefined` ⇒ legacy body-or-default chain.
+ * scenario gate sees `undefined` (absent) ⇒ request-name-or-deployment-default chain. Present ⇒ a center that cannot answer
+ * reads `"unavailable"` on the scenario face (the gate refuses), never `undefined`.
  */
 export declare function createPrincipalEntitlementsClient(opts: EntitlementsResolverOpts): PrincipalEntitlementsClient;
 /** Back-compat face for core's seam-only consumers: the caps half of {@link createPrincipalEntitlementsClient}. */

package/dist/runtime-caps-resolver.js

@@ -91,6 +91,13 @@ export function createPrincipalEntitlementsClient(opts) {
     const fetchCaps = opts.fetchCaps ?? fetchPrincipalCaps;
     const now = opts.now ?? (() => Date.now());
     const onError = opts.onError ?? ((err, principal) => defaultLogger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }));
+    const audit = (err, principal) => {
+        try {
+            onError(err, principal);
+        }
+        catch {
+        }
+    };
     const binNow = createIdentityBins(opts.center.credential, (credential) => ({
         center: { baseUrl: opts.center.baseUrl, credential },
         cache: new Map(),
@@ -136,14 +143,14 @@ export function createPrincipalEntitlementsClient(opts) {
                     return entry;
                 }
                 if (r.executionDrift) {
-                    try {
-                        onError(new Error(`execution ruling wire drift: ${r.executionDrift}`), principal);
-                    }
-                    catch { }
+                    audit(new Error(`execution ruling wire drift: ${r.executionDrift}`), principal);
+                }
+                if (r.scenarioDrift) {
+                    audit(new Error(`scenario ruling wire drift: ${r.scenarioDrift}`), principal);
                 }
                 const entry = {
                     caps: toCoreRuntimeCaps(r.runtimeCaps),
-                    ...(r.scenario ? { scenario: r.scenario } : {}),
+                    ...(r.scenarioDrift ? { scenario: "unavailable" } : r.scenario ? { scenario: r.scenario } : {}),
                     ...(r.execution ? { execution: r.execution } : {}),
                     ...(r.etag ? { etag: r.etag } : {}),
                     expiresAt: now() + ttlMs,
@@ -159,14 +166,11 @@ export function createPrincipalEntitlementsClient(opts) {
                 catch {
                     e = new Error("center fetch failed with an unstringifiable rejection reason");
                 }
-                const entry = { caps: { allowWorkflows: false, allowFork: false, autoMode: false, autoModeDenySource: "org", bypassPermissions: false }, expiresAt: now() + denyTtlMs };
+                const entry = { caps: { allowWorkflows: false, allowFork: false, autoMode: false, autoModeDenySource: "org", bypassPermissions: false }, scenario: "unavailable", expiresAt: now() + denyTtlMs };
                 if (!recordDeny)
                     readMintedDeny.add(entry);
                 putCache(bin.cache, principal, entry);
-                try {
-                    onError(e, principal);
-                }
-                catch { }
+                audit(e, principal);
                 return entry;
             }
             finally {

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,16 @@
+/**
+ * 钥匙保管目录的布局常量 —— 引擎建目录、建停驻行封签子目录时用的**唯一**值(`src/sealed-key.ts` 读它们)。
+ * 钥匙文件的权限位不在这里:它就是本服务文件的那一个值 `plugins/owner-only-file-mode.ts` 的 `OWNER_ONLY_FILE_MODE`(部署事实同读它)。
+ *
+ * 单独成一只零依赖的叶子模块:随包部署事实 `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;
+/**
+ * 停驻行凭据封签那一域的保管子目录名(在模型钥匙保管目录之下:`<保管目录>/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,3 @@
+export const SEALED_KEY_DIR_MODE = 0o700;
+export const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+//# sourceMappingURL=sealed-key-layout.js.map

package/dist/sealed-key.js

@@ -1,7 +1,10 @@
 import { createHash } from "node:crypto";
-import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { ensureDir } from "@sema-agent/core";
 import _sodium from "libsodium-wrappers";
+import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE } from "./sealed-key-layout.js";
+import { OWNER_ONLY_FILE_MODE } from "./plugins/owner-only-file-mode.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
@@ -61,8 +64,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);
+    ensureDir(dir);
+    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 +102,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: OWNER_ONLY_FILE_MODE });
+        await chmod(path, OWNER_ONLY_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 +123,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 {
@@ -25,7 +25,7 @@ export interface SessionListItem {
      *  ⇒ 在跑 latest 键诚实缺席)。
      *  读法一致:缺席 = 「此行无已知 engine runId」,禁读成其它含义。⚠️ 与 `lastRunId`(= latest run 的 **task_id**)
      *  是两条身份轴,命名对齐 core `SessionStoreSummary.lastTaskRunId`。wire:additive 键零投影透传
-     *  (sessions-list.ts);sema-sdk spec `SessionSummary` 闭集候 SDK 半场开键([ref]/.82 班车)。 */
+     *  (sessions-list.ts);sema-sdk spec `SessionSummary` 已声明此键(对账门 `test/sdk-live-parity.test.ts`)。 */
     lastTaskRunId?: string;
     /** The session's title — the user's (`PATCH /v1/sessions/:id`) or, until the user sets one, the auto-titler's
      *  (null = untitled / lister face has no session_meta). One column, two writers, one order: `session-row.ts`. */
@@ -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,10 +176,25 @@ 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)。
- * 属主 = `headOf(id)?.owner`、住客 = 头的 `incarnation`(比较用 core `compareOccupants`,拿令牌去写用 `sessionFaceOfHead`)、叶子 = 头的 `leafId`
+ * 属主 = `headOf(id)?.owner`、住客 = 头的 `incarnation`(两头比较用 core `compareOccupants`:没有行 ⇒ `unknown`,两侧都有令牌且相等或都无令牌 ⇒ `same`,
+ * 一侧有一侧无 ⇒ `different`;拿令牌去写用 `sessionFaceOfHead`,它对无令牌的头响亮拒)、叶子 = 头的 `leafId`
  * —— 此前本面另有五只按 id 读(`ownerOf` / `incarnationOf` / `sessionFaceOf` / `getHead` / `getLeafId`),全部退役;规则在 `src/session-incarnation.ts` 头注,
  * 「店有没有这只读」只判 `headReadOf` 一处。
  */
@@ -203,6 +219,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 +246,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>;
@@ -256,7 +289,8 @@ export type OwnerAwareSessionStore = SessionStore & {
     importEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     /** 2c session-sync (§7/§8) — IDEMPOTENT replace: atomically purge any existing conversation log for `sessionId`
      *  then import `entries` verbatim under `owner`. Unlike importEntries (plain INSERT, fresh-only) this is safe to
-     *  re-run / apply over an existing session (fast-forward, retry). owner-guarded delete (defense-in-depth). */
+     *  re-run / apply over an existing session (fast-forward, retry). Owner-guarded (defense-in-depth): the importer's own row is
+     *  rewritten in place — its incarnation and the deployment cells kept on it (title, pin, instruction baseline, workspace, placement) stay. */
     replaceEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import into `realSessionId` under a shadow id
      *  `${realSessionId}#stg-${token}` (the route mints the uuidv7 `token`). Returns a {@link StagingHandle} the NDJSON