@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/remote-env-file-error.d.ts

@@ -1,4 +1,38 @@
+/**
+ * shell 型 execution-env 适配器把一次 **exec 失败**包成 `FileError` 时的**共享码映射**。
+ *
+ * ── 为什么需要它(2026-07-25,深挖第一轮的跨腿对拆)────────────────────────────────────────────────
+ * `ssh` / `k8s` / `adb` / `local-docker` 的文件面都是「发一条 shell 命令,再把 `ExecutionError` 包成
+ * `FileError`」。**28 处**包装点写的全是同一句 `new FileError("unknown", r.error.message, …)` ——
+ * 于是 exec 层已经正确分类出来的 `aborted`(用户取消)在文件层被**一律抹成 `unknown`**。
+ *
+ * 🔴 后果不是"码不好看":`FileErrorCode` 里的 `aborted` 存在的唯一意义,就是让调用方分辨
+ * **「用户取消」与「硬失败」**。抹成 unknown 之后:①一次取消被措辞成失败;②任何 keyed-on-code 的重试
+ * 会把**已被取消的操作再打一遍**。host 腿没有这个问题,因为它直接用 `fs` + 自己的分类器
+ * (AbortError → `aborted`)—— 也就是说这 4 条腿丢的正是 host 腿有的那个信息。
+ *
+ * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [1689] RB-74
+ * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
+ * **文件面的 exec 包装必须走这里**,而这条能被机器检查(见 `test/env-adapter-file-error-parity.test.ts`)。
+ */
 import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema-agent/core";
+/** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionError, path?: string): FileError;
+/**
+ * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器(design/158 B6 R2 裁决:k8s 形=正形)。
+ *
+ * 此前四腿三向分叉:ssh/adb 硬编码 `not_found`(把 EACCES 谎报成"不存在"——keyed-on-code 的调用方会
+ * 对一个权限问题走"不存在"分支);local-docker 分类但无 fallback(缺文件报 unknown),且其
+ * `/no such file|not found/` 宽包含会把 `sh: realpath: not found`(**命令**缺失,127)误判成**文件**不存在。
+ *
+ * 护栏次序是本函数的语义主体,先于分类:
+ *  1. 命令缺失形(`command not found` / `applet not found` / `: not found`)→ `unknown` —— 工具不存在
+ *     不是文件不存在;probe 族的 not_found fallback 绝不能吞它。
+ *  2. 完整硬失败(EIO/ELOOP/ENAMETOOLONG/ENOSPC)→ `unknown` —— 同 k8s 原注:真错不被 read-op 的
+ *     not_found fallback 吞掉。
+ *
+ * `fallback` 由站点显式给:probe 族(readlink/realpath/stat——"它在吗"类问题)传 `not_found`
+ * (空 stderr + exit≠0 的主导原因就是缺文件);mutate 族(mkdir/rm/mktemp)传 `unknown`(诚实降级)。
+ */
 export declare function classifyFsStderr(stderr: string, p: string | undefined, fallback?: "unknown" | "not_found"): FileError;
 //# sourceMappingURL=remote-env-file-error.d.ts.map

package/dist/plugins/remote-env-file-error.js

@@ -1,8 +1,45 @@
+/**
+ * shell 型 execution-env 适配器把一次 **exec 失败**包成 `FileError` 时的**共享码映射**。
+ *
+ * ── 为什么需要它(2026-07-25,深挖第一轮的跨腿对拆)────────────────────────────────────────────────
+ * `ssh` / `k8s` / `adb` / `local-docker` 的文件面都是「发一条 shell 命令,再把 `ExecutionError` 包成
+ * `FileError`」。**28 处**包装点写的全是同一句 `new FileError("unknown", r.error.message, …)` ——
+ * 于是 exec 层已经正确分类出来的 `aborted`(用户取消)在文件层被**一律抹成 `unknown`**。
+ *
+ * 🔴 后果不是"码不好看":`FileErrorCode` 里的 `aborted` 存在的唯一意义,就是让调用方分辨
+ * **「用户取消」与「硬失败」**。抹成 unknown 之后:①一次取消被措辞成失败;②任何 keyed-on-code 的重试
+ * 会把**已被取消的操作再打一遍**。host 腿没有这个问题,因为它直接用 `fs` + 自己的分类器
+ * (AbortError → `aborted`)—— 也就是说这 4 条腿丢的正是 host 腿有的那个信息。
+ *
+ * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [1689] RB-74
+ * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
+ * **文件面的 exec 包装必须走这里**,而这条能被机器检查(见 `test/env-adapter-file-error-parity.test.ts`)。
+ */
 import { FileError } from "@sema-agent/core";
