@sema-agent/server 7.81.0 → 7.82.1

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

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+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 {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
@@ -41,7 +41,23 @@ export interface AdbEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
 /** [R78]#1: adb stderr markers that mean the DEVICE TRANSPORT died mid-op (not a normal command failure) —
- *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests. */
+ *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests.
+ *
+ *  🔴 **S-401 把这个判据的输入面改了一半(复审 F12 纠正:原来写的「此前 stderr 恒空 ⇒ 整条是死码」是
+ *  **overclaim**,被本车自己的真机读数推翻)**。`exec-out` 合流的是**设备**的 stderr;**adb 客户端自己的**
+ *  诊断在两种传输下都照样走宿主 stderr。真机实测(同一台设备,拔掉 serial):
+ *  `adb -s BOGUS exec-out 'true'` ⇒ host exit **255** + stderr `error: device 'BOGUS' not found`;
+ *  `adb -s BOGUS shell -T -- 'true'` ⇒ host exit **1** + stderr `adb: device 'BOGUS' not found`。
+ *  ⇒ 本判据在 S-401 之前**对 adb 客户端级的传输故障是工作的**(这也正是原作者把词表写成这些 adb 自家
+ *  措辞的原因);S-401 改变的是**设备侧 stderr 从此也进这条通道**。
+ *
+ *  ⚠️ **随之而来的、如实登记的一格**:分流之后落到这里的 stderr **既有 adb 自己的诊断,也有设备命令自己的
+ *  输出**(adb 客户端把两者写在同一个 fd 上,真机实测无法在传输层分开)。于是设备上一条自己打印
+ *  `Connection reset by peer` 的命令(curl/nc)会被判成 `transport_lost`:本次命令结果不返回、`connected`
+ *  置假、下一次 exec fail-closed 直到 reconnect。**刻意不收窄词表**——词表收窄的方向是「漏判一次真掉线」,
+ *  那是 fail-open;误判的方向是多断一次连接,是 fail-closed。[ref] 轴上后者必须赢(能力探测的失败方向要与
+ *  能力语义方向一致)。ssh / k8s 两腿不吃这一格,因为它们的传输层自己给「通道关闭却没有 exit status」这个
+ *  **结构**信号;adb 的 shell v2 没有等价物,所以这里只能靠标记词,**这条臂就把话说在这里**。 */
 export declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     /**
@@ -123,8 +139,15 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     absolutePath(p: string): Promise<Result<string, FileError>>;
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
-    /** 文件面的终态门 —— 读面此前**连 `connected` 都不查**,所以 destroy 之后还能从真设备读出文件内容。
-     *  与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面都在 destroy 后 fail-closed)。 */
+    /** 文件面的门 —— 与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面在未连/已拆时都 fail-closed)。
+     *
+     *  🔴 **S-401 复审 F2:这道门此前只查 `destroyed`,不查 `connected`**,于是 `readBinaryFile` /
+     *  `readTextFile` / `readTextLines` / `appendFile` 能在**从没连过**的 env 上直接打一次真设备往返。
+     *  在本批之前那只是个不一致;本批**新开的 `shell_v2` fail-closed 闸就长在 `connect()` 里**,
+     *  所以「不查 connected」= 那道闸对整个读面**不生效** —— 而 `readTextFile` 把错误文本当文件内容返回
+     *  正是本 P1 点名的症状之一。闸的射程必须覆盖它要保护的每一个面,否则它只是一句话。
+     *  ⇒ 规则收成一条:**这只 env 在 connect 成功之前、destroy 之后,文件面一个字都不答。**
+     *  (`exec`/`execStream` 本就是这条规则,见 `:257`/`:276`;文件面从此同判,不再是两套。) */
     private fsGate;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -139,6 +162,10 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {
@@ -158,6 +185,42 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     }): Promise<Result<string, FileError>>;
     /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private adb;
