@sema-agent/server 7.92.0 → 7.92.1

package/dist/config-catalog.js

@@ -163,6 +163,7 @@ export const CONFIG_CATALOG = [
     r("HOST_BG_READ_CAP", "orchestration", "number", "host 后台 shell 每次轮询增量读上限(字节)", { staticDefault: String(1024 * 1024) }),
     r("HOST_COMMAND_TIMEOUT_MS", "orchestration", "number", "host 车道单命令超时(ms)"),
     r("HOST_EXEC_SPOOL_ENABLED", "orchestration", "boolean", "host 车道执行 spool 开关", { staticDefault: "true" }),
+    r("HOST_FS_DRAIN_WAIT_MS", "orchestration", "number", "host 执行环境拆除时等在飞文件写落地的上界(ms;到点 destroy 返回,rm 仍排在那批写之后;下限 1)", { staticDefault: "10000" }),
     r("HOST_SHELL_PATH", "orchestration", "path", "host 车道 shell 覆写口(POSIX 与 win32 同源解析)"),
     r("HOST_WORKSPACE_BASE", "orchestration", "path", "host 车道工作区 base"),
     r("IMAGE_BAKES_ENABLED", "orchestration", "boolean", "烤镜像 job API(/v1/images/bakes*;需 SQL 池 + 非空 operator 名单,boot 断言)", { staticDefault: "false", danger: SEC }),

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

@@ -103,6 +103,55 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
+    /** 🔴 S-539 在飞的 fs **写**登记表(`liveFgSpools` 同律:「还有人在动这棵树,就别删它」)。
+     *  为什么按 promise 存而不是计数:只有 promise 才能被 `destroy()` **await**;计数只能轮询。 */
+    private readonly inflightFs;
+    /** 一次性:慢 drain 只抱怨一次(一条按次数刷屏的 teardown 读数没人会看)。 */
+    private inflightFsDrainWarned;
+    /**
+     * 🔴 S-539 —— 把一只**会在 workspace / spool 根里建路径或改路径**的 fs 动作登记为「在飞」,直到它 settle。
+     *
+     * ── 病(旧 `destroy()` 的自称与实情)──────────────────────────────────────────────────────────
+     * `destroy()` 只 await 了 `ensurePrepared()` 那只 memo(`preparing`),于是它顶注里的
+     * 「eliminating the prepared-flag race entirely」只对 **prepare 那一段**成立。写面在
+     * `await this.fsReady(p)` 放行**之后**还会自己碰一次磁盘(`writeFile`/`appendFile` 的
+     * `mkdir(dirname)`、`createDir` 的 `mkdir`、`createTempDir`/`createTempFile` 在 spool 根下建),
+     * 那一次调用与 destroy 的 `fs.rm` 是**两条独立 fs 调用在 libuv 线程池里赛跑**:rm 先 ⇒ `mkdir -p` 把已拆除
+     * 的工作区重建成**孤儿**(而 rm 成功后 `untrackEphemeralHostWorkspace()` 已注销 ⇒ 兜底腿也捞不回);
+     * mkdir 先 ⇒ 随后 rm 删掉,调用方拿到 `EINVAL`/`ENOENT` 而不是 "already destroyed"。
+     *
+     * ── 治(一处定义,十几个面共用)────────────────────────────────────────────────────────────────
+     * 调用点必须在方法体的**第一个同步段**里调它(第一个 `await` 之前),登记才与 `destroy()` 置 `destroyed`
+     * 的同步段互斥。于是二者只有两种相对次序,**两种都安全**:
+     *  · 先登记 ⇒ destroy 的快照看得到它,`rm` 等它 settle 之后才发;
+     *  · 后登记 ⇒ 这一面自己的 `fsReady` 看得到 `destroyed`,一个字节都不碰磁盘。
+     * 登记放在 `await this.fsReady(...)` **之后**就没有这个性质:那一刻已经跨过一个 microtask,destroy 可能刚好
+     * 在这中间把快照取完了。所以形状是 `return this.withInflightFs(async () => { …原方法体… })`,
+     * 而不是在方法体里补一句 `if (this.destroyed)` —— 后者仍然不原子(查完到动手之间还有让出点)。
+     *
+     * ── 读面刻意不进来 ─────────────────────────────────────────────────────────────────────────────
+     * ① 读不建路径:拆除之后一次在飞的读拿到 ENOENT 是**诚实**的,复活目录这条病与它无关;
+     * ② 把读拉进来会让 teardown 去等一次可能**永不 settle** 的读(workspace 里的 FIFO / 特殊文件),
+     *    把 destroy 挂死 —— 拿一条新的可用性病换一条不存在的正确性收益。
+     * 判据因此是一句话:**「可能建路径或改路径的那些面」进在飞集合**,不是「过了 fsReady 的都进」。
+     */
+    private withInflightFs;
+    /**
+     * 等 `destroy()` 取到的那批在飞写全部 settle。**永不抛**;答「在时限内清空了吗」。
+     *
+     * 🔴 两条都不能要,所以有第三条(合并复审 [high] 打出来的):
+     *  ① 无界等 —— workspace 里的 FIFO / 特殊文件会让一次 `writeFile` **永不 settle**,而拆除在 run 收尾路径上
+     *     ⇒ 整条收尾停摆。用一条新的可用性病换一条正确性收益,不划算。
+     *  ② 到点就照删 —— 把 S-539 的竞态**原样**搬回来(rm 与在飞 mkdir 再次在线程池里赛跑),只是把窗口从
+     *     「总是」改成「慢的时候」;一条确定的病换一条间歇的病,更糟。
+     *  ③ **到点就不再占着调用方,但 rm 依旧排在那批写之后**(`destroy()` 里的 `void …then(removeOwnedTrees)`)。
+     *     次序保证一个字节不松,teardown 变成「有界返回」。teardown 契约(core 1.258.2)禁的是**抛**,不是**慢**;
+     *     这一条连慢都不欠。
+     *
+     * 快照是 `destroy()` 在同步段取的,所以 destroy **之后**才登记的那些面(唯一一族:`appendFile` 的
+     * `lingeringBgWrite` 残余镜像写)不在这一批里 —— 它们按设计就是跨 destroy 存活的,等它们等于等后台 shell。
+     */
+    private drainInflightFs;
     private ensureSpoolRoot;
     /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
     private readonly persistent;
@@ -155,6 +204,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
      *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     destroy(): Promise<void>;
+    /** `destroy()` 真正动手删的那一段(本 env **自有**的两棵树:spool 根 + ephemeral workspace)。
+     *  抽成一只是因为它有两个调用时机 —— 在飞写按时清空时由 `destroy()` 直接 await,超时时挂在那批写后面异步跑
+     *  (见 {@link drainInflightFs} 头注③)。永不抛(teardown 契约)。 */
+    private removeOwnedTrees;
     cleanup(): Promise<void>;
     get backgroundCapabilities(): BackgroundShellCapability["backgroundCapabilities"];
     private _bgManager?;
@@ -210,7 +263,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** S-539:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
+     *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
+     *  (`lingeringBgWrite`):那一族登记在 destroy 的快照**之后**,所以 destroy 不会去等它们 —— 正确,
+     *  它们按设计跨 destroy 存活(等它们等于等后台 shell)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -231,10 +289,14 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。 */
     createDir(p: string, options?: {
         recursive?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面**不会**复活目录(`fs.rm` 只删),进在飞集合的理由是
+     *  同一条:destroy 的 rm 把树从它脚下抽走 ⇒ 一次本该 ok 的删返回 `not_found`。判据是「可能建或改路径」,
+     *  不是「可能复活目录」—— 少一条例外就少一处以后要重新想清楚的地方。 */
     remove(p: string, options?: {
         recursive?: boolean;
         force?: boolean;
@@ -252,7 +314,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
      *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
      *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。这一面建在 **spool 根**下,而 destroy 也会整树删那个根 ——
+     *  `fs.mkdtemp` 不建父目录,所以它不会复活什么,坏处是一次本该成功的调用返回 `not_found`。 */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注;spool 根同 `createTempDir`)。 */
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;

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

@@ -14,6 +14,7 @@ import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
 const HOST_BG_MAX_CONCURRENT = numEnvOr("HOST_BG_MAX_CONCURRENT", 8, 1);
 const HOST_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("HOST_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const HOST_BG_MAX_TIMEOUT_SEC = numEnvOr("HOST_BG_MAX_TIMEOUT_SEC", 1800, HOST_BG_DEFAULT_TIMEOUT_SEC);
@@ -62,6 +63,41 @@ export class RemoteHostExecutionEnv {
     destroyed = false;
     spoolRootDir;
     liveFgSpools = new Set();
+    inflightFs = new Set();
+    inflightFsDrainWarned = false;
+    withInflightFs(fn) {
+        const p = fn();
+        this.inflightFs.add(p);
+        const forget = () => void this.inflightFs.delete(p);
+        void p.then(forget, forget);
+        return p;
+    }
+    async drainInflightFs(inflight) {
+        if (inflight.length === 0)
+            return true;
+        const settled = Promise.allSettled(inflight);
+        const waitMs = inflightFsDrainWaitMs();
+        const timedOut = Symbol("inflight-fs-drain-timeout");
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(timedOut), waitMs);
+            timer.unref?.();
+        });
+        try {
+            const drained = (await Promise.race([settled, deadline])) !== timedOut;
+            if (!drained && !this.inflightFsDrainWarned) {
+                this.inflightFsDrainWarned = true;
+                console.warn(`RemoteHostExecutionEnv.destroy: ${this.inflightFs.size} in-flight filesystem write(s) did not settle within ` +
+                    `${waitMs}ms — returning from teardown now; removal of ${this.workspaceDir} stays ordered AFTER those writes ` +
+                    `and will land when they finish (a write that never settles, e.g. a FIFO target inside the workspace, defers it)`);
+            }
+            return drained;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     ensureSpoolRoot() {
         if (!this.spoolRootDir)
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
@@ -130,25 +166,32 @@ export class RemoteHostExecutionEnv {
         this.destroyed = true;
         const p = this.preparing;
         this.preparing = undefined;
+        const inflight = [...this.inflightFs];
         try {
             await p?.catch(() => { });
         }
         finally {
-            if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
-                try {
-                    await fs.rm(this.spoolRootDir, { recursive: true, force: true });
-                }
-                catch { }
-                this.spoolRootDir = undefined;
-            }
-            if (this.persistent)
-                return;
+            if (await this.drainInflightFs(inflight))
+                await this.removeOwnedTrees();
+            else
+                void Promise.allSettled(inflight).then(() => this.removeOwnedTrees());
+        }
+    }
+    async removeOwnedTrees() {
+        if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
             try {
-                await fs.rm(this.workspaceDir, { recursive: true, force: true });
-                untrackEphemeralHostWorkspace(this.workspaceDir);
-            }
-            catch {
+                await fs.rm(this.spoolRootDir, { recursive: true, force: true });
             }
+            catch { }
+            this.spoolRootDir = undefined;
+        }
+        if (this.persistent)
+            return;
+        try {
+            await fs.rm(this.workspaceDir, { recursive: true, force: true });
+            untrackEphemeralHostWorkspace(this.workspaceDir);
+        }
+        catch {
         }
     }
     async cleanup() {
@@ -905,37 +948,41 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: this.fileError(e, abs, abortSignal) };
         }
     }
-    async writeFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.writeFile(abs, data, { signal: abortSignal });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    writeFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.writeFile(abs, data, { signal: abortSignal });
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
-    async appendFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p, { lingeringBgWrite: true });
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            if (abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.appendFile(abs, data);
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    appendFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p, { lingeringBgWrite: true });
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                if (abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.appendFile(abs, data);
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
     async fileInfo(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1058,66 +1105,74 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: fe };
         }
     }
