@syrkos/filaxis 0.1.0-alpha.10

package/src/file-edit.ts

@@ -0,0 +1,195 @@
+/**
+ * file-edit.ts — 受控文件编辑（远端 CAS 原子写回 + 合成 SSH 往返）
+ *
+ * 第六季盲测实锤：SKILL 教了受控编辑但 SDK 无一级导出——Agent 读 7 轮源码自研
+ * 20 行样板（50 万 cache tokens）；裸 SSH 组则 sed -i 两翻车并写坏远端配置。
+ *
+ * 第七季盲测反馈（B2 逐秒拆解）：旧实现一次 editFile = 5 次串行 SSH 往返
+ * （stat/read/stat/write/stat），Windows 无 ControlMaster 下放大到 15s+。
+ * 本版：合成 **2 次往返**（读+戳 1 次；**远端 CAS 原子写回** 1 次——GPT 并发
+ * 安全意见采纳：「最后一次校验与写入放进同一个远端受控操作」——戳比对与写回
+ * 在远端一条命令内原子完成，杜绝 A/B 丢失更新）+ 方言适配（stat/base64 三族，
+ * 每 driver 缓存一次探测）。大文件（base64>30KB）自动回落旧 5 次路径（fs 层）。
+ *
+ * **仅适用 UTF-8 文本**（readFile 返回 UTF-8 字符串；二进制文件的编辑走
+ * readBase64 + 消费方自行改写 + writeFile）。
+ */
+import type { RuntimeDriver } from "./driver.js";
+
+export interface EditFileOptions {
+    /** 多处命中时全替换（缺省 false——多处命中报错，精确替换语义） */
+    all?: boolean;
+}
+
+export interface EditFileResult {
+    path: string;
+    occurrences: number;
+    bytesBefore: number;
+    bytesAfter: number;
+    /** 写前锁核验的 mtimeMs（CAS 远端原子比对用） */
+    lockedAtMtimeMs: number;
+}
+
+export class EditConflictError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "EditConflictError";
+    }
+}
+
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+
+/** 单引号安全检查（base64/stamp 等嵌入 shell 引号前的红线） */
+const shellSafe = (s: string) => !s.includes("'") && !s.includes("\n");
+
+interface ShellDialect {
+    statCmd: string; // 戳命令（输出 "mtime size"）
+    enc: string;    // base64 编码 argv（无换行）
+    dec: string;    // base64 解码 argv
+    /** 内容指纹命令模板（{f}=文件——三族 fallback 链：sha256sum → sha256 -q → openssl；
+     *  CAS 戳的内容分量：stat %Y 秒级粒度有同秒同 size 盲区——内容指纹封死） */
+    shaCmd: string;
+}
+
+/**
+ * stat 戳命令模板（{f}=文件——行为 fallback 链，不探版本：GNU -c 优先、
+ * 失败自动 BSD -f——CI 实证版本探测在 Ubuntu 误判走 BSD 分支）。
+ */
+const statCmdOf = (f: string) => `stat -c '%Y %s' ${f} 2>/dev/null || stat -f '%m %z' ${f} 2>/dev/null`;
+
+/** 每 driver 的方言缓存（key=driver 描述符投影——仅 base64 族） */
+const dialectCache = new Map<string, ShellDialect>();
+
+async function dialectOf(drv: RuntimeDriver): Promise<ShellDialect> {
+    const key = JSON.stringify(drv.descriptor);
+    const hit = dialectCache.get(key);
+    if (hit) return hit;
+    // 一次往返探测 base64 族（-w 0 GNU / 解码 -d vs -D）
+    const probe = await drv.exec(
+        "echo FX2=$(printf filaxis | base64 -w 0 2>/dev/null | head -c 8);" +
+        "echo FX3=$(printf ZmlsYXhpcw== | base64 -d 2>/dev/null | head -c 7);" +
+        "echo FX4=$(printf ZmlsYXhpcw== | base64 -D 2>/dev/null | head -c 7)",
+        { timeoutMs: 15_000 },
+    );
+    const out = probe.stdout || "";
+    const b64Gnu = /FX2=ZmlsYXhp/.test(out);
+    const decD = /FX4=filaxis/.test(out);
+    const d: ShellDialect = {
+        statCmd: "", // 行为 fallback（statCmdOf）——不走探测
+        enc: b64Gnu ? "base64 -w 0" : "base64",
+        dec: decD ? "base64 -D" : "base64 -d",
+        shaCmd: `{ sha256sum ${"{f}"} 2>/dev/null || sha256 -q ${"{f}"} 2>/dev/null || openssl dgst -sha256 ${"{f}"} 2>/dev/null | tail -1; } | head -c 12`,
+    };
+    dialectCache.set(key, d);
+    return d;
+}
+
+/**
+ * 受控编辑（合成 2 次往返 + 远端 CAS 原子写回）：
+ * ① 读+戳（1 次往返）：`stat 戳; __FXS__; base64 读` —— 拿 (mtime,size)+全文
+ * ② 精确替换（本地）：0 命中/多处命中（未开 all）拒绝
+ * ③ CAS 原子写回（1 次往返）：远端一条命令内完成「戳比对 + tmp 写 + mv 原子替换 + 新戳回执」
+ *    —— 戳不符（他人先写）→ EditConflictError；写后回执新戳
+ *
+ * @throws EditConflictError TOCTOU 冲突（CAS 戳不符）
+ * @throws Error 未命中 / 多处命中（未开 all）/ 远端层无 stat 能力
+ */
+export async function editFile(
+    drv: RuntimeDriver,
+    path: string,
+    oldStr: string,
+    newStr: string,
+    opts: EditFileOptions = {},
+): Promise<EditFileResult> {
+    const dialect = await dialectOf(drv);
+    // 读+戳 合成一次往返（读时戳与读到的内容同窗——读后他人写 → CAS 必不符）
+    const qp = q(path);
+    const readCmd = `${statCmdOf(qp)}; ${dialect.shaCmd.replace(/\{f\}/g, qp)}; echo __FXS__; ${dialect.enc} ${qp} 2>/dev/null`;
+    const r = await drv.exec(readCmd, { timeoutMs: 30_000 });
+    const [stampPart, b64Part] = (r.stdout || "").split("__FXS__");
+    const originStampRaw = (stampPart ?? "").trim();
+    const originLines = originStampRaw.split(/\n/);
+    const statStamp = (originLines[0] ?? "").trim();
+    const shaStamp = (originLines[1] ?? "").trim();
+    if (!shellSafe(statStamp) || !shellSafe(shaStamp)) {
+        throw new Error(`远端戳异常（stat/sha256 输出非单行）: ${path}`);
+    }
+    const originParts = statStamp.split(/\s+/);
+    const origin = {
+        mtimeMs: parseInt(originParts[0] ?? "0", 10) * 1000,
+        size: parseInt(originParts[1] ?? "0", 10),
+    };
+    if (!origin.size || !shaStamp) throw new Error(`文件不存在或指纹异常: ${path}（${originStampRaw}）`);
+    const content0 = Buffer.from((b64Part ?? "").replace(/\s+/g, ""), "base64").toString("utf-8");
+
+    const occurrences = content0.split(oldStr).length - 1;
+    if (occurrences === 0) {
+        // 安全红线：oldStr 可能含敏感信息（token/密码）——错误信息不嵌入原文，只给长度与行数线索
+        throw new Error(`未命中待替换片段（0 处）: ${path}（oldStr 长度 ${oldStr.length}，文件 ${content0.length} 字符）`);
+    }
+    if (occurrences > 1 && !opts.all) {
+        throw new Error(`多处命中（${occurrences} 处）——精确替换语义拒绝；确认全替换请传 { all: true }: ${path}`);
+    }
+    const edited = opts.all ? content0.split(oldStr).join(newStr) : content0.replace(oldStr, newStr);
+
+    const newB64 = Buffer.from(edited, "utf-8").toString("base64");
+    if (newB64.length > 30_000) {
+        // 大文件回落 fs 层旧路径（CAS 单命令超过远端 ARG_MAX 安全线）
+        return editFileViaFs(drv, path, edited, occurrences);
+    }
+
+    const cmd =
+        `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` +
+        `[ "$(${dialect.shaCmd.replace(/\{f\}/g, qp)})" = "${shaStamp}" ]; then ` +
+        `printf %s ${q(newB64)} | ${dialect.dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` +
+        `echo "FX_OK $(stat -c '%Y %s' ${qp} 2>/dev/null || stat -f '%m %z' ${qp} 2>/dev/null)"; ` +
+        `else echo FX_CAS_FAIL; fi`;
+
+    const cas = await drv.exec(cmd, { timeoutMs: 30_000 });
+    const out = (cas.stdout || "").trim();
+    if (out.startsWith("FX_CAS_FAIL")) {
+        throw new EditConflictError(
+            `TOCTOU 冲突：CAS 戳不符（他人先写）: ${path}（读时 stat ${statStamp} sha ${shaStamp}）`,
+        );
+    }
+    if (!out.startsWith("FX_OK")) {
+        throw new Error(`远端 CAS 写回异常: ${path}（输出 ${out.slice(0, 80)}）`);
+    }
+    return {
+        path,
+        occurrences,
+        bytesBefore: origin.size,
+        bytesAfter: edited.length,
+        lockedAtMtimeMs: origin.mtimeMs,
+    };
+}
+
+/** 大文件回落路径（fs 层 5 次往返——语义同 CAS：精确替换+TOCTOU+base64 写回） */
+async function editFileViaFs(
+    drv: RuntimeDriver,
+    path: string,
+    edited: string,
+    occurrences: number,
+): Promise<EditFileResult> {
+    if (!drv.fs.stat) {
+        throw new Error(`该层不支持受控编辑（fs.stat 缺席——TOCTOU 锁依赖）: ${path}`);
+    }
+    const before = await drv.fs.stat(path);
+    if (!before) throw new Error(`文件不存在: ${path}`);
+    const lockCheck = await drv.fs.stat(path);
+    if (!lockCheck || lockCheck.mtimeMs !== before.mtimeMs || lockCheck.size !== before.size) {
+        throw new EditConflictError(
+            `TOCTOU 冲突：读取后文件已被他人修改（mtime ${before.mtimeMs}→${lockCheck?.mtimeMs}）: ${path}`,
+        );
+    }
+    await drv.fs.writeFile(path, edited);
+    const after = await drv.fs.stat(path);
+    if (after && before.mtimeMs === after.mtimeMs && before.size === after.size) {
+        if (edited.length !== after.size) {
+            throw new Error(`写后回读异常（size 未随写入变化）: ${path}`);
+        }
+    }
+    return {
+        path, occurrences, bytesBefore: before.size, bytesAfter: edited.length, lockedAtMtimeMs: before.mtimeMs,
+    };
+}