+    /**
+     * 🔴 **S-401 —— 本适配器跑设备命令的唯一往返形**(`exec` / `execStream` / `readBinaryFile` 三个调用点
+     * 共用一只;此前 `exec-out` 写了三遍,于是「传输到底给不给退出码」这件事没有属主)。
+     *
+     * **`adb shell`(shell protocol v2)而不是 `adb exec-out`。** 协议出处 = adb 自己的 `adb help`:
+     * `-x: disable remote exit codes and stdout/stderr separation` —— 即**不带** `-x` 的 `adb shell` 就是
+     * 「远端退出码 + stdout/stderr 分流」那一形。`exec-out` 走的是另一条 `exec:` 服务:单条裸流,设备
+     * stderr **合流进 stdout**,宿主进程退出码**恒 0**。
+     *
+     * 真机实测(车GV 2026-09-17,SM-S721B / Android 15 / toybox 0.8.11 / adb 1.0.41 `35.0.2`,设备 features
+     * 含 `shell_v2`),逐条复现而不是从文档推断:
+     * - `exec-out 'false'` ⇒ 宿主 exit **0**;`shell -T -- 'false'` ⇒ **1**;`shell -T -- 'exit 7'` ⇒ **7**
+     * - `exec-out 'realpath -- <坏链>'` ⇒ exit 0 + 错误文本在 **stdout**;`shell -T --` ⇒ exit 1 + 在 **stderr**
+     * - 1 MiB 随机字节 `cat` 回读:两形 md5 **相同**(`shell -T` 无 CRLF 转换、无包裹字节),故 binary 面照用
+     * - 同一条 `realpath` 的墙钟:`shell -T` 68 ms/次 vs `exec-out` 79 ms/次(n=10)—— 不是性能代价
+     *
+     * 修前的后果链([ref] 安全轴静默 fail-open):共享基座 `posix-shell-fs.ts` 的**每一处**失败判据(7 处)
+     * 与链原语 `remote-shell.ts` 的 `runSymlinkChain`(第 8 处)认的都是 `exitCode !== 0`,而这条传输恒答 0
+     * ⇒ adb 腿上 `realpath` / `readlink` / `stat` / `ls` / `cat` **永不失败**,`canonicalPath` 把那行**错误
+     * 文本**当成 canonical key 交给敏感路径门。⚠️ **复审 F15 纠正:原文写「五处」是数错了**,而且漏掉的
+     * 第 8 处恰恰是最贵的一处 —— `canonicalChain`(S-362 / core 7.21.0 [ref],上一版刚接)在 exit 恒 0 下会把
+     * **合流进 stdout 的错误文本当成链上的跳**解析出来,等于给 core 的路径判官递一条**伪造的** symlink 链。
+     *
+     * 🔴 **`-T` 与 `--` 都是承重件,不是装饰**:
+     * - `-T` = 不分配 pty。带 pty 的交互 shell 会把 stderr 并进 stdout 并做 CRLF 转换(council §9.2 的那句话
+     *   本身没错,错的是它被用来给 `exec-out` 背书)。给了命令的 `adb shell` 默认本就不开 pty,`-T` 是**显式**
+     *   关闭,不依赖那个默认。
+     * - `--` = 终止 adb 自己的旗标解析。没有它,**首字符为 `-` 的设备命令会被 adb 当成自己的旗标吃掉**
+     *   (真机复现:`adb shell -T '-x'` 不报错,直接变成一个挂住的交互 shell)—— 而 `-x` 恰好就是关掉
+     *   远端退出码与分流的那根旗标,即「一条以 `-x` 开头的命令能静默把本修关回去」。真机验证 `--` 之后的
+     *   参数原样落到设备 shell(`adb shell -T -- '-x'` ⇒ 设备答 `/system/bin/sh: -c: requires an argument`)。
+     *
+     * 命令永远是**最后一个**参数,整条包在一个 argv 元素里(设备侧 `sh -c` 收全串,与 `withCwdEnv` 的
+     * `cd … && …` 前缀语义一致)。
+     */
+    private deviceShellArgs;
     private withCwdEnv;
 }
 /**

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

@@ -5,7 +5,7 @@ import { spawn } from "node:child_process";
 import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
-import { fileErrorFromExec } from "./remote-env-file-error.js";
+import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "adb";
 const ok = (value) => ({ ok: true, value });
@@ -76,6 +76,18 @@ export class RemoteAdbExecutionEnv {
         const state = st.value.stdout.trim();
         const err = `${st.value.stdout} ${st.value.stderr}`.toLowerCase();
         if (state === "device") {
+            const feats = await this.adb(["-s", this.cfg.serial, "features"], { signal, timeoutMs: this.cfg.commandTimeoutMs });
+            if (!feats.ok)
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `adb features failed: ${feats.error.message}`, feats.error) };
+            if (feats.value.exitCode !== 0) {
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `adb features exited ${feats.value.exitCode} for ${this.cfg.serial}: ${feats.value.stderr.trim().slice(0, 200) || "(no stderr)"} — could not read the device's feature list this attempt`) };
+            }
+            if (!/(^|\s)shell_v2(\s|$)/.test(feats.value.stdout.trim())) {
+                return {
+                    ok: false,
+                    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.`),
+                };
+            }
             this.connected = true;
             return ok(this.workspaceHandle());
         }
@@ -112,7 +124,7 @@ export class RemoteAdbExecutionEnv {
         if (!this.connected)
             return { ok: false, error: new ExecutionError("shell_unavailable", "ADB device not connected — call connect() first") };
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        const r = await this.adb(["-s", this.cfg.serial, "exec-out", wrapped], {
+        const r = await this.adb(this.deviceShellArgs(wrapped), {
             signal: options?.abortSignal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs,
             onStdout: options?.onStdout,
@@ -130,7 +142,7 @@ export class RemoteAdbExecutionEnv {
         if (!this.connected)
             throw new RemoteExecutionError("connect_failed", "ADB device not connected — call connect() first");
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.adbPath, ["-s", this.cfg.serial, "exec-out", wrapped], { stdio: ["ignore", "pipe", "pipe"] });
+        const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"] });
         const queue = [];
         let finished = false;
         let failure;
@@ -176,6 +188,7 @@ export class RemoteAdbExecutionEnv {
             if (queue.length >= 512 && !paused) {
                 paused = true;
                 child.stdout.pause();
+                child.stderr.pause();
             }
             signalReady();
         };
@@ -206,6 +219,7 @@ export class RemoteAdbExecutionEnv {
                 if (paused) {
                     paused = false;
                     child.stdout.resume();
+                    child.stderr.resume();
                 }
                 if (failure)
                     throw failure;
@@ -244,6 +258,8 @@ export class RemoteAdbExecutionEnv {
     fsGate(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
+        if (!this.connected)
+            return { ok: false, error: new FileError("unknown", "ADB device not connected — call connect() first", this.resolve(p)) };
         return undefined;
     }
     async readBinaryFile(p, abortSignal) {
@@ -251,21 +267,11 @@ export class RemoteAdbExecutionEnv {
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        const r = await this.adb(["-s", this.cfg.serial, "exec-out", `cat ${shellQuote(abs)}`], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
+        const r = await this.adb(this.deviceShellArgs(`cat ${shellQuote(abs)}`), { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
-        const errOut = r.value.stderr.trim();
-        if (errOut) {
-            if (/no such file/i.test(errOut))
-                return { ok: false, error: new FileError("not_found", errOut, abs) };
-            if (/permission denied/i.test(errOut))
-                return { ok: false, error: new FileError("permission_denied", errOut, abs) };
-            if (/is a directory/i.test(errOut))
-                return { ok: false, error: new FileError("is_directory", errOut, abs) };
-            return { ok: false, error: new FileError("unknown", errOut, abs) };
-        }
         if (r.value.exitCode !== 0)
-            return { ok: false, error: new FileError("unknown", `adb exec-out cat exited ${r.value.exitCode}`, abs) };
+            return { ok: false, error: classifyFsStderr(r.value.stderr.trim() || `adb cat exited ${r.value.exitCode}`, abs) };
         return ok(r.value.stdoutBytes ?? new Uint8Array(0));
     }
     async readTextFile(p, abortSignal) {
@@ -284,6 +290,9 @@ export class RemoteAdbExecutionEnv {
         return ok(lines);
     }
     async writeFile(p, content, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
         const abs = this.resolve(p);
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
@@ -348,6 +357,9 @@ export class RemoteAdbExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }
@@ -433,6 +445,9 @@ export class RemoteAdbExecutionEnv {
             });
         });
     }
+    deviceShellArgs(command) {
+        return ["-s", this.cfg.serial, "shell", "-T", "--", command];
+    }
     withCwdEnv(command, cwd, env) {
         const parts = [];
         const dir = cwd ?? this.cwd;

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

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
+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 ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } 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];
 /** Minimal optional observability hooks (kept structural so the adapter stays standalone-testable). */
