@sema-agent/server 7.138.0 → 7.140.0

package/dist/runs.d.ts

@@ -263,10 +263,14 @@ export declare function graftParkToolCallId<T>(result: T, cs: ParkCheckpointRead
  * Preemption (POST /v1/assistant/tasks/:id/preempt, [ref] seam #2): a SECOND, INDEPENDENT controller
  * (`preemptCtrl`, registered in `preemptable`) carries the scheduler's graceful "yield this task" — when raised,
  * core durably SUSPENDS the task at the next clean turn boundary (gate resource_limit, reason "preempt") so it is
- * RESUMABLE, the opposite of cancel's kill. It is wired ONLY on the plain-stream path: the verify/cascade
- * branches finalize with `setTerminal` unconditionally (no `setSuspended`), so a preempt-suspend there would write
- * a non-terminal "suspended" as terminal and release the session lock — and preempt's contract is graceful, not a
- * failure. Cross-replica via the `preempt_requested` flag (same heartbeat tick). Eligibility (resourceSuspend +
+ * RESUMABLE, the opposite of cancel's kill. It is wired ONLY on the plain-stream path. A cascade cannot honor it: a
+ * rung's pause lands on the rung's own engine-minted session, which the host's resume chain cannot reach (the
+ * host-boundary judge settles it terminal). A verify task carries the resource-suspend opt-in (a budget / turns /
+ * walltime limit parks its implementation leg or fix round), but its FIRST slice here is not wired to the preempt
+ * signal (`preemptEligible` below is false for verify, so the preempt endpoint answers a no-op for a verify run this
+ * replica owns); a RESUMED verify leg is wired (`resume-legs.ts` registers every resume leg in `preemptableRuns` and
+ * threads `preemptSignal` into `resumeWithVerification`). Cross-replica via the `preempt_requested` flag (same heartbeat
+ * tick). Eligibility (resourceSuspend +
  * durable store + durable tool-results + remote env) is core's call: an ineligible task's preemptSignal no-ops.
  *
  * Steering (POST /v1/runs/:id/steer, [ref]): the live core `TaskStream` is registered in `steerable` so the
@@ -332,7 +336,8 @@ approval?: {
     streamApprovalOn: boolean;
     windowMs: number | undefined;
     windowMarginMs: number;
-    declaredFamilies: ReadonlySet<ApprovalFrameFamily>;
+    declaredFamilies: ReadonlySet<ApprovalFrameFamily>; /** 出处带车道:这条执行上下文的车道(装配点 `durable-run-leg.ts` 写 `ctx.lane`)。 */
+    executionLane: import("./execution-lane-caps.js").ExecutionLane;
 }, 
 /** [ref]:park 投影腿的 checkpoint 读口(`deps.checkpointStore`)。在场时,durable park 的
  *  `suspended` 事件带 `toolCallId`(graft 见 {@link parkToolCallId});缺席=旧字节逐字不变。 */

package/dist/runs.js

@@ -1,5 +1,5 @@
 import { runWithVerification, runCascade, defaultTaskRegistry, taskNotificationDedupKey, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
-import { failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
+import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
 import { NOT_IN_ROSTER, entryProblemsFacts } from "./entry-problems.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { TOOL_DECLARATION_HTTP_STATUS } from "./tool-declaration-http-status.js";
@@ -19,6 +19,7 @@ import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.j
 import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
+import { isParkLedgerEventType } from "./trace/ledger-events.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { errorText as errText } from "./observability/err-text.js";
 import { LIVENESS_HEARTBEAT_MS } from "./config-invariants.js";
@@ -88,6 +89,7 @@ const PREPARE_REFUSAL_HTTP_STATUS = {
     "config.project_identity_mismatch": 409,
     "config.memory_project_marker": 409,
     "config.memory_project_marker_nested": 409,
+    "config.read_deny_floor_unkept": 409,
 };
 export function resumeAtHttpStatus(result) {
     const code = failureCodeOf(result.terminal);
@@ -296,11 +298,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     if (approval) {
         const coordinator = approval.coordinator;
         spec.onAsk = approvalLeg.unattended
-            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}) }, approvalLeg.unattended)
+            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}), executionLane: approval.executionLane }, approvalLeg.unattended)
             : coordinator.boundAsk({
                 owner: elicitOwner ?? owner,
                 taskId,
                 ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
+                executionLane: approval.executionLane,
                 ...(approvalLeg.active ? { legKey: "", ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}) } : {}),
             });
     }
@@ -325,14 +328,38 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     let legLive = true;
     const notifiedKeys = new NotifiedKeys();
     const subagentHandleEvictions = [];
