@sema-agent/server 7.131.0 → 7.133.0

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

@@ -1,13 +1,16 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, normalizePromptEpoch, } from "@sema-agent/core";
+import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, } 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";
+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 { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
+import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
+import { createLogger } from "../observability/logger.js";
 import { classifySyncRelationshipByIds, SyncConflictError, 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";
@@ -82,21 +85,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        if (this.floorSeq <= 0)
-            return undefined;
-        let cursor = this.floorSeq;
-        for (;;) {
-            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, cursor]);
-            if (res.rows.length === 0)
-                return undefined;
-            for (const r of res.rows) {
-                const e = decodeSessionEventPayload(r.payload, this.sessionId, r.seq);
-                const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
-                if (d)
-                    return d;
-            }
-            cursor = Number(res.rows[res.rows.length - 1].seq);
-        }
+        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]);
@@ -185,13 +177,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)
@@ -214,7 +208,7 @@ export class PgSessionStore {
         }
         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`);
@@ -222,7 +216,26 @@ export class PgSessionStore {
         assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
         return { session: new StoredSession(storage), sessionId };
     }
-    async register(sessionId, owner, placement) {
+    async register(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) " +
@@ -516,7 +529,7 @@ export class PgSessionStore {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(placedRes.rows[0], owner));
+            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRes.rows[0], owner));
             await conn.query("COMMIT");
         }
         catch (err) {

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";
@@ -204,6 +198,12 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /**
+     * 交给宿主 `adb` CLI 的 env —— 宿主子进程 env 的唯一组合(`server-secret-env.ts` `hostSubprocessEnv`),继承词 `"all"`:本服务自有凭据(起服声明的名与值)
+     * 任何词都不交,adb 自己要读的变量(`ADB_VENDOR_KEYS` / `ANDROID_*` …)照交 —— 形状剥会剥 `ADB_VENDOR_KEYS`(名形),设备鉴权因此断。首次调用拉起的常驻 adb server
+     * 继承的就是这一份。命令本身跑在设备的 shell 里,本 env 到不了设备。每次起进程现算一次(与 host shell 同)。
+     */
+    private cliEnv;
     /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private adb;
     /**

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

@@ -2,9 +2,11 @@ import path from "node:path";
 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 { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -30,7 +32,10 @@ export class RemoteAdbExecutionEnv {
     connected = false;
     destroyed = false;
     connectPromise;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     cdPath = "unknown";
     cfg;
     spawnFn;
@@ -45,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;
     }
@@ -116,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());
         }
@@ -180,7 +191,7 @@ export class RemoteAdbExecutionEnv {
         if (this.destroyed)
             throw new RemoteExecutionError("connect_failed", "execution env already destroyed");
         const wrapped = buildCwdEnvCommand(command, this.workingDirOf(options?.cwd), options?.env, "raw").command;
-        const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"] });
+        const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
         const queue = [];
         let finished = false;
         let failure;
@@ -276,7 +287,8 @@ export class RemoteAdbExecutionEnv {
                         clearTimeout(waitTimer);
                 }
                 if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms) {
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
                 }
             }
             while (queue.length)
@@ -417,13 +429,16 @@ export class RemoteAdbExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    cliEnv() {
+        return hostSubprocessEnv({ site: "server.remote-env-adb.spawn-env", policy: "all", allow: [] });
+    }
     adb(args, opts) {
         if (this.destroyed)
             return Promise.resolve({ ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") });
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;
-            const child = this.spawnFn(this.cfg.adbPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+            const child = this.spawnFn(this.cfg.adbPath, args, { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");

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

@@ -12,6 +12,7 @@ export const DEVICE_OUTCOME_TO_FILE_ERROR = {
     callback_error: "unknown",
     invalid: "invalid",
     is_directory: "is_directory",
+    liveness_no_output: "unknown",
     not_directory: "not_directory",
     not_found: "not_found",
     not_supported: "not_supported",
@@ -33,6 +34,7 @@ export const DEVICE_OUTCOME_TO_EXEC_ERROR = {
     callback_error: "callback_error",
     invalid: "unknown",
     is_directory: "unknown",
+    liveness_no_output: "liveness_no_output",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "shell_unavailable",
@@ -763,6 +765,7 @@ const OUTCOME_TO_REMOTE_ERROR = {
     callback_error: "unknown",
     invalid: "unknown",
     is_directory: "unknown",
+    liveness_no_output: "liveness_no_output",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "unsupported",

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

@@ -321,7 +321,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * a command that hangs DURING execution (not creation) would otherwise wait the E2B command timeout (= the
      * lifetime when none is set, the original hang bug). With a `liveness` bound (the caller stated no `timeout` —
      * `exec-bounds.ts`) it races wait() against an idle check: no stdout/stderr for `liveness.ms` ⇒ hung → kill + typed
-     * retryable "timeout" with the shared cut sentence. `lastProgress()` is bumped by the stdout/stderr callbacks, so a
+     * retryable `liveness_no_output` (the shared cut: code, sentence and the window in whole seconds — `buildLivenessCut`). `lastProgress()` is bumped by the stdout/stderr callbacks, so a
      * slow-but-PROGRESSING command (long `npm ci`) is never killed. Both cuts reject with an `ExecutionError` carrying
      * its real code (exec returns it as-is) — a `RemoteExecutionError` here would reach {@link execError}'s text match
      * and land as `unknown`. The rejection is armed BEFORE the kill: the kill rejects `wait()` too, and the race must

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

@@ -3,7 +3,7 @@ import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { numEnvOr, runSymlinkChain, shellQuote } from "./remote-shell.js";
-import { commandBoundsOf, firstBoundOf, laneLivenessOf, livenessCutMessage, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf, firstBoundOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
 const DEFAULT_MOUNT_PATH = "/home/user";
@@ -297,7 +297,10 @@ export class RemoteContainerExecutionEnv {
             startCut = true;
             this.settleAbandonedStart(starting);
             const cut = e instanceof RemoteExecutionError && e.code === "timeout" && !options?.abortSignal?.aborted;
-            return { ok: false, error: cut ? new ExecutionError("timeout", boundCutMessage(first)) : this.execError(e, options?.abortSignal) };
+            if (!cut)
+                return { ok: false, error: this.execError(e, options?.abortSignal) };
+            const bc = boundCut(first);
+            return { ok: false, error: new ExecutionError(bc.code, bc.message, undefined, undefined, bc.noOutputSec) };
         }
         const onAbort = () => { if (!detached)
             void handle.kill().catch(() => { }); };
@@ -425,8 +428,10 @@ export class RemoteContainerExecutionEnv {
         catch (e) {
             finished = true;
             this.settleAbandonedStart(starting);
-            if (e instanceof RemoteExecutionError && e.code === "timeout" && !options?.signal?.aborted)
-                throw new RemoteExecutionError("timeout", boundCutMessage(first), e);
+            if (e instanceof RemoteExecutionError && e.code === "timeout" && !options?.signal?.aborted) {
+                const bc = boundCut(first);
+                throw new RemoteExecutionError(bc.code, bc.message, e);
+            }
             throw this.remoteError(e, "connect_failed");
         }
         handle
@@ -490,7 +495,10 @@ export class RemoteContainerExecutionEnv {
                 const idle = liveness === undefined
                     ? undefined
                     : new Promise((_, reject) => {
-                        timer = setTimeout(() => reject(new RemoteExecutionError("timeout", livenessCutMessage(liveness))), liveness.ms);
+                        timer = setTimeout(() => {
+                            const cut = buildLivenessCut(liveness);
+                            reject(new RemoteExecutionError(cut.code, cut.message));
+                        }, liveness.ms);
                     });
                 try {
                     await (idle === undefined ? next : Promise.race([next, idle]));
@@ -850,7 +858,8 @@ export class RemoteContainerExecutionEnv {
                         return;
                     const idleFor = Date.now() - lastProgress();
                     if (idleFor >= bound.ms) {
-                        reject(new ExecutionError("timeout", livenessCutMessage(bound)));
+                        const cut = buildLivenessCut(bound);
+                        reject(new ExecutionError(cut.code, cut.message, undefined, undefined, cut.noOutputSec));
                         void handle.kill().catch(() => { });
                         this.cfg.metrics?.inc("remote_env_exec_idle_timeout_total", { provider: PROVIDER });
                     }
@@ -866,7 +875,7 @@ export class RemoteContainerExecutionEnv {
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
-                    reject(new ExecutionError("timeout", boundCutMessage({ ms: wall.totalMs, cut: "wall" })));
+                    reject(new ExecutionError("timeout", wallCutMessage(wall.totalMs)));
                     void handle.kill().catch(() => { });
                 }, wall.leftMs);
             }
@@ -969,8 +978,11 @@ export function e2bExecutionEnvFactory(config, deps) {
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
-function boundCutMessage(first) {
-    return first.cut === "wall" ? `exec exceeded ${first.ms}ms` : livenessCutMessage(first.cut);
+function wallCutMessage(ms) {
+    return `exec exceeded ${ms}ms`;
+}
+function boundCut(first) {
+    return first.cut === "wall" ? { code: "timeout", message: wallCutMessage(first.ms) } : buildLivenessCut(first.cut);
 }
 function providerTimedOut(e) {
     return e?.name === "TimeoutError" || /timeout|timed out/i.test(errMsg(e));

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

@@ -314,17 +314,17 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /**
-     * S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。host 腿是 node:fs 腿,所以按
-     * 提货单 [ref] @server 五适配器段的第一行,与 core 的 `NodeExecutionEnv.canonicalChain` **同形**:对整条
-     * 拼法 `readlink`,再对每一跳 `readlink`,**上限 64**、**只锚不折**、**遇环即止**;win32 宿主上跳到共享
-     * (UNC)时**记下该跳并停止探测**(不碰网络,CC `vr` 对网络拼法只给拼法)。
+     * S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。host 腿是 node:fs 腿:走法(对整条拼法 `readlink`、再对每一跳
+     * `readlink`,**上限**、**只锚不折**、**遇环即止**、win32 宿主上跳到共享(UNC)时**记下该跳并停止探测** —— 不碰网络)是 core 导出的
+     * `walkSymlinkChain`,本腿只供它**逐跳的读口**;上限、播种、锚法、UNC 判都在那一只里,本仓不再重写第二遍。
      *
-     * 🔴 **不复用 core 的实现而是同形重写**:`NodeExecutionEnv` 是 core 的内部类,包根不导出它的这只方法;
-     * 而本腿的每一次读都必须先过 {@link fsReady}(2026-07-25 全族统一:拆除之后只读面不得与写面自相矛盾),
-     * 那道门在 core 的实现里不存在。同形的判据钉在 `test/remote-env-canonical-chain.test.ts`。
+     * 🔴 为什么本腿仍自备读口而不是整体复用 core 的 `NodeExecutionEnv.canonicalChain`:本腿的每一次读都必须先过 {@link fsReady}
+     * (2026-07-25 全族统一:拆除之后只读面不得与写面自相矛盾),那道门在 core 的实现里不存在 —— 门在**起点**过一次,读口不再逐跳过
+     * (中途 destroy 不改变「这一次链读」的读数:每跳是同一次往返里对本机盘的读,与旧循环逐字同姿势)。
      *
-     * 链尽的三种 errno(`EINVAL` 不是软链 / `ENOENT` 不存在 / `ENOTDIR`)⇒ `ok` + 到此为止的跳;其余 errno
-     * (`EACCES` …)⇒ `ok:false`(core 读作「这一次没有跳」,**永不是拒绝**)。非链接的叶答 `[]`。
+     * 链尽的三种 errno(`EINVAL` 不是软链 / `ENOENT` 不存在 / `ENOTDIR`)由本腿的 `fileError` 归成 `invalid` / `not_found` / `not_directory`,
+     * core 的走法读作「到此为止」⇒ `ok` + 到此为止的跳;其余 errno(`EACCES` …)⇒ `ok:false`(core 读作「这一次没有跳」,**永不是拒绝**)。
+     * 非链接的叶答 `[]`。同形的判据钉在 `test/remote-env-canonical-chain.test.ts`,「读 core 导出」的钉在 `test/core-export-single-source-*.test.ts`。
      */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;

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

@@ -5,12 +5,12 @@ import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
-import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
-import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
@@ -24,7 +24,6 @@ const HOST_BG_FILE_CAP = numEnvOr("HOST_BG_FILE_CAP", 64 * 1024 * 1024, HOST_BG_
 export const HOST_BG_KILL_GRACE_MS = numEnvOr("HOST_BG_KILL_GRACE_MS", 1000, 0);
 const HOST_BG_MEM_CAP = numEnvOr("HOST_BG_MEM_CAP", 8 * 1024 * 1024, 64 * 1024);
 const ok = (value) => ({ ok: true, value });
-const UNC_SPELLING = /^[\\/]{2}[^\\/]+[\\/]+[^\\/]/;
 const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
@@ -919,7 +918,8 @@ export class RemoteHostExecutionEnv {
                 if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms) {
                     finished = true;
                     kill();
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
                 }
             }
             while (queue.length)
@@ -1099,36 +1099,14 @@ export class RemoteHostExecutionEnv {
         const ready = await this.fsReady(p);
         if (!ready.ok)
             return ready;
-        const hops = [];
-        let cur = this.resolve(p);
-        const seen = new Set([cur]);
-        for (let i = 0; i < SYMLINK_CHAIN_MAX_HOPS; i += 1) {
-            let target;
+        return walkSymlinkChain(this.resolve(p), async (hop) => {
             try {
-                target = await fs.readlink(cur);
+                return ok(await fs.readlink(hop));
             }
             catch (e) {
-                const fe = this.fileError(e, cur, abortSignal);
-                if (fe.code === "invalid" || fe.code === "not_found" || fe.code === "not_directory")
-                    break;
-                return { ok: false, error: fe };
+                return { ok: false, error: this.fileError(e, hop, abortSignal) };
             }
-            let next;
-            if (path.isAbsolute(target))
-                next = target;
-            else {
-                const dir = path.dirname(cur);
-                next = dir.endsWith(path.sep) ? `${dir}${target}` : `${dir}${path.sep}${target}`;
-            }
-            if (seen.has(next))
-                break;
-            seen.add(next);
-            hops.push(next);
-            if (IS_WIN32 && UNC_SPELLING.test(next))
-                break;
-            cur = next;
-        }
-        return ok({ hops });
+        });
     }
     async exists(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1325,7 +1303,7 @@ export class RemoteHostExecutionEnv {
     }
     childEnv(perCommand, spawnShell) {
         const base = spawnShell !== undefined
-            ? hostSubprocessEnv({ site: "server.remote-env-host.inherit-scrub", policy: this.cfg.inheritEnv, allow: [] })
+            ? hostSubprocessEnv({ site: "server.remote-env-host.spawn-env", policy: this.cfg.inheritEnv, allow: [] })
             : composeHostSubprocessEnv({ policy: this.cfg.inheritEnv, allow: [] });
         if (this.cfg.env)
             Object.assign(base, this.cfg.env);