@sema-agent/server 7.144.0 → 7.146.0

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;
@@ -486,7 +486,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 fleetPublisher?.onEvent(ev);
                 await userInputLedger?.observeLegEvent(stream, ev);
-                acceptance?.observe(ev);
+                await acceptance?.observe(ev);
                 await workspaceRecorder?.observe(ev);
                 await flushPromptManifest();
                 switch (ev.type) {

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;
@@ -113,9 +113,13 @@ export interface SessionCaller {
  * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**([ref] 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除 / 同步族的存量互认臂 {@link legacyUnownedSessionOk}、
  * 审批豁免面、notify 面的无主臂都经它,不各写一份):
  *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
- *  · 无主的 **placed** 行(委派子代:属主 = 委派树根的属主,`delegated-session-owner.ts`)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
- *    或出示了 service 凭据、不报主体的调用方 —— 只配 token 的单用户部署、BFF 的系统调用)。任何具名主体(含经 BFF 代发的)与没有 service 凭据的无身份调用方都不成立:
- *    这一行要么属于一棵无身份调用方的树,要么属主还没定下(升级前写下、回填还没判出 / 判断时来源还没有属主)—— 后者把它当公共行,就是把别人那棵树的子代转录交给拿到 id 的人。
+ *  · 无主的 **placed** 行(委派子代:属主 = 引擎判的委派树属主,三只持久会话店建行那一笔原样记 `placement.owner`,`null` = 根匿名;`delegated-session-owner.ts` 头注)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
+ *    或出示了 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 没有回填臂)
+ *    —— 后者把它当公共行,就是把别人那棵树的子代转录交给拿到 id 的人。
  *  · 有主的行 ⇒ 不在本臂。
  */
 export declare function ownerlessRowOpen(cell: SessionOwnerCell, caller: SessionCaller): boolean;
@@ -172,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)。
@@ -184,7 +202,7 @@ export type OwnerAwareSessionStore = SessionStore & {
     register?: (sessionId: string, owner: string | null) => Promise<void>;
     /** [ref] placed 分区的元组读口(店的既有读口,一行 PK 读;`undefined` = 普通会话或无此行)。店不交它 = 不实现 placement = 没有 placed 行(无 repo 的内存店)。两个读者:
      *  ① 会话面的属主门只在属主为 NULL 时读它一次(无主的 placed 行不是公共行,`http/principal-gate.ts` 的 `sessionOwnerCellOf`);
-     *  ② 会话视图读它投影体顶层 `agent` 键(`audit.ts` 的 `sessionAgentOf`,只在视图读上付):店没有这一面 ⇒ 键缺席,读面不凭别处另铸子代身份。 */
+     *  ② `agent` 的唯一读口 `session-agent.ts` 的 `readSessionAgent`(会话视图体顶层、运维审批队列的停驻行同读):店没有这一面 ⇒ 键缺席,读面不凭别处另铸子代身份。 */
     placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
     /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column).
      *  `includeUnowned` = [ref] 窄互认第二臂的**第三条件**(`owner IS NULL`)的 SQL 承载位:置真时