-    const parkNeedsReview = async (res) => {
-        await sink.appendParked("needs_review", res);
+    const parkRowWrite = {
+        suspended: (sealed) => runStore.setSuspended(taskId, sealed),
+        needs_review: (sealed) => runStore.setNeedsReview(taskId, sealed),
+    };
+    const parkLeg = async (word, res) => {
+        const grafted = await graftParkToolCallId(res, parkCheckpointReader);
+        await sink.appendParked(word, grafted);
         await flushModelUsage();
-        const sealed = sealResultForExit(res);
-        reached = { kind: "needs_review", result: sealed };
-        await runStore.setNeedsReview(taskId, sealed);
+        const sealed = sealResultForExit(grafted);
+        reached = { kind: word, result: sealed };
+        await parkRowWrite[word](sealed);
+        acceptance?.settle(sealed);
         metrics?.addGauge("runs_active", -1);
-        metrics?.inc("tasks_total", { status: "needs_review" });
+        metrics?.inc("tasks_total", { status: word });
+    };
+    const settleLegResult = async (engineResult) => {
+        const result = atHostBoundary(engineResult, spec.sessionId);
+        const parkWord = result.terminal.kind === "paused" ? outwardPlane(result.terminal).status : undefined;
+        if (parkWord !== undefined && isParkLedgerEventType(parkWord)) {
+            await parkLeg(parkWord, result);
+            return;
+        }
+        const settled = causeAtDone !== undefined ? cancelledResult(causeAtDone, result) : result;
+        settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
+        const safe = await withModelUsage(sealResultForExit(settled));
+        await sink.appendDone(safe);
+        reached = { kind: "done", result: safe };
+        const plane = outwardPlane(safe.terminal);
+        await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
+        await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
+        acceptance?.settle(safe);
+        recordDone(safe, settledAsCancel ? CANCELLED_CODE : plane.status);
     };
     const instructionLeg = createInstructionSelectionLeg();
     const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys, onActivity: (kind, statusData) => recordTurnActivity(taskId, kind, statusData), legSections: () => ({ instructions: instructionLeg.segment(), skills: runSkillsOf(spec) }) });
@@ -418,32 +445,18 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     void sink.appendStatus(e).catch((err) => completionDiagLog?.("status_event_append_failed", { route: "bg-run-composite", taskId, err: err instanceof Error ? err.message : String(err) }));
                 },
             };
-            if (verify !== undefined) {
-                const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify, { ...fwdInternals, ...statusSeat });
-                await flush();
-                await flushPromptManifest();
-                const safe = await withModelUsage(sealResultForExit(result));
-                await append("done", { result: safe });
-                reached = { kind: "done", result: safe };
-                const plane = outwardPlane(safe.terminal);
-                await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
-                await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
-                acceptance?.settle(safe);
-                recordDone(safe, plane.status);
-                return;
-            }
-            if (cascade !== undefined) {
-                const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade, { ...fwdInternals, ...statusSeat });
+            const compositeLeg = verify !== undefined
+                ? () => runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify, { ...fwdInternals, ...statusSeat })
+                : cascade !== undefined
+                    ? () => runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade, { ...fwdInternals, ...statusSeat })
+                    : undefined;
+            if (compositeLeg !== undefined) {
+                const result = await compositeLeg();
+                observedDone = result;
+                causeAtDone = cancelCtrl.cause();
                 await flush();
                 await flushPromptManifest();
-                const safe = await withModelUsage(sealResultForExit(result));
-                await append("done", { result: safe });
-                reached = { kind: "done", result: safe };
-                const plane = outwardPlane(safe.terminal);
-                await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
-                await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
-                acceptance?.settle(safe);
-                recordDone(safe, plane.status);
+                await settleLegResult(result);
                 return;
             }
             const stream = runner.runTaskStream({ ...spec, taskId, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, undefined, fwdInternals);
@@ -478,33 +491,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 if (ev.type === "done") {
                     await flush();
-                    const parkStatus = ev.result.terminal.kind === "paused" ? outwardPlane(ev.result.terminal).status : undefined;
-                    if (parkStatus === "suspended") {
-                        const grafted = await graftParkToolCallId(ev.result, parkCheckpointReader);
-                        await sink.appendParked("suspended", grafted);
-                        await flushModelUsage();
-                        const sealed = sealResultForExit(grafted);
-                        reached = { kind: "suspended", result: sealed };
-                        await runStore.setSuspended(taskId, sealed);
-                        metrics?.addGauge("runs_active", -1);
-                        metrics?.inc("tasks_total", { status: "suspended" });
-                        continue;
-                    }
-                    if (parkStatus === "needs_review") {
-                        await parkNeedsReview(ev.result);
-                        continue;
-                    }
-                    {
-                        const settled = causeAtDone !== undefined ? cancelledResult(causeAtDone, ev.result) : ev.result;
-                        settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
-                        const safe = await withModelUsage(sealResultForExit(settled));
-                        await sink.appendDone(safe);
-                        reached = { kind: "done", result: safe };
-                        const plane = outwardPlane(safe.terminal);
-                        await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
-                        await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
-                        recordDone(safe, failureCodeOf(safe.terminal) === CANCELLED_CODE ? CANCELLED_CODE : plane.status);
-                    }
+                    await settleLegResult(ev.result);
                     continue;
                 }
                 await sink.onEvent(ev);
@@ -531,6 +518,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     owner: elicitOwner ?? owner,
                     abortSignal: cancelCtrl.signal,
                     ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
+                    executionLane: approval.executionLane,
                     emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
                     emitRevoke: (f) => approvalEmit(f),
                     legKey: "",
@@ -579,11 +567,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, reached.result);
                 acceptance?.settle(reached.result);
             }