@@ -250,6 +250,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  缺它 ⇒ 合法的悬空链接让整个工具调用失败。必须返回**原始链接目标**(`readlink` 不带 `-f`)。
      *  本腿的文件面也走 `exec`(与 canonicalPath 同通道),所以实现方式与 shell 腿一致。 */
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。本腿的文件面走原生 SDK 的
+     *  `exec`([ref] B6 的既有裁决:host 与 e2b 是原生 API 腿,**不并**进 `posix-shell-fs` 基座),但
+     *  「链怎么走、怎么读」与四条 shell 腿**是同一份**:脚本与读法的单一属主在 `remote-shell.ts`,这里只多一行
+     *  传输。一次往返、上限 64、只锚不折、遇环即止;`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。
+     *  🔴 exit≠0 归 `unknown` 而不是 `not_found`(与本腿 `readLink` 那一格刻意分家,同 `posix-shell-fs` 的理由):
+     *  「叶不是软链」与「叶不存在」在这条命令上都是 exit 0 + 空 stdout,所以 exit≠0 一定不是「文件不在」。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -2,7 +2,7 @@ import path from "node:path";
 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, shellQuote } from "./remote-shell.js";
+import { numEnvOr, runSymlinkChain, shellQuote } from "./remote-shell.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
 const DEFAULT_MOUNT_PATH = "/home/user";
@@ -692,6 +692,9 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: new FileError("not_found", r.value.stderr.trim() || `readlink failed for ${abs}`, abs) };
         return ok(r.value.stdout.trim());
     }
+    async canonicalChain(p, abortSignal) {
+        return runSymlinkChain(this.resolve(p), (cmd) => this.exec(cmd, { abortSignal }));
+    }
     async canonicalPath(p, abortSignal) {
         const abs = this.resolve(p);
         const r = await this.exec(`realpath -- ${shellQuote(abs)}`, { abortSignal });

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

@@ -1,4 +1,4 @@
-import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundPoll, type BackgroundSpawnOptions } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, 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, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundPoll, type BackgroundSpawnOptions } 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 RemoteHostExecutionEnv}. */
@@ -216,6 +216,20 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     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` 对网络拼法只给拼法)。
+     *
+     * 🔴 **不复用 core 的实现而是同形重写**:`NodeExecutionEnv` 是 core 的内部类,包根不导出它的这只方法;
+     * 而本腿的每一次读都必须先过 {@link fsReady}(2026-07-25 全族统一:拆除之后只读面不得与写面自相矛盾),
+     * 那道门在 core 的实现里不存在。同形的判据钉在 `test/remote-env-canonical-chain.test.ts`。
+     *
+     * 链尽的三种 errno(`EINVAL` 不是软链 / `ENOENT` 不存在 / `ENOTDIR`)⇒ `ok` + 到此为止的跳;其余 errno
+     * (`EACCES` …)⇒ `ok:false`(core 读作「这一次没有跳」,**永不是拒绝**)。非链接的叶答 `[]`。
+     */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {
         recursive?: boolean;

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

@@ -5,7 +5,7 @@ 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 } from "./remote-shell.js";
+import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
@@ -22,6 +22,7 @@ const HOST_BG_FILE_CAP = numEnvOr("HOST_BG_FILE_CAP", 64 * 1024 * 1024, HOST_BG_
 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)`),
@@ -1006,6 +1007,41 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: this.fileError(e, abs, abortSignal) };
         }
     }
+    async canonicalChain(p, abortSignal) {
+        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;
+            try {
+                target = await fs.readlink(cur);
+            }
+            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 };
+            }
+            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 (process.platform === "win32" && UNC_SPELLING.test(next))
+                break;
+            cur = next;
+        }
+        return ok({ hops });
+    }
     async exists(p, abortSignal) {
         const ready = await this.fsReady(p);
         if (!ready.ok)

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

@@ -1,4 +1,4 @@
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, 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 { 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";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
@@ -310,6 +310,10 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -919,6 +919,9 @@ export class RemoteK8sExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

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

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+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}. */
@@ -166,6 +166,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-local-docker.js

@@ -406,6 +406,9 @@ export class RemoteLocalDockerExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

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

@@ -1,5 +1,5 @@
 import { type SshHostKeyPolicy } from "../ssh-host-key.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+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 SshEnvConfig {
     host: string;
@@ -171,6 +171,10 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private posixFsInst?;
     private get posixFs();
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -548,6 +548,9 @@ export class RemoteSshExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-shell.d.ts

@@ -2,7 +2,7 @@
  * Shared shell/path helpers for the SSH + ADB `RemoteExecutionEnv` adapters. Kept in ONE place so the
  * security-sensitive quoting can't drift between adapters (council design/#4, #5).
  */
-import type { FileInfo } from "@sema-agent/core";
+import type { ExecutionError, FileError, FileInfo, RemoteExecutionError, Result, SymlinkChain } from "@sema-agent/core";
 import type { ChildProcess } from "node:child_process";
 /**
  * D5 pipe-destroy grace (parity with core's vendored `EXEC_FORCE_SETTLE_GRACE_MS`, harness/env/nodejs.js):
@@ -32,4 +32,77 @@ export declare function drainNumEnvWarnings(): Array<{
     raw: string;
 }>;
 export declare function numEnvOr(name: string, def: number, min: number): number;
+export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
+/**
+ * 一次往返走完叶 symlink 链的 POSIX sh 脚本(**纯数据**:返回一个命令串 ⇒ `build*`,CLAUDE.md 工厂律)。
+ *
+ * 🔴 `readlink` **缺失**必须与「不是软链」分开:两者在 shell 里都是 exit≠0,而 `|| break` 会把「工具不在」
+ *   静默读成「零跳」—— 那是安全轴上的静默兜底(链视图整条消失,判官少一个视图)。所以脚本**先探**一次
+ *   `command -v`,缺失时打一句 `readlink: not found` 到 stderr 并 exit 127 —— 那句话正好命中
+ *   {@link import("./remote-env-file-error.js").classifyFsStderr} 的**命令缺失护栏**(它把命令缺失归
+ *   `unknown` 而不是 `not_found`),于是调用方拿到的是 `ok:false`(core 读作「这一次没有跳」,永不是拒绝)
+ *   而不是一个伪造的空链。
+ *
+ * 🔴 **整条命令包在一个 `{ …; }` 里**,理由是**调用方会给它加前缀**:四条腿的 `withCwdEnv` 都拼
+ *   `cd <dir> && <命令>`(ssh `:760` / k8s `:1418` / adb `:578` / local-docker 同形)。这里连着犯过两次错,
+ *   两次都记下来,因为它们是**同一个坑的两面**:
+ *   · 写成 `command -v … || { …; }`:`||` 与前缀的 `&&` 结成一条链(`cd X && command -v … || { … }`),
+ *     **`cd` 失败时跑的是探测的失败臂** —— 报「readlink 不在」而真相是「那个目录没了」,运维去修一个没坏的东西;
+ *   · 改成独立语句 `if ! …; fi; c=…; while …`:前缀的 `&&` 只短路**那一条 `if`**,后面的循环照跑 ——
+ *     于是「`cd` 失败 ∧ readlink 缺失」这一格里,`|| break` 把工具缺失吞成零跳,脚本 **exit 0 + 空 stdout**,
+ *     调用方拿到一条**伪造的空链**。这正是探测本来要挡的那个静默兜底([ref] 轴),换了个入口回来了。
+ *   ⇒ 正解是**让整条命令只有一个退出状态**:包进 `{ …; }`,前缀的 `&&` 要么统治全部、要么全部不跑。
+ *     `cd` 失败 ⇒ 退出码来自 `cd` 自己、stderr 是它自己的话 ⇒ `ok:false`(core 读作「这一次没有跳」),
+ *     诚实且指向真因;`cd` 成功 ⇒ 探测与循环照旧。`{ }` 不是子 shell,里面的 `exit 127` 照样结束整条命令。
+ *
+ * 词法细节(逐条对着 core 的 Node 实现写,两边同形):绝对目标直接接上;相对目标用参数展开
+ * `${c%/*}` 取**当前这条链接**所在目录(不调 `dirname` —— toybox 的 `dirname` 不认 `--`,且这里零外部命令
+ * 更省一次 fork),根目录那一格(`${c%/*}` 为空)补 `/`。**全程不折叠 `..`**。
+ */
+export declare function buildSymlinkChainCommand(absPath: string): string;
+/**
+ * {@link buildSymlinkChainCommand} 的 stdout → `SymlinkChain.hops`。
+ *
+ * 三件事**只在这里**做一次(四条 shell 腿 + e2b 共读):
+ *  · **环即止** —— 出现重复跳时在**重复的那一跳之前**截断(CC `vr` 的 `d.has(u)` 同律),且 seen 表用
+ *    **被寻址的拼法播种**(S-408,core 裁 2026-09-17:契约句「不重复被寻址的拼法」的正解是**起点本身不是一跳**——
+ *    链视图列的是「从被寻址拼法出发经过的中间拼法」,链绕回起点即结束、起点不再列;成环的事实由终点判决
+ *    `canonicalPath`(realpath ELOOP ⇒ unresolvable ⇒ 拒)承担,不由链视图承担)。于是 `a -> b`、`b -> a`,问 `a`,
+ *    答 `[b]`,与 core `NodeExecutionEnv.canonicalChain`(`new Set([resolved])` 播种)逐字节同形。此前本族从空表
+ *    开始、答 `[b, a]`(7.82.0 及之前;多一个冗余视图 —— 判官对 `a` 已按拼法判过一次),裁定后对齐。
+ *    脚本侧不做:
+ *    POSIX sh 里维护一张 seen 表要么靠内嵌换行的 `case` 模式(易碎),要么另起一个进程;放在这里则
+ *    **一份实现**被四条腿与 e2b 共用,且与 host 腿的 Node 循环逐字节对得上。代价如实登记:链上真有环时,
+ *    远端在**那一次往返内**最多多跑到 64 次 `readlink`(有界,不是无界探测),而报出来的跳与 host 腿相同。
+ *  · **上限 64** —— 脚本已经封顶,这里再切一次是对**传输层**的不信任(答多了不当真),不是第二份判据。
+ *  · **逐行 trim** —— 与本族 `readLink` 的既有姿态**同一条**(基座头注:链接目标含换行是病态形,按 trim
+ *    处理,不假装支持)。残留如实写出来:目标拼法真带首尾空白时,trim 后的跳可能与真目标差几个字节 ——
+ *    方向上只会让一条跳**匹配不到**受保护行(少问,不是多放行),而终点判决(`canonicalPath`)完全不经本路。
+ */
+export declare function symlinkChainHopsFromStdout(stdout: string, addressed: string): string[];
+/** {@link runSymlinkChain} 的传输面 —— 各腿的 `exec` 收敛成的那一个形(与 `PosixShellFs` 基座的 `run` 同形)。 */
+export type ShellChainRun = (cmd: string) => Promise<Result<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}, ExecutionError | RemoteExecutionError>>;
+/**
+ * **shell 形 `canonicalChain` 的全部半场,一处**(对抗复审 F4 [low],验真后按类修)。
+ *
+ * 此前脚本与读法收在这里,而「怎么把它们接到传输上、exit≠0 怎么归码」在**两处**各写一遍:
+ * `posix-shell-fs.ts`(四条 shell 腿)与 `remote-env-e2b.ts`(原生 SDK 腿)。两份五行代码语义相同、
+ * 错误归类却各写各的,于是「e2b 与四条 shell 腿答得一样」只靠一句注释担保 —— 复审的换靶变异实测:
+ * 把 e2b 那五行改成 `return ok({ hops: [] })`,**全部钉照绿**。收成一只函数之后,那条担保是结构事实:
+ * 两边调的是同一个函数,分叉无处可生;基座上那一整套行为钉同时就是 e2b 的钉。
+ *
+ * 归码(两腿共用同一条,不再各写各的):
+ *  · 传输自己失败 ⇒ {@link fileErrorFromExec}(`aborted` 穿透,其余诚实降级 `unknown`);
+ *  · exit≠0 ⇒ {@link classifyFsStderr} 且 fallback 取 **`unknown` 而不是 `not_found`** —— 这条命令上
+ *    「叶不是软链」与「叶不存在」**都是 exit 0 + 空 stdout**(脚本里的 `|| break`),所以任何 exit≠0
+ *    都**不是**「这个文件不在」,而是解析器自己出了事(工具缺失 / cwd 没了 / 传输坏 / shell 拒)。
+ *    把它折成 `not_found` 会让运维去找一条根本没丢的路径。
+ *    ⚠️ 例外由 `classifyFsStderr` 自己认:`cd` 失败那一格的 stderr 里真带「No such file」,它按**那句话**
+ *    归 `not_found` —— 那时真的有一条路径没了(工作目录),所以那个码是对的。
+ */
+export declare function runSymlinkChain(absPath: string, run: ShellChainRun): Promise<Result<SymlinkChain, FileError>>;
 //# sourceMappingURL=remote-shell.d.ts.map