@@ -200,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`). */
@@ -214,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>;
@@ -260,6 +295,10 @@ export type OwnerAwareSessionStore = SessionStore & {
      *  Phase-B route streams batches into (`appendBatch`) then commits (`commit`, the atomic swap) / aborts. The shadow
      *  rows have NO session_meta → invisible to wake until commit writes meta LAST = the sole commit point. */
     beginImportStaging?: (realSessionId: string, token: string) => StagingHandle;
+    /** 带戳存档的早拒口(只有 local 店有这一形:更早的版本写下的属主戳留在引擎存档头上,一次性迁移改写不了的;SQL 孪生没有 ⇒ 不交这一口,调用方按「没有带戳存档」处置)。
+     *  只读、零写、不持锁;带戳 ⇒ 抛 `StampedSessionArchiveError`(`session-error-wire.ts` 映射 409 `conflict.session_archive_stamped`),没有存档 / 匿名存档 ⇒ 放行。
+     *  这是拒绝判对「这份存档带不带戳」的**唯一**读口(fork 的源与改日志的提交也问同一只);读者:会话同步导入第一阶段对按 id 分类出的 fork / stale(没带同意)的早拒。 */
+    assertArchiveAnonymous?: (sessionId: string) => Promise<void>;
     /** 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under a `${realSessionId}#stg-${token}` id
      *  (NO session_meta probe — `exportEntries` returns null for an unregistered id), oldest-first. The import gate is now
      *  the per-line `StreamingImportValidator` (core 1.143.0) driven during the stream, so this is no longer the

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-agent.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 🔴 **一只会话在委派树里的位置 —— 一个来源、一只读口、一种 wire 写法**(`agent: { id?, parentSessionId?, rootSessionId? }`)。
+ *
+ * 来源只有一个:会话行上**存下来的委派元组**(core `SessionPlacementRecord`)—— 引擎在**后台**委派子代(带耐久 agent 行、店声明了委派分区)建会话那一笔交给店、
+ * 店原样记下,首写不可变。三只持久会话店都存:SQL 两孪生在 `session_meta` 的 `placement_*` 列(`plugins/session-placement.ts` 的 `placementFromRow`),
+ * local 后端(7.141.0 起)在会话存档行头(core 文件 repo)。读口是店的 `placementOf`(一行 PK 探针;店不交它 = 不存元组)。
+ *
+ * 读者(同一只读口 {@link readSessionAgent}、同一只投影 {@link sessionAgentOf},逐值同答):
+ *  · 会话视图 `GET /v1/sessions/:id` 体顶层的 `agent`(视图读才付探针;探针抛 ⇒ 视图读响亮失败,`boot/session-faces.ts`);
+ *  · 运维审批队列 `GET /v1/approvals` 的停驻行(`pending[]` 的 `checkpoint` 族)与 `/v1/approvals/stream` 的 `pending` 帧:行的身份就是它那只会话
+ *    (决断口 `/v1/approvals/:sessionId/decide`),行上的 `agent` = 同一只会话在视图上的 `agent`;一行读不出 ⇒ 只这一行缺键、F 类兜底计数
+ *    (`http/routes/approvals-assistant.ts`)。
+ * 不另立第二只读法:fleet 行 / 后台 agent 行上的同名事实是引擎别的记录,读面不拿它们回填或改写这里的答案。
+ *
+ * 投影律(不另铸):`id` = 元组的 `handle`(耐久 agent 行的 `a…` 键,与 fleet 行的 `id`、`GET /v1/agents/roster` 的 `handle` 同一个串);`parentSessionId` /
+ * `rootSessionId` = 元组的同名格(派它的会话 / 委派树的根会话);元组缺哪一格这里就缺哪一格;元组的 `scope`(租户键)/ `placedAt` / `kind` 不上 wire。
+ * 键在场 = 这是一只委派子代的会话(元组只存了 `kind` 时是 `{}`);键缺席 = 不是 placed 行(宿主会话、同步委派的子代、`subagent_type: "fork"` 的后台子代 ——
+ * 它的会话是父会话的一只普通分叉;`DB_BACKEND=local` 到 7.140.x 停驻时拷进宿主店的子代转录,那一份是普通会话行)、这台部署的店不存元组(无 repo 的内存店
+ * 〔`DB_BACKEND=memory`〕、嵌入方自建且不声明委派分区的店),或那一读没读成 —— 消费方一律读作「这台 server 没有说」,不读作「不是子代」。
+ */
+import type { SessionPlacementRecord } from "@sema-agent/core";
+/** 一只会话在委派树里的位置(wire 键 `agent` 的值形)。 */
+export interface SessionAgent {
+    id?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
+}
+/** 交委派元组读口的会话店面(本仓三只持久会话店与缓存包装层都交;内存店不交)。 */
+export interface PlacementReadingSessionStore {
+    readonly placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
+}
+/** {@link SessionAgent} 的唯一投影:店答出的委派元组 → `agent` 的值;`undefined`(普通会话 / 店没有这一面)⇒ 调用方不铸键。 */
+export declare function sessionAgentOf(placement: SessionPlacementRecord | undefined): SessionAgent | undefined;
+/**
+ * `agent` 的**唯一读口**:店的 `placementOf` 一读 → {@link sessionAgentOf}。店不交 `placementOf` ⇒ `undefined`(这台部署不存元组,不探)。
+ * 探针抛 ⇒ 原样上抛 —— 读不出怎么说归读者(视图读响亮失败;队列只缺那一行的键并计数),本函数不替任何一面把故障说成「不是子代」。
+ */
+export declare function readSessionAgent(store: PlacementReadingSessionStore | undefined, sessionId: string): Promise<SessionAgent | undefined>;
+//# sourceMappingURL=session-agent.d.ts.map

package/dist/session-agent.js

@@ -0,0 +1,16 @@
+export function sessionAgentOf(placement) {
+    if (placement === undefined)
+        return undefined;
+    return {
+        ...(placement.handle !== undefined ? { id: placement.handle } : {}),
+        ...(placement.parentSessionId !== undefined ? { parentSessionId: placement.parentSessionId } : {}),
+        ...(placement.rootSessionId !== undefined ? { rootSessionId: placement.rootSessionId } : {}),
+    };
+}
+export async function readSessionAgent(store, sessionId) {
+    const placementOf = store?.placementOf;
+    if (placementOf === undefined)
+        return undefined;
+    return sessionAgentOf(await placementOf.call(store, sessionId));
+}
+//# sourceMappingURL=session-agent.js.map

