@syrkos/filaxis 0.1.0-alpha.10

package/src/layer-env.ts

@@ -0,0 +1,331 @@
+/**
+ * layer-env.ts — 层环境规格与自发现（FEAT-16 / AC-17）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/layer-env.ts` Phase A 段
+ * （源锚 8977ff3），OSS 化：
+ * - yaml 依赖剥 → JSON 持久化（零 npm 依赖红线；语义等价，格式记实施偏差）
+ * - scrubber 剥 → 探测只落蒸馏值（版本/有无/型号），全量输出不落盘（hook 面=exec 回调在消费方）
+ * - 观察投影/行为契约（源 Phase B/C 轴）不随——属消费方策略层
+ *
+ * 语义（生产锤炼）：两段式探测（快亚秒 + 慢包导入）；PTY 回显防御（值含 $( 一律
+ * 丢弃）；探测真实性红线（nvidia-smi 失败文案不得记为 GPU 型号）；环境身份键
+ * hops 不进键（同落点经不同路径=同一环境）。
+ */
+import { createHash } from "node:crypto";
+import { rename, stat, mkdir, writeFile, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { RuntimeDescriptor } from "./driver.js";
+import { enterStepsOf, type SshConnParams } from "./ssh-helpers.js";
+
+// ════════════════ 数据模型 ════════════════
+
+/** 层环境规格（蒸馏快照——版本号/有无/型号，非全量 dump） */
+export interface LayerEnvironmentSpec {
+    os?: string;
+    kernel_arch?: string;
+    python?: string;
+    node?: string;
+    bun?: string;
+    java?: string;
+    cuda?: string;
+    gpu?: { model: string; vram_mb?: number };
+    docker?: boolean;
+    /** 关键包（present-only，"torch@2.4.0" 形态；匹配按 @ 前名） */
+    packages?: string[];
+}
+
+export interface SshHopLite {
+    host: string;
+    conn?: SshConnParams;
+}
+
+/** 重进路径投影（agent 据此零试错重进该层；环境身份不含 hops，重进路径含） */
+export interface LayerConnectionInfo {
+    driver: string;
+    target?: string;
+    conn?: SshConnParams;
+    hops?: SshHopLite[];
+    enters?: Array<{ cmd: string; label?: string }>;
+    launch_cmd?: string;
+}
+
+/** 单层条目 */
+export interface LayerEnvEntry {
+    connection: LayerConnectionInfo;
+    environment: LayerEnvironmentSpec;
+    discovered_at: string;
+    /** 连接拓扑+环境快照 hash（漂移检测锚点：命中不一致 → stale 供重探，不自动覆盖） */
+    fingerprint: string;
+    /** 探测部分失败的说明（诚实标注，不假装完整） */
+    probe_note?: string;
+}
+
+export interface LayerEnvConfigFile {
+    layers: Record<string, LayerEnvEntry>;
+}
+
+// ════════════════ 环境身份键 ════════════════
+
+/**
+ * 环境身份键（两键两职责之一：driverKey 管连接复用，本键管规格归属）：
+ * 落点[+端口]/enter 标签链——hops 不进键（同落点经不同路径=同一环境规格）。
+ */
+export function layerEnvKey(desc: RuntimeDescriptor): string {
+    if (desc.driver === "local") return "local";
+    const c = (desc.config ?? {}) as Record<string, unknown>;
+    if (c.pty === true) {
+        const conn = c.connParams as SshConnParams | undefined;
+        const hostPart = `${desc.target ?? "?"}${conn?.port ? `:${conn.port}` : ""}`;
+        const enters = enterStepsOf(c).map((s) => s.label ?? slugify(s.cmd));
+        return [hostPart, ...enters].join("/");
+    }
+    return `${desc.driver}:${desc.target ?? "default"}`;
+}
+
+function slugify(s: string): string {
+    return s.trim().toLowerCase().replace(/\s+/g, "-").slice(0, 40) || "enter";
+}
+
+// ════════════════ 两段式探测命令 ════════════════
+
+/** stage 1（快：亚秒级）——OS/架构/语言运行时/GPU/CUDA/docker；输出行 `fx_key=value` */
+export function buildProbeStage1(): string {
+    return [
+        // 引号原样直书——'\\"' 会发出两字符 cut 分隔符（vm-homelab PTY 实证）
+        // os-release 缺席时的 fallback 链（报告 #4：群晖 DSM 用 /etc.defaults/VERSION）
+        `echo "fx_os=$(grep PRETTY_NAME /etc/os-release 2>/dev/null | head -1 | cut -d'"' -f2)"`,
+        `echo "fx_os_dsm=$(grep -E '^productversion=' /etc.defaults/VERSION 2>/dev/null | sed 's/productversion=/Synology DSM v/;s/"//g')"`,
+        `echo "fx_kernel_arch=$(uname -s -m 2>/dev/null)"`,
+        `echo "fx_python=$(if command -v python3 >/dev/null 2>&1; then python3 --version 2>&1; elif command -v python >/dev/null 2>&1; then python --version 2>&1; fi | head -1)"`,
+        `echo "fx_node=$(node --version 2>&1 | head -1)"`,
+        `echo "fx_bun=$(bun --version 2>&1 | head -1)"`,
+        `echo "fx_java=$(java -version 2>&1 | head -1)"`,
+        `echo "fx_gpu=$(nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null | head -1)"`,
+        `echo "fx_cuda=$(nvidia-smi 2>/dev/null | grep -o 'CUDA Version: [0-9.][0-9.]*' | head -1 | grep -o '[0-9][0-9.]*')"`,
+        `echo "fx_docker=$(command -v docker >/dev/null 2>&1 && echo yes || echo no)"`,
+    ].join("; ");
+}
+
+/** stage 2（慢：python 冷导入 10s+）——关键包版本；有 GNU timeout 逐项 15s 兜底 */
+export function buildProbeStage2(): string {
+    const py = `command -v python3 >/dev/null 2>&1 && echo python3 || echo python`;
+    const parts = [
+        `__FX_PY=$(${py}); __FX_TO=""; command -v timeout >/dev/null 2>&1 && __FX_TO="timeout 15"`,
+    ];
+    for (const pkg of PROBE_PACKAGES) {
+        if (pkg.kind === "python") {
+            parts.push(`echo "fx_pkg_${pkg.key}=$($__FX_TO "$__FX_PY" -c '${pkg.probe}' 2>/dev/null)"`);
+        } else {
+            parts.push(`echo "fx_tool_${pkg.key}=$($__FX_TO ${pkg.probe} 2>/dev/null | head -1)"`);
+        }
+    }
+    return parts.join("; ");
+}
+
+/** 关键包探测清单（扩展在此加行） */
+export const PROBE_PACKAGES: Array<{ key: string; kind: "python" | "tool"; probe: string; matchNames: string[] }> = [
+    { key: "torch", kind: "python", probe: "import torch;print(torch.__version__)", matchNames: ["torch", "pytorch"] },
+    { key: "transformers", kind: "python", probe: "import transformers;print(transformers.__version__)", matchNames: ["transformers", "huggingface"] },
+    { key: "onnxruntime", kind: "python", probe: "import onnxruntime;print(onnxruntime.__version__)", matchNames: ["onnxruntime", "onnx"] },
+    { key: "numpy", kind: "python", probe: "import numpy;print(numpy.__version__)", matchNames: ["numpy"] },
+    { key: "ffmpeg", kind: "tool", probe: "ffmpeg -version", matchNames: ["ffmpeg"] },
+    { key: "git", kind: "tool", probe: "git --version", matchNames: ["git"] },
+];
+
+/**
+ * 探测输出解析（纯函数）：`fx_key=value` 行 → 蒸馏规格。
+ * PTY 回显防御：回显行是未展开原文（值含 `$(`）——一律丢弃。
+ * 真实性红线：nvidia-smi 失败文案（驱动不通信）不得记为 GPU 型号。
+ */
+export function parseProbeOutput(stdout: string): LayerEnvironmentSpec {
+    const spec: LayerEnvironmentSpec = {};
+    const pkgs: string[] = [];
+    for (const rawLine of stdout.split(/\r?\n/)) {
+        const m = rawLine.trim().match(/^fx_([a-z0-9_]+)=(.*)$/);
+        if (!m) continue;
+        const val = m[2]!.trim();
+        if (!val || val.includes("$(") || val.includes("__FX")) continue; // 回显防御
+        switch (m[1]) {
+            case "os": spec.os = val || undefined; break;
+            case "os_dsm": if (val) spec.os = val; break; // DSM fallback 覆盖空 os
+            case "kernel_arch": spec.kernel_arch = val; break;
+            case "python": if (/Python \d/.test(val)) spec.python = val; break;
+            case "node": if (/^v?\d/.test(val)) spec.node = val.replace(/^v/, ""); break;
+            case "bun": if (/^\d+\./.test(val)) spec.bun = val; break;
+            case "java": if (/version/i.test(val)) spec.java = val; break;
+            case "gpu": {
+                const gm = val.match(/^(.+?),\s*(\d+)\s*MiB$/);
+                if (gm) {
+                    spec.gpu = { model: gm[1]!.trim(), vram_mb: parseInt(gm[2]!, 10) };
+                } else if (val && looksLikeGpuModel(val)) {
+                    spec.gpu = { model: val };
+                }
+                break;
+            }
+            case "cuda": if (/^\d+(\.\d+)*$/.test(val)) spec.cuda = val; break;
+            case "docker": spec.docker = val === "yes"; break;
+            default: {
+                const pm = m[1]!.match(/^(?:pkg|tool)_(.+)$/);
+                if (pm) {
+                    const key = pm[1]!;
+                    const def = PROBE_PACKAGES.find((p) => p.key === key);
+                    const version = extractVersion(val);
+                    const name = def?.key ?? key;
+                    pkgs.push(version ? `${name}@${version}` : name);
+                }
+            }
+        }
+    }
+    if (!spec.os && spec.kernel_arch) spec.os = spec.kernel_arch.split(/\s+/)[0];
+    if (pkgs.length > 0) spec.packages = [...new Set(pkgs)];
+    return spec;
+}
+
+function extractVersion(raw: string): string | undefined {
+    if (!raw) return undefined;
+    const m = raw.match(/(\d+(\.\d+)+[a-z0-9._-]*)/i) || raw.match(/version\s+(\S+)/i) || raw.match(/(\d+\.\d+)/);
+    return m?.[1];
+}
+
+/** 裸 GPU 型号形态收窄：短、无句子气、非报错文案（生产实证：失败文案曾被记为型号） */
+function looksLikeGpuModel(val: string): boolean {
+    if (val.length > 60) return false;
+    if (/failed|error|couldn|can't|unable|no device|not found|driver/i.test(val)) return false;
+    if (/[.!?]$/.test(val)) return false;
+    return /^[A-Za-z0-9 ()+.-]+$/.test(val);
+}
+
+// ════════════════ 持久化（JSON + 原子写 + mtime 缓存） ════════════════
+
+export class LayerEnvStore {
+    private cache: { mtimeMs: number; cfg: LayerEnvConfigFile } | null = null;
+
+    constructor(public readonly path: string) {}
+
+    async load(force = false): Promise<LayerEnvConfigFile> {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await stat(this.path)).mtimeMs;
+        } catch {
+            const cfg: LayerEnvConfigFile = { layers: {} };
+            this.cache = { mtimeMs: 0, cfg };
+            return cfg;
+        }
+        if (!force && this.cache?.mtimeMs === mtimeMs) return this.cache.cfg;
+        try {
+            const parsed = JSON.parse(await readFile(this.path, "utf-8")) as LayerEnvConfigFile;
+            const cfg: LayerEnvConfigFile = parsed?.layers && typeof parsed.layers === "object"
+                ? { layers: parsed.layers }
+                : { layers: {} };
+            this.cache = { mtimeMs, cfg };
+            return cfg;
+        } catch {
+            return this.cache?.cfg ?? { layers: {} }; // 坏文件：不崩，返回空
+        }
+    }
+
+    /** 原子写：tmp + rename */
+    async save(cfg: LayerEnvConfigFile): Promise<void> {
+        await mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp`;
+        await writeFile(tmp, JSON.stringify(cfg, null, 2), "utf-8");
+        await rename(tmp, this.path);
+        this.cache = null; // 失效缓存（下次 load 重 stat）
+    }
+
+    /** 写入/更新一层规格；漂移检测：指纹不一致标 stale 不自动覆盖（显式 force 才覆写） */
+    async upsert(key: string, entry: LayerEnvEntry, force = false): Promise<{ stale: boolean }> {
+        const cfg = await this.load();
+        const existing = cfg.layers[key];
+        if (existing && !force && existing.fingerprint !== entry.fingerprint) {
+            return { stale: true }; // 环境可能已漂移——不覆盖，供重探决策
+        }
+        cfg.layers[key] = entry;
+        await this.save(cfg);
+        return { stale: false };
+    }
+}
+
+/** 连接投影（descriptor → LayerConnectionInfo；重进路径含 hops） */
+export function projectConnection(desc: RuntimeDescriptor): LayerConnectionInfo {
+    const c = (desc.config ?? {}) as Record<string, unknown>;
+    const hops: SshHopLite[] = Array.isArray(c.sshHops)
+        ? (c.sshHops as SshHopLite[]).map((h) => (typeof h === "string" ? { host: h } : h))
+        : [];
+    return {
+        driver: desc.driver,
+        target: desc.target,
+        conn: c.connParams as SshConnParams | undefined,
+        hops: hops.length ? hops : undefined,
+        enters: enterStepsOf(c).map((s) => ({ cmd: s.cmd, label: s.label })),
+        launch_cmd: typeof c.launchCmd === "string" ? c.launchCmd : undefined,
+    };
+}
+
+/** 指纹：连接投影 + 环境快照 hash */
+export function layerFingerprint(conn: LayerConnectionInfo, spec: LayerEnvironmentSpec): string {
+    return "sha256:" + createHash("sha256")
+        .update(JSON.stringify({ conn: { driver: conn.driver, target: conn.target, enters: conn.enters }, spec }))
+        .digest("hex").slice(0, 24);
+}
+
+// ════════════════ 匹配（needs → 层键命中） ════════════════
+
+export interface LayerMatchResult {
+    key: string;
+    entry: LayerEnvEntry;
+}
+
+/**
+ * 按需求匹配层：needs 形如 "gpu" / "torch"（包名） / "python>=3.12"（版本比较）。
+ * 全部 need 命中才入选；结果不排序（调用方按需排）。
+ */
+export function matchLayers(cfg: LayerEnvConfigFile, needs: string[]): LayerMatchResult[] {
+    const out: LayerMatchResult[] = [];
+    for (const [key, entry] of Object.entries(cfg.layers)) {
+        const spec = entry.environment;
+        const ok = needs.every((need) => {
+            const vm = need.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(>=|<=|>|<|=)?\s*([\d.]+)?$/);
+            if (!vm) return false;
+            const name = vm[1]!.toLowerCase();
+            const op = vm[2];
+            const want = vm[3];
+            if (name === "gpu") return spec.gpu != null;
+            if (name === "docker") return spec.docker === true;
+            if (name === "cuda") return spec.cuda != null;
+            if (name === "python" || name === "node" || name === "bun" || name === "java") {
+                const have = spec[name];
+                if (!have) return false;
+                if (!op || !want) return true;
+                return compareVersion(extractVersion(have) ?? "0", want, op);
+            }
+            // 包名匹配（matchNames 别名 + @ 版本）
+            const pkg = (spec.packages ?? []).find((p) => {
+                const base = p.split("@")[0]!;
+                const def = PROBE_PACKAGES.find((d) => base === d.key || d.matchNames.includes(base));
+                return base === name || def?.matchNames.includes(name);
+            });
+            if (!pkg) return false;
+            if (!op || !want) return true;
+            return compareVersion(pkg.split("@")[1] ?? "0", want, op);
+        });
+        if (ok) out.push({ key, entry });
+    }
+    return out;
+}
+
+function compareVersion(a: string, b: string, op: string): boolean {
+    const pa = a.split(".").map((x) => parseInt(x, 10) || 0);
+    const pb = b.split(".").map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0) {
+            if (op === ">=") return d > 0;
+            if (op === "<=") return d < 0;
+            if (op === ">") return d > 0;
+            if (op === "<") return d < 0;
+            return false;
+        }
+    }
+    return op === ">=" || op === "<=" || op === "="; // 相等
+}

package/src/local-driver.ts

@@ -0,0 +1,325 @@
+/**
+ * local-driver.ts — 本地 Transport（进程内执行 + 原生 fs + 会话挂接）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/local-driver.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3），按 REQ-0001 OSS 化改造：
+ * - 剥 SubstrateSecurity（执行网/沙箱属消费方策略）
+ * - exec 改造（FEAT-03）：stdout/stderr 分离返回（源版混流 resolve）；
+ *   effectiveUser 经 nonce marker 尾缀实测（子 shell 包裹 + $? 变量锁——
+ *   用户命令内写 exit 也不丢退出码与 marker，见 docs/implementation-notes.md 锦囊 3）；
+ *   channel:"pty" 显式拒绝（local 无 PTY 层——pty 通道语义属远端交互 Transport）
+ * - exec 审计留痕保留（status/log 落盘 tempDir——「执行有迹」）
+ * - shell 可配（缺省 bash；Windows 需 Git Bash/WSL——平台差异显式声明）
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import * as crypto from "node:crypto";
+import type {
+    RuntimeDriver,
+    FileSystemDriver,
+    FileEntry,
+    ExecOptions,
+    ExecResult,
+    RuntimeDescriptor,
+} from "./driver.js";
+import {
+    LocalSessionManager,
+} from "./local-session-manager.js";
+import type {
+    SessionStartOptions,
+    SessionHandleInfo,
+    WatchOptions,
+    ReadLogOptions,
+} from "./session-types.js";
+import type { FilaxisLogger } from "./logger.js";
+import { noopLogger } from "./logger.js";
+import { resolveLocalShell } from "./shell-discovery.js";
+
+export interface LocalDriverOptions {
+    /** 缺省工作目录 */
+    cwd?: string;
+    /** exec 状态/日志目录（缺省 os.tmpdir()/filaxis-exec） */
+    execDir?: string;
+    /** 执行 shell（缺省 bash） */
+    shell?: string;
+    logger?: FilaxisLogger;
+}
+
+/** 本地 Transport：进程内执行 + 原生 fs */
+export class LocalRuntimeDriver implements RuntimeDriver {
+    descriptor: RuntimeDescriptor = { driver: "local", target: "localhost" };
+    fs: FileSystemDriver;
+
+    /** 会话式 exec 引擎（长跑 + 双文件落盘 + 热窗口 + watch） */
+    readonly sessions: LocalSessionManager;
+
+    private readonly defaultCwd?: string;
+    private readonly execDir: string;
+    private readonly shell: string;
+    private readonly log: FilaxisLogger;
+
+    constructor(opts: LocalDriverOptions = {}) {
+        this.defaultCwd = opts.cwd;
+        this.execDir = opts.execDir ?? path.join(tmpdir(), "filaxis-exec");
+        this.log = opts.logger ?? noopLogger;
+        this.shell = resolveLocalShell(opts.shell, this.log);
+        this.fs = new LocalFileSystem();
+        this.sessions = new LocalSessionManager({
+            logDir: path.join(this.execDir, "sessions"),
+            shell: this.shell,
+            logger: this.log,
+        });
+    }
+
+    /** 从 descriptor 构建（descriptor.cwd 初始化缺省工作目录） */
+    static fromDescriptor(descriptor: RuntimeDescriptor, fallbackCwd?: string): LocalRuntimeDriver {
+        const drv = new LocalRuntimeDriver({ cwd: descriptor.cwd ?? fallbackCwd });
+        (drv as { descriptor: RuntimeDescriptor }).descriptor = descriptor;
+        return drv;
+    }
+
+    async init() {
+        // No-op for local
+    }
+
+    async destroy() {
+        // 会话引擎句柄保留 TTL 自回收；此处无强制清理面（processMgr 属后续批次）
+    }
+
+    async getCwd(): Promise<string> {
+        return this.defaultCwd || process.cwd();
+    }
+
+    async getEnv(key: string): Promise<string | undefined> {
+        return process.env[key];
+    }
+
+    // ── 会话式 exec（委托 LocalSessionManager）──
+    async execSession(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo> {
+        return this.sessions.start(command, opts);
+    }
+    async tailSession(sessionId: string, lines = 50): Promise<string[]> {
+        return this.sessions.tail(sessionId, lines);
+    }
+    async readSessionLog(sessionId: string, opts?: ReadLogOptions): Promise<string> {
+        return this.sessions.readLog(sessionId, opts);
+    }
+    watchSession(sessionId: string, opts: WatchOptions): { cancel(): void } {
+        return this.sessions.watch(sessionId, opts);
+    }
+    async stopSession(sessionId: string): Promise<{ exitCode?: number | null }> {
+        return this.sessions.stop(sessionId);
+    }
+    listSessions(): Array<{ sessionId: string; command: string; running: boolean; startedAt: number }> {
+        return this.sessions.list();
+    }
+
+    async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+        if (options?.channel === "pty") {
+            throw new Error('local Transport 不支持 channel:"pty"（PTY 交互语义属远端 Transport；本地 exec 通道天然分离且恒可用）');
+        }
+
+        await fs.mkdir(this.execDir, { recursive: true });
+        const taskId = crypto.randomBytes(8).toString("hex");
+        const logPath = path.join(this.execDir, `${taskId}.log`);
+        const statusPath = path.join(this.execDir, `${taskId}.status.json`);
+
+        // FEAT-03 marker：子 shell 包裹业务命令，$? 变量锁 + nonce 防撞——
+        // 用户命令内写 exit 42 也不丢退出码与 effectiveUser
+        const nonce = crypto.randomBytes(6).toString("hex");
+        const marker = `__FILAXIS_META_${nonce}__`;
+        const wrapped =
+            `( ${command} ); __filaxis_ec=$?; ` +
+            `printf '\\n${marker}:%d:%s\\n' "$__filaxis_ec" "$(id -un 2>/dev/null)"; ` +
+            `exit $__filaxis_ec`;
+
+        return new Promise<ExecResult>((resolve, reject) => {
+            let stdout = "";
+            let stderr = "";
+
+            const env = { ...process.env, ...options?.env };
+            const cwd = options?.cwd || this.defaultCwd || process.cwd();
+
+            // 不使用 shell: true——Node 会再包一层 sh -c，stdin 读取类命令（wc、无参 cat）挂死
+            const p = spawn(this.shell, ["-c", wrapped], {
+                env,
+                cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+
+            const startTime = Date.now();
+            const writeStatus = async (status: string, extra: Record<string, unknown> = {}) => {
+                try {
+                    await fs.writeFile(statusPath, JSON.stringify({
+                        pid: p.pid,
+                        command,
+                        status,
+                        startTime,
+                        endTime: Date.now(),
+                        ...extra,
+                    }, null, 2), "utf-8");
+                } catch { /* 状态文件写入失败不影响主流程 */ }
+            };
+            void writeStatus("running");
+
+            const logStream = createWriteStream(logPath);
+            p.stdout.on("data", (d: Buffer) => { stdout += d; logStream.write(d); });
+            p.stderr.on("data", (d: Buffer) => { stderr += d; logStream.write(d); });
+
+            let settled = false;
+            let finished = false;
+            const cleanupProcess = (exitStatus: string, extra: Record<string, unknown> = {}) => {
+                if (finished) return;
+                finished = true;
+                logStream.end();
+                return writeStatus(exitStatus, extra);
+            };
+            const detachLifecycle = () => {
+                if (timeout) clearTimeout(timeout);
+                if (onAbort) signal?.removeEventListener("abort", onAbort);
+            };
+
+            const timeout = options?.timeoutMs ? setTimeout(() => {
+                if (settled) return;
+                settled = true;
+                finished = true; // 审计终态封口（审查问题 3：后台进程晚死时 close 不得把 timeout 覆写成 completed）
+                detachLifecycle();
+                // 超时=放弃该进程（继续后台写日志）。此时才 unref：被放弃的子进程
+                // 不应撑事件循环。⚠️ 不能 spawn 后立即 unref——Bun 下 unref 子进程
+                // 不保活事件循环，低活动场景 close 事件永不触发，exec 静默挂死。
+                p.unref();
+                logStream.end();
+                void writeStatus("timeout", { error: "Command timeout", exitCode: null });
+                const e = new Error(`Command timeout after ${options.timeoutMs}ms (process continues in background, log: ${logPath}, status: ${statusPath})`) as Error & { outcome: "unknown" };
+                e.outcome = "unknown"; // 远端/本地进程终态未核实——审查问题 3：对齐 ssh 侧语义
+                reject(e);
+            }, options.timeoutMs) : null;
+
+            const signal = options?.signal;
+            const onAbort = signal ? () => {
+                if (settled) return;
+                settled = true;
+                finished = true; // 审计终态封口（close 不得覆写 aborted）
+                detachLifecycle();
+                try { p.kill("SIGTERM"); } catch { /* 已退出 */ }
+                logStream.end();
+                void writeStatus("aborted", { error: "Aborted by AbortSignal", exitCode: null });
+                const abortErr = new Error("Command aborted by AbortSignal（本地进程已 SIGTERM，终态未核实——outcome=unknown）") as Error & { name: "AbortError"; outcome: "unknown" };
+                abortErr.name = "AbortError";
+                abortErr.outcome = "unknown";
+                reject(abortErr);
+            } : null;
+            if (signal && onAbort) {
+                if (signal.aborted) onAbort();
+                else signal.addEventListener("abort", onAbort, { once: true });
+            }
+
+            p.on("close", (code) => {
+                detachLifecycle();
+                if (settled) return;
+                settled = true;
+                const finish = () => {
+                    // 完成哨兵原则（故障注入 1B 同源收口）：marker 尾缀是「跑完」唯一
+                    // 凭证——未见哨兵（外部 kill -9/信号杀，code===null）reject 附半截
+                    // 现场；哨兵在场退出码以哨兵为准。
+                    let out = stdout;
+                    let effectiveUser: string | undefined;
+                    let sentinelCode: number | undefined;
+                    const mIdx = out.lastIndexOf(`\n${marker}:`);
+                    if (mIdx !== -1) {
+                        const metaLine = out.slice(mIdx + 1).split("\n", 1)[0] ?? "";
+                        const m = metaLine.match(new RegExp(`^${marker}:(-?\\d+):(.*)$`));
+                        if (m) {
+                            effectiveUser = m[2] === "" ? undefined : m[2];
+                            sentinelCode = parseInt(m[1]!, 10);
+                            out = out.slice(0, mIdx); // mIdx 处的 \n 是 printf 的，连同剥掉
+                        }
+                    }
+                    // ★ 审计与事实对齐（审查问题 3）：先验哨兵，后写审计——
+                    //   completed 只在有哨兵时落盘（exitCode 用哨兵真实码）；
+                    //   无哨兵落 killed + exitCode null（绝不把 null ?? 0 伪成完成）
+                    logStream.end();
+                    if (sentinelCode === undefined) {
+                        void writeStatus("killed", { exitCode: null, closeCode: code ?? null });
+                        const e = new Error(
+                            `命令未完成（无完成哨兵——进程被信号终止，close code=${code}）。半截现场 stdout 尾 500:\n${out.slice(-500)}\nstderr 尾 300:\n${stderr.slice(-300)}`,
+                        ) as Error & { outcome: "unknown" };
+                        e.outcome = "unknown";
+                        reject(e);
+                        return;
+                    }
+                    void writeStatus("completed", { exitCode: sentinelCode });
+                    resolve({ stdout: out, stderr, exitCode: sentinelCode, effectiveUser });
+                };
+                finish();
+            });
+
+            p.on("error", (err) => {
+                detachLifecycle();
+                const pWrite = cleanupProcess("failed", { error: err.message, exitCode: -1 });
+                if (settled) return;
+                settled = true;
+                if (pWrite) void pWrite.then(() => reject(err), () => reject(err));
+                else reject(err);
+            });
+        });
+    }
+}
+
+class LocalFileSystem implements FileSystemDriver {
+    async readFile(filePath: string): Promise<string> {
+        return await fs.readFile(filePath, "utf-8");
+    }
+
+    /** 二进制安全读取（裸 base64——readFile 的 UTF-8 会破坏二进制字节） */
+    async readBase64(filePath: string): Promise<string> {
+        const buf = await fs.readFile(filePath);
+        return Buffer.from(buf).toString("base64");
+    }
+
+    async writeFile(filePath: string, content: string): Promise<void> {
+        await fs.writeFile(filePath, content, "utf-8");
+    }
+
+    async exists(filePath: string): Promise<boolean> {
+        try {
+            await fs.access(filePath);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async stat(filePath: string): Promise<{ mtimeMs: number; size: number } | null> {
+        try {
+            const st = await fs.stat(filePath);
+            return { mtimeMs: st.mtimeMs, size: st.size };
+        } catch {
+            return null;
+        }
+    }
+
+    async readdir(dirPath: string): Promise<FileEntry[]> {
+        const dirents = await fs.readdir(dirPath, { withFileTypes: true });
+        return await Promise.all(dirents.map(async (d) => {
+            const stats = await fs.stat(path.join(dirPath, d.name)).catch(() => null);
+            return {
+                name: d.name,
+                isDirectory: d.isDirectory(),
+                size: stats?.size,
+                mtime: stats?.mtimeMs,
+            };
+        }));
+    }
+
+    async rm(filePath: string, options?: { recursive?: boolean; force?: boolean}): Promise<void> {
+        await fs.rm(filePath, options);
+    }
+
+    async mkdir(dirPath: string, options?: {recursive?: boolean}): Promise<void> {
+        await fs.mkdir(dirPath, options);
+    }
+}