package/src/file-transfer.ts

@@ -0,0 +1,196 @@
+/**
+ * file-transfer.ts — 跨机文件传输 get/put（FEAT-14 / AC-15）
+ *
+ * 实现分级降级（PRD FEAT-14）：
+ *   ① base64 管道（本文件主路径）——非 PTY exec 通道，跨 Transport 一致
+ *      （docker/k8s 无 sftp；分块 append + decode 落位 + size/sha256 双校验）
+ *   ② sftp 子进程快路径——仅 SSH Transport 大文件（CI sshd 矩阵验证；此处留
+ *      扩展点，调用方经 stack.features().sftp 判定后自行接入）
+ *
+ * 方言适配（dialect.ts 接线）：base64/sha256 原语按连接探测缓存渲染——
+ * OPNsense（BSD 无 -w）/Alpine（busybox）不再必错（Aethelum tmux-driver
+ * base64 -w 0 生产实锤的根治件）。
+ *
+ * exec 注入回调——零 I/O 假设，mock 全测。
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import type { RemoteDialect } from "./dialect.js";
+
+/** 远端执行回调（通常是 driver 的 exec 通道） */
+export type TransferExec = (command: string) => Promise<{ stdout: string; exitCode: number }>;
+
+/** put 分块大小（base64 字符数——单条命令行安全长度内） */
+const CHUNK_B64 = 48 * 1024;
+
+export interface TransferResult {
+    bytes: number;
+    /** 远端回读核实的 sha256（与本地一致才返回成功） */
+    sha256: string;
+    /** 校验是否通过 */
+    verified: boolean;
+}
+
+export class TransferVerificationError extends Error {
+    constructor(op: "put" | "get", detail: string) {
+        super(`文件传输校验失败（${op}）: ${detail}`);
+        this.name = "TransferVerificationError";
+    }
+}
+
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+
+/**
+ * 上行 put：本地 → 远端。分块 base64 append 到远端临时文件 → 方言 decode 落位
+ * → size + sha256 回读双校验。任何一步退出码非零 → 抛错（落位原子性：先临时
+ * 文件后 mv 语义——失败不污染目标）。
+ */
+export async function putFile(
+    exec: TransferExec,
+    dialect: RemoteDialect,
+    localPath: string,
+    remotePath: string,
+): Promise<TransferResult> {
+    if (!dialect.base64Decode.length) {
+        throw new Error("远端 base64 原语不可用（方言探测 unknown）——该路径不支持文件传输");
+    }
+    const content = await fs.readFile(localPath);
+    const b64 = content.toString("base64");
+    const tmp = `${remotePath}.filaxis-tmp`;
+
+    await exec(`rm -f ${q(tmp)}`);
+    for (let i = 0; i < b64.length; i += CHUNK_B64) {
+        const chunk = b64.slice(i, i + CHUNK_B64);
+        const r = await exec(`printf %s ${q(chunk)} >> ${q(tmp)}`);
+        if (r.exitCode !== 0) throw new Error(`put 分块写入失败（chunk ${i / CHUNK_B64}）: ${r.stdout}`);
+    }
+    // 落位：方言 decode → 目标（原子替换语义）
+    const dec = dialect.base64Decode.join(" ");
+    const mv = await exec(`${dec} < ${q(tmp)} > ${q(remotePath)} && rm -f ${q(tmp)}`);
+    if (mv.exitCode !== 0) {
+        await exec(`rm -f ${q(tmp)}`).catch(() => undefined);
+        throw new Error(`put 落位失败: ${mv.stdout}`);
+    }
+    // 双校验：size + sha256（方言渲染）
+    const localSha = createHash("sha256").update(content).digest("hex");
+    const v = await verify(exec, dialect, remotePath, content.length, localSha);
+    if (!v.verified) throw new TransferVerificationError("put", v.detail);
+    return { bytes: content.length, sha256: localSha, verified: true };
+}
+
+/**
+ * 下行 get：远端 → 本地。方言 base64 编码回传 → 本地落盘 → sha256 对核。
+ */
+export async function getFile(
+    exec: TransferExec,
+    dialect: RemoteDialect,
+    remotePath: string,
+    localPath: string,
+): Promise<TransferResult> {
+    if (!dialect.base64Encode.length) {
+        throw new Error("远端 base64 原语不可用（方言探测 unknown）——该路径不支持文件传输");
+    }
+    const enc = dialect.base64Encode.join(" ");
+    const r = await exec(`${enc} < ${q(remotePath)}`);
+    if (r.exitCode !== 0) throw new Error(`get 编码回传失败: ${r.stdout}`);
+    const content = Buffer.from(r.stdout.replace(/\s+/g, ""), "base64");
+    await fs.writeFile(localPath, content);
+    const localSha = createHash("sha256").update(content).digest("hex");
+    const v = await verify(exec, dialect, remotePath, content.length, localSha);
+    if (!v.verified) throw new TransferVerificationError("get", v.detail);
+    return { bytes: content.length, sha256: localSha, verified: true };
+}
+
+/** size + sha256 回读双校验（sha256 原语缺席时降级为仅 size——诚实标注 verified 语义） */
+async function verify(
+    exec: TransferExec,
+    dialect: RemoteDialect,
+    remotePath: string,
+    expectSize: number,
+    expectSha: string,
+): Promise<{ verified: boolean; detail: string }> {
+    const sz = await exec(`wc -c < ${q(remotePath)}`);
+    const size = parseInt((sz.stdout || "").trim(), 10);
+    if (size !== expectSize) return { verified: false, detail: `size 不一致（远端 ${size} ≠ 本地 ${expectSize}）` };
+    if (!dialect.sha256.length) {
+        // sha256 原语缺席：size 单校验通过即通过（方言 unknown 的诚实降级）
+        return { verified: true, detail: "size-only（sha256 原语缺席）" };
+    }
+    const sh = await exec(`${dialect.sha256.join(" ")} < ${q(remotePath)}`);
+    const remoteSha = (sh.stdout || "").replace(/[^0-9a-f]/g, "");
+    if (!remoteSha.includes(expectSha)) {
+        return { verified: false, detail: `sha256 不一致（远端 ${remoteSha.slice(0, 16)}… ≠ 本地 ${expectSha.slice(0, 16)}…）` };
+    }
+    return { verified: true, detail: "size+sha256" };
+}
+
+// ════════════════ sftp 快路径（FEAT-14 ②：仅 SSH Transport 大文件） ════════════════
+
+import { spawn as defaultSpawn, type ChildProcess } from "node:child_process";
+
+export type SftpSpawnImpl = (argv: string[], batch: string) => Promise<{ exitCode: number | null; stderr: string }>;
+
+async function defaultSftpSpawn(argv: string[], batch: string): Promise<{ exitCode: number | null; stderr: string }> {
+    return new Promise((resolve, reject) => {
+        const p: ChildProcess = defaultSpawn("sftp", argv, { stdio: ["pipe", "pipe", "pipe"] });
+        let stderr = "";
+        p.stderr?.on("data", (d: Buffer) => { stderr += d; });
+        p.stdin?.write(batch);
+        p.stdin?.end();
+        p.on("close", (code) => resolve({ exitCode: code, stderr }));
+        p.on("error", reject);
+    });
+}
+
+export interface SftpOptions {
+    /** 连接参数（host key 策略/端口/密钥——与 ssh 通道同源） */
+    connArgs: string[];
+    /** spawn 注入（缺省真实 sftp 子进程 + `-b -` batch 模式）——mock 全测关键 */
+    spawnImpl?: SftpSpawnImpl;
+}
+
+/**
+ * sftp 快路径 put：`sftp -b -` batch 模式（stdin 喂 `put` 命令）。
+ * 成功后仍走 size/sha256 双校验（与 base64 路径同一信任标准——快路径不豁免校验）。
+ * 缺席/失败由调用方捕获后降级 base64 管道（PRD FEAT-14 降级链）。
+ */
+export async function sftpPutFile(
+    exec: TransferExec,
+    dialect: RemoteDialect,
+    localPath: string,
+    remotePath: string,
+    opts: SftpOptions,
+): Promise<TransferResult> {
+    const doSpawn = opts.spawnImpl ?? defaultSftpSpawn;
+    const batch = `put ${q(localPath)} ${q(remotePath)}\n`;
+    const r = await doSpawn([...opts.connArgs, "-b", "-"], batch);
+    if (r.exitCode !== 0) {
+        throw new Error(`sftp put 失败（exit=${r.exitCode}）——可降级 base64 管道: ${r.stderr.trim().slice(0, 200)}`);
+    }
+    const content = await fs.readFile(localPath);
+    const localSha = createHash("sha256").update(content).digest("hex");
+    const v = await verify(exec, dialect, remotePath, content.length, localSha);
+    if (!v.verified) throw new TransferVerificationError("put", v.detail);
+    return { bytes: content.length, sha256: localSha, verified: true };
+}
+
+/** sftp 快路径 get（batch `get`；校验同 put） */
+export async function sftpGetFile(
+    exec: TransferExec,
+    dialect: RemoteDialect,
+    remotePath: string,
+    localPath: string,
+    opts: SftpOptions,
+): Promise<TransferResult> {
+    const doSpawn = opts.spawnImpl ?? defaultSftpSpawn;
+    const batch = `get ${q(remotePath)} ${q(localPath)}\n`;
+    const r = await doSpawn([...opts.connArgs, "-b", "-"], batch);
+    if (r.exitCode !== 0) {
+        throw new Error(`sftp get 失败（exit=${r.exitCode}）——可降级 base64 管道: ${r.stderr.trim().slice(0, 200)}`);
+    }
+    const content = await fs.readFile(localPath);
+    const localSha = createHash("sha256").update(content).digest("hex");
+    const v = await verify(exec, dialect, remotePath, content.length, localSha);
+    if (!v.verified) throw new TransferVerificationError("get", v.detail);
+    return { bytes: content.length, sha256: localSha, verified: true };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * 牵丝 Filaxis — 面向自动化与 Agent 的远程执行运行时 SDK
+ * 千里一线，执行有迹。—— Connect · Execute · Observe · Reattach
+ *
+ * M1 第一批出口：契约与纯逻辑件。驱动实现（ssh/local/tmux）、会话管理器、
+ * 事件总线按里程碑分批落位（REQ-0001 M1-M4）。
+ */
+export * from "./driver.js";
+export * from "./session-types.js";
+export * from "./session-buffer.js";
+export * from "./logger.js";
+export * from "./local-session-manager.js";
+export * from "./local-driver.js";
+export * from "./events.js";
+export * from "./factory.js";
+export * from "./runtime-stack.js";
+export * from "./dialect.js";
+export * from "./ssh-helpers.js";
+export * from "./remote-session-manager.js";
+export * from "./ssh-pty-driver.js";
+export * from "./tmux-driver.js";
+export * from "./terminal-manager.js";
+export { DEFAULT_TERMINAL_CONFIG, compilePromptPatterns, TmuxError } from "./terminal/types.js";
+export type { TerminalConfig, PromptPayload, PromptResponder, TmuxResult } from "./terminal/types.js";
+export * from "./terminal/output-buffer.js";
+export * from "./stream-session-manager.js";
+export * from "./file-transfer.js";
+export * from "./layer-env.js";
+export { resolveLocalShell } from "./shell-discovery.js";
+export { createAgentToolkit } from "./agent-toolkit.js";
+export type { AgentToolkit, AgentToolDef, AgentToolHandlers, AgentToolkitOptions } from "./agent-toolkit.js";
+export { discoverLayer } from "./layer-discovery.js";
+export type { DiscoverLayerOptions, DiscoverLayerResult } from "./layer-discovery.js";
+export * from "./stream-window.js";
+export { Vt100Screen } from "./vt100-screen.js";
+export type { Vt100ScreenOptions } from "./vt100-screen.js";
+export { editFile, EditConflictError } from "./file-edit.js";
+export type { EditFileOptions, EditFileResult } from "./file-edit.js";

package/src/layer-discovery.ts

@@ -0,0 +1,79 @@
+/**
+ * layer-discovery.ts — 异步层环境探测助手（冷启动锦囊之异步侧）
+ *
+ * 探测不阻塞建层：`discoverLayer(driver)` 返回 Promise，消费方（自发现编排/
+ * 观察窗）自行选择 fire-and-forget 或 await——建层与探测解耦。
+ * 两段式（stage1 快 / stage2 慢包导入）+ 蒸馏 + 落盘（stale 防漂移）+ 可选跳过 stage2。
+ */
+import {
+    buildProbeStage1,
+    buildProbeStage2,
+    parseProbeOutput,
+    layerEnvKey,
+    layerFingerprint,
+    projectConnection,
+    LayerEnvStore,
+    type LayerEnvEntry,
+    type LayerEnvironmentSpec,
+} from "./layer-env.js";
+import type { RuntimeDriver } from "./driver.js";
+
+export interface DiscoverLayerOptions {
+    /** 落盘 Store（缺省内存态——探测结果仍返回不落盘） */
+    store?: LayerEnvStore;
+    /** 跳过 stage2（慢包导入——10s+；快路径/离线探测） */
+    skipStage2?: boolean;
+    /** stage2 独立超时（缺省 120s——由调用方驱动 exec 超时） */
+    stage2TimeoutMs?: number;
+    logger?: { warn(msg: string): void };
+}
+
+export interface DiscoverLayerResult {
+    key: string;
+    spec: LayerEnvironmentSpec;
+    /** stage2 失败/跳过时如实标注（诚实不假装完整） */
+    probeNote?: string;
+    stale?: boolean;
+    entry?: LayerEnvEntry;
+}
+
+/** 异步探测一层环境：两段式 → 蒸馏 → （可选）落盘（漂移标 stale 不覆盖） */
+export async function discoverLayer(
+    driver: RuntimeDriver,
+    opts: DiscoverLayerOptions = {},
+): Promise<DiscoverLayerResult> {
+    const key = layerEnvKey(driver.descriptor);
+
+    const r1 = await driver.exec(buildProbeStage1(), { timeoutMs: 30_000 });
+    const spec = parseProbeOutput(r1.stdout);
+    let probeNote: string | undefined;
+    if (!opts.skipStage2) {
+        try {
+            const r2 = await driver.exec(buildProbeStage2(), {
+                timeoutMs: opts.stage2TimeoutMs ?? 120_000,
+            });
+            const spec2 = parseProbeOutput(r2.stdout);
+            spec.packages = spec2.packages; // stage2 增量合并（包）
+        } catch (err) {
+            probeNote = `stage2 失败（${err instanceof Error ? err.message : String(err)}）——packages 可能缺席`;
+            opts.logger?.warn(`[discoverLayer ${key}] ${probeNote}`);
+        }
+    } else {
+        probeNote = "stage2 skipped";
+    }
+
+    const entry: LayerEnvEntry = {
+        connection: projectConnection(driver.descriptor),
+        environment: spec,
+        discovered_at: new Date().toISOString(),
+        fingerprint: layerFingerprint(projectConnection(driver.descriptor), spec),
+        probe_note: probeNote,
+    };
+
+    let stale: boolean | undefined;
+    if (opts.store) {
+        const r = await opts.store.upsert(key, entry);
+        stale = r.stale;
+    }
+    return { key, spec, probeNote, stale, entry: opts.store ? undefined : entry };
+}