@sema-agent/server 7.130.0 → 7.132.0

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -437,13 +437,17 @@ export interface UnreadableRuleBucket {
     readonly ownerKey: string;
     readonly why: string;
 }
-/** M11 一次跑完的读数。 */
-export interface UndurableScopePurge {
-    readonly removed: readonly UndurableScopeRuleRow[];
+/**
+ * M11 写进的读数账 —— 三格与一次性迁移段那一只收据账(`one-time-migrations.ts` 的 `MigrationReceipts`)上的同名三格**同名同形**,迁移段把它的账直接递进来
+ * (S-1594:一次起服一只收据账,M11 不另起第二套):删掉的行在那只桶的回写**提交的那一刻**追加,之后任何一步失败,拒因随账带走它们。
+ */
+export interface UndurableScopePurgeReadings {
+    /** 删掉的行(一行一条读数;每只桶的回写提交之后才追加)。 */
+    readonly undurableScopeRuleRows: UndurableScopeRuleRow[];
     /** 连续争不过在线写者(OCC 每次都输)而留到下一次起服的桶数。那些桶里的坏行这期间照旧由引擎读侧丢掉并告知。 */
-    readonly bucketsDeferred: number;
+    undurableScopeRuleBucketsDeferred: number;
     /** 读腿整桶拒的桶(形 / 指纹 / behavior 闭集 / 墓碑规范文本 / 单一验证器):一个字节不动,逐桶交出拒因,等人处置。 */
-    readonly bucketsUnreadable: readonly UnreadableRuleBucket[];
+    readonly undurableScopeRuleBucketsUnreadable: UnreadableRuleBucket[];
 }
 /** {@link purgeUndurableScopeRows} 要的最小查询口(一次性迁移段的 `MigrationDb` 同形;占位符按方言由本函数写)。 */
 export interface UndurableScopePurgeDb {
@@ -458,13 +462,15 @@ export interface UndurableScopePurgeDb {
  * 而撤销口删不动它(引擎的写臂对这种 scope 的墓碑同样拒)。⇒ 一次性迁移,不留「撤销口对坏 scope 另开一条读法」的长期双读。
  *
  * 读法与写法都是**店的那一只**:每只桶先过唯一判官 {@link decodeBucketRow}(读腿用的同一只),判官整桶拒 ⇒ 这只桶**一个字节不动**,
- * 进 `bucketsUnreadable`(桶键 + 不带行内容的拒因;读腿对它的整桶拒仍是它的属主,出路是人);判官放行 ⇒ 在那份合法状态上筛 scope,
+ * 进 `undurableScopeRuleBucketsUnreadable`(桶键 + 不带行内容的拒因;读腿对它的整桶拒仍是它的属主,出路是人);判官放行 ⇒ 在那份合法状态上筛 scope,
  * 经写臂的同一只 {@link writeBucket} 整桶 OCC 回写(`WHERE owner_key = ? AND rev = ?`,rev+1,落盘字节与指纹同写臂)—— 不碰别的桶。
  * **硬删、不铸墓碑**:墓碑的作用是挡同步回灌,而引擎的 sync-join 对 scope 不合法的入站行本来就丢(`applySyncJoin`),
  * 本店也不实现同步(见 `apply` 的 sync-join 臂)。
  * 幂等:第二跑零命中零写(读不出的桶每一跑照报,直到有人处置)。
+ * 读数写进调用方递进来的账(`into`,{@link UndurableScopePurgeReadings}):删掉的行在那只桶的回写提交之后追加 ⇒ 本函数半途抛出时,已删的行已经在账上;
+ * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,S-1594)。
  */
-export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: "tidb" | "pg", now?: () => number): Promise<UndurableScopePurge>;
+export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: "tidb" | "pg", into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
  *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {

package/dist/plugins/permission-rule-store-sql.js

@@ -783,21 +783,7 @@ export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
 export const RULE_REAP_BATCH = 500;
 const UNDURABLE_PURGE_PAGE = 200;
 const UNDURABLE_PURGE_OCC_ATTEMPTS = 5;
-export async function purgeUndurableScopeRows(db, dialect, now = Date.now) {
-    const acc = { removed: [], bucketsDeferred: 0, bucketsUnreadable: [] };
-    try {
-        await purgeAllBuckets(db, dialect, now, acc);
-    }
-    catch (e) {
-        if (acc.removed.length === 0)
-            throw e;
-        throw new Error(`the one-time removal of persisted permission rules whose scope the engine refuses failed AFTER removing ${acc.removed.length} row(s) — record them before retrying: ` +
-            acc.removed.map((r) => `${r.kind} in bucket ${r.ownerKey} (${r.behavior} ${r.tool}, scope root ${JSON.stringify(r.scopeRoot)})`).join("; ") +
-            `. Underlying failure: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
-    }
-    return acc;
-}
-async function purgeAllBuckets(db, dialect, now, acc) {
+export async function purgeUndurableScopeRows(db, dialect, into, now = Date.now) {
     const cols = `owner_key, ${bucketRowColumns(dialect)}`;
     let after = "";
     for (;;) {
@@ -813,11 +799,11 @@ async function purgeAllBuckets(db, dialect, now, acc) {
                 const outcome = await purgeOneBucket(db, dialect, ownerKey, row, now);
                 switch (outcome.kind) {
                     case "purged":
-                        acc.removed.push(...outcome.rows);
+                        into.undurableScopeRuleRows.push(...outcome.rows);
                         settled = true;
                         break;
                     case "unreadable":
-                        acc.bucketsUnreadable.push({ ownerKey, why: outcome.why });
+                        into.undurableScopeRuleBucketsUnreadable.push({ ownerKey, why: outcome.why });
                         settled = true;
                         break;
                     case "clean":
@@ -835,7 +821,7 @@ async function purgeAllBuckets(db, dialect, now, acc) {
                 }
             }
             if (!settled)
-                acc.bucketsDeferred += 1;
+                into.undurableScopeRuleBucketsDeferred += 1;
         }
         if (page.length < UNDURABLE_PURGE_PAGE)
             break;

package/dist/plugins/pg-session-storage.d.ts

@@ -1,4 +1,4 @@
-import { BaseSessionStorage, type PromptEpochDescriptor, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type SessionRowPatch } from "../session-row.js";
@@ -30,10 +30,9 @@ export declare class PgSessionStorage extends BaseSessionStorage {
     private readonly sessionId;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
-    /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin
-     *  (keyset-paged to exhaustion: a bounded scan over restatement-less pre-epoch compactions would
-     *  misreport an epoch-bearing session as pre-epoch — codex HIGH). */
-    getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
+    /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin: the same reading
+     *  ({@link scanEpochAnchor}, the record as stored), this backend's page query. */
+    getEpochAnchor(): Promise<unknown>;
     /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static wake(pool: Pool, sessionId: string): Promise<PgSessionStorage | null>;
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */

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

@@ -1,8 +1,9 @@
 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";
@@ -82,21 +83,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.sessionId, 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;
+        });
     }
     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]);
@@ -516,7 +506,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

@@ -204,6 +204,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,10 @@ 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 { 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";
@@ -180,7 +181,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 +277,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 +419,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);