@sema-agent/server 7.138.0 → 7.139.0

package/dist/http/resume-legs.js

@@ -6,9 +6,6 @@ import { parkDecisionFingerprint } from "../orchestration/workflow-park-decision
 import { headReadOf } from "../session-incarnation.js";
 import { createSessionWorkspaceRecorder, legSessionWitnessOf, sessionWorkspaceStoreOf } from "../session-workspace.js";
 const DELIVERY_NOT_RECORDED = "workflow park decide: this delivery no longer holds the host session (its claim was released) — the decision was not recorded and this delivery was not started";
-const headUnavailable = async (sessionId) => {
-    throw new Error(`parked decide cannot verify which occupant session ${sessionId} belongs to: this deployment's session store has no head read (headOf; every built-in store has one) — refusing rather than resuming unverified`);
-};
 import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import { graftParkToolCallId, parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { failureCodeOf, nestedPauseOf, sealResultForExit, outwardPlane } from "../terminal.js";
@@ -50,7 +47,7 @@ import { createImagesLocal } from "./routes/images.js";
 import { createCapabilitiesLocal } from "./routes/capabilities.js";
 import { gatedPrincipal, explicitOperatorOk, runIdentityOf } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
-import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
+import { commitExecutionContext, isRootSessionGoneError, resolveExecutionContext, rootSessionAbsentAnswer, stampSpecRoot } from "./execution-context.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { ASK_USER_QUESTION_TOOL_NAME, isApprovalGateKind, isEngineQuestionRow } from "../approval-content-kind.js";
 import { deploymentListAsks } from "../approval.js";
@@ -102,6 +99,7 @@ const WORKER_SWAP_REDEEMABLE = {
     unknown_model_ref: true,
     not_a_model_ref: true,
     unknown_role_word: true,
+    no_model_for_role: true,
 };
 function checkpointRowRedeemableElsewhere(reason) {
     return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
@@ -416,10 +414,30 @@ export function createResumeLegs(ctx) {
                     checkpointStore: cs,
                     registry: defaultTaskRegistry,
                     reviveSurface: parkedSurface,
-                    headOf: headReadOf(deps.sessionStorage) ?? headUnavailable,
                     ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
                     ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
                     ...(deps.toolApproval ? { approverSeatFor: windowZeroSeatOf(deps.toolApproval) } : {}),
+                    execution: {
+                        resolve: async (root) => {
+                            let ctx;
+                            try {
+                                ctx = await resolveExecutionContext(deps, { kind: "continuation", root, principal: decodeCheckpointScope(cp.scope) });
+                            }
+                            catch (e) {
+                                if (isRootSessionGoneError(e))
+                                    return { ok: false, gone: true };
+                                if (e instanceof HttpError)
+                                    return { ok: false, gone: false, answer: resumeRefusalWithCard(resumeBlockedByPolicyAnswer(httpErrorRefusal(e)), true) };
+                                throw e;
+                            }
+                            const occupant = ctx.occupant;
+                            if (occupant === undefined) {
+                                throw new Error(`parked decide: root session ${root} resolved without an occupant reading — the parked revive leg is wired to a session store without an execution placement seat (sessionStorage.executionPlacement), which createHttpServer should have refused at startup; refusing rather than resuming with nobody judging the root session's occupant after the claim`);
+                            }
+                            return { ok: true, ctx: { ...ctx, occupant } };
+                        },
+                        commitDeps: deps,
+                    },
                     ...(deps.logger ? { warn: parkWarn } : {}),
                 }, { ...parkedReq, selectedGate: captureSelectedGate() }, { handle: origin.handle, row: origin.row }));
                 void ctxPromise.catch(() => { });
@@ -520,7 +538,7 @@ export function createResumeLegs(ctx) {
                 hostDecision,
             };
             const verifyRounds = verifyRoundsFromBody(ctx.body);
-            const driven = await driveResumeIntoRunLog({ peerLease: resolved.peerLease, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, commitment: { kind: "gate_resolved", ...captureSelectedGate() }, verifyRounds, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(boundGrant ? { onResumeCommitted: boundGrant } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}), ...(ownerLeaseAdmittedHere ? { ownerLeaseAdmitted: true } : {}) });
+            const driven = await driveResumeIntoRunLog({ peerLease: resolved.peerLease, execution: resolved.execution, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, commitment: { kind: "gate_resolved", ...captureSelectedGate() }, verifyRounds, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(boundGrant ? { onResumeCommitted: boundGrant } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}), ...(ownerLeaseAdmittedHere ? { ownerLeaseAdmitted: true } : {}) });
             noteLateSettleIfAccepted(driven);
             return driven;
         }
@@ -528,17 +546,19 @@ export function createResumeLegs(ctx) {
             resolved.peerLease.release();
         }
     }