package/dist/plugins/remote-shell.js

@@ -1,3 +1,4 @@
+import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
 export function armPipeDestroyGrace(child) {
     const t = setTimeout(() => {
@@ -36,4 +37,38 @@ export function numEnvOr(name, def, min) {
     }
     return Math.max(min, (Number.isFinite(n) ? n : 0) || def);
 }
+export const SYMLINK_CHAIN_MAX_HOPS = 64;
+export function buildSymlinkChainCommand(absPath) {
+    return (`{ if ! command -v readlink >/dev/null 2>&1; then printf 'readlink: not found\\n' >&2; exit 127; fi; ` +
+        `c=${shellQuote(absPath)}; n=0; ` +
+        `while [ "$n" -lt ${SYMLINK_CHAIN_MAX_HOPS} ]; do ` +
+        `t=$(readlink -- "$c") || break; ` +
+        `case "$t" in "") break ;; /*) c="$t" ;; ` +
+        `*) d="${"${c%/*}"}"; case "$d" in "") c="/$t" ;; */) c="$d$t" ;; *) c="$d/$t" ;; esac ;; esac; ` +
+        `printf '%s\\n' "$c"; n=$((n+1)); done; }`);
+}
+export function symlinkChainHopsFromStdout(stdout, addressed) {
+    const hops = [];
+    const seen = new Set([addressed]);
+    for (const raw of stdout.split("\n")) {
+        const hop = raw.trim();
+        if (hop === "")
+            continue;
+        if (seen.has(hop))
+            break;
+        seen.add(hop);
+        hops.push(hop);
+        if (hops.length >= SYMLINK_CHAIN_MAX_HOPS)
+            break;
+    }
+    return hops;
+}
+export async function runSymlinkChain(absPath, run) {
+    const r = await run(buildSymlinkChainCommand(absPath));
+    if (!r.ok)
+        return { ok: false, error: fileErrorFromExec(r.error, absPath) };
+    if (r.value.exitCode !== 0)
+        return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
+    return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout, absPath) } };
+}
 //# sourceMappingURL=remote-shell.js.map