@sema-agent/server 7.138.0 → 7.140.0

package/dist/device-store.d.ts

@@ -1,3 +1,5 @@
+import type { DeviceBindOutcome, DeviceRebindOutcome, InMemoryExecutionPlacementSeat } from "./execution-placement.js";
+import type { SessionFace } from "./session-incarnation.js";
 /**
  * device lane 的 HTTP 错误码闭集(v2 §4.8 逐字)。**唯一导出点** —— 端点车(A-3/车C)从这里取,
  * 禁在路由里手抄字面量(§4.8 task-R1-12:「下表即闭集全集,禁四份手抄」)。
@@ -33,7 +35,7 @@ export declare const DEVICE_ERROR_CODES: {
      *  (管理面,`http/routes/devices.ts`);adapter/准入链结构上不产它。 */
     readonly REBIND_REV_CONFLICT: "device.rebind_rev_conflict";
     /** O4 换绑动词(v2 稿 §2 步 4):该根会话名下有非终态 run(durable 判据 = run store 的 session
-     *  claim;hub 内存在途计数**不作门**——跨副本不可见)—— 体带 `activeTaskId`。铸造点同上一条。 */
+     *  claim;hub 内存在途计数**不作门**——跨副本不可见;保证 = 设备店换绑事务内锁根行后那一读,池级读只作早拒)—— 体带 `activeTaskId`。铸造点同上一条。 */
     readonly REBIND_ACTIVE_RUN: "device.rebind_active_run";
 };
 /** {@link DEVICE_ERROR_CODES} 的值联合 —— 闭集(未知码 = 编译错误,[ref] 词表纪律)。 */
@@ -113,14 +115,6 @@ export interface DeviceRow {
     createdAtMs: number;
     rev: number;
 }