package/dist/session-error-wire.d.ts

@@ -49,8 +49,8 @@
  *    由 {@link sessionErrorWireOf} 按**型**先认:两面同答 409 `conflict.session_archive_stamped` + 固定句 {@link STAMPED_SESSION_ARCHIVE_SENTENCE}(与上一句的属主变更拒同状态、不同码:
  *    两件事的出路相反 —— 属主变更从第一阶段重来,带戳存档删掉会话再推 —— 机读方按码分支,不读句子)。
  *    open 面上它是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局(`terminal.code: "conflict"`),提交腿不另作处置。
- *    带戳存档的具名拒在提交里排在一切同步冲突判之前(`local-session-store.ts` 的 `assertArchiveAnonymousHeld`):改日志的推送的每一形(干净追加 / 载荷分叉 / fork / stale,带同意与否)都答它的这一句 ——
- *    带戳存档的日志换不了,同步冲突的出路(带同意重来)无从谈起。
+ *    带戳存档的具名拒在提交里排在一切同步冲突判之前(`local-session-store.ts` 的 `assertArchiveAnonymous`,带戳判的唯一读口;fork 的源与第一阶段的早拒问的是同一只):改日志的推送的每一形(干净追加 / 载荷分叉 / fork / stale,带同意与否)都答它的这一句 ——
+ *    带戳存档的日志换不了,同步冲突的出路(带同意重来)无从谈起。第一阶段(`POST …/sync/import`)按 id 分类出 fork / stale 而没带同意时,通用冲突的出路同样是死路 ⇒ 路由先问这一口,带戳 ⇒ 第一阶段就答这一句(不等带同意的第二轮)。
  *  · `storage` / `unknown` —— 留白:故障类,通用 500 就是它们今天的应答。
  *
  * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
@@ -92,8 +92,8 @@ export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated a
  */
 export declare const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported \u2014 start the sync again";
 /**
- * local 店的具名拒(唯一铸点 `plugins/local-session-store.ts`):这只会话的引擎存档仍带更早版本写下的属主戳(一次性迁移 M33 改写不了它,或数据根跳过了带这次迁移的版本)
- * ⇒ 不在它上面造新存档(fork),也不原地换它的日志(改日志的推送);零写。`SessionError.code` 是 core 闭集的 `conflict`;句子(给运维日志,点名会话 id)归本错,
+ * local 店的具名拒(唯一铸点 `plugins/local-session-store.ts` 的 `assertArchiveAnonymous`):这只会话的引擎存档仍带更早版本写下的属主戳(一次性迁移 M33 改写不了它,或数据根跳过了带这次迁移的版本)
+ * ⇒ 不在它上面造新存档(fork),也不原地换它的日志(改日志的推送,含第一阶段对 fork / stale 的早拒);零写。`SessionError.code` 是 core 闭集的 `conflict`;句子(给运维日志,点名会话 id)归本错,
  * wire 上发自己的码 `conflict.session_archive_stamped` + 固定句 {@link STAMPED_SESSION_ARCHIVE_SENTENCE}(两面同一码同一句;映射 {@link sessionErrorWireOf}):
  * 同一个 core 词 `conflict` 在 import 面上还有属主变更那一件事(出路相反),机读方要能按码把两件事分开。
  */

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";

