@sema-agent/server 7.137.0 → 7.139.0

package/dist/sandbox-git-plane.d.ts

@@ -52,8 +52,8 @@ export declare function sandboxGitPlanePremisesOf(config: ServiceConfig, reading
 }): SandboxGitPlanePremises;
 /**
  * Wiring point — the effective `sandboxGit` block (the origins this deployment routes through the broker, canonical form, ≤ 16). Its shape
- * and its canonical-form judge belong to the settings-schema contract package (14.7.0); until that release is picked up there is no block to
- * read ⇒ `null` (the plane stays off, `no_origins`). Replaced by the package reader on pickup — no local copy of the shape.
+ * and its canonical-form judge belong to the settings-schema contract package (`SandboxGitConfig`, 14.7.0 — picked up: the block rides the effective
+ * wire verbatim); this reader is not wired to it yet ⇒ `null` (the plane stays off, `no_origins`). To be replaced by the package reader — no local copy of the shape.
  */
 export declare function readSandboxGitConfig(_config: ServiceConfig): {
     readonly origins: readonly string[];

package/dist/security.d.ts

@@ -1,11 +1,12 @@
 import type { IncomingMessage } from "node:http";
-import { type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import { type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 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 SessionFace } from "./session-incarnation.js";
-import type { SessionRowPatch } from "./session-row.js";
+import type { ClientSessionRowWrite, ReplaySessionRowWrite, ReplaySessionRowWriteOutcome, SessionRowPatch, SessionRowWriteOutcome } from "./session-row.js";
+import type { ExecutionPlacementSeat } from "./execution-placement.js";
+import type { ForkTarget, ForkToOutcome } from "./plugins/session-fork.js";
 import { type OwnerlessClaim } from "./delegated-session-owner.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. */
@@ -32,6 +33,19 @@ export interface SessionListItem {
     /** Pinned by the user (`PATCH /v1/sessions/:id`). ALWAYS present — `false` by default (a session's state, not a capability);
      *  a lister face with no session_meta answers `false` (nothing there can pin it). */
     pinned: boolean;
+    /** The row tag (`src/session-row.ts` `sessionRowTagOf`): an opaque one-way digest of this occupant's writable cells — the precondition a
+     *  `PATCH /v1/sessions/:id` carries back as `expectedRowTag`. Present-iff the row can be written conditionally (the store has the row write
+     *  primitive ∧ the row has an occupant token); additive key, passed through unprojected (`sessions-list.ts`). Same name and meaning as
+     *  `SessionSummary.rowTag` in `plugins/store-contracts.ts`. */
+    rowTag?: string;
+}
+/**
+ * 会话店的行格写原语(规则与判序:`session-row.ts` 头注「写原语」)—— 按入口分两只重载:客户端写(PATCH)的结局闭集四员;行重放(2c 导入落定后的那一笔)
+ * 只有 `written` / `absent`(`changed` / `mirror` 对它不可达)。
+ */
+export interface SessionRowCellsWriter {
+    (sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionListItem>>;
+    (sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionListItem>>;
 }
 /** A SessionStore that may additionally expose tenant-ownership ops (the TiDB store does) AND the
  *  `SessionRepo` enumeration/lifecycle seam (§0.5: list/fork/delete homed on the session abstraction's own
@@ -187,17 +201,24 @@ export type OwnerAwareSessionStore = SessionStore & {
      *  row of the list face (no such session, or a placed / delegation-transcript session, which never lists). Reader: the 2c
      *  manifest (`title` / `pinned`). */
     sessionSummaryOf?: (sessionId: string) => Promise<SessionListItem | undefined>;
-    /** The session row's writable bits (`title` / `pinned`) — the ONLY writer of a user-set title or pin (`title: null` clears it back
-     *  to the automatic title; the auto-titler's `setTitleIfNull` fills a NULL title only; the law of the two writers is written in
-     *  `session-row.ts`). **Written on the occupant the caller verified, and only on it**: `face` is the live occupant (`sessionFaceOfHead` over the `headOf` read)
-     *  the caller's gate judged; the write and the read-back are both conditioned on that occupant's incarnation (the same law as
-     *  the parked decide leg's two reads, `session-incarnation.ts`). Answers that occupant's list row after the write
-     *  ({@link sessionSummaryOf}'s projection); `undefined` = no list row for that occupant (deleted, re-registered by anyone in the
-     *  meantime, or a placed session) — nothing was written. A failed write throws. */
-    patchSessionMeta?: (sessionId: string, patch: SessionRowPatch, face: SessionFace) => Promise<SessionListItem | undefined>;
+    /** The session row's write primitive for its writable cells (`title` / `pinned`) — the ONLY writer of a user-set title or pin (`title: null`
+     *  clears it back to the automatic title; the auto-titler's `setTitleIfNull` fills a NULL title only; the law of the two writers and of this
+     *  primitive is written in `session-row.ts`). Judged under the row's lock by one judge (`judgeSessionRowWrite`): the row expectation
+     *  (core `SessionRowExpectation` — the occupant the caller's gate read, owner + incarnation, judged by core `sessionRowMatches`) → the writer
+     *  (a client write on a read-only mirror ⇒ `mirror`) → the row tag (a client's `rowTag` that the locked row no longer carries ⇒ `changed`) → write.
+     *  `written` / `changed` carry the list row read after the commit / rollback ({@link sessionSummaryOf}'s projection, with its new `rowTag`);
+     *  `absent` = no list row for that occupant (deleted, re-registered, owner restamped, or a placed session) — nothing was written. A failed write throws. */
+    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). */
+     *  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>;
+    /** 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>;
+    /** 执行席(规则在 `execution-placement.ts`):根会话行上这一位住客的那一格的唯一读口(`read`)与 place / markMirror 两只写口。三店都有;两只包装原样转发。
+     *  缺席 = 会话店没有执行放置(只有不带它的测试走廊 / 嵌入形),调用方各按自己的缺席臂处置。 */
+    executionPlacement?: ExecutionPlacementSeat;
     /** E21 — purge a session's conversation history (session_meta/session_event); idempotent (false if absent).
      *  `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
      *  route already owner-gates; this pins the DELETE to the authenticated tenant so even a buggy gate can't purge
@@ -285,6 +306,11 @@ export interface AuthContext {
     principal?: string;
     /** The session to run against (resolved + ownership-checked here, then returned to the caller). */
     sessionId: string;
+    /**
+     * 属主门判的那一读(会话店 `headOf` 的整只头;现铸 / 未知 id 臂是登记后那一读)—— 执行上下文解析器的 `judged`:解析器读到的行头住客与它不同 ⇒ 404(门与解析之间会话被删并同 id 重登记)。
+     * 缺 = 店没有 `headOf`(读不出头的店;只一元车道表、无执行席的形可达)。
+     */
+    head?: SessionHead;
     /** Long-term memory scope, derived from the principal (not the body). Undefined disables memory. */
     memoryScope?: string;
     /** 142-S4:the request's SHAPE-VALIDATED **且已归一(小写)** 的 projectId(body.projectId 过 core

package/dist/security.js

@@ -84,7 +84,11 @@ export function createAuthorizer(config, sessionStore) {
         }
         const requireExisting = body.requireExistingSession === true;
         const headOf = headReadOf(sessionStore);
-        const readOwner = headOf === undefined ? undefined : async (id) => (await headOf(id))?.owner;
+        let head;
+        const readOwner = headOf === undefined ? undefined : async (id) => {
+            head = await headOf(id);
+            return head?.owner;
+        };
         const register = sessionStore.register?.bind(sessionStore);
         const requested = typeof body.sessionId === "string" && body.sessionId ? body.sessionId : undefined;
         let sessionId;
@@ -126,8 +130,10 @@ export function createAuthorizer(config, sessionStore) {
             sessionId = uuidv7();
             if (register)
                 await register(sessionId, principal ?? null);
+            if (readOwner)
+                await readOwner(sessionId);
         }
-        return { principal, sessionId, memoryScope: memoryScopeFor(config, principal, projectId), resolvedProjectId: projectId };
+        return { principal, sessionId, memoryScope: memoryScopeFor(config, principal, projectId), resolvedProjectId: projectId, ...(head === undefined ? {} : { head }) };
     };
 }
 export const PRINCIPAL_MAX_LENGTH = 190;

package/dist/server-secret-env.d.ts

@@ -13,7 +13,7 @@
  * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕(现场按**腿**命名);git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。射程 = **每一条**宿主腿:
  * src 里每一只值引 `node:child_process` 的文件都是登记腿、其中每一次起子进程都显式交组合出的 env(普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
  * 腿的继承词是调用点的事实,按「子进程里跑的是谁选的代码」定:模型命令(host shell,交任务自己的词)/ 仓里的钩子与凭据助手(三条 git 腿)/ 执行仓代码的
- * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(引擎的 `[names]` 臂);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
+ * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(十二名基础名单,`[names]` 臂;请求的继承词只给工具 shell、对 hook 不作用)、请求的有效环境层作授予叠在继承结果之上(引擎的 `hostChildEnv`);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
  * 在容器 / 设备里跑、那边的 env 由 `-e` 显式给)⇒ `"all"` —— 只扣本服务自有凭据,CLI 与它的凭据助手 / 插件要读的生态变量照交(形状剥会剥
  * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
@@ -23,7 +23,7 @@
  *    **机器派生**、不手抄、不按「归谁消费」切({@link serverWithheldEnvNames} 一处)。声明两个时机、同一只 {@link declareServerWithheldEnv}:起服第一步(三个进程入口:
  *    `boot/stage-01-config.ts` / `run-local.ts` / `bake-runner/main.ts`,在任何执行环境构造与 spawn 之前 —— 声明先于构造才有构造时拒;此时没有生效配置 = 空表),
  *    与每次生效配置换代(`web-admin-client/apply-effective.ts` 本体:CAS 之后、Runner 换装与 commit 之前 —— 声明先于席位,旧世代不声明)。名单只随**落地**的世代
- *    增长(本进程 env 是 boot 期输入:一个名字一旦指过本进程的凭据,条目改名 / 删掉之后它的值仍在 env 里 ⇒ 落地过的名不退出;没落地的候选不留痕 —— 换装拒 ⇒
+ *    增长(本进程 env 是 boot 期输入:一个名字一旦指过本进程的凭据,条目改名 / 删掉之后它的值仍在 env 里 ⇒ 落地过的名不退出;没落地的候选不留痕 —— 名单重判命中 / 换装拒 ⇒
  *    {@link withdrawServerWithheldEnv} 撤回到换代前的集合)。声明失败(坏形名 / 运行时回填名)⇒ 引擎抛且声明保持原状:起服那次 = 拒启,换代那次 = 候选整拒(与 stage
  *    抛同路)。能力词 `inherit_env.own_credentials_withheld` 在本进程的事实 =
  *    {@link ownCredentialsWithheld}:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合(活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;
@@ -38,10 +38,13 @@
  * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给沙箱」的唯一实现。调用:沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` /
  * `K8S_SANDBOX_ENV`(`config.ts`)与名单解析器的「在不在」判。宿主子进程的剥后放回(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)不经它 —— 那是引擎的严格名单臂(上一段)。
  * host shell 的 `inheritEnv:[names]`(hermetic 形)7.129.0 起由引擎读(与 core `NodeExecutionEnv` 同名选项同义,点到自有凭据名即拒),不经本谓词。
- * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错拒启 / 源里没有的名按序号 warn),本函数只管取值。
+ * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错 / 点名名单型旋钮 / 点名本服务自有凭据名 ⇒ 拒启;源里没有的名按序号 warn),本函数只管取值。
  * 「点名」在各处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
  * 剥后放回形(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)的放回本身也经引擎:{@link composeHostSubprocessEnv} 把名单交引擎的严格名单臂(`inheritedHostEnv([names])`)叠在
- * 继承结果之上 ⇒ 点到本服务自有凭据名 = 引擎抛(spawn 时;起服时解析器 `parseEnvNameAllowlist` 按表列 `channel` 已用同一只判 `inheritEnvPolicyProblem` 拒过),
+ * 继承结果之上 ⇒ 点到本服务自有凭据名 = 引擎在**组合这一刻**抛(语言服务器在构造时组合一次、之后 spawn 用那份静态记录;bake-runner 每次 spawn 组合;
+ * 起服时解析器 `parseEnvNameAllowlist` 已用同一只判 `inheritEnvPolicyProblem` 拒过 —— 解析器对五只名单一律拒,点到**解析时已声明**的自有凭据名的沙箱名单因此
+ * 到不了 {@link allowlistedEnv} 取值这一步;声明之后增长(中心 / config.d 模型条目的 `apiKeyEnv` 换代并进)时,换代声明对活配置里每只名单此刻交出去的名用同一只判
+ * 重判一次 —— 命中 ⇒ 撤回这次增长、候选整拒,已装好的沙箱 env / 语言服务器 env 不变成本服务的凭据,`config.ts` `ownCredentialHitsInForce`),
  * 点到的变量值是本服务凭据的副本 = 引擎扣下。本仓不另判。
  */
 import { type InheritEnvPolicy, type SecretEnvFinding } from "@sema-agent/core";
@@ -64,7 +67,7 @@ export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKe
 /**
  * 🔴 **唯一声明点**:把本进程自有凭据向引擎声明(core 7.52.0 `declareWithheldEnv({ names, values })`;重声明即整表替换,从下一次 spawn 起生效)。`modelApiKeyEnv` = 这一次要并进的
  * 模型条目表(起服第一步 = 空表;换代 = 候选表)。两臂都只随**落地**的世代增长(落地过的名 / 值来源不退出:本进程 env 是 boot 期输入;没落地的候选不留痕 ——
- * 换装拒 ⇒ {@link withdrawServerWithheldEnv})。
+ * 名单重判命中 / 换装拒 ⇒ {@link withdrawServerWithheldEnv})。
  *  · **名臂**:此前声明过的 ∪ 这张表的 {@link serverWithheldEnvNames}。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` …)响亮抛且声明保持原状 —— 本函数不接住:
  *    起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。第一次交表带着名臂与**此前已收下的值**(引擎收过、env 不变 ⇒ 同值照收),
  *    所以这一次抛只可能是名的问题。
@@ -76,7 +79,8 @@ export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKe
  */
 export declare function declareServerWithheldEnv(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 席位拒 ⇒ 撤回最近一次声明(两臂一起回到它之前的那一份):`applyEffective` 在 Runner 换装抛时调,紧跟着那一次 {@link declareServerWithheldEnv} —— 没落地的候选不留痕。
+ * 候选没落地 ⇒ 撤回最近一次声明(两臂一起回到它之前的那一份),两个调用点都紧跟着那一次 {@link declareServerWithheldEnv}、同步无 await:换代声明 helper 在名单重判命中时调,
+ * `applyEffective` 在 Runner 换装抛时调 —— 没落地的候选不留痕。
  * 退回去的那一份是引擎之前接受过的(名确定、值来源的值随 env 不变)⇒ 不抛;连撤两次是同一个结果(幂等)。
  */
 export declare function withdrawServerWithheldEnv(): void;
@@ -94,18 +98,21 @@ export declare function ownCredentialsWithheld(): boolean;
 export declare function ownCredentialValuesWithheld(): boolean;
 /** 测试缝:撤回声明(引擎侧重声明为空表)、忘掉两份声明镜像、点名记账与活配置;生产代码从不调它。 */
 export declare function __resetServerWithheldEnvForTest(): void;
-/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键。 */
+/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键、调用方显式交的授予(按序叠在继承之上,后者赢)。 */
 export interface HostSubprocessEnvRequest {
     readonly site: SecretEnvScrubSite;
     readonly policy?: InheritEnvPolicy | undefined;
     readonly allow: readonly string[];
+    /** 调用方显式交给子进程的变量(今天只有 settings hooks:有效环境层 = 请求 `settings.env` + hook 自己的变量)。引擎判形:名字空 / 带 `=` / NUL / 孤代理项、
+     *  值不是串或带 NUL / 孤代理项 ⇒ 组合**抛**,拒句点名授予与变量(不带值、不回显坏名);调用点按「起不来」处置。 */
+    readonly grants?: readonly Readonly<Record<string, string>>[] | undefined;
 }
 /**
  * 🔴 **宿主子进程 env 的唯一组合**:{@link composeHostSubprocessEnv} + 留痕。**没有按原样交给子进程**的名字(剥掉的)经 `site` 留痕;点名放回的键取回源值,
  * 不是剥除,不计数、不披露。源 env 恒为本进程 env(引擎只读 `process.env`,本仓没有第二个源)。
  *
  * 九条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
- * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(严格名单)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
+ * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(十二名严格名单 + 有效环境层作授予)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。

package/dist/server-secret-env.js

@@ -1,4 +1,4 @@
-import { declareWithheldEnv, inheritedHostEnv } from "@sema-agent/core";
+import { declareWithheldEnv, hostChildEnv, inheritedHostEnv } from "@sema-agent/core";
 import { CONFIG_CATALOG } from "./config-catalog.js";
 import { ENV_NAME_ALLOWLIST_KNOB_NAMES } from "./env-name-allowlist-knobs.js";
 import { recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
@@ -84,7 +84,9 @@ export function hostSubprocessEnv(o) {
 }
 export function composeHostSubprocessEnv(o, findings = []) {
     const putBack = o.allow.length > 0 ? inheritedHostEnv([...o.allow], findings) : {};
-    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...putBack };
+    const child = hostChildEnv(o.policy ?? "scrub", putBack, ...(o.grants ?? []));
+    findings.push(...child.withheld);
+    return child.env;
 }
 export function withheldFromHostSubprocess(o, regranted) {
     const findings = [];

package/dist/session-children-retire.d.ts

@@ -27,6 +27,13 @@
  *    (修复验证轮两条 opus 腿同命中:修前预检看的是内存句柄的**状态**(不是 running / pending ⇒ 够不着),本副本刚停、写在飞的子代因此被答成
  *    「在别的副本上」的 409 —— 同一个「这只子代在不在本进程」的判断有两个写者。)
  *
+ * ## 一只预检、一只协调器、一个 scope(树活性的子代半)
+ * 能在树活着时改根放置 / 住客的三门 —— 删除(`boot/session-faces.ts`)、换绑(`routes/devices.ts`)、导入(`routes/session-sync.ts`)—— 与显式结清口
+ * `POST /v1/sessions/:id/children/retire`(`routes/background.ts`)都只经这里:**观察**只有 {@link probeSessionChildren}(同一次枚举交出活子代句柄
+ * `liveChildren` 与不可达的那几只),**结清**只有 {@link retireSessionChildren}(结果交首轮观察到的句柄 `observed`);scope 只有一处取
+ * {@link sessionChildrenScope}(会话属主 `owner ?? "default"`)。wire 上的 `children` / `remaining` 一律经名册的 id 投影出门。
+ * 子代半是**写前一次观察**:子代登记在 core 的后台子代店,写者的事务装不进这一读(认领半才是写事务内那一读,`execution-placement-sql.ts` 头注)。
+ *
  * ## 循环(有上界)
  * 作废 / 停止与一次并发的 `/decide` 可能交错:expire 的 CAS 输给了决定腿的 resolve ⇒ 那只子代被唤醒成 running ⇒ 下一轮枚举看见
  * 它、停掉它。循环到「枚举不出活的子代」为止,轮数有上界({@link RETIRE_MAX_ROUNDS});本进程 kill 的耐久写是 core 的异步写链,
@@ -51,26 +58,37 @@ export interface RetireSessionChildrenDeps extends ChildrenSource {
     registry: Pick<TaskRegistry, "stopTask" | "reconcileParkedAgents" | "activeDelegationHandles">;
     sleep?: (ms: number) => Promise<void>;
 }
-/** 可达性预检的结果(零写)。`unreachableHandles` 只含本进程结束不了的那几只;可达的子代不在这里。 */
+/**
+ * 可达性预检的结果(零写)。`liveChildren` = 这一次枚举观察到的全部活子代句柄(running / parked;换绑 / 导入两门的 409 体 `children` 就是它);
+ * `unreachableHandles` 只含其中本进程结束不了的那几只(删除门与结清口的 409 `remaining`);可达的子代不在那里。
+ */
 export type SessionChildrenReachability = {
     readonly reachable: true;
-    readonly live: number;
+    readonly liveChildren: readonly string[];
 } | {
     readonly reachable: false;
-    readonly live: number;
+    readonly liveChildren: readonly string[];
     readonly unreachableHandles: readonly string[];
 };
-/** 结束子代的结果。`incomplete` = 时序失败(本进程的停止还没落盘 / 预检之后冒出来的子代),不是可达性。 */
+/**
+ * 结束子代的结果。`observed` = 首轮枚举观察到的活子代句柄(成功形 `all` 下它们已全部结清 —— 结清口应答的 `children`)。
+ * `incomplete` = 时序失败(本进程的停止还没落盘 / 预检之后冒出来的子代),不是可达性。
+ */
 export type RetireSessionChildrenOutcome = {
     readonly stopped: "all";
-    readonly found: number;
+    readonly observed: readonly string[];
     readonly rounds: number;
 } | {
     readonly stopped: "incomplete";
-    readonly found: number;
+    readonly observed: readonly string[];
     readonly rounds: number;
     readonly remainingHandles: readonly string[];
 };
+/**
+ * 以一只根会话为根的后台子代在哪个 scope 分区里枚举 —— **唯一一处取**:会话属主 `owner ?? "default"`(删除门、换绑 / 导入两门、结清口同读;
+ * 子代按 run 的 principal 登记、与会话属主不同源的那一形是既有缺陷,修在这里一处)。
+ */
+export declare function sessionChildrenScope(owner: string | null): string;
 /**
  * **可达性预检**(零写;协调器在任何破坏性步骤之前调)。parked 行在有 checkpoint 店时可达(expire + reconcile 在任何副本上都成);
  * running 行除非 {@link runsOnAnotherReplica} 都可达(`getAccessibleTask` / `agentStore.get` 都是纯读,不动任何东西)。
@@ -79,9 +97,9 @@ export declare function probeSessionChildren(deps: ProbeSessionChildrenDeps, roo
 /** 以 `rootSessionId` 为根、在 `scope` 分区里的后台子代:作废 parked、停掉 running,重新枚举到没有活的为止(有上界)。 */
 export declare function retireSessionChildren(deps: RetireSessionChildrenDeps, rootSessionId: string, scope: string): Promise<RetireSessionChildrenOutcome>;
 /**
- * 结束子代这一步的**时序**失败(可达性已在预检过了):本进程发出的停止在上界内没有全部落地。协调器抛它 ⇒ 路由通用 500;
- * session_meta 不删(E21「子腿失败 ⇒ 不删 meta ⇒ 幂等重试收敛」的既有契约),账本那一腿此时已经删了 —— 与任何一条子腿中途失败同形。
- * 文案不带句柄(句柄进运维 warn `session_delete_children_stop_incomplete`)。
+ * 结束子代这一步的**时序**失败(可达性已在预检过了):本进程发出的停止在上界内没有全部落地。两只调用方(删除协调器、结清口)抛它 ⇒ 路由通用 500;
+ * 删除:session_meta 不删(E21「子腿失败 ⇒ 不删 meta ⇒ 幂等重试收敛」的既有契约),账本那一腿此时已经删了 —— 与任何一条子腿中途失败同形;
+ * 结清口:重试同一请求收敛。文案不带句柄(句柄进运维 warn)。
  */
 export declare class SessionChildrenStopIncompleteError extends Error {
     readonly sessionId: string;

package/dist/session-children-retire.js

@@ -1,5 +1,8 @@
 export const RETIRE_MAX_ROUNDS = 6;
 const RETIRE_BACKOFF_MS = [0, 25, 50, 100, 200, 400];
+export function sessionChildrenScope(owner) {
+    return owner ?? "default";
+}
 async function liveChildren(deps, rootSessionId, scope) {
     const out = new Map();
     if (deps.agentStore !== undefined) {
@@ -22,7 +25,8 @@ export async function probeSessionChildren(deps, rootSessionId, scope) {
         if (unreachable)
             unreachableHandles.push(child.handle);
     }
-    return unreachableHandles.length === 0 ? { reachable: true, live: live.length } : { reachable: false, live: live.length, unreachableHandles };
+    const handles = live.map((c) => c.handle);
+    return unreachableHandles.length === 0 ? { reachable: true, liveChildren: handles } : { reachable: false, liveChildren: handles, unreachableHandles };
 }
 async function runsOnAnotherReplica(deps, handle, rootSessionId, scope) {
     if (deps.registry.getAccessibleTask(handle, { scope, sessionId: rootSessionId }) !== undefined)
@@ -35,7 +39,7 @@ async function runsOnAnotherReplica(deps, handle, rootSessionId, scope) {
 export async function retireSessionChildren(deps, rootSessionId, scope) {
     const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     let live = await liveChildren(deps, rootSessionId, scope);
-    const found = live.length;
+    const observed = live.map((c) => c.handle);
     let rounds = 0;
     while (live.length > 0 && rounds < RETIRE_MAX_ROUNDS) {
         rounds++;
@@ -56,8 +60,8 @@ export async function retireSessionChildren(deps, rootSessionId, scope) {
         live = await liveChildren(deps, rootSessionId, scope);
     }
     return live.length === 0
-        ? { stopped: "all", found, rounds }
-        : { stopped: "incomplete", found, rounds, remainingHandles: live.map((c) => c.handle) };
+        ? { stopped: "all", observed, rounds }
+        : { stopped: "incomplete", observed, rounds, remainingHandles: live.map((c) => c.handle) };
 }
 async function expireParkedCard(deps, handle, scope) {
     if (deps.agentStore === undefined || deps.checkpointStore === undefined)
@@ -76,7 +80,7 @@ export class SessionChildrenStopIncompleteError extends Error {
     remaining;
     constructor(sessionId, remaining) {
         super(`session ${sessionId}: ${remaining} background agent(s) this replica stopped had not settled within ${RETIRE_MAX_ROUNDS} rounds — ` +
-            `the session record was kept so the delete can be retried (it converges once they settle)`);
+            `the operation stopped before its next step (a delete keeps the session record) so it can be retried (it converges once they settle)`);
         this.sessionId = sessionId;
         this.remaining = remaining;
         this.name = "SessionChildrenStopIncompleteError";

package/dist/session-incarnation.d.ts

@@ -29,11 +29,14 @@
  *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`。
  *    空值只可能来自没铸化身的写腿、人为改库,或跳过了 7.104.0–7.135.x(那几版的起服迁移给存量行铸令牌,窗关后已删码)直接升上来的库 ——
  *    把它当「通配」就是让任何人都能和这一行比成同一位住客。
- *  · **不上 wire、不进模型上下文、不进日志正文**:日志里要点名时只打 {@link incarnationLogPrefix}(前 8 位)。
+ *  · **不上 wire、不进模型上下文、不进日志正文**:日志里要点名时只打 {@link incarnationLogPrefix}(前 8 位)。值本身不出进程;唯一出进程的形是
+ *    **单向摘要** —— 它折进会话列表行的行标签(`session-row.ts` 的 `sessionRowTagOf`,与会话 id、属主、可写格一起 SHA-256),摘要不可逆
+ *    (令牌是 v4 随机串),只让「住客换了」在标签上看得见。
  *
  * ## 谁读它(全部派生自那一只头读)
- *  · `/decide` 的 parked 赎回腿(`parked-decide.ts`):claim 前读一次、claim 后再读一次,会话不在或不是同一位住客 ⇒ 回滚 claim、
- *    答既有的 `409 decide.not_parked`;赎回面(`parked-revive-surface.ts`)只在属主相等**且**两次读是同一位住客时交继承座。
+ *  · `/decide` 的 parked 赎回腿(`parked-decide.ts`):对根会话一读一判 —— 认领之前执行上下文解析器那一次执行席行读(与头读同一行、同一列)是唯一一读,
+ *    认领之后唯一写口按那一读的住客定址判一次(化身 ∧ 属主;不在或不是那一位 ⇒ 回滚认领、答既有的 `409 decide.not_parked`);
+ *    赎回面(`parked-revive-surface.ts`)只收写口放行的那一位,属主 = 卡的 principal 时交继承座。
  *  · core 的记忆引擎:Runner 读**它取到的那只会话**的 `getMetadata().incarnation`(SQL 两店的 wake 带出这一列;local 店交出的会话
  *    在元数据上答边档那一格),不再有宿主座。
  *  · 没取会话的那一侧(k8s 工作区空间的分区,`boot/execution-env.ts`):会话店的 `headOf`,经 {@link sessionFaceOfHead} 拿令牌;缓存包装层原样转发。
@@ -75,7 +78,7 @@ export declare class SessionIncarnationMissingError extends Error {
  */
 export type EmptyIncarnationReading = "refuse" | "absent";
 /**
- * 行上化身那一格的**唯一解码**(店读出的头、活住客的投影、SQL 两店 wake 带出的会话元数据、留存删除的空间键、整段换装的沿用判据都经它 ——
+ * 行上化身那一格的**唯一解码**(店读出的头、活住客的投影、SQL 两店 wake 带出的会话元数据、留存删除的空间键、整段换装的沿用判据({@link carriedRowCells})都经它 ——
  * 「是不是一只令牌」只判这一处)。非空字符串 ⇒ 那只令牌;否则按 `empty`({@link EmptyIncarnationReading}):缺省 `refuse` ⇒
  * {@link SessionIncarnationMissingError},`absent` ⇒ `undefined`。
  */
@@ -116,15 +119,21 @@ export declare function sessionFaceOfHead(sessionId: string, head: SessionHead |
  * 委派继承律读的都是这一只返回值。缺席 = 店没有实装 `headOf`(读不出属主 / 住客 / 叶子,调用方各按自己的 fail-closed 臂处置)。
  */
 export declare function headReadOf(store: object | undefined): HeadRead | undefined;
+/** 换装沿用的行格(化身 + fork 键):{@link carriedRowCells} 的答案。`forkKey: null` = 没有可沿用的键(新建行 / 行上本来没有)。 */
+export interface CarriedRowCells {
+    readonly incarnation: string;
+    readonly forkKey: string | null;
+}
 /**
- * session-sync **整段换装**(replace)时化身的去留 —— 三只店共用的一句判据:换装删掉再插回的是**同一位住客**的那一行
- * (删除带属主门),所以行在、属主相同、那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 沿用;
- * 行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
+ * session-sync **换装**(整段换装 / 暂存提交)时行格的去留 —— 三只店共用的一句判据:换装只换内容,换的是**同一行**
+ * ⇒ 行在且那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 化身与 fork 键(`fork_key` / local `forkKey`:建这一行的那次 fork
+ * 请求的键,只由 fork 创建点写、此后每个写携带)**一起沿用**(属主重戳与否不改这一判:同一行 = 同一位住客);行不在(这是一次新建)或还是空的存量形 ⇒
+ * 铸一只新化身、没有 fork 键。属主不在这里判:每只店在自己的属主门上判过被换的那一行(SQL 孪生的 replace 只交「属主门删得到的那一行」),读不中的换装一个字节不写。
  */
-export declare function carriedIncarnation(sessionId: string, prior: {
-    owner?: unknown;
+export declare function carriedRowCells(sessionId: string, prior: {
     incarnation?: unknown;
-} | undefined, owner: string | null): string;
+    forkKey?: unknown;
+} | undefined): CarriedRowCells;
 /**
  * `session_meta.incarnation` 的列定义 —— 两方言各一句,**唯一属主**:中央 DDL(`tidb-pool.ts` / `pg-session-storage.ts` 的
  * `CREATE TABLE session_meta`)内插这同一串;存量库缺这一列时,起服列册探针(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE … ADD COLUMN …`

package/dist/session-incarnation.js

@@ -67,9 +67,11 @@ export function headReadOf(store) {
     const read = store?.headOf;
     return typeof read === "function" ? read.bind(store) : undefined;
 }
-export function carriedIncarnation(sessionId, prior, owner) {
-    const held = prior !== undefined && (prior.owner ?? null) === owner ? incarnationFromCell(sessionId, prior.incarnation, "absent") : undefined;
-    return held ?? mintSessionIncarnation();
+export function carriedRowCells(sessionId, prior) {
+    const held = prior === undefined ? undefined : incarnationFromCell(sessionId, prior.incarnation, "absent");
+    if (held === undefined)
+        return { incarnation: mintSessionIncarnation(), forkKey: null };
+    return { incarnation: held, forkKey: typeof prior?.forkKey === "string" && prior.forkKey !== "" ? prior.forkKey : null };
 }
 export const SESSION_META_INCARNATION_COLUMN = {
     name: "incarnation",

package/dist/session-row.d.ts

@@ -1,10 +1,114 @@
+import { type SessionLogMark, type SessionRowExpectation } from "@sema-agent/core";
 /** `title` 列的宽度(字符)= 用户标题的上界。两方言 DDL 内插它。 */
 export declare const SESSION_TITLE_MAX_CHARS = 120;
-/** 会话行的可写位(体闭集;两键至少一键)。会话店唯一写口 `patchSessionMeta` 的形参。`title: null` = 清回自动标题(列写 NULL)。 */
+/** 会话行的可写位(体闭集;两键至少一键)。会话店唯一行格写口 `writeSessionRowCells` 的格参。`title: null` = 清回自动标题(列写 NULL)。 */
 export interface SessionRowPatch {
     readonly title?: string | null;
     readonly pinned?: boolean;
 }
+/** 一行可写格的整组当前值(每格必在;没被写过的格 = 它的缺省值)。 */
+export type SessionRowCells = {
+    readonly [K in keyof SessionRowPatch]-?: Exclude<SessionRowPatch[K], undefined>;
+};
+/**
+ * 可写格的闭集与每格缺省值 —— **一只记录**(头注「格的闭集与缺省值是一只记录」):PATCH 体闭集的键表与 {@link sessionRowTagOf} 的取格都读它;
+ * 映射型把它与 {@link SessionRowPatch} 双向绑住(漏一键 / 多一键 = 编译红)。
+ */
+export declare const SESSION_ROW_CELL_DEFAULTS: SessionRowCells;
+/** 行标签的形:SHA-256 的 base64url(无填充)= 43 个 `[A-Za-z0-9_-]` 字符。体读者对 `expectedRowTag` 判的就是它。 */
+export declare const SESSION_ROW_TAG_SHAPE: RegExp;
+/** 算一只行标签要的四样:会话 id、属主、这一位住客的化身(非空)、可写格的整组当前值。 */
+export interface SessionRowTagInput {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly incarnation: string;
+    readonly cells: SessionRowCells;
+}
+/**
+ * 行标签 —— 唯一一只(头注「行标签」):纯函数、无进程密钥,多副本对同一行算出同一个串。格按 {@link SESSION_ROW_CELL_DEFAULTS} 的键取、
+ * 值等于缺省的不入、按键名升序成 `[[键, 值], …]`。化身只以这只单向摘要的形式出进程(`session-incarnation.ts` 头注)。
+ */
+export declare function sessionRowTagOf(row: SessionRowTagInput): string;
+/**
+ * 列表行上的 `rowTag` 键(present-iff 这一行可被条件写 = 店有行写口 ∧ 行上有化身):三只店的列表行映射都经它,化身那一格由调用方经
+ * `incarnationFromCell(…, "absent")` 解码好交进来(`undefined` = 行上没有令牌 ⇒ 键缺席,不铸)。
+ */
+export declare function sessionRowTagKey(row: {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly incarnation: string | undefined;
+    readonly cells: SessionRowCells;
+}): {
+    readonly rowTag?: string;
+};
+/** 客户端写(PATCH):行期望 + 可选的行标签(只有 PATCH 入口给)。 */
+export interface ClientSessionRowWrite {
+    readonly writer: "client";
+    readonly row: SessionRowExpectation;
+    readonly rowTag?: string;
+}
+/** 行重放(2c 导入落定后的那一笔):只有行期望 —— 它是镜像行的名写者,不判镜像、不带标签。 */
+export interface ReplaySessionRowWrite {
+    readonly writer: "replay";
+    readonly row: SessionRowExpectation;
+}
+/** 写原语的写法(写者身份闭集两员)。 */
+export type SessionRowWrite = ClientSessionRowWrite | ReplaySessionRowWrite;
+/**
+ * 写原语的结局(闭集四员):`written` / `changed` 带提交(回滚)之后另读的那一行(列表行投影,含新 `rowTag`);`mirror`(客户端写在只读镜像上)/
+ * `absent`(行期望不中 / 没有行 / 委派分区行 / 应答行已不是判过的那一位住客)一个字节没写。
+ */
+export type SessionRowWriteOutcome<Row> = {
+    readonly kind: "written";
+    readonly row: Row;
+} | {
+    readonly kind: "changed";
+    readonly row: Row;
+} | {
+    readonly kind: "mirror";
+} | {
+    readonly kind: "absent";
+};
+/** 行重放的结局:`changed` / `mirror` 对它不可达(判官对 `replay` 不判标签、不判镜像)。 */
+export type ReplaySessionRowWriteOutcome<Row> = Extract<SessionRowWriteOutcome<Row>, {
+    readonly kind: "written" | "absent";
+}>;
+/** 写原语在锁下读到的那一行 —— 三店各自读成这一形,交同一只判官 {@link judgeSessionRowWrite}。 */
+export interface LockedSessionRow {
+    readonly owner: string | null;
+    /** 化身那一格(`incarnationFromCell(…, "absent")` 解码:空 / 非串 ⇒ `undefined` = 住客未知,与 core 同读)。 */
+    readonly incarnation: string | undefined;
+    /** 委派分区行(SQL `placement_kind` 非空;local 没有)—— 不在列表面上,不写。 */
+    readonly placed: boolean;
+    /** 执行格是 `mirror`(写者在别处,本处只读)。 */
+    readonly mirror: boolean;
+    readonly cells: SessionRowCells;
+}
+/** 判官的四答(`write` = 可以写;其余三答 = 一个字节不写)。 */
+export type SessionRowVerdict = "write" | "changed" | "mirror" | "absent";
+/**
+ * 写原语的**唯一判官**(头注「写原语」):三店在各自的锁下读出那一行、交这一只,判序因此逐字同形 ——
+ *  ① **行期望**:core 的 `sessionRowMatches(how.row, 锁住的行, logNow)`;不中、没有行(`undefined`)、委派分区行 ⇒ `absent`;
+ *  ② **写者身份**:`client` ∧ 执行格为 `mirror` ⇒ `mirror`(镜像在本处只读;`replay` 是镜像的名写者,照写);
+ *  ③ **标签**:`client` 带 `rowTag` ∧ 锁住的行算出的标签({@link sessionRowTagOf})≠ 它 ⇒ `changed`(行上没有化身 ⇒ 算不出标签 ⇒ 任何标签都不中);
+ *  ④ `write`。
+ * 没有「已生效 ⇒ 写」的豁免:标签不中一律 `changed` —— 整体摘要分不出「住客换了」还是「格变了」,豁免会让恰好已有目标值的新住客拿到写。
+ * `logNow` 只在行期望带 `log` 时被调(调用方在同一把锁下先读好那只 mark)。
+ */
+export declare function judgeSessionRowWrite(sessionId: string, how: SessionRowWrite, locked: LockedSessionRow | undefined, logNow: () => SessionLogMark): SessionRowVerdict;
+/** 应答行:提交 / 回滚之后另读的那一行 + 读到它时行上的住客(属主 + 化身那一格)。 */
+export interface SessionRowAnswer<Row> {
+    readonly row: Row;
+    readonly occupant: {
+        readonly owner: string | null;
+        readonly incarnation: string | undefined;
+    };
+}
+/**
+ * 判官答 `write` / `changed` 之后的结局 —— 三店同一只:应答行(提交 / 回滚之后另读)仍是判过的那一位住客(同一只 core 判官 `sessionRowMatches`,只比行期望的住客半,
+ * 不比日志 mark —— 那一维判的是写之前)⇒ `written` / `changed` 带它;读不到、或已换了住客 / 属主 ⇒ `absent`(不把另一位住客的行答给这位调用方)。
+ */
+export declare function settleSessionRowWrite<Row>(how: SessionRowWrite, verdict: "write" | "changed", answer: SessionRowAnswer<Row> | undefined): SessionRowWriteOutcome<Row>;
 /** 一条已分类的拒:码 + 不回显输入的句子。 */
 export interface SessionRowProblem {
     readonly code: "request.body_shape" | "request.field_invalid";
@@ -27,13 +131,18 @@ export declare function readSessionPinned(v: unknown): {
 } | {
     readonly problem: SessionRowProblem;
 };
+/** PATCH 体读出来的东西:要写的格 + 可选的前置条件(客户端读到的行标签)。 */
+export interface SessionRowPatchRequest {
+    readonly patch: SessionRowPatch;
+    /** 在场 = 「这一行仍是我读到的那一份才写」(写原语在锁住的那一行上比 {@link sessionRowTagOf});缺席 = 无条件写。 */
+    readonly expectedRowTag?: string;
+}
 /**
- * `PATCH /v1/sessions/:id` 体的**唯一**读者。形不对(非对象 / 空 / 表外键)⇒ `request.body_shape`;两键各走自己那一格的读者。
+ * `PATCH /v1/sessions/:id` 体的**唯一**读者。形不对(非对象 / 表外键 / 一格可写位都没有 —— 只带 `expectedRowTag` 也算)⇒ `request.body_shape`;
+ * 各格走自己那一格的读者;`expectedRowTag` 不是 {@link SESSION_ROW_TAG_SHAPE} ⇒ `request.field_invalid`。先形后值,值的判序:`title` → `pinned` → `expectedRowTag`。
  * 拒句不回显调用方的键名或值。
  */
-export declare function readSessionRowPatch(body: unknown): {
-    readonly patch: SessionRowPatch;
-} | {
+export declare function readSessionRowPatch(body: unknown): SessionRowPatchRequest | {
     readonly problem: SessionRowProblem;
 };
 //# sourceMappingURL=session-row.d.ts.map