@sema-agent/server 7.132.0 → 7.134.0

package/dist/plugins/pg-session-storage.js

@@ -1,5 +1,5 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, } from "@sema-agent/core";
+import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement, } from "@sema-agent/core";
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
 import { escapeLike } from "./sql-escape.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
@@ -7,14 +7,17 @@ import { scanEpochAnchor } from "./session-epoch-anchor.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
 import { toIso } from "./sql-row-helpers.js";
-import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
+import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
-import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
+import { createLogger } from "../observability/logger.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
 const isDupKey = isPgUniqueViolation;
 function baselineQuery(text, values) {
     return { text, values, query_timeout: BASELINE_IO_DEADLINE_MS };
@@ -83,10 +86,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.sessionId, this.floorSeq, async (beforeSeq) => {
+        return scanEpochAnchor(this.floorSeq, async (beforeSeq) => {
             const res = await this.pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq < $2 AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`, [this.sessionId, beforeSeq]);
             return res.rows;
-        });
+        }, (row) => decodeSessionEventPayload(row.payload, this.sessionId, row.seq));
     }
     static async wake(pool, sessionId) {
         const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
@@ -175,13 +178,15 @@ export class PgSessionStore {
     retention = MANAGED_RETENTION;
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
-    constructor(pool) {
+    log;
+    constructor(pool, opts = {}) {
         this.pool = pool;
+        this.log = opts.log ?? createLogger();
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null, opts?.placement);
+            await this.createOnAcquire(id, opts?.placement);
             return this.load(id, false, opts);
         }
         if (opts?.requireExisting)
@@ -189,7 +194,7 @@ export class PgSessionStore {
         const inflight = this.pending.get(sessionId);
         if (inflight) {
             const acquired = await inflight;
-            assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
+            admitSessionPlacement(sessionId, await this.placementOf(sessionId), opts ?? {}, placementCapabilityOf(this));
             return acquired;
         }
         const p = this.load(sessionId, false, opts).finally(() => this.pending.delete(sessionId));
@@ -199,20 +204,44 @@ export class PgSessionStore {
     async load(sessionId, requireExisting = false, opts) {
         let storage = await PgSessionStorage.wake(this.pool, sessionId);
         if (storage) {
-            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
+            admitSessionPlacement(sessionId, (await storage.getMetadata()).placement, opts ?? {}, placementCapabilityOf(this));
             return { session: new StoredSession(storage), sessionId };
         }
         if (requireExisting)
             throw new SessionError("not_found", `session ${sessionId} not found`);
-        await this.register(sessionId, null, opts?.placement);
+        await this.createOnAcquire(sessionId, opts?.placement);
         storage = await PgSessionStorage.wake(this.pool, sessionId);
         if (!storage) {
             throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
         }
-        assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
+        admitSessionPlacement(sessionId, (await storage.getMetadata()).placement, opts ?? {}, placementCapabilityOf(this));
         return { session: new StoredSession(storage), sessionId };
     }
-    async register(sessionId, owner, placement) {
+    async register(sessionId, owner) {
+        if (typeof owner !== "string" && owner !== null) {
+            if ((await this.ownerOf(sessionId)) !== undefined)
+                return;
+            assertFirstOwnerWritable(sessionId, owner);
+        }
+        await this.insertMeta(sessionId, owner, undefined);
+    }
+    async createOnAcquire(sessionId, placement) {
+        if (placement === undefined)
+            return this.insertMeta(sessionId, null, undefined);
+        await createPlacedSessionRow(sessionId, placement, {
+            readFaces: (ids) => this.sourceFaces(ids),
+            insert: (owner) => this.insertMeta(sessionId, owner, placement),
+            readOwner: () => this.ownerOf(sessionId),
+        }, this.log);
+    }
+    async claimOwnerless(sessionId, incarnation, owner) {
+        return ((await this.pool.query(CLAIM_OWNERLESS_PLACED_SQL.pg, [...claimOwnerlessParams(sessionId, incarnation, owner)])).rowCount ?? 0) > 0;
+    }
+    async sourceFaces(ids) {
+        const res = await this.pool.query(`SELECT session_id, owner, incarnation FROM session_meta WHERE session_id IN (${ids.map((_, i) => `$${i + 1}`).join(", ")})`, [...ids]);
+        return new Map(res.rows.map((r) => [String(r.session_id), sessionFaceFromRow(String(r.session_id), r.owner ?? null, r.incarnation)]));
+    }
+    async insertMeta(sessionId, owner, placement) {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
@@ -406,10 +435,11 @@ export class PgSessionStore {
         }
     }
     async fork(sourceId, owner) {
-        const metaRes = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = $1", [sourceId]);
+        const metaRes = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = $1", [sourceId]);
         if (!metaRes.rows[0])
             return null;
         const leafId = metaRes.rows[0].leaf_id ?? null;
+        const forkOwner = forkOwnerOf(owner, metaRes.rows[0].owner ?? null) ?? null;
         const eventRes = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("pg", "payload")}, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [sourceId]);
         const rows = eventRes.rows;
         const newId = uuidv7();
@@ -422,7 +452,7 @@ export class PgSessionStore {
                 const payload = String(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, owner, now, now, leafId, rows.length, mintSessionIncarnation()]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, forkOwner, now, now, leafId, rows.length, mintSessionIncarnation()]);
             await conn.query("COMMIT");
             return newId;
         }
@@ -619,6 +649,23 @@ class PgStagingHandle {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
+            const now = new Date();
+            const minted = mintSessionIncarnation();
+            if (opts.expectedOwner !== undefined) {
+                const cas = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [this.realSessionId, opts.expectedOwner]);
+                if (cas.rowCount !== 1) {
+                    await conn.query("ROLLBACK");
+                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                }
+            }
+            else {
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,NULL,0,$5) ON CONFLICT (session_id) DO NOTHING", [this.realSessionId, owner, now, now, minted]);
+                const claimed = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [this.realSessionId]);
+                if (String(claimed.rows[0]?.incarnation) !== minted) {
+                    await conn.query("ROLLBACK");
+                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                }
+            }
             const staged = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const dst = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const dstMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
@@ -627,15 +674,15 @@ class PgStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${dstMeta.rows[0].placement_kind} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = staged.rows.map((r) => String(r.entry_id));
-            const dstIds = dstMeta.rows.length > 0 ? dst.rows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOwner !== undefined ? dst.rows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
-            if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
+            if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.query("ROLLBACK");
                 throw new SyncConflictError(this.realSessionId, rel);
             }
-            if (rel.relation === "fast_forward" && opts?.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
-                const dstFull = await conn.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [this.realSessionId]);
-                const stagedFull = await conn.query(`SELECT entry_id, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [this.stagingId]);
+            if (rel.relation === "fast_forward" && opts.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
+                const dstFull = await conn.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE`, [this.realSessionId]);
+                const stagedFull = await conn.query(`SELECT entry_id, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE`, [this.stagingId]);
                 const dstSet = new Set(dstIds);
                 const dstEntries = dstFull.rows.map((r) => decodeSessionEventPayload(r.payload, this.realSessionId, r.seq));
                 const stagedShared = stagedFull.rows.filter((r) => dstSet.has(String(r.entry_id))).map((r) => decodeSessionEventPayload(r.payload, this.stagingId, r.entry_id));
@@ -647,13 +694,11 @@ class PgStagingHandle {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [this.realSessionId]);
             await conn.query("UPDATE session_event SET session_id = $1 WHERE session_id = $2", [this.realSessionId, this.stagingId]);
-            const lastRes = await conn.query(`SELECT ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq DESC LIMIT 1`, [this.realSessionId]);
+            const lastRes = await conn.query(`SELECT ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq DESC LIMIT 1 FOR UPDATE`, [this.realSessionId]);
             let leafId = null;
             if (lastRes.rows[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRes.rows[0].payload, this.realSessionId, "last staged row"));
-            const now = new Date();
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7) " +
-                "ON CONFLICT (session_id) DO UPDATE SET owner = EXCLUDED.owner, updated_at = EXCLUDED.updated_at, leaf_id = EXCLUDED.leaf_id, leaf_seq = EXCLUDED.leaf_seq", [this.realSessionId, owner, now, now, leafId, srcIds.length, mintSessionIncarnation()]);
+            await conn.query("UPDATE session_meta SET owner = $1, updated_at = $2, leaf_id = $3, leaf_seq = $4 WHERE session_id = $5", [owner, now, leafId, srcIds.length, this.realSessionId]);
             const afterMeta = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (afterMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");

package/dist/plugins/remote-env-adb.d.ts

@@ -1,20 +1,12 @@
 import { spawn } from "node:child_process";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
-export interface AdbEnvConfig {
+export interface AdbEnvConfig extends LaneHomeConfig {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
     serial: string;
     /** Path to the adb binary. Default "adb" (must be on PATH in the runner image). */
     adbPath?: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** On-device workspace root; relative paths resolve against it. Default "/data/local/tmp". */
     mountPath?: string;
     commandTimeoutMs?: number;
@@ -86,8 +78,10 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     private destroyed;
     /** 在飞的那一次懒连接(单飞记忆)——见 {@link ensureConnected}。settle 即清,**不缓存败诺**。 */
     private connectPromise?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):设备 shell 里执行用户的 home —— 声明胜,否则首连时 `adb shell` 实测的 `$HOME`(Android 常为 `/` 或 `/data/local/tmp` 一类,读到什么填什么,绝对即可),见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道**不对证**声明:Android 没有 POSIX 登录家目录,声明是运维的断言,照单全收。 */
+    private readonly homeSeat;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";

package/dist/plugins/remote-env-adb.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
@@ -31,7 +32,10 @@ export class RemoteAdbExecutionEnv {
     connected = false;
     destroyed = false;
     connectPromise;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     cdPath = "unknown";
     cfg;
     spawnFn;
@@ -46,7 +50,7 @@ export class RemoteAdbExecutionEnv {
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 800 },
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: false, onAbsent: config.onHomeAbsent });
         this.spawnFn = deps?.spawn ?? spawn;
         this.injectedConnectOnce = deps?.connectOnce;
     }
@@ -117,6 +121,12 @@ export class RemoteAdbExecutionEnv {
                     error: new RemoteExecutionError("unsupported", `device ${this.cfg.serial} does not advertise the 'shell_v2' feature, so this adapter cannot establish that its command round-trip carries a real exit code with stderr kept separate — the two properties every filesystem judgment on this lane depends on to tell failure from success. Refusing to connect rather than run on an unverifiable transport: attach a device that supports adb shell protocol v2.`),
                 };
             }
+            if (this.homeSeat.asks) {
+                const home = await this.adb(this.deviceShellArgs(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.commandTimeoutMs });
+                if (!home.ok && home.error.code === "aborted")
+                    return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while reading the device's home") };
+                this.homeSeat.settle(home.ok && home.value.exitCode === 0 ? { ok: true, stdout: home.value.stdout } : { ok: false, reason: home.ok ? `exit ${home.value.exitCode}` : home.error.message });
+            }
             this.connected = true;
             return ok(this.workspaceHandle());
         }

package/dist/plugins/remote-env-device.d.ts

@@ -17,10 +17,9 @@ type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
  * 🔴 三条不许折错的线:
  *  ① `outcome_unknown` **原样过境**——core 把它排除在 `RETRYABLE_REMOTE_ERROR_CODES` 之外正是为了
  *     「可能已经执行过」这一格;折成 `timeout`/`transport_lost` 会让上层按可重试处理,重驱已提交副作用。
- *  ② `target_unavailable`(never-started 的诚实词)在 `FileErrorCode` 上**没有对位词** —— 落
- *     `transport_lost`:它的契约是「连接故事已知、重连后可重试」,而 never-started 的重试确实是安全的。
- *     诚实残余:file 面因此**分不出**「从未开始」与「传输中断」,两者都落在同一个可重试桶里(方向对、
- *     粒度粗)。要分得开需要 core 在 `FileErrorCode` 上补 never-started 词 —— 已作 O12 的后续请托登记。
+ *  ② `target_unavailable`(never-started 的诚实词)**原样过境** —— core 7.54.0([ref] r3)给 `FileErrorCode` 补了同名词
+ *     (目标在 commit 前拒、从未开始、零效果,目标回来后重试安全;写车道据它撤回首触记录、不计 edited)。修前文件面无对位词,
+ *     落 `transport_lost`(「传输中断」= 重试白名单读作「可能已执行」),file 面分不出「从未开始」与「传输中断」—— 那条 O12 后续请托随本版兑现。
  *  ③ exec 专属词(`shell_unavailable`/`spawn_error`/`callback_error`/`suspended`/`auth_failed`)出现在
  *     file 面上是**设备端协议违约**(它把一个 exec 结局贴到一次文件操作上)⇒ 落 `unknown`,不猜。
  */
@@ -38,9 +37,8 @@ type RejectCode = DeviceRejectCode;
 /**
  * 汇聚端的 **typed 拒**(投递门**之前**,§5.3 投递边界:设备从未可能见过这条指令)→ core 错误码。
  *
- * 🔴 全部落在**可安全重试**的那一侧,这是投递边界给的硬事实,不是乐观估计。exec 面用 O12 的
- * `target_unavailable`(「目标在 commit 前拒了,命令从未启动」的诚实词);file 面无对位词,同上落
- * `transport_lost`。
+ * 🔴 全部落在**可安全重试**的那一侧,这是投递边界给的硬事实,不是乐观估计。exec 面与 file 面用同一个
+ * `target_unavailable`(「目标在 commit 前拒了,指令从未启动」的诚实词;file 面自 core 7.54.0 起有它,修前落 `transport_lost`)。
  * 例外 `identity_mismatch` / `revoked` / `not_found`:那是**永久**拒(换设备/吊销/不是你的),重试
  * 只会同样失败 —— exec 面落 `auth_failed`(NEVER retry 的那一格),file 面无对位词落 `permission_denied`
  * (「这条路你走不通,而且不是暂时的」是它最近的语义)。
@@ -324,6 +322,15 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
  *  ③ 「这个 placement 根本没绑设备」是**装配/准入错误**,不是一次运行期业务拒绝 —— 响亮抛,让 spawn
  *     失败(core 对 `isolation:"worktree"` 的同款姿势:宁可 throw,绝不静默给一个不对的 env)。
  *     对比:「绑了但现在不在线」是运行期事实 ⇒ 构造成功,`connect()` 回 typed `device.offline`。
+ *
+ * 🔴 **工厂的每一只拒都是 typed 拒**(core 7.54.0 [ref] r3 契约:工厂抛的 `.code` 原样成失败终局的码):经 {@link deviceFactoryRefusal} 一处铸,码取
+ * `DEVICE_ERROR_CODES` 闭集(装配错误取 `config.placement_root_invalid`),句子里的 `[码]` 与 `.code` 同值。修前抛裸 `Error`,码只在句子里。
+ *
+ * 🔴 **续跑腿的投递围栏**(core 7.54.0 [ref] r3 / #2061,`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备(`resumeWorkspace.deviceId`)⇒
+ * 本工厂**只**在那台设备上铸 —— placement 根此刻绑的不是它(换绑过)⇒ 抛 typed `device.identity_mismatch`(换绑后赎回的同一个词,零新码),
+ * 句子点名两台设备;不连另一台、不改道(新设备没有那个工作区)。读当前绑定只为判出这一拒与取属主,铸的设备恒是行记下的那一台。
+ * 「绑的就是它但现在不在线」与新跑同形:构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。
+ * 行没记设备(非设备车道 / 早于该字段的行)⇒ 不声明要兑现的设备,按普通路由走。句柄(`workspaceHandle()`)恒报连接真到达的设备,不抄 `resumeWorkspace`。
  */
 export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
 /**

package/dist/plugins/remote-env-device.js

@@ -22,7 +22,7 @@ export const DEVICE_OUTCOME_TO_FILE_ERROR = {
     shell_unavailable: "unknown",
     spawn_error: "unknown",
     suspended: "unknown",
-    target_unavailable: "transport_lost",
+    target_unavailable: "target_unavailable",
     timeout: "timeout",
     transport_lost: "transport_lost",
     unknown: "unknown",
@@ -66,20 +66,20 @@ export const DEVICE_REJECT_TO_EXEC_ERROR = {
     "draining": "target_unavailable",
 };
 export const DEVICE_REJECT_TO_FILE_ERROR = {
-    "device.not_bound": "transport_lost",
-    "device.offline": "transport_lost",
-    "device.busy": "transport_lost",
-    "device.attached_elsewhere": "transport_lost",
-    "device.claim_conflict": "transport_lost",
+    "device.not_bound": "target_unavailable",
+    "device.offline": "target_unavailable",
+    "device.busy": "target_unavailable",
+    "device.attached_elsewhere": "target_unavailable",
+    "device.claim_conflict": "target_unavailable",
     "device.provider_mismatch": "permission_denied",
     "device.identity_mismatch": "permission_denied",
     "device.revoked": "permission_denied",
     "device.enrollment_invalid": "permission_denied",
     "not_found.device": "permission_denied",
-    "device.rebind_rev_conflict": "transport_lost",
-    "device.rebind_active_run": "transport_lost",
-    "limit.rate_exceeded": "transport_lost",
-    "draining": "transport_lost",
+    "device.rebind_rev_conflict": "target_unavailable",
+    "device.rebind_active_run": "target_unavailable",
+    "limit.rate_exceeded": "target_unavailable",
+    "draining": "target_unavailable",
 };
 const DEVICE_REJECT_TO_REMOTE_ERROR = {
     "device.not_bound": "connect_failed",
@@ -232,7 +232,7 @@ export class RemoteDeviceExecutionEnv {
                 failure: {
                     remote: "connect_failed",
                     exec: "target_unavailable",
-                    file: "transport_lost",
+                    file: "target_unavailable",
                     message: `[device.admission_unavailable] the device admission read failed, so this session's device could not be confirmed (fail-closed): ${err instanceof Error ? err.message : String(err)}`,
                 },
             };
@@ -780,25 +780,33 @@ const OUTCOME_TO_REMOTE_ERROR = {
     transport_lost: "transport_lost",
     unknown: "unknown",
 };
+function deviceFactoryRefusal(code, message) {
+    return Object.assign(new Error(message), { code });
+}
 export function deviceExecutionEnvFactory(deps) {
     const execTimeoutMs = deps.execTimeoutMs ?? 1_800_000;
     return async (ctx) => {
         const rootSessionId = ctx.placementRootSessionId;
         if (typeof rootSessionId !== "string" || rootSessionId.length === 0) {
-            throw new Error("device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [config.placement_root_invalid] — " +
+            throw deviceFactoryRefusal("config.placement_root_invalid", "device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [config.placement_root_invalid] — " +
                 "the device placement is keyed on the run tree's placement root; defaulting to the child sessionId would read as a NEW placement (v2 §4.3.2 / core design/380 O1①)");
         }
         const binding = await deps.store.getSessionBinding(rootSessionId);
         if (!binding) {
-            throw new Error(`device lane: no device binding for placement root ${rootSessionId} [${DEVICE_ERROR_CODES.NOT_BOUND}] — ` +
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.NOT_BOUND, `device lane: no device binding for placement root ${rootSessionId} [${DEVICE_ERROR_CODES.NOT_BOUND}] — ` +
                 "the submit-time admission chain must bind the root session to a device before a run reaches the factory (v2 §4.3.2)");
         }
+        const recordedDevice = ctx.resumeWorkspace?.deviceId;
+        if (recordedDevice !== undefined && recordedDevice !== binding.deviceId) {
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, `device lane: this resume rebuilds the workspace on device ${recordedDevice}, but placement root ${rootSessionId} is now bound to ${binding.deviceId} [${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] — ` +
+                "a parked call does not follow a rebind (the new device has no copy of that workspace); finish or cancel the parked task, then start it again on the device now bound");
+        }
         const view = await deps.store.readDeviceForAdmission(binding.deviceId, binding.owner);
         if (!view) {
-            throw new Error(`device lane: the bound device is gone or not owned by the binding's principal [${DEVICE_ERROR_CODES.NOT_FOUND}]`);
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.NOT_FOUND, `device lane: the bound device is gone or not owned by the binding's principal [${DEVICE_ERROR_CODES.NOT_FOUND}]`);
         }
         if (view.row.status === "revoked") {
-            throw new Error(`device lane: the bound device has been revoked [${DEVICE_ERROR_CODES.REVOKED}] — revocation is terminal; re-enrolling mints a NEW deviceId (v2 §8-R4)`);
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.REVOKED, `device lane: the bound device has been revoked [${DEVICE_ERROR_CODES.REVOKED}] — revocation is terminal; re-enrolling mints a NEW deviceId (v2 §8-R4)`);
         }
         assertPosixDevicePlatform(view.row.platformOs, view.row.deviceId);
         return new RemoteDeviceExecutionEnv({

package/dist/plugins/remote-env-k8s.d.ts

@@ -4,9 +4,10 @@ import { type CacheMissMemory, type WorkspaceCacheCapability } from "../workspac
 import { type SandboxEgressGap, type SandboxIpv6 } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
-export interface K8sEnvConfig {
+export interface K8sEnvConfig extends LaneHomeConfig {
     /** API server URL. Default: in-cluster (`https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT`). */
     apiUrl?: string;
     /** Bearer token. Default: in-cluster service-account token file. */
@@ -20,15 +21,6 @@ export interface K8sEnvConfig {
     image: string;
     /** RuntimeClass for the VM boundary. Default "kata-qemu" (set "" to run plain runc — tests/dev only). */
     runtimeClass?: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root inside the pod; created on connect. Default "/workspace". */
     mountPath?: string;
     /** Pod lifetime (`activeDeadlineSeconds`; env `K8S_TIMEOUT_MS`) — the whole-pod leak guard, and the ceiling background-shell
@@ -275,8 +267,10 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  the space restore (`latest` names an archive that is there and did not come back — {@link restoreSnapshot}) and the pod's admission (the cluster created
      *  the pod and it ended `Failed` before it ran — {@link createPod}). Neither goes away by asking again: the same request answers the same. */
     private connectRefusal?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):pod 里执行用户的 home —— 声明胜,否则 pod 就绪那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时 pod 起来之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证(与 local-docker / ssh 同一只判官、同一句拒)。 */
+    private readonly homeSeat;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -616,6 +610,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * `latest` is not published, loud) → move `latest` → keep N → the row is deleted (always, saved or failed).
      * A lost fence, an upload or a pointer failure ⇒ one `workspace_snapshot_failed` line + the `failed` outcome; `latest`
      * keeps naming the previous snapshot, so the next run restores THAT — never an empty workspace dressed up as a restore.
+     * `latest` is moved only onto an object the upload wrote: a pod that is gone when the tar is due (it vanished while the fence was
+     * being claimed) uploads nothing, and is that same upload failure.
      */
     private persistWorkspace;
     private execUrl;

package/dist/plugins/remote-env-k8s.js

@@ -18,6 +18,7 @@ import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js"
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "k8s";
 const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
 const K8S_BG_MAX_CONCURRENT = numEnvOr("K8S_BG_MAX_CONCURRENT", 8, 1);
@@ -177,7 +178,10 @@ export class RemoteK8sExecutionEnv {
     idleWaiters = [];
     connectInFlight;
     connectRefusal;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     cdPath = "unknown";
     cfg;
     deps;
@@ -217,7 +221,7 @@ export class RemoteK8sExecutionEnv {
             ...(config.snapshotExclude && config.snapshotExclude.length > 0 ? { snapshotExclude: config.snapshotExclude } : {}),
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
         this.deps = deps ?? {};
         this.laneLiveness = laneLivenessOf(this.cfg.livenessMs, "K8S_LIVENESS_MS");
         const occupant = occupantKeyOf(config.spaceOccupant);
@@ -675,13 +679,24 @@ export class RemoteK8sExecutionEnv {
         }
         this.podName = name;
         this.podIP = podIP;
-        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}`);
+        const askHome = this.homeSeat.asks;
+        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}${askHome ? ` && { ${LANE_HOME_PROBE_COMMAND} || true; }` : ""}`);
         if (!mk.ok || mk.value.exitCode !== 0) {
             await this.deletePod(name).catch(() => { });
             this.podName = undefined;
             this.podIP = undefined;
             return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace mkdir failed: ${mk.ok ? mk.value.stderr : mk.error.message}`) };
         }
+        if (askHome) {
+            const verdict = this.homeSeat.settle({ ok: true, stdout: mk.value.stdout });
+            if (verdict !== undefined) {
+                await this.deletePod(name).catch(() => { });
+                this.podName = undefined;
+                this.podIP = undefined;
+                const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+                return verdict.answered ? this.holdRefusal(error) : { ok: false, error };
+            }
+        }
         if (cache?.fresh)
             this.logger?.warn("workspace_cache_fresh", { space: incarnationLogPrefix(cache.spaceKey), claim: cache.claim.name, size: cache.size });
         return ok(this.workspaceHandle());
@@ -927,8 +942,11 @@ export class RemoteK8sExecutionEnv {
         if (target.lane === "park" && this.inFlight.size > 0)
             return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
         const snapshotId = mintSnapshotId(this.occupantIncarnation);
-        if (!this.podName)
-            return ok(snapshotId);
+        if (!this.podName) {
+            return target.lane === "space"
+                ? { ok: false, error: new RemoteExecutionError("connect_failed", "the sandbox pod was gone when the run-end snapshot reached the upload — nothing was saved (the workspace could not be read), and `latest` keeps naming the previous snapshot") }
+                : ok(snapshotId);
+        }
         const presigned = this.presignSnapshot({ ...target, method: "PUT", snapshotId });
         if (!presigned.ok)
             return presigned;

package/dist/plugins/remote-env-local-docker.d.ts

@@ -1,24 +1,16 @@
 import { spawn } from "node:child_process";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Construction config for {@link RemoteLocalDockerExecutionEnv}. */
-export interface LocalDockerEnvConfig {
+export interface LocalDockerEnvConfig extends LaneHomeConfig {
     /**
      * Base container image to run the task in. **REQUIRED — no default** (domestic-images iron rule: the registry
      * is the operator's choice, never a hardcoded `docker.io` origin). e.g. the docker.io/claybobby pool or an
      * in-network `node:20` mirror (SWR deprecated).
      */
     image: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root INSIDE the container; relative paths resolve against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Path to the docker binary (or a docker-compatible CLI). Default "docker" (must be on PATH in the worker). */
@@ -77,8 +69,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     };
     /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明胜,否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -95,6 +87,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private connecting?;
     /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
     private homeRefusal?;
+    /** 家目录的座(声明胜 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
     workspaceHandle(): WorkspaceHandle;
@@ -107,9 +101,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     }>;
     private doConnect;
     /**
-     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、
-     * 同一份 `-e` env),交唯一判官 `judgeLaneHome`。环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);
-     * 没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,但不记(与任何一次起容器失败同:下一次连接重问);调用方中止 ⇒ `aborted`、不记。没声明 ⇒ 不问(`undefined`)。容器由调用方收。
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
+     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
+     * 但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
+     * 调用方中止 ⇒ `aborted`、不记、不交座。容器由调用方收。
      */
     private homeVerdict;
     suspendVM(_options?: VmLifecycleOptions): Promise<{