-    const ONE_SHOT_SUBMIT_KEYS = ["resumeAt", "restoreFiles", "acceptPartialRestore", "rewindFilesTo", "rewindFiles", "userAttachments", "images"];
+    const ONE_SHOT_SUBMIT_KEYS = ["resumeAt", "restoreFiles", "acceptPartialRestore", "rewindFilesTo", "userAttachments", "images"];
     const ONE_SHOT_SUBMIT_STRIP = Object.fromEntries(ONE_SHOT_SUBMIT_KEYS.map((k) => [k, undefined]));
     const resolveResumeSpec = async (ctx, req, auth, lease) => {
         const engineNotices = [];
-        const spec = await deps.resolveSpec({ ...ctx.body, ...ONE_SHOT_SUBMIT_STRIP }, req, auth, {
+        const execution = await resolveExecutionContext(deps, { kind: "continuation", root: auth.sessionId, principal: auth.principal });
+        const spec = stampSpecRoot(await deps.resolveSpec({ ...ctx.body, ...ONE_SHOT_SUBMIT_STRIP }, req, auth, {
             leg: "resume",
             onNotice: (n) => engineNotices.push(n),
             ...(ctx.unattendedLeg === true ? { unattendedLeg: true } : {}),
             lease,
-        });
-        return { spec, engineNotices };
+            execution,
+        }), execution);
+        return { spec, engineNotices, execution };
     };
     const refuseStoredBodyReplay = (sessionId, refusal) => {
         deps.logger?.warn?.("resume_refused_stored_body", { sessionId, ...storedBodyReplayLogFields(refusal) });
@@ -550,8 +570,8 @@ export function createResumeLegs(ctx) {
             return { ok: false, answer: refuseStoredBodyReplay(auth.sessionId, replay) };
         const lease = deps.peerDesk.lease("resume");
         try {
-            const { spec, engineNotices } = await resolveResumeSpec(ctx, req, auth, lease);
-            return { ok: true, spec, engineNotices, peerLease: lease };
+            const { spec, engineNotices, execution } = await resolveResumeSpec(ctx, req, auth, lease);
+            return { ok: true, spec, engineNotices, execution, peerLease: lease };
         }
         catch (e) {
             lease.release();
@@ -583,7 +603,7 @@ export function createResumeLegs(ctx) {
     }
     async function driveResumeLeg(args, onAccepted) {
         const resumeLegStartedAt = Date.now();
-        const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds, resumeCtx } = args;
+        const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds, resumeCtx, execution } = args;
         const reparkStatus = outcome.gate === "plan_review" ? "needs_review" : "suspended";
         const commitResumeCtx = () => Promise.resolve().then(() => deps.checkpointStore.putCtx(resumeCtx.sessionId, sealCheckpointCtx({ ...resumeCtx.ctx, writerVersion: serviceVersion() }, deps.checkpointCtxSealing, resumeCtx.sessionId))).catch((e) => {
             deps.metrics?.inc("resume_ctx_not_persisted_total");
@@ -627,12 +647,14 @@ export function createResumeLegs(ctx) {
             if (created.existing) {
                 throw new Error(`wake fresh run: createRun observed an existing row for the freshly minted taskId ${freshId} (no idempotency key was sent) — refusing to treat it as a busy session`);
             }
+            if (created.sessionAbsent)
+                return rootSessionAbsentAnswer();
             if (!created.ok) {
                 return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
             }
-            const placementReject = await commitPlacement(deps, deps.runStore, freshId, undefined);
+            const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId: freshId }, execution);
             if (placementReject)
-                return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
+                return placementReject;
             taskId = freshId;
             freshRunClaimed = true;
         }
@@ -643,11 +665,12 @@ export function createResumeLegs(ctx) {
         if (deps.toolApproval && taskId) {
             const toolApproval = deps.toolApproval;
             resumeTaskConfig.onAsk = approvalLeg.unattended
-                ? toolApproval.boundUnattendedAsk({ owner: principal ?? null, taskId, sessionId }, approvalLeg.unattended)
+                ? toolApproval.boundUnattendedAsk({ owner: principal ?? null, taskId, sessionId, executionLane: execution.lane }, approvalLeg.unattended)
                 : toolApproval.boundAsk({
                     owner: principal ?? null,
                     taskId,
                     sessionId,
+                    executionLane: execution.lane,
                     ...(approvalLeg.active ? { legKey, ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}) } : {}),
                 });
         }
@@ -713,6 +736,11 @@ export function createResumeLegs(ctx) {
             claimedRow = freshRunClaimed ? true : await deps.runStore.markResuming(taskId, deps.instanceId ?? "default");
             if (!claimedRow)
                 return notResumableAnswer();
+            if (!freshRunClaimed) {
+                const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId }, execution);
+                if (placementReject)
+                    return placementReject;
+            }
             markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
             fleetPub?.onStart();
             const rs = deps.runStore;