-    async createDir(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(abs, { recursive: options?.recursive ?? true });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
-        }
-    }
-    async remove(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            if (!options?.force) {
-                await fs.lstat(abs);
+    createDir(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(abs, { recursive: options?.recursive ?? true });
+                return ok(undefined);
             }
-            await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
-            return ok(undefined);
-        }
-        catch (e) {
-            const fe = this.fileError(e, abs, options?.abortSignal);
-            if (options?.force && fe.code === "not_found")
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
+            }
+        });
+    }
+    remove(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                if (!options?.force) {
+                    await fs.lstat(abs);
+                }
+                await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
                 return ok(undefined);
-            return { ok: false, error: fe };
-        }
+            }
+            catch (e) {
+                const fe = this.fileError(e, abs, options?.abortSignal);
+                if (options?.force && fe.code === "not_found")
+                    return ok(undefined);
+                return { ok: false, error: fe };
+            }
+        });
     }
-    async createTempDir(prefix = "tmp-", abortSignal) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        try {
-            return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
-        }
+    createTempDir(prefix = "tmp-", abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            try {
+                return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
+            }
+        });
     }
-    async createTempFile(options) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        const prefix = options?.prefix ?? "";
-        const suffix = options?.suffix ?? "";
-        try {
-            const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
-            const abs = path.join(this.ensureSpoolRoot(), name);
-            if (options?.abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            await fs.writeFile(abs, "", { flag: "wx" });
-            return ok(abs);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
-        }
+    createTempFile(options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            const prefix = options?.prefix ?? "";
+            const suffix = options?.suffix ?? "";
+            try {
+                const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
+                const abs = path.join(this.ensureSpoolRoot(), name);
+                if (options?.abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                await fs.writeFile(abs, "", { flag: "wx" });
+                return ok(abs);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
+            }
+        });
     }
     resolve(p) {
         return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
@@ -1207,7 +1262,7 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
-        return inside(this.workspaceDir) || (this.spoolRootDir !== undefined && inside(this.spoolRootDir));
+        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.92.0",
+  "version": "7.92.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",