-            else if (reached?.kind === "suspended") {
-                await runStore.setSuspended(taskId, reached.result);
-            }
-            else if (reached?.kind === "needs_review") {
-                await runStore.setNeedsReview(taskId, reached.result);
+            else if (reached !== undefined) {
+                await parkRowWrite[reached.kind](reached.result);
+                acceptance?.settle(reached.result);
             }
             else if (thrownCancelCause !== undefined && observedDone === undefined) {
                 const c = cancelledResult(thrownCancelCause);
@@ -612,9 +598,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         }
         if (reached?.kind === "done")
             recordDone(reached.result, failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status);
-        else if (reached?.kind === "suspended") {
+        else if (reached !== undefined) {
             metrics?.addGauge("runs_active", -1);
-            metrics?.inc("tasks_total", { status: "suspended" });
+            metrics?.inc("tasks_total", { status: reached.kind });
         }
         else if (settledAsCancel) {
             recordDone(null, CANCELLED_CODE);

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

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

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,14 +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 **换装**(整段换装 / 暂存提交 / local 落在既有行上的导入)时化身的去留 —— 三只店共用的一句判据:换装只换内容,换的是**同一行**
- * ⇒ 行在且那一格里有一只令牌(唯一解码 {@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: {
+export declare function carriedRowCells(sessionId: string, prior: {
     incarnation?: unknown;
-} | undefined): 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 …`
@@ -136,7 +146,7 @@ export declare function carriedIncarnation(sessionId: string, prior: {
  */
 export declare const SESSION_META_INCARNATION_COLUMN: {
     readonly name: "incarnation";
-    readonly tidb: "incarnation VARCHAR(64) NOT NULL DEFAULT ''";
+    readonly mysql: "incarnation VARCHAR(64) NOT NULL DEFAULT ''";
     readonly pg: "incarnation VARCHAR(64) COLLATE \"C\" NOT NULL DEFAULT ''";
 };
 //# sourceMappingURL=session-incarnation.d.ts.map

package/dist/session-incarnation.js

@@ -67,13 +67,15 @@ export function headReadOf(store) {
     const read = store?.headOf;
     return typeof read === "function" ? read.bind(store) : undefined;
 }
-export function carriedIncarnation(sessionId, prior) {
+export function carriedRowCells(sessionId, prior) {
     const held = prior === undefined ? undefined : incarnationFromCell(sessionId, prior.incarnation, "absent");
-    return held ?? mintSessionIncarnation();
+    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",
-    tidb: "incarnation VARCHAR(64) NOT NULL DEFAULT ''",
+    mysql: "incarnation VARCHAR(64) NOT NULL DEFAULT ''",
     pg: `incarnation VARCHAR(64) COLLATE "C" NOT NULL DEFAULT ''`,
 };
 //# sourceMappingURL=session-incarnation.js.map

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

@@ -139,7 +139,7 @@ export declare function sessionPolicyErrorFacts(e: SessionPolicyError): Readonly
  *  · `conflict`(409)—— CAS 输了,重读 `rev` 再来。**码位与状态逐字不变**。
  *  · `loosen_forbidden`(403)—— 非 operator 想放松。**码位与状态逐字不变**。⚠️ 这个词还有**第二个铸点**([ref] B5,
  *    如实登记、未改):PG 后端的 SQL 双生对含 NUL / 孤代理字节的规则拒收时借用了它
- *    (`plugins/session-policy-store-sql.ts` 的 `pgHasUnstorable` 臂)—— 那一形**既非放宽也非越权**,operator 写同样撞上;
+ *    (`stores-sql/session-policy-store-sql.ts` 的 `pgHasUnstorable` 臂)—— 那一形**既非放宽也非越权**,operator 写同样撞上;
  *    core 的闭集里没有「输入不可存」这个词,改码位要先裁定新码与 PUT / 2c 导入两条入口同判(DEBTS [ref] B5)。
  *  · `corrupt`(**500**)—— 店读不出它自己该读的那份字节(记号/行被列外篡改或撕裂,或存着引擎今天的形读法读不出的规则体)。
  *    不是 4xx:调用方没做错任何事,它也改不了这件事;不是 503:重试改不了判(修复路径是**人**去改回或删掉那一行,