-export interface DeviceSessionRow {
-    /** 键 = **根**会话(task-R1-3:后代继承不另绑)。 */
-    rootSessionId: string;
-    deviceId: string;
-    owner: DeviceOwner;
-    boundAtMs: number;
-    rev: number;
-}
 export interface DeviceAuditRow {
     id: number;
     atMs: number;
@@ -147,7 +141,7 @@ export interface DeviceEnrollTokenRow {
 export declare const DEVICE_KEY_MAX_BYTES = 190;
 /** `device_id` 列宽(`dev_` + 26 位 Crockford base32 ULID = 30 字节,64 是三倍余量)。 */
 export declare const DEVICE_ID_MAX_BYTES = 64;
-/** `root_session_id` 列宽(提交入口硬拒 >64 的 sessionId,128 留一倍余量)。 */
+/** 根会话 id 的形门上界(换绑路由的路径段;会话行 `session_id` 宽 64,提交入口硬拒 >64 的 sessionId,128 留一倍余量 —— 超宽的 id 等值读不到任何行)。 */
 export declare const DEVICE_SESSION_ID_MAX_BYTES = 128;
 /** `pubkey` / `token_hash` 列宽(Ed25519 b64 = 44,sha256 hex = 64)。 */
 export declare const DEVICE_PUBKEY_MAX_BYTES = 128;
@@ -176,10 +170,12 @@ export declare function assertDevicePubkeyShape(pubkey: string): void;
 export declare function assertNewDeviceShape(input: NewDeviceInput): void;
 export declare function assertIssueTokenShape(input: IssueEnrollTokenInput): void;
 export declare function assertRevokeShape(input: RevokeDeviceInput): void;
+/** device 首绑入参的整形门(三形共用:内存参照实现与两方言从同一处过)。 */
+export declare function assertPlaceDeviceShape(input: PlaceDeviceExecutionInput): void;
 /** O4 换绑入参的整形门(三形共用)。`expectedRev` 收窄为非负整数:它要进 SQL 等值谓词,小数/负数/NaN
  *  在两方言的 BIGINT 比对下不是「不匹配」而是各自的隐式转换歧义面 —— 在门口拒,方言分歧面消失。
  *  ⚠️ HTTP 层对坏形先答 400(业务拒绝);这里的抛是**编程/装配错误**的兜底,不是 wire 分支。 */
-export declare function assertRebindShape(input: RebindSessionInput): void;
+export declare function assertRebindShape(input: RebindDeviceExecutionInput): void;
 export declare function assertAcquireShape(input: AcquireConnectionInput): void;
 /** token 摘要必须是**规范形**(小写 sha256 hex):大小写混形在 VARBINARY/COLLATE "C" 下是两个键,
  *  于是同一个明文 token 能被消费两次 —— 这是 §7-T5 ③「一次性 CAS」的直接跳过面。 */
@@ -268,73 +264,53 @@ export type ConsumeEnrollTokenResult =
  | {
     outcome: "pubkey_taken";
 };
-export interface BindSessionInput {
-    rootSessionId: string;
-    deviceId: string;
-    /** 验证过的复合身份;与 devices 行的 owner 在**同一事务**内比对(§4.3.2 首绑)。 */
-    owner: DeviceOwner;
-}
-/** §4.3.2 首绑协议的判别式结果 —— 并发争抢**单赢家,无未定义态**。 */
-export type BindSessionResult = {
-    outcome: "bound";
-    row: DeviceSessionRow;
-}
-/** 并发输家或重试,但绑的是**同一台**设备 ⇒ 幂等成功。 */
- | {
-    outcome: "idempotent";
-    row: DeviceSessionRow;
-}
-/** 根会话已绑**另一台**设备(或另一个 owner)⇒ `device.claim_conflict`。 */
- | {
-    outcome: "conflict";
-    row: DeviceSessionRow;
+/**
+ * device 车道的**首绑**(§4.3.2;认领之后的初始放置写,§3.3 转换表 place / bind 两行):根会话行上这一位住客的执行格
+ * absent → writer(device, D),或迁移回填的 writer(device, ∅) → writer(device, D)。绑定**住在会话行上**(唯一载体;
+ * 列与语句的属主 = `plugins/execution-placement-sql.ts`),本店只负责「设备行判 + 写格」同一事务(锁序:设备行 → 根 `session_meta`)。
+ */
+export interface PlaceDeviceExecutionInput {
+    /** 根会话(放置键;后代继承,不另绑)。 */
+    readonly root: string;
+    /** 意图那一读的住客(会话店执行席 `seat.read(root)` 交出的那一位)—— 写按住客谓词定址:住客换了 ⇒ `gone`,永不写到新住客身上。 */
+    readonly occupant: SessionFace;
+    readonly deviceId: string;
+    /** 验证过的复合身份;与设备行的 owner 在**同一事务**内比对,写进格的两属主列(绑定属主 = 设备属主)。 */
+    readonly owner: DeviceOwner;
 }
-/** 设备不存在**或**不是请求方的 —— 反枚举同形(见文件头注)。 */
- | {
-    outcome: "device_not_found";
+/**
+ * 首绑的判别式结果 —— 并发争抢**单赢家,无未定义态**。格的那几臂与判官同一张表(`DeviceBindOutcome`:`bound` / 同设备 `same`(幂等成功)/
+ * 异设备 `device_conflict` / 异车道 `tree_bound` / `mirror` / 住客不是判过的那一位或行不在 `gone`),外加设备行的两臂:
+ * 设备不存在**或**不是请求方的(反枚举同形,见文件头注)/ 已吊销。
+ */
+export type PlaceDeviceExecutionResult = DeviceBindOutcome | {
+    readonly outcome: "device_not_found";
 } | {
-    outcome: "device_revoked";
+    readonly outcome: "device_revoked";
 };
 /**
- * O4 显式换绑(2026-08-30 v2 稿 §2)。`owner` = **绑定行的**复合身份(HTTP 层已裁决:属主同域或
- * explicit operator;operator 代操作时传的也是行的 owner,不是操作员自己)——店内所有谓词恒带它,
- * 判别位在店里就消失(反枚举,文件头注)。`expectedRev` = 壳从 S-4 读面拿到的前态(强制显式,
- * 防两操作员并发换绑互踩)。
+ * O4 显式换绑(2026-08-30 v2 稿 §2;§3.3 转换表 rebind 行)。`occupant` = 换绑门那一读的住客;`owner` = 门判过的**格上**两属主列
+ * (HTTP 层已裁决:属主同域或 explicit operator;operator 代操作时传的也是格上的 owner,不是操作员自己)——店内所有谓词恒带它,
+ * 判别位在店里就消失(反枚举,文件头注)。`expectedRev` = 壳从执行放置读面拿到的前态(强制显式,防两操作员并发换绑互踩)。
  */
-export interface RebindSessionInput {
-    rootSessionId: string;
-    toDeviceId: string;
-    expectedRev: number;
-    owner: DeviceOwner;
+export interface RebindDeviceExecutionInput {
+    readonly root: string;
+    readonly occupant: SessionFace;
+    readonly owner: DeviceOwner;
+    readonly expectedRev: number;
+    readonly targetDeviceId: string;
 }
 /**
- * O4 换绑的判别式结果(门序 = v2 稿 §2:目标设备在场 → 幂等短路 → 前态 CAS → 审计;活跃 run 门在
- * **HTTP 层**、CAS 之前判 —— run store 是另一只店,CAS 语句不兼职)。
+ * O4 换绑的判别式结果(门序 = v2 稿 §2 + 读写序律:目标设备在场 → 锁根行读认领 → 幂等短路 → 前态 CAS → 审计)。格的那几臂与判官同一张表
+ * (`DeviceRebindOutcome`:`rebound` 带被换下的那台 / 真幂等 `idempotent` / 前态输 `rev_conflict` 携当前格 / `gone` = 行不在、住客换了、不是 writer(device, D)、
+ * 或绑定属主不是判过的那一位 —— 反枚举同形),外加:目标设备不在 / 不是该 owner 的 / **已吊销**(三臂同折 404;吊销不单列 = 判别位在店里就消失);
+ * 写事务内锁根行后读到认领 `active_run`(SQL 后端;读写序律只在 SQL 后端立 —— 内存参照实现没有认领表,答不出这一臂,内存走廊的认领判据是路由的早拒)。
  */
-export type RebindSessionResult = 
-/** CAS 赢家:`rev+1` + `bound_at` 刷新 + `session_rebound` 审计行**同一事务**提交。 */
-{
-    outcome: "rebound";
-    row: DeviceSessionRow;
-}
-/** 真幂等:`toDeviceId` ≡ 当前绑定 ∧ `expectedRev` ≡ 当前 rev ⇒ 回显不加 rev、不写审计。 */
- | {
-    outcome: "idempotent";
-    row: DeviceSessionRow;
-}
-/** 前态输(rev 不符,含「toDeviceId 同但 rev 错」——前态错就是错)⇒ 携当前行供壳一跳重定位。 */
- | {
-    outcome: "rev_conflict";
-    row: DeviceSessionRow;
-}
-/** 绑定行不在**或**不是该 owner 的 —— 反枚举同形(HTTP 层折 404 同串)。 */
- | {
-    outcome: "binding_not_found";
-}
-/** 目标设备不在 / 不是该 owner 的 / **已吊销** —— v2 稿 §2 步 2:三臂同折 404(设备 id 也是
- *  不可枚举面);吊销不单列 = 判别位在店里就消失,消费层想泄也泄不出来。 */
- | {
-    outcome: "device_not_found";
+export type RebindDeviceExecutionResult = DeviceRebindOutcome | {
+    readonly outcome: "device_not_found";
+} | {
+    readonly outcome: "active_run";
+    readonly activeTaskId: string;
 };
 export interface RevokeDeviceInput {
     deviceId: string;
@@ -415,14 +391,10 @@ export interface DeviceStore {
     /** 世代谓词命中 = true;0 行 = 已失权。 */
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
-    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
-    /** O4 显式换绑(v2 稿 §2 步 2/3/5):目标设备门 + 前态 CAS + `session_rebound` 审计行同一事务。
-     *  活跃 run 门**不在这里**(run store 是另一只店)—— 由 HTTP 层在调用前判(v2 稿 §2 步 4)。 */
-    rebindSession(input: RebindSessionInput): Promise<RebindSessionResult>;
-    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
-    /** purge coordinator 座(§6 注②:core 的会话删除是**逐 store 显式调用**,不是 DB 自动扫;
-     *  只建表不接 purge = 删会话后绑定残留 ⇒ sessionId 重用致旧设备粘连/claim conflict/隐私残留)。 */
-    deleteByRootSession(rootSessionId: string): Promise<number>;
+    /** 首绑(认领之后的初始放置写):设备行判(active ∧ 属主)+ 写格同一事务,按住客谓词定址。 */
+    placeDeviceExecution(input: PlaceDeviceExecutionInput): Promise<PlaceDeviceExecutionResult>;
+    /** O4 显式换绑(v2 稿 §2 步 2/3/5):目标设备门 + 写事务内锁根行读认领 + 前态 CAS + `session_rebound` 审计行同一事务。 */
+    rebindDeviceExecution(input: RebindDeviceExecutionInput): Promise<RebindDeviceExecutionResult>;
     appendAudit(input: AppendAuditInput): Promise<void>;
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }
@@ -432,15 +404,19 @@ declare function cloneOwner(o: DeviceOwner): DeviceOwner;
  * 语义 oracle。**单线程 JS 的原子性**替代 SQL 事务:每个方法体内没有 `await`(除了返回值),所以
  * 「读-判-写」在事件循环上不可分割 —— 与 SQL 侧的单事务 CAS 语义等价,这也是为什么并发格
  * (两个并发消费同一 token)在这一形上必须给出与真库**同一个**赢家/输家分布。
+ *
+ * 绑定不在本店:它是会话行上的执行格。构造**必收**测试走廊的会话行 {@link InMemoryExecutionPlacementSeat}(同为参照实现,生产零引用)——
+ * 首绑 / 换绑在它上面做(判官与 SQL 语句模块同一组),读者经同一只席的 `read(root)` 读。
  */
 export declare class InMemoryDeviceStore implements DeviceStore {
     private readonly devices;
-    private readonly sessions;
     private readonly tokens;
     private readonly audit;
     private auditSeq;
     private readonly now;
-    constructor(opts?: {
+    private readonly seat;
+    constructor(opts: {
+        seat: InMemoryExecutionPlacementSeat;
         now?: () => number;
     });
     issueEnrollToken(input: IssueEnrollTokenInput): Promise<DeviceEnrollTokenRow>;
@@ -454,17 +430,14 @@ export declare class InMemoryDeviceStore implements DeviceStore {
     acquireConnection(input: AcquireConnectionInput): Promise<AcquireConnectionResult>;
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
-    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
-    rebindSession(input: RebindSessionInput): Promise<RebindSessionResult>;
-    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
-    deleteByRootSession(rootSessionId: string): Promise<number>;
+    placeDeviceExecution(input: PlaceDeviceExecutionInput): Promise<PlaceDeviceExecutionResult>;
+    rebindDeviceExecution(input: RebindDeviceExecutionInput): Promise<RebindDeviceExecutionResult>;
     appendAudit(input: AppendAuditInput): Promise<void>;
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
     private isOnline;
     private pushAudit;
     /** 返回**拷贝**:调用方拿到的行改了也不能污染店内状态(SQL 侧天然如此,InMemory 必须显式做)。 */
     private snapshotDevice;
-    private snapshotSession;
 }
 export { sameOwner as sameDeviceOwner, cloneOwner as cloneDeviceOwner };
 //# sourceMappingURL=device-store.d.ts.map

package/dist/device-store.js

@@ -123,9 +123,14 @@ export function assertRevokeShape(input) {
     assertBoundedText("revokedBy", input.revokedBy, DEVICE_TEXT_LIMITS.actor);
     assertBoundedText("revokeReason", input.reason ?? "", DEVICE_TEXT_LIMITS.revokeReason);
 }
+export function assertPlaceDeviceShape(input) {
+    assertRootSessionIdShape(input.root);
+    assertDeviceIdShape(input.deviceId);
+    assertDeviceOwnerShape(input.owner);
+}
 export function assertRebindShape(input) {
-    assertRootSessionIdShape(input.rootSessionId);
-    assertDeviceIdShape(input.toDeviceId);
+    assertRootSessionIdShape(input.root);
+    assertDeviceIdShape(input.targetDeviceId);
     assertDeviceOwnerShape(input.owner);
     if (!Number.isInteger(input.expectedRev) || input.expectedRev < 0) {
         throw new Error(`device-store: expectedRev must be a non-negative integer (got ${input.expectedRev}) — it enters a byte-exact BIGINT equality predicate`);
@@ -194,13 +199,14 @@ function cloneOwner(o) {
 }
 export class InMemoryDeviceStore {
     devices = new Map();
-    sessions = new Map();
     tokens = new Map();
     audit = [];
     auditSeq = 0;
     now;
+    seat;
     constructor(opts) {
-        this.now = opts?.now ?? (() => Date.now());
+        this.seat = opts.seat;
+        this.now = opts.now ?? (() => Date.now());
     }
     async issueEnrollToken(input) {
         assertIssueTokenShape(input);
@@ -361,57 +367,24 @@ export class InMemoryDeviceStore {
         row.rev += 1;
         return true;
     }
-    async bindSession(input) {
-        assertRootSessionIdShape(input.rootSessionId);
-        assertDeviceIdShape(input.deviceId);
-        assertDeviceOwnerShape(input.owner);
+    async placeDeviceExecution(input) {
+        assertPlaceDeviceShape(input);
         const device = this.devices.get(input.deviceId);
         if (!device || !sameOwner(device.owner, input.owner))
             return { outcome: "device_not_found" };
         if (device.status !== "active")
             return { outcome: "device_revoked" };
-        const existing = this.sessions.get(input.rootSessionId);
-        if (existing) {
-            const same = existing.deviceId === input.deviceId && sameOwner(existing.owner, input.owner);
-            return { outcome: same ? "idempotent" : "conflict", row: this.snapshotSession(existing) };
-        }
-        const row = {
-            rootSessionId: input.rootSessionId,
-            deviceId: input.deviceId,
-            owner: cloneOwner(input.owner),
-            boundAtMs: this.now(),
-            rev: 0,
-        };
-        this.sessions.set(row.rootSessionId, row);
-        return { outcome: "bound", row: this.snapshotSession(row) };
+        return this.seat.bindDevice(input.root, input.occupant, { id: input.deviceId, owner: cloneOwner(input.owner) }, new Date(this.now()).toISOString());
     }
-    async rebindSession(input) {
+    async rebindDeviceExecution(input) {
         assertRebindShape(input);
-        const device = this.devices.get(input.toDeviceId);
+        const device = this.devices.get(input.targetDeviceId);
         if (!device || !sameOwner(device.owner, input.owner) || device.status !== "active")
             return { outcome: "device_not_found" };
-        const row = this.sessions.get(input.rootSessionId);
-        if (!row || !sameOwner(row.owner, input.owner))
-            return { outcome: "binding_not_found" };
-        if (row.deviceId === input.toDeviceId && row.rev === input.expectedRev)
-            return { outcome: "idempotent", row: this.snapshotSession(row) };
-        if (row.rev !== input.expectedRev)
-            return { outcome: "rev_conflict", row: this.snapshotSession(row) };
-        const from = row.deviceId;
-        row.deviceId = input.toDeviceId;
-        row.boundAtMs = this.now();
-        row.rev += 1;
-        this.pushAudit({ event: "session_rebound", deviceId: input.toDeviceId, owner: row.owner, detail: { from, to: input.toDeviceId, rev: row.rev } });
-        return { outcome: "rebound", row: this.snapshotSession(row) };
-    }
-    async getSessionBinding(rootSessionId) {
-        assertRootSessionIdShape(rootSessionId);
-        const row = this.sessions.get(rootSessionId);
-        return row ? this.snapshotSession(row) : null;
-    }
-    async deleteByRootSession(rootSessionId) {
-        assertRootSessionIdShape(rootSessionId);
-        return this.sessions.delete(rootSessionId) ? 1 : 0;
+        const out = this.seat.rebindDevice(input.root, input.occupant, cloneOwner(input.owner), input.expectedRev, input.targetDeviceId, new Date(this.now()).toISOString());
+        if (out.outcome === "rebound")
+            this.pushAudit({ event: "session_rebound", deviceId: input.targetDeviceId, owner: input.owner, detail: { from: out.from, to: input.targetDeviceId, rev: out.device.rev } });
+        return out;
     }
     async appendAudit(input) {
         this.pushAudit(input);
@@ -440,9 +413,6 @@ export class InMemoryDeviceStore {
     snapshotDevice(row) {
         return { ...row, owner: cloneOwner(row.owner) };
     }
-    snapshotSession(row) {
-        return { ...row, owner: cloneOwner(row.owner) };
-    }
 }
 export { sameOwner as sameDeviceOwner, cloneOwner as cloneDeviceOwner };
 //# sourceMappingURL=device-store.js.map

package/dist/device-ws-hub.js

@@ -832,7 +832,8 @@ export function createDeviceWsHub(options) {
             return { kind: "rejected", reject: rejection(DEVICE_DRAINING_CODE, "this device hub is closed for shutdown — the instruction was never dispatched (safe to retry once the device reconnects on a replacement replica)", DRAIN_RETRY_AFTER_SEC) };
         if (draining)
             return drainingRejectResult();
-        const admitted = await enrollment.admitSession({ rootSessionId: input.rootSessionId, requester: input.requester });
+        const placement = await enrollment.readPlacement(input.rootSessionId);
+        const admitted = await enrollment.admitSession({ rootSessionId: input.rootSessionId, placement, requester: input.requester });
         if (!admitted.ok)
             return { kind: "rejected", reject: admitted.reject };
         if (abortedNow())

package/dist/env-name-allowlist-knobs.d.ts

@@ -10,12 +10,13 @@
  *      带外凭据(e2b / docker / k8s 车道本来就是多租户 fleet 的主形),与 LSP 那条「本机子进程」的形不同;多租户下起服说一句。
  *  · `BAKE_ENV_ALLOW`([ref] 残余,7.103.0)由 **bake-runner 进程**读(构建宿主守护进程:没有主体、没有租户 ⇒ 没有姿态列,
  *    不进 {@link describeAllowlistPostures} 的姿态句)。它与服务侧四只旋钮同一只解析器、同一只「点名放行」谓词、同一条「原文按凭据类」律。
- *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词,解析器按它定「不许点哪些名」):
+ *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词)。它只定拒句里「交到哪里」那半句与出路的主语,**不定拒不拒**:「不许点哪些名」对五只一律
+ *    = 名单型旋钮名 ∪ 本服务自有凭据名(引擎此刻的声明:起服解析时判一次,声明增长时由换代声明对活配置里每只服务侧名单此刻交出去的名重判一次;判官 = 引擎
+ *    `inheritEnvPolicyProblem`,与引擎拒嵌入方白名单同句),规则全文在解析器头注 ②。
  *    - `host-put-back`(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)—— 剥后放回形:宿主子进程的 env 先经唯一组合(引擎扣掉本服务自有凭据 + 形状剥),
- *      名单点到的键再从本进程环境**原样**取回叠上去。点到本服务自有凭据名 = 把引擎刚扣下的那枚交回去 ⇒ 起服拒,判官 = 引擎同一只
- *      (`inheritEnvPolicyProblem`,读起服声明;与引擎拒嵌入方白名单同句)。
+ *      名单点到的键再从本进程环境**原样**取回叠上去;点到本服务自有凭据名 = 把引擎刚扣下的那枚交回那只子进程。
  *    - `sandbox-grant`(三只沙箱名单)—— 沙箱 env 的唯一来源(沙箱不从本进程继承任何东西),部署方显式交出的带外凭据([ref] 照转发);
- *      本列不在「自有凭据」律的射程里,只拒点名名单型旋钮(原文按凭据类)。
+ *      点到本服务自有凭据名 = 把它装进模型读得到的沙箱 env。沙箱要凭据 ⇒ 部署方给沙箱另铸一把(名与值都不同于本服务的任何凭据)。
  * 表是 `Record<旋钮, …>`:闭集加一只旋钮而不补行 = 编译红;行形随读它的进程定(服务进程 ⇒ 必须写姿态列)。
  *
  * 🔴 **姿态列只在这里写一次**([ref];7.101.0 合并复审 O9):凡要对人说「多租户下哪只旋钮忽略、哪只照转发」的句子,一律取

package/dist/exec-cut.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 一条**跑过**才被切的命令,执行错误怎么造、切断那一刻输出往哪去的**唯一一条律**(七只 adapter —— host〔管道 / spool 两形〕/ adb / e2b / ssh / k8s /
+ * local-docker / device —— 同读这一只):
+ *
+ *   命令已经起跑、之后被切 —— 墙钟(`timeout`)、静默界(`liveness_no_output`)、调用方中止(`aborted`)、宿主侧输出回调失败(`callback_error`)—— 它在被切之前
+ *   写出的 stdout / stderr 是真实的工作成果,必须原样带在 `ExecutionError.partialStdout` / `partialStderr` 上(core 合同:参考行为是超时保留**全部**已捕获的输出,
+ *   只追加一句「超时了」;丢掉 600 s 的构建日志会逼模型盲重跑)。引擎只从这两个字段读输出拼工具结果,从 `message` 读不到 ——
+ *   缺席就报「(no output was produced before the cutoff)」,模型对着一个其实已写了进度的命令说「什么也没产出」。
+ *
+ *   **切断即落定**:切断时本层手里还没交出的输出(远端 shell 腿 cwd 过滤器压着的 stderr 尾巴、host spool 还没泵的字节)只**记账**(尾窗 / detach tee),
+ *   随错误交回,不经调用方的输出回调**外发**。**落定先于构造,构造只记账**:构造结局会做事的腿(ssh / adb / k8s / host spool —— 冲刷压着的尾巴、泵 spool、
+ *   杀进程)的 `finish` 收一只构造结局的函数,先置落定,再构造、收尾、解决 —— 构造期间不调调用方的代码,重入的 detach / abort / close 读到的都是「已落定」。
+ *   正常结束同一顺序:压着的尾巴先记账、解决,**之后**才交给回调(那是流本身的结尾,不是切断)—— 回调里发生什么(重入、抛错)都改不了、也挂不住结局。
+ *   构造只读尾窗 / SDK 句柄字段的腿(host 管道 / local-docker / e2b)造错误即读,没有可重入的东西;device 的错误在投递结算之后才造。
+ *
+ * 与 `exec-bounds.ts` 的分工:那一只定「什么界在何时切、切断报哪个码、哪句话、几秒」(`buildLivenessCut` 等);这一只定「切断的错误带什么」。静默切断的
+ * 数据(`buildLivenessCut` 的返回)直接就是这里的 {@link ExecCut};墙钟与中止切断各 adapter 自己说句子(它们的成因词各车道不同),错误一律经 {@link createCutError} 造;
+ * 码是数据的腿(device:码由对端说,经映射表落到本侧)经 {@link createExecFailure} 按同一判别造。
+ *
+ * 输出的口径 = 同一条命令正常收口时 `exec` 会交出的那一份,切断不另设一道界、不二次切片:自带有界滚动尾窗(`RollingTailBuffer`)的腿读尾窗的当前文本,被丢掉的字节照旧附
+ * `markTruncated` 的记号({@link buildCapturedOutput});收口交出的是 SDK 整串的腿(e2b)读 SDK 句柄自己的记录;device 读它自己收齐的两路串。远端 shell 腿(ssh / adb / k8s)
+ * 的 stderr 在读之前先把 cwd 过滤器压着的尾巴记进账,与正常收口同一步。`message` 只陈述事实(哪一界、多少毫秒),不再夹输出。
+ *
+ * 不在本律里:命令**没起跑**就失败的码(`spawn_error` / `shell_unavailable` / 起跑前的 `aborted` / device 投递门之前的拒)按定义没有输出;结果未知
+ * (`transport_lost` / `outcome_unknown`)与未分类(`unknown`)的码引擎不读它的 partial —— 判别只有 {@link isRanThenCutCode} 一处。
+ */
+import { ExecutionError, type ExecutionErrorCode, type RollingTailBuffer } from "@sema-agent/core";
+/** 命令已起跑、随后被切的四个码(core `ExecutionError` 注:`partialStdout` / `partialStderr` 为这四个码而设)。 */
+export type RanThenCutCode = Extract<ExecutionErrorCode, "timeout" | "liveness_no_output" | "aborted" | "callback_error">;
+/**
+ * 一次切断的数据:码 + 句。`noOutputSec` 只属静默切断(静默窗口的整秒数,core `ExecutionError` 第五构造参)—— 与 `exec-bounds.ts` 的
+ * `buildLivenessCut` 返回值同形,可直接传入。
+ */
+export type ExecCut = {
+    readonly code: Exclude<RanThenCutCode, "liveness_no_output">;
+    readonly message: string;
+} | {
+    readonly code: "liveness_no_output";
+    readonly message: string;
+    readonly noOutputSec?: number;
+};
+/** 切断那一刻命令已写出的输出(纯数据;两路都是字符串,没写 = 空串)。 */
+export interface CapturedOutput {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * 切断那一刻两路滚动尾窗里的内容 = 该命令正常收口时 `exec` 交出的那一份(滚出窗外的字节照旧附 {@link markTruncated} 的记号)。
+ * `stdout` 缺席 = 这一次往返把 stdout 整份留作**数据载荷**(字节精确的文件读取:adb / local-docker 的 `binary`、k8s 的非 `boundOutput`)—— 载荷不是
+ * 命令输出,被切的数据读取没有「已写出的输出」可交给读者,stdout 记空串;stderr 恒是命令输出。
+ */
+export declare function buildCapturedOutput(stdout: RollingTailBuffer | undefined, stderr: RollingTailBuffer): CapturedOutput;
+/** 一条起跑后被切的命令的执行错误 —— 唯一造法(见文件头注):码 / 句取自 `cut`,输出取自 `captured`(逐字,不截)。 */
+export declare function createCutError(cut: ExecCut, captured: CapturedOutput): ExecutionError;
+/**
+ * 码是**数据**时的执行错误(device:对端说的词经映射表落到本侧,这一刻才知道是哪个码)—— 同一条律:命令起跑过(`ran` = 它已写出的输出)且码是起跑后被切的
+ * 四个之一 ⇒ 经 {@link createCutError} 带输出;其余(没起跑 = `ran` 缺席 / 结果未知 / 未分类)按律不带。码在调用处就是字面量的腿直接用 {@link createCutError}。
+ */
+export declare function createExecFailure(code: ExecutionErrorCode, message: string, ran?: CapturedOutput): ExecutionError;
+//# sourceMappingURL=exec-cut.d.ts.map

package/dist/exec-cut.js

@@ -0,0 +1,36 @@
+import { ExecutionError, markTruncated } from "@sema-agent/core";
+function isRanThenCutCode(code) {
+    switch (code) {
+        case "timeout":
+        case "liveness_no_output":
+        case "aborted":
+        case "callback_error":
+            return true;
+        case "shell_unavailable":
+        case "spawn_error":
+        case "transport_lost":
+        case "suspended":
+        case "auth_failed":
+        case "outcome_unknown":
+        case "target_unavailable":
+        case "unknown":
+            return false;
+    }
+}
+export function buildCapturedOutput(stdout, stderr) {
+    const err = stderr.result();
+    const out = stdout?.result();
+    return {
+        stdout: out === undefined ? "" : markTruncated(out.text, out.droppedBytes),
+        stderr: markTruncated(err.text, err.droppedBytes),
+    };
+}
+export function createCutError(cut, captured) {
+    return new ExecutionError(cut.code, cut.message, undefined, { stdout: captured.stdout, stderr: captured.stderr }, cut.code === "liveness_no_output" ? cut.noOutputSec : undefined);
+}
+export function createExecFailure(code, message, ran) {
+    if (ran !== undefined && isRanThenCutCode(code))
+        return createCutError({ code, message }, ran);
+    return new ExecutionError(code, message);
+}
+//# sourceMappingURL=exec-cut.js.map