@@ -1140,6 +1168,7 @@ export function createResumeLegs(ctx) {
                         owner: principal ?? null,
                         abortSignal: cancelCtrl.signal,
                         sessionId,
+                        executionLane: execution.lane,
                         emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
                         emitRevoke: (f) => approvalEmit(f),
                         legKey,
@@ -1328,7 +1357,7 @@ export function createResumeLegs(ctx) {
             const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
             const verifyRounds = verifyRoundsFromBody(ctx.body);
             const selectedGate = durableRowIdentity("decision-receipt", cp.checkpointId, token);
-            return await driveResumeIntoRunLog({ peerLease: resolved.peerLease, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, commitment: { kind: "gate_resolved", ...selectedGate }, verifyRounds, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+            return await driveResumeIntoRunLog({ peerLease: resolved.peerLease, execution: resolved.execution, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, commitment: { kind: "gate_resolved", ...selectedGate }, verifyRounds, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
         }
         finally {
             resolved.peerLease.release();
@@ -1367,9 +1396,9 @@ export function createResumeLegs(ctx) {
             return resolved.answer;
         try {
             const { spec, engineNotices } = resolved;
-            const hostSpec = { ...spec, objective, sessionId };
+            const hostSpec = { ...spec, objective };
             const out = await mintAndDriveDurableRun(routeCtxBase, deps.runStore, {
-                prepared: { spec: hostSpec, runner: runnerFor(hostSpec), auth, body: ctx.body, acceptance: createRunAcceptance({}, { objective }), peerLease: resolved.peerLease, ...(engineNotices.length > 0 ? { engineNotices } : {}) },
+                prepared: { spec: hostSpec, runner: runnerFor(hostSpec), auth, body: ctx.body, acceptance: createRunAcceptance({}, { objective }), peerLease: resolved.peerLease, execution: resolved.execution, ...(engineNotices.length > 0 ? { engineNotices } : {}) },
                 fleetScope: resumeFleetScope(req, auth),
                 elicitOwner: principal ?? null,
                 source: "workflow_parked_decide",
@@ -1455,6 +1484,7 @@ export function createResumeLegs(ctx) {
             const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
             return await driveResumeIntoRunLog({
                 peerLease: resolved.peerLease,
+                execution: resolved.execution,
                 runner: runnerFor(spec),
                 token,
                 sessionId: cp.sessionId,
@@ -1581,7 +1611,7 @@ export function createResumeLegs(ctx) {
                 hostDecision,
             };
             const selectedGate = durableRowIdentity("decision-receipt", cp.checkpointId, token);
-            const out = await driveResumeIntoRunLog({ peerLease: resolved.peerLease, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, commitment: { kind: "gate_resolved", ...selectedGate }, verifyRounds, resumeCtx: { sessionId, ctx: rebuildCtx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+            const out = await driveResumeIntoRunLog({ peerLease: resolved.peerLease, execution: resolved.execution, runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, commitment: { kind: "gate_resolved", ...selectedGate }, verifyRounds, resumeCtx: { sessionId, ctx: rebuildCtx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
             return out;
         }
         finally {

package/dist/http/route-ctx.d.ts

@@ -32,6 +32,7 @@ import type { VerifyRoundsSpec } from "./verify-rounds.js";
 import type { RunAbort } from "../run-cancel-context.js";
 import type { RunIdentity } from "../identity-source.js";
 import type { PeerLease } from "../peer-seat.js";
+import type { RootedTaskSpec } from "./execution-context.js";
 import type { GateCommitment, GateSettlementEvidence } from "../gate-settlement.js";
 /** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。
  *  [ref]:`cancelledViaVerb`(按 taskId 键控的「这次是取消动词」旁表)删除 —— 中止成因改挂在每条腿自己的
@@ -117,11 +118,13 @@ export interface RouteRequestState {
 /** B4①(命名化):`prepareSpec` 的返回形(tasks.ts/runs.ts 两域共同消费的属性面)——原为 6 成员内联匿名对象。
  *  命名后好处不只是过 B4 门:两个消费域现在都能对同一个符号做 `import type` 标注,而不是各自重推断结构。 */
 export interface PreparedTaskSubmission {
-    spec: TaskSpec;
+    /** 盖过根的 spec(`http/execution-context.ts` `stampSpecRoot` 是唯一写者):`sessionId` 恒在 = 这次提交的根会话。 */
+    spec: RootedTaskSpec;
     /** [ref]:本次提交的执行 Runner —— 场景 hands=none 时是无手孪生(不挂 executionEnvFactory)。
      *  两个消费域一律用它,不再直接摸 `deps.runner`(那正是「场景表态了、执行点没听」的缝)。 */
     runner: Runner;
-    auth?: RequestAuth;
+    /** authorizer 交出的身份与根(必填席,恒在;续跑家族的内部车道交它从 checkpoint 重建的那一只)。 */
+    auth: RequestAuth;
     verify?: VerifyRoundsSpec;
     cascade?: boolean;
     jobId?: string;
@@ -137,13 +140,11 @@ export interface PreparedTaskSubmission {
      */
     warnings?: readonly EntryProblem[];
     /**
-     * [ref](device lane 首绑写协议,design §4.3.2 两阶段 placement)—— **已校验、未写库**的 placement 意图。
-     *
-     * 缺席的两种含义都等价于「本腿没有 placement 要提交」:①本部署不是 device 车道(绝大多数);
-     * ②本腿不是 fresh 根提交(resume 家族根本不经 `prepareSpec`)。在场 ⇒ 每个 `runStore.createRun(`
-     * 成功点**必须**把它交给 `commitPlacement`(唯一写入属主;类级机器门钉住每个调用点都接了)。
+     * 这次执行的**执行上下文**(唯一解析器 `http/execution-context.ts` `resolveExecutionContext` 的产物:根 · 住客 · 放置态 · 车道 · device 车道的设备意图)。
+     * 提交门在装配之前铸(fresh);`/decide` 的宿主新 turn 交续跑折叠器铸的那一只(continuation)。每个 `runStore.createRun(` 成功点**必须**把它交给
+     * 认领之后的唯一写口 `commitExecutionContext`(类级机器门钉住每个调用点都接了)。
      */
-    bindingIntent?: import("./device-placement.js").DevicePlacementIntent;
+    execution: import("./execution-context.js").RootedExecutionContext;
     /**
      * 这次提交的**受理座**(`run-acceptance.ts`):标题器只在引擎受理之后起。提交门(`prepareSpec`)随 spec 一起铸;
      * 三条提交腿只喂它(持流的形逐帧 `observe`,终局落行之后 `settle` 一次),不再各自判「什么时候起标题」。
@@ -226,6 +227,11 @@ export interface WorkflowDecisionDelivery {
 /** B4①(命名化):`driveResumeIntoRunLog` 的入参形(resume 家族共用)——原为 9 成员内联匿名对象。 */
 export interface DriveResumeArgs {
     token: CheckpointToken;
+    /**
+     * 这条续跑的执行上下文(续跑折叠器经唯一解析器铸的 continuation 形:根 = checkpoint 的会话)。本腿认领之后(wake 的建行 / `markResuming` CAS 赢)
+     * 交给唯一写口 `commitExecutionContext`(按解析器那一读的住客再断言 writer(L) / absent 落格;住客换了 ⇒ 释放 + 404)。
+     */
+    execution: import("./execution-context.js").RootedExecutionContext;
     /**
      * 🔴 **[ref] 合并复审 F2 [high] —— 「本次续跑真正用的那个体」,由本腿在赢下 CAS 之后写回耐久层**
      * (验真后修;必填 —— `driveResumeIntoRunLog` 今天恰有**四个**调用点:legacy `/decide`(`resumeCheckpoint`)、

package/dist/http/routes/background.d.ts

@@ -1,7 +1,7 @@
 /**
  * [ref](core 7.32.0 [ref] 的 server 半场;wire 形 [ref] / [ref] / [ref] 定)—— **会话后台任务的两只读口**:
  *
- *   `GET  /v1/sessions/:id/background`        → 200 `{ rows: [{ id, description?, type, status, createdAt, sessionScoped, retained? }] }`
+ *   `GET  /v1/sessions/:id/background`        → 200 `{ rows: [{ id, description?, type, status, createdAt, sessionScoped, retained?, sessionId? }] }`
  *   `POST /v1/sessions/:id/background/stop`   body `{ includeRetained: boolean }` → 200 `{ receipts: [{ id, outcome }] }`
  *
  * 消费方:cli [ref] ①(删前核登记)/ [ref](退出三选一:「Exit and stop tasks」= `includeRetained:true`,`sema kill` =
@@ -28,6 +28,16 @@
  * oracle);显式 operator 可读可停任何会话(监督动作)。零模型工作 ⇒ 不进 billable、不吃 drain 503;停止口是 mutating ⇒
  * `rateLimited`。能力位 `background: { listFace, exitFaces }` 与两口的 501 从同一个谓词推导(会话属主面在场)。
  *
+ * ── 结清口:子代结清只有一只协调器 ─────────────────────────────────────────────────────────────────
+ * `POST /v1/sessions/:id/children/retire`(无体)→ 200 `{ children: string[] }`:**显式**结清以本会话为根的后台子代(running 停掉、parked
+ * 作废卡并对账翻终态),与 `DELETE /v1/sessions/:id` 同调**一只**预检 `probeSessionChildren` 与**一只**协调器 `retireSessionChildren`
+ * (`session-children-retire.ts`)、同一个 scope(`sessionChildrenScope`)。预检有本副本结束不了的 ⇒ 409 `conflict.session_children_alive{remaining}`
+ * (与删除门同码同投影,一只都不动);停不净(时序失败)⇒ 与删除门同一失败契约(通用 500,重试收敛)。`children` = 首轮观察到、且已全部
+ * 结清的子代,每项经名册的 id 投影 `rosterAgentId`(与换绑 / 导入两门 409 体的 `children` 同形同投影)。它不判根认领(停止口也不判):
+ * 根 run 活着时它可再派子代 —— 由换绑 / 导入门写事务内的认领读兜。鉴权 / 限流 / 无凭据写门与停止口同。
+ * **停止口的已发语义逐字不动**:它只中止 running 的后台 agent / workflow 并收 shell,停驻子代与待决卡留着 —— 「停别的、留卡待决」与
+ * 「把树结清」是两个意图、两只口。
+ *
  * 🔴 **停止口在无凭据写门内**(`credentialGated: ["POST"]`;车OL F1 = 7.102.0 合并复审 gpt-6 腿 [high]):门的两个合取项它都中
  *   —— ① 授权的唯一输入是 principal 头(属主判 `sessionOwnerOk` 与 operator 臂 `explicitOperatorOk` 读的都是 `gatedPrincipal`,
  *   无 service 凭证的部署上它收调用方自报的头);② 不可撤销、爆炸半径跨租户(知道会话 id + 自报它的属主 ⇒ 停掉那个会话的后台
@@ -53,12 +63,24 @@ export interface SessionBackgroundRow {
     createdAt: number;
     sessionScoped: boolean;
     retained?: true;
+    /** 后台 agent 行的子会话 id(引擎绑定之后才有;缺席 ⇒ 键不在)。 */
+    sessionId?: string;
 }
 /** 停止口的一条受据(`outcome` 逐字透传 core 闭集)。 */
 export interface SessionBackgroundReceipt {
     id: string;
     outcome: BackgroundShellHardKillReceipt["outcome"];
 }
+/** 结清口的路径(换绑 / 导入两门的子代半 409 以它点名下一步;与执行面拒体带 `forkPath` 同一形)。 */
+export declare function childrenRetirePath(sessionId: string): string;
+/**
+ * 子代半命中的拒体两键(换绑 409 `device.rebind_active_run`、导入 409 `session_active` 同一只):`children` = 预检那一次枚举观察到的活子代
+ * (`probeSessionChildren` 的 `liveChildren`)经名册 id 投影,`retirePath` = 结清口。
+ */
+export declare function liveChildrenRefusal(sessionId: string, liveChildren: readonly string[]): {
+    children: string[];
+    retirePath: string;
+};
 export declare function handleBackground(req: IncomingMessage, res: ServerResponse, match: RouteMatch<BackgroundRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const BACKGROUND_ROUTES: readonly [{
     readonly id: "session-background-list";
@@ -71,6 +93,12 @@ export declare const BACKGROUND_ROUTES: readonly [{
     readonly label: "/v1/sessions/:id/background/stop";
     readonly credentialGated: readonly ["POST"];
     readonly methods: readonly ["POST"];
+}, {
+    readonly id: "session-children-retire";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/children/retire";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
 }];
 /** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
 export type BackgroundRouteId = RouteIdsOf<typeof BACKGROUND_ROUTES>;

package/dist/http/routes/background.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { reapSessionBackgroundHard } from "../../background-session-reap.js";
+import { probeSessionChildren, retireSessionChildren, sessionChildrenScope, SessionChildrenStopIncompleteError } from "../../session-children-retire.js";
+import { rosterAgentId } from "./agents-roster.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
@@ -20,6 +22,7 @@ const ROW_KEY_DISPOSITION = {
     description: "keep",
     toolUseId: "strip",
     updatedAt: "strip",
+    sessionId: "keep",
 };
 void ROW_KEY_DISPOSITION;
 function projectRow(r) {
@@ -31,13 +34,20 @@ function projectRow(r) {
         createdAt: r.createdAt,
         sessionScoped: r.sessionScoped,
         ...(r.retained === true ? { retained: true } : {}),
+        ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
     };
 }
+export function childrenRetirePath(sessionId) {
+    return `/v1/sessions/${encodeURIComponent(sessionId)}/children/retire`;
+}
+export function liveChildrenRefusal(sessionId, liveChildren) {
+    return { children: liveChildren.map((handle) => rosterAgentId({ handle })), retirePath: childrenRetirePath(sessionId) };
+}
 const StopBodySchema = z.object({ includeRetained: z.boolean() }).strict();
 export async function handleBackground(req, res, match, ctx) {
     const { deps } = ctx;
     const id = match.decl.id;
-    if (id === "session-background-stop" && ctx.helpers.rateLimited(req, res))
+    if ((id === "session-background-stop" || id === "session-children-retire") && ctx.helpers.rateLimited(req, res))
         return;
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && principal === undefined) {
@@ -71,7 +81,7 @@ export async function handleBackground(req, res, match, ctx) {
     const operator = explicitOperatorOk(principal, deps.config);
     if (!operator && !ctx.helpers.sessionOwnerOk(req, res, await sessionOwnerCellOf(owned.sessionStorage, sessionId, owner)))
         return;
-    const scope = owner ?? "default";
+    const scope = sessionChildrenScope(owner);
     switch (id) {
         case "session-background-list": {
             const rows = defaultTaskRegistry.list({ owner: sessionId, sessionId, scope }, { limit: LIST_LIMIT }).map(projectRow);
@@ -83,6 +93,22 @@ export async function handleBackground(req, res, match, ctx) {
             sendJson(res, 200, { receipts: receipts.map((r) => ({ id: r.taskId, outcome: r.outcome })) });
             return;
         }
+        case "session-children-retire": {
+            const sources = { agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry };
+            const reach = await probeSessionChildren(sources, sessionId, scope);
+            if (!reach.reachable) {
+                deps.logger?.warn("session_children_retire_unreachable", { sessionId, remaining: reach.unreachableHandles.length, handles: reach.unreachableHandles });
+                sendError(res, 409, "conflict.session_children_alive", "this session still has background agents running where this replica cannot stop them (on another replica, for example), so nothing was retired — `remaining` lists their ids (the same ids `GET /v1/agents/roster` shows); retry once they finish, or stop them where they run", { remaining: reach.unreachableHandles.map((handle) => rosterAgentId({ handle })) });
+                return;
+            }
+            const out = await retireSessionChildren(sources, sessionId, scope);
+            if (out.stopped === "incomplete") {
+                deps.logger?.warn("session_children_retire_incomplete", { sessionId, remaining: out.remainingHandles.length, handles: out.remainingHandles });
+                throw new SessionChildrenStopIncompleteError(sessionId, out.remainingHandles.length);
+            }
+            sendJson(res, 200, { children: out.observed.map((handle) => rosterAgentId({ handle })) });
+            return;
+        }
         default:
             return assertNever(id);
     }
@@ -90,5 +116,6 @@ export async function handleBackground(req, res, match, ctx) {
 export const BACKGROUND_ROUTES = [
     { id: "session-background-list", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background$/, label: "/v1/sessions/:id/background", methods: ["GET"] },
     { id: "session-background-stop", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/background\/stop$/, label: "/v1/sessions/:id/background/stop", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "session-children-retire", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/children\/retire$/, label: "/v1/sessions/:id/children/retire", credentialGated: ["POST"], methods: ["POST"] },
 ];
 //# sourceMappingURL=background.js.map

package/dist/http/routes/devices.d.ts

@@ -8,19 +8,19 @@
  *     **hub 在场性**判 —— v1 部署形 = 单副本(基线稿 §4.6),汇聚端的活连接集就是本副本的 presence
  *     真源;`name` = displayName,空串诚实缺席;`lastSeenAt` ISO-8601)。**吊销行不列**:revoked 是
  *     终态(重注册 = 新 deviceId),列出来只会被壳当换绑目标然后撞 404。
- *   · `GET  /v1/devices/sessions/:rootSessionId` —— S-4 绑定读面(壳换绑 UX 的全部材料):
- *     `{ rootSessionId, boundDevice: { deviceId, rev, boundAt } }`。稿 §4 允许「并入 session 读面」或
- *     「独立读面」两形,选**独立读面**:sessions 的 GET 面承诺「无参请求字节不变」(routes/sessions.ts
- *     的 additive contract 注),且 audit 投影由 boot/session-faces 组装、不持 device 店 —— 并入即跨
- *     装配缝加一次店读;独立读面把 device wire 族收在一个文件里,户口与门序自洽。
- *   · `POST /v1/devices/sessions/:rootSessionId/rebind` —— 显式换绑动词(v2 稿 §2 门序五步,逐字):
- *     ① gatedPrincipal + owner 门(非属主 404 反枚举同串,[ref] 纪律)
+ *   · 绑定读面在会话族:`GET /v1/sessions/:id/execution-placement`(`routes/sessions.ts`;体 = 执行放置格的 wire 投影,
+ *     device 车道上是 `{ role: "writer", lane: "device", device: { deviceId, rev } }`)。绑定是根会话行上的执行格,读只有会话店的执行席一只。
+ *   · `POST /v1/devices/sessions/:rootSessionId/rebind` —— 显式换绑动词(v2 稿 §2 门序五步):
+ *     ① gatedPrincipal + owner 门 —— 一次行读(会话店执行席:住客 + 格),属主门判**格上**两属主列(非属主 404 反枚举同串,[ref] 纪律)
  *     ② 目标设备在场门(不存在 / 不是该域的 / 已吊销 ⇒ 404 **同串** —— 设备 id 也是不可枚举面)
- *     ③ 无活跃 run 门(**CAS 前判、CAS 语句不兼职**;durable 判据 = run store 的 session claim
- *        `getActiveTaskId`,hub 内存在途计数不作门 —— 内存态跨副本不可见;拒 = 409
- *        `device.rebind_active_run` 体带 `activeTaskId`)
- *     ④ 前态 CAS(店内单事务:`rev` 恒变列 + `session_rebound` 审计行;输 = 409
- *        `device.rebind_rev_conflict` 体带 `currentRev` —— [ref] currentPending 哲学,壳一跳重定位)
+ *     ③ 无活跃 run 门:池级 `getActiveTaskId` 读一次作**早拒**(零审计行);**保证**在设备店的换绑事务里 —— 同一连接先锁根会话行、
+ *        再锁定读 `task_active`,有认领 ⇒ 不写(读写序律;hub 内存在途计数不作门 —— 内存态跨副本不可见);两处同拒 409
+ *        `device.rebind_active_run` 体带 `activeTaskId`
+ *     ③′ 子代半(写前一次观察):以根为根的活后台子代(running / parked;`probeSessionChildren` 那一次枚举,scope = 会话属主 `sessionChildrenScope`,
+ *        与删除门同读)⇒ 同码 409,体 `children`(名册 id)+ `retirePath`(显式结清口 —— 先结清、再换绑)
+ *     ④ 前态 CAS(店内单事务:按门那一读的住客 ∧ 格上两属主列 ∧ rev 定址,`execution_rev` 恒变列 + `session_rebound` 审计行;输 = 409
+ *        `device.rebind_rev_conflict` 体带 `currentRev` —— [ref] currentPending 哲学,壳一跳重定位;门后会话被删并同 id 重登记 ⇒ 住客不符 ⇒ 设备 404,
+ *        永不写到新住客的格上)
  *     ⑤ 赢 = 200 `{ rootSessionId, deviceId, rev, workspaceCarryover: "none" }`。
  *     幂等形:toDeviceId ≡ 当前 ∧ expectedRev ≡ 当前 rev ⇒ 200 回显不加 rev(真幂等,不写审计)。
  *     `workspaceCarryover: "none"` 是 **wire 冻结字面**(v2 稿 §5):换绑只改路由,不搬字节 —— 壳据
@@ -34,7 +34,7 @@
  * 才构成一个 device 域;缺 tenant claim 的凭据(纯 principal 头 / 静态 token 直连)**判不出域** ⇒
  * 非 operator 一律响亮 403(fail-closed + loud,[ref]:静默空列表是假健康)——基线稿对 enrollment 的
  * 同向裁定是「缺 tenant/global scope 明确拒注册」。enrollment/管理端点与**首绑写协议**都从
- * 这同一个函数取域([ref] 起它住在 `http/device-placement.ts` —— 提交腿也要用,放在路由域里是层序倒挂),
+ * 这同一个函数取域(它住在 `http/execution-context.ts` —— 提交腿的设备准入也要用,放在路由域里是层序倒挂),
  * 不得手抄第二份派生。
  *
  * ── 反枚举 404 的单一铸造点 ──────────────────────────────────────────────────────────────────────
@@ -81,12 +81,6 @@ export declare const DEVICES_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/devices/sessions/:id/rebind";
     readonly methods: readonly ["POST"];
-}, {
-    readonly id: "device-session";
-    readonly pattern: RegExp;
-    readonly label: "/v1/devices/sessions/:id";
-    readonly credentialGated: readonly ["GET"];
-    readonly methods: readonly ["GET"];
 }, {
     readonly prefix: "/v1/devices/";
     readonly credentialGated: readonly ["POST"];

package/dist/http/routes/devices.js

@@ -3,8 +3,12 @@ import { explicitOperatorOk, gatedPrincipal, sendPrincipalRefusal } from "../pri
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { DEVICE_PLATFORM_OS, DEVICE_PUBKEY_MAX_BYTES, DEVICE_TEXT_LIMITS, assertDeviceIdShape, assertDevicePubkeyShape, assertRootSessionIdShape, isDeviceAbsolutePath, sameDeviceOwner, } from "../../device-store.js";
+import { boundDeviceOf } from "../../execution-placement.js";
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { probeSessionChildren, sessionChildrenScope } from "../../session-children-retire.js";
+import { liveChildrenRefusal } from "./background.js";
 import { DEFAULT_ENROLL_TOKEN_TTL_SEC } from "../../device-enrollment.js";
-import { deviceOwnerDomainOf } from "../device-placement.js";
+import { deviceOwnerDomainOf } from "../execution-context.js";
 import { echoKeyName } from "../../request-key-closure.js";
 const DEVICE_NOT_FOUND_MESSAGE = "device not found";
 const NO_DEVICE_DOMAIN_MESSAGE = "device management needs a caller domain: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`) and is not an explicit operator — connect through the registry auth bridge, or configure OPERATOR_PRINCIPALS";
@@ -32,9 +36,6 @@ function deviceListRow(row, online) {
         ...(row.lastSeenAtMs !== null ? { lastSeenAt: new Date(row.lastSeenAtMs).toISOString() } : {}),
     };
 }
-function boundDeviceOf(row) {
-    return { deviceId: row.deviceId, rev: row.rev, boundAt: new Date(row.boundAtMs).toISOString() };
-}
 function sendDeviceRejection(res, rej) {
     if (rej.retryAfterSec !== undefined)
         res.setHeader("retry-after", String(rej.retryAfterSec));
@@ -112,7 +113,6 @@ function parseEnrollBody(res, body) {
 export async function handleDevices(req, res, match, ctx) {
     switch (match.decl.id) {
         case "devices-list":
-        case "device-session":
         case "device-session-rebind":
         case "device-enroll-tokens":
         case "device-enroll":
@@ -248,31 +248,19 @@ export async function handleDevices(req, res, match, ctx) {
         return;
     }
     const rootSessionId = decoded;
-    if (match.decl.id === "device-session") {
-        if (!operator && domain === undefined) {
-            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
-            return;
-        }
-        const binding = await store.getSessionBinding(rootSessionId);
-        if (!binding || (!operator && !sameDeviceOwner(binding.owner, domain))) {
-            sendDeviceNotFound(res);
-            return;
-        }
-        sendJson(res, 200, { rootSessionId, boundDevice: boundDeviceOf(binding) });
-        return;
-    }
     if (!operator && domain === undefined) {
         sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
         return;
     }
-    const binding = await store.getSessionBinding(rootSessionId);
-    if (!binding || (!operator && !sameDeviceOwner(binding.owner, domain))) {
+    const placement = await enrollment.readPlacement(rootSessionId);
+    const binding = placement === undefined ? undefined : boundDeviceOf(placement.cell);
+    if (placement === undefined || !binding || (!operator && !sameDeviceOwner(binding.owner, domain))) {
         sendDeviceNotFound(res);
         return;
     }
     const body = (await readJson(req));
     if (typeof body !== "object" || body === null || typeof body.toDeviceId !== "string" || body.expectedRev === undefined) {
-        sendError(res, 400, "request.body_shape", "body must be { toDeviceId: string, expectedRev: number } — expectedRev is the binding rev read from GET /v1/devices/sessions/{rootSessionId} (explicit prior state; two concurrent operators must not silently stomp each other)");
+        sendError(res, 400, "request.body_shape", "body must be { toDeviceId: string, expectedRev: number } — expectedRev is the device rev read from GET /v1/sessions/{sessionId}/execution-placement (explicit prior state; two concurrent operators must not silently stomp each other)");
         return;
     }
     if (typeof body.expectedRev !== "number" || !Number.isInteger(body.expectedRev) || body.expectedRev < 0) {
@@ -295,16 +283,24 @@ export async function handleDevices(req, res, match, ctx) {
         sendError(res, 409, "device.rebind_active_run", "this session has a non-terminal run — rebinding now would leave in-flight work addressed at another workspace; cancel the run (or let it finish), then retry", { activeTaskId });
         return;
     }
-    const result = await store.rebindSession({ rootSessionId, toDeviceId, expectedRev, owner: binding.owner });
+    const tree = await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, rootSessionId, sessionChildrenScope(placement.occupant.owner));
+    if (tree.liveChildren.length > 0) {
+        sendError(res, 409, "device.rebind_active_run", "this session still has background agents running or waiting on an approval under it — rebinding now would leave them addressed at the old device; retire them (POST retirePath) or let them finish, then retry", liveChildrenRefusal(rootSessionId, tree.liveChildren));
+        return;
+    }
+    const result = await store.rebindDeviceExecution({ root: rootSessionId, occupant: placement.occupant, owner: binding.owner, expectedRev, targetDeviceId: toDeviceId });
     switch (result.outcome) {
         case "rebound":
         case "idempotent":
-            sendJson(res, 200, { rootSessionId, deviceId: result.row.deviceId, rev: result.row.rev, workspaceCarryover: "none" });
+            sendJson(res, 200, { rootSessionId, deviceId: result.device.id, rev: result.device.rev, workspaceCarryover: "none" });
             return;
         case "rev_conflict":
-            sendError(res, 409, "device.rebind_rev_conflict", "expectedRev does not match the binding's current rev — the session↔device binding changed since it was read; re-read it and retry with currentRev", { currentRev: result.row.rev });
+            sendError(res, 409, "device.rebind_rev_conflict", "expectedRev does not match the binding's current rev — the session↔device binding changed since it was read; re-read it and retry with currentRev", { currentRev: result.device.rev });
+            return;
+        case "active_run":
+            sendError(res, 409, "device.rebind_active_run", "this session has a non-terminal run — rebinding now would leave in-flight work addressed at another workspace; cancel the run (or let it finish), then retry", { activeTaskId: result.activeTaskId });
             return;
-        case "binding_not_found":
+        case "gone":
         case "device_not_found":
             sendDeviceNotFound(res);
             return;
@@ -321,7 +317,6 @@ export const DEVICES_ROUTES = [
     { id: "device-enroll", path: "/v1/devices/enroll", credentialGated: ["POST"], methods: ["POST"] },
     { id: "device-revoke", pattern: /^\/v1\/devices\/(?<deviceId>[^/]+)\/revoke$/, label: "/v1/devices/:deviceId/revoke", methods: ["POST"] },
     { id: "device-session-rebind", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)\/rebind$/, label: "/v1/devices/sessions/:id/rebind", methods: ["POST"] },
-    { id: "device-session", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)$/, label: "/v1/devices/sessions/:id", credentialGated: ["GET"], methods: ["GET"] },
     { prefix: "/v1/devices/", credentialGated: ["POST"] },
 ];
 //# sourceMappingURL=devices.js.map