package/dist/session-resident-background.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `/health.inflight` 计法表第四类 —— **会话驻留的后台 shell / monitor**。
+ *
+ * ## 病
+ * 引擎在飞数原先只数 HTTP 腿与 leader 腿。模型在会话里起的后台 shell / monitor(`run_in_background`)活过起它的那一条腿 —— 腿一收,它在这份数里是 0:
+ * 读 `/health` 判「这台引擎是否空闲」的外部判官看不见它们,只好另拼一条谓词 —— 同一个事实两个读法。
+ *
+ * ## 两个事实(本文件只产总数里的第三项 `sessionResident`)
+ * `/health.inflight`(总数,{@link inflightTotal})= 引擎此刻托管着多少活 = `http + leader + sessionResident`,可观测事实;
+ * `drainState.blockingInflight`(阻断集,{@link blockingInflightOf})= 还有没有必须等完的活 = `http + leader`,排空 / 孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判停读它。
+ * 本文件产出的 `sessionResident` **只进总数、不进阻断集**:驻留 shell 不是一条腿,等它没有意义;一只不退出的 shell(`while true`)若阻断,崩溃孤儿引擎就永生。
+ * 窗到 / 排空完成,退出边界的后台收割收掉它们,retain 行按 retain 既有语义活过受控退。
+ *
+ * ## 读法(本文件是唯一属主)
+ * 行集 = core `TaskRegistry.liveTasks(access)` 的投影:`type ∈ {background_bash, monitor}` ∧ `status === "running"` ∧ `sessionScoped` ∧ 非 retain
+ * ({@link isSessionResidentShellRow})。
+ *  · **选座 `liveTasks`,不读 `list()`**:`list()` 是显示投影,硬帽 500 行(core 注:resolution must NEVER ride the display-capped list());
+ *    进程级的在飞总数是外部判官判「引擎是否空闲」的依据,不能骑显示帽 —— 超过 500 行时 `list()` 会静默少数,方向恰是「以为空闲」。`liveTasks` 无显示帽。
+ *  · **retain 行不计**:显式 retain 的行是「交付的活服务」,按 core 契约活过引擎的受控退(退出边界对它 `retained_skipped`),
+ *    不是「引擎托管着、会随它收掉」的活 —— 报它,判官会把一个本就该活过引擎的服务读成引擎的负载。
+ *  · **只数 shell 与 monitor**:后台 agent / workflow 行属计法表的别的类,不在这一类里。
+ *  · **非会话驻留行不数**:挂在 run 腿上的后台行(`sessionScoped` 为假)随腿登记在 HTTP 腿项里,数它是第二次。
+ *
+ * ## 枚举源
+ * core 的 `canAccess` 要求访问元组带 `scope`(缺 scope 一律拒),`list` / `liveTasks` 因此只读「调用方可达行」,没有进程总数的读口(core 不立新 getter)。
+ * 进程级的数要由本仓自己枚举「本进程有哪些会话」:枚举源 = **围栏表**(`boot/execution-env.ts` 的 `SessionScopedRegistries.sessionOwners`):
+ * 每次提交经 resolve-spec 写一笔(会话 id → 属主),删会话的 E21 级联清一笔,LRU 有界。scope 轴 = {@link sessionChildrenScope}(会话属主 `?? "default"`,
+ * 删除门 / 换绑门 / 结清口 / 会话后台读面同一个取法,不另取)。
+ *
+ * ## 读到的边界(成文,不静默)
+ *  · 围栏表是 LRU(上界 4096 会话):被挤出表的会话,它的驻留行在这里不可见 —— 回到改前的读数(不是新的错),不会多数;
+ *  · 不经 resolve-spec 的内部车道(服务为自己起的 run)不写围栏表,它们起的会话驻留行同样不可见;
+ *  · 删会话的级联在 `dropSessionScoped` 之后、后台收割之前失败(会话行因此没删)时,围栏表已先清:该会话还在跑的驻留行在下一次提交重新围栏之前不可见
+ *    (同样回到改前的读数;修法是把 `dropSession` 的「清秘密」与「忘身份」拆开,属围栏表的属主,不在本读法里);
+ *  · 每次读是 O(围栏表会话数 × 注册表行数)(`liveTasks` 逐会话走一遍注册表);表的上界 4096、注册表行数小,量级是毫秒。
+ *
+ * ## 读不出 ⇒ 非空闲(响亮,不替成 0)
+ * 本函数在 `/health` 应答和崩溃遗言(uncaught 处理器里读总数)里被调,**不许抛**(崩溃遗言里一次抛会吞掉遗言本身)。判停路径(排空 / 租约 / SIGHUP)读阻断集,
+ * 不求值本函数。某个会话的 `liveTasks` 读失败 ⇒ 该会话按 **1 只在跑**计(读不出 ⇒ 非空闲:判官宁可当有活)并经 `onUnreadable` 报出 ——
+ * 调用方必须给报口(装配层一会话一行 `session_resident_background_unreadable`),不存在静默的 0。
+ */
+import { type TaskListRow, type TaskRegistry } from "@sema-agent/core";
+/** 枚举源的形:会话 id → 会话属主(`null` = 匿名)。`Map` 满足它。 */
+export type SessionOwners = Iterable<readonly [sessionId: string, owner: string | null]>;
+/** 这一类里的行判:唯一写处(计数与单测同读)。 */
+export declare function isSessionResidentShellRow(row: TaskListRow): boolean;
+/** 一个会话的驻留行读失败的报口(由调用方给出:装配层记运维行)。 */
+export type UnreadableSessionReport = (sessionId: string, err: unknown) => void;
+/**
+ * 本进程里会话驻留的、仍在跑的后台 shell / monitor 行数。`registry` 缺省 = 进程级单例;参数只供测试换桩(只用到 `liveTasks`)。
+ * `onUnreadable` 必给:读失败的会话按 1 计并经它报出(文件头「读不出 ⇒ 非空闲」)。读法与边界见文件头。
+ */
+export declare function countSessionResidentBackground(sessions: SessionOwners, opts: {
+    readonly registry?: Pick<TaskRegistry, "liveTasks">;
+    readonly onUnreadable: UnreadableSessionReport;
+}): number;
+//# sourceMappingURL=session-resident-background.d.ts.map