+/** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export function fileErrorFromExec(e, path) {
+    // `aborted` 是唯一必须穿透的一条:它是调用方区分「取消」与「失败」的唯一机器判据。
+    // 其余 exec 码(shell_unavailable / transport_lost / connect_failed / timeout …)在文件层没有对位语义,
+    // 落 `unknown` 是诚实的 —— 但**消息与 cause 都保留**,排障信息不丢。
     const code = e.code === "aborted" ? "aborted" : "unknown";
     return new FileError(code, e.message, path, e);
 }
+/**
+ * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器(design/158 B6 R2 裁决:k8s 形=正形)。
+ *
+ * 此前四腿三向分叉:ssh/adb 硬编码 `not_found`(把 EACCES 谎报成"不存在"——keyed-on-code 的调用方会
+ * 对一个权限问题走"不存在"分支);local-docker 分类但无 fallback(缺文件报 unknown),且其
+ * `/no such file|not found/` 宽包含会把 `sh: realpath: not found`(**命令**缺失,127)误判成**文件**不存在。
+ *
+ * 护栏次序是本函数的语义主体,先于分类:
+ *  1. 命令缺失形(`command not found` / `applet not found` / `: not found`)→ `unknown` —— 工具不存在
+ *     不是文件不存在;probe 族的 not_found fallback 绝不能吞它。
+ *  2. 完整硬失败(EIO/ELOOP/ENAMETOOLONG/ENOSPC)→ `unknown` —— 同 k8s 原注:真错不被 read-op 的
+ *     not_found fallback 吞掉。
+ *
+ * `fallback` 由站点显式给:probe 族(readlink/realpath/stat——"它在吗"类问题)传 `not_found`
+ * (空 stderr + exit≠0 的主导原因就是缺文件);mutate 族(mkdir/rm/mktemp)传 `unknown`(诚实降级)。
+ */
 export function classifyFsStderr(stderr, p, fallback = "unknown") {
     const msg = stderr.trim();
     if (/command not found|applet not found|:\s+not found\s*$/im.test(msg))

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

@@ -1,36 +1,89 @@
 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";
+/** 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}. */
 export interface HostEnvConfig {
+    /**
+     * Base directory under which this adapter creates its per-task working directory. Default {@link os.tmpdir}.
+     * The actual workspace is `<workspaceBase>/sema-host-<id>` and is `rm -rf`'d on {@link destroy}.
+     */
     workspaceBase?: string;
+    /**
+     * Stable id mixed into the per-task workspace dir name (e.g. the sessionId). A short random suffix is always
+     * appended so two envs sharing an id never collide. Default = a random id.
+     */
     id?: string;
+    /**
+     * Out-of-band env injected into EVERY command (secrets etc.). The control plane resolves secret env-NAMEs
+     * from the worker's own `process.env` and passes the resolved values here — they never enter the model
+     * prompt or the tool command string. Merged UNDER per-command `options.env` (per-call wins). The host's
+     * own `process.env` is the default base (a local coding agent inherits the user's environment).
+     */
     env?: Record<string, string>;
+    /** Per-command wall-clock bound (ms) when the caller gives none. Default {@link DEFAULT_COMMAND_TIMEOUT_MS}. */
     commandTimeoutMs?: number;
+    /** Shell-child env policy (D1; mirrors core's `NodeExecutionEnv`). Default `"scrub"`: inherit the worker's
+     *  `process.env` but DROP secret-pattern keys (core's `scrubSecretEnv` — `*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD`…)
+     *  so a model-driven shell can't `printenv DEEPSEEK_API_KEY` and exfiltrate orchestrator secrets — keeps PATH/HOME/
+     *  locale/build (low breakage). `"all"` = inherit everything (explicit opt-out, trusted local dev). A `string[]` =
+     *  strict allowlist. `env`/per-command `options.env` ALWAYS pass through verbatim. */
     inheritEnv?: "scrub" | "all" | string[];
+    /** @deprecated use {@link inheritEnv}. `true`→`"all"`, `false`→`[]` (hermetic). Ignored if `inheritEnv` is set. */
     inheritProcessEnv?: boolean;
+    /**
+     * EXACT persistent working directory (TOC, CC-like): when set, the adapter uses THIS dir verbatim — NO
+     * `sema-host-<id>-<rand>` per-task subdir — and **NEVER `rm -rf`s it on {@link destroy}**. It is the
+     * user's OWN directory (e.g. the cwd `run-local` was invoked in), not an adapter-created ephemeral sandbox,
+     * so the agent's file edits PERSIST and are user-visible (like a local coding agent working in your repo).
+     * Takes precedence over `workspaceBase`/`id` (those are ignored). Default unset = ephemeral random + cleanup.
+     */
     workspaceDir?: string;
+    /** R7 self-wake: the injected `SchedulerCapability` backend (the TOC self-wake scheduler write side).
+     *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 design/136 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
+     *  reports `supported:false` → INERT (no scheduler tools). Injected at boot only on the single-user host lane. */
     scheduler?: SchedulerCapability;
+    /** design/103 background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
+     *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(旧名 HOST_BG_DISABLED=true 兼容期内仍认)。 */
     backgroundShell?: boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
+    /** design/61 §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
     };
+    /** R7 自唤醒: structural delegation to the injected scheduler backend. `hasScheduler(env)` checks BOTH the method
+     *  presence (always, since we implement the interface) AND `schedulerCapabilities.supported===true` — which is only
+     *  true when a backend was injected, so a host env without one stays INERT (the four scheduler tools don't mount). */
     get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{
         id: ScheduledTaskId;
     }, SchedulerError>>;
     cancel(id: ScheduledTaskId, ctx: SchedulerContext): Promise<Result<void, SchedulerError>>;
     list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
+    /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at the workspace root. */
     cwd: string;
     private readonly workspaceDir;
     private readonly cfg;
+    /** Workspace created on disk (lazily, on first use). */
     private prepared;
+    /** Terminal once {@link destroy} ran — guards fs/exec from running against a removed workspace. */
     private destroyed;
+    /** [1116] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
+     *  `git clean -fdx` 类清理会 unlink 活跃 spool(子进程经继承 fd 对 unlinked inode 继续写,而父进程
+     *  按路径 statSync/read 静默断=输出丢失+轮转帽失效);顺带不再弄脏 user-owned workspace(TOC/CC
+     *  persistent 形)。懒建;destroy 整树清。 */
     private spoolRootDir?;
+    /** 🔴 在飞的 fg spool 目录登记表(2026-07-25)。`destroy()` 原来只看 `bgManager.hasShells()` 就 `rm -rf`
+     *  spool 根 —— 而**前台** exec 的 spool 也在同一个根下,子进程通过继承的 fd 继续往已 unlink 的 inode 写,
+     *  父进程按**路径** stat/read 于是什么都看不到 ⇒ 命令照跑、副作用照落盘,但 stdout 被静默截断,还返回
+     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core RB-73 同形:写已释放的 inode。)
+     *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
     private ensureSpoolRoot;
+    /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
     private readonly persistent;
+    /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     private preparing?;
     private readonly handle;
     constructor(config?: HostEnvConfig);
@@ -63,6 +116,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** The "connection" is the local process; there is nothing to re-establish. Idempotent success (unless destroyed). */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -70,6 +124,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** `rm -rf` the per-task workspace (NOT the machine). Idempotent, best-effort, never throws (cleanup contract).
+     *
+     *  core 1.258.2 destroy 契约注(remote-env.d.ts):非隔离 env(host lane,capabilities.isolation
+     *  缺席)的 destroy = 工作区/对象级清理,**不得收割仍在跑的后台进程**——收割全权归 `disposeBackgroundShells`
+     *  (它带 timeout/session keep-alive except 名单)。此前这里的无-except 全灭把
+     *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
+     *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
     get backgroundCapabilities(): BackgroundShellCapability["backgroundCapabilities"];
@@ -79,6 +140,20 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     spawnBackground(command: string, options?: BackgroundSpawnOptions): Promise<Result<{
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
+    /**
+     * design/116 detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
+     * shell — the mid-flight ctrl+b path. The exec child writes to pipes (not files, unlike a `launch`-spawned
+     * bg shell), so adoption splices those live pipes into fresh bg spool files: pre-fill them with the output
+     * captured so far (the detach TEE, fed from the exec's FIRST chunk → TaskOutput's first read has the full
+     * history), then append every subsequent chunk. From then on the shell is indistinguishable from a spawned one
+     * (poll by cursor, kill by pgid, the BG-timeout wall applies). Returns the opaque shellId, or `undefined` when
+     * the live-shell limit is hit (detach refused → the exec keeps running in the foreground; NEVER a dropped process).
+     *
+     * `memOut`/`memErr` are the exec's tee-from-start buffers (Fable-5 review #3, mirrors the E2B tee): they were fed
+     * every chunk since process start THROUGH THE SAME per-stream StringDecoder that keeps feeding post-detach, so a
+     * multibyte codepoint straddling the detach instant decodes correctly (the old seed-from-fg-tail handoff decoded
+     * the two halves in separate passes → U+FFFD at the seam).
+     */
     private adoptRunningExec;
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
@@ -93,9 +168,15 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
             shellId: string;
         };
     }, ExecutionError>>;
+    /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
+    /** [1116] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
+     *  独占建(core openSpoolPair 同形)。失败=undefined(调用方回退管道形)。 */
     private openFgSpool;
+    /** [1116] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
     private execViaSpool;
+    /** [1116] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
+     *  共码);同一文件单一字节流=天然无 decoder 接缝(mem-tee 版为此专门修过的病在此结构性不存在)。 */
     private adoptRunningExecSpool;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     absolutePath(p: string): Promise<Result<string, FileError>>;
@@ -122,28 +203,98 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         force?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** 🔴 临时文件/目录**不放进 workspace**(2026-07-25 修)。
+     *  原来两者都建在 `this.workspaceDir` 下,而 **TOC/CC 形的 workspaceDir 就是用户自己的目录**,且 `destroy()`
+     *  明文永不删它 ⇒ core 给**每个**后台 bash 都调一次 `createTempFile({prefix:"bash-task-", suffix:".output"})`
+     *  ⇒ 用户仓库根目录按后台任务数累积 `bash-task-<hex>.output`(内容=命令输出)+ 每次 `createTempDir` 一个
+     *  `tmp-XXXXXX/`,**永久**留在他们的 git 树里。两条独立判据说明这是偏差不是设计:①core 自己的 TOC 参照实现
+     *  `NodeExecutionEnv.createTempFile` 放的是 `os.tmpdir()`;②**本适配器早就为了同一个理由把 spool 根搬去了
+     *  tmpdir**([1116] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
+     *  改用本 env 自己的 tmp 根(`ensureSpoolRoot()`,已在 `os.tmpdir()` 下):
+     *   · 用户目录不再被写入;
+     *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
+     *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
+     *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /** Resolve a (possibly relative) path against {@link cwd} like the other adapters. Host paths are platform-native. */
     private resolve;
+    /** Lazily create the per-task workspace exactly once (memoized; concurrent first-use shares it). */
     private ensurePrepared;
     private shellReady;
+    /**
+     * @param opts.lingeringBgWrite 只由 {@link appendFile} 传 true —— 允许「destroy 之后、仍在册的后台 shell
+     *   的输出镜像写」。
+     *
+     * 🔴 为什么需要这个口(2026-07-25,cli dogfood 报的现象追出来的真因):`destroy()` 无条件置
+     * `destroyed = true`,于是文件面**全拒**;而 `pollBackground` 直通 bgManager、**没有** destroyed 门。
+     * 这与本适配器自己遵守的 core 契约(1.258.2「destroy 不得收割后台进程」,上方 destroy() 里也为
+     * 「dispose 前仍可轮询」的残余刻意保留了 spool 根)直接打架:我们**刻意**让后台 shell 跨 destroy 存活并
+     * 继续被轮询,却拒掉它们要写的那个文件 ⇒ core 的 `appendFile` 一失败即置 `spool.mirrorFailed`,用户在一个
+     * 其实成功的后台任务上看到「[!] The output file is INCOMPLETE」。已用真子进程执行验证过这个不对称。
+     *
+     * 放行判据刻意收紧到三条同时成立,少一条都拒:
+     *  ① `persistent` —— 只有 TOC/CC 形(构造时给了 `workspaceDir` = 用户自己的目录)。那一形 destroy() 明文
+     *     「NEVER rm -rf it」,什么都没删,文件确实还在,core 还告诉用户「Read it any time」⇒ 报 INCOMPLETE 是谎。
+     *     **ephemeral 形不放行**:它的 destroy() 真的 rm -rf 了 workspace,而 `createTempFile` 恰把 outputFile
+     *     建在 workspace 里 ⇒ 镜像目标已被删,拒写是**诚实**的;放行反而会让 appendFile 的 mkdir -p 把一个已拆除
+     *     的工作目录**复活**成孤儿目录。
+     *  ② 还有后台 shell **在册** —— 判据与 destroy() 里"跳过删 spool 根"用的是同一个 `hasShells()`,即
+     *     「还有人在读写这些文件」这一个事实,不是两套规则。没有 shell 在册时 `destroyed` 照旧是硬护栏。
+     *  ③ 只对 append 一个动作开 —— 不是把整个文件面在 destroy 之后重新开门。
+     * 用 `this._bgManager?.` 而不是惰性 getter:拆除路径上不该顺手 **新建** 一个 manager。
+     */
+    /** destroy 后「残余镜像写」的**路径**判据 —— 与方法判据(`lingeringBgWrite`)并列,两者都满足才放行。
+     *
+     *  🔴 为什么需要它(深挖第一轮打在我自己头上的一条,2026-07-25):我原先的放行只看方法标志,于是 destroy 之后
+     *  `appendFile` 能**新建**文件、`mkdir -p` 建整棵树、甚至写 workspace **之外**的绝对路径 —— 而我在 fsReady
+     *  头注里写的是「别的文件动作在 destroy 之后没有正当理由」。探针实测把这个不一致钉了出来:说是"窄",在路径
+     *  维度上一点都不窄。
+     *
+     *  收紧到恰好贴合唯一的正当调用方(core 的后台输出镜像):
+     *   ① 目标必须在 **workspace 之内**(`createTempFile` 就把 outputFile 建在这儿)—— 挡住"写到工作区外面";
+     *   ② 目标**必须已经存在** —— 镜像写的文件是 destroy **之前**建好的,所以"新建"从来不是这条路的需求;
+     *      这一条同时挡掉 `mkdir -p` 建新目录树的副作用。
+     *  同步 `existsSync` 而不是 await:这是拆除路径上的判据,不该再引入一次异步让出。 */
     private isLingeringMirrorTarget;
     private fsReady;
+    /** Base env (process.env when inheriting) merged with the adapter's secret env, then per-command overrides win. */
+    /** D1 secure default = `"scrub"`: inherit `process.env` minus secret-pattern keys (core's `scrubSecretEnv`, single
+     *  source of truth). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
+     *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
     private mergeEnv;
     private fileError;
 }
+/**
+ * `ExecutionEnvFactory` for the TOC `host` backend (DUAL-MODE-DESIGN §5). Wiring this onto a deployment makes
+ * its agent run DIRECTLY on the worker's machine (no container) — the local-coding-agent default. One fresh
+ * env per task; the Runner owns the lifetime and calls `destroy()` (= `rm -rf` the workspace) on task end.
+ *
+ * Mirrors `e2bExecutionEnvFactory`: returns the env **unconnected** (lazy) and folds the per-task
+ * `ctx.sessionId` into the workspace dir id so two concurrent tasks never share a working directory.
+ */
 export declare function hostExecutionEnvFactory(config?: HostEnvConfig): ExecutionEnvFactory;
 export { localDockerExecutionEnvFactory, type LocalDockerEnvConfig, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
+/** Config for the (not-yet-implemented) `remote-docker` provider: run each task in a container on a REMOTE
+ *  docker daemon (e.g. over a TLS docker endpoint). Fast-follow per DUAL-MODE-DESIGN §5. */
 export interface RemoteDockerEnvConfig {
+    /** Container image to run the task in. */
     image: string;
+    /** Workspace mount path inside the container. */
     mountPath?: string;
+    /** Remote docker daemon endpoint (e.g. tcp://host:2376 or ssh://user@host). Required for remote-docker. */
     dockerHost: string;
+    /** Out-of-band env injected into the container (secrets resolved by the control plane). */
     env?: Record<string, string>;
 }
+/**
+ * `remote-docker` factory entry point — wired but an explicit TODO (DUAL-MODE-DESIGN §5 fast-follow). Throws
+ * at factory-BUILD time so selecting it before it exists fails loud rather than degrading isolation silently.
+ */
 export declare function remoteDockerExecutionEnvFactory(_config: RemoteDockerEnvConfig): ExecutionEnvFactory;
 //# sourceMappingURL=remote-env-host.d.ts.map