agent-trellis 0.18.0 → 0.20.0

package/dist/evolve/sources.js

@@ -0,0 +1,29 @@
+/**
+ * 可选信号源探测(trellis-evolve 任务 11.3)。
+ *
+ * agent-bridge 委托记录是可选信号源:缺席是合法状态,SHALL NOT 使运行
+ * 失败——探测返回 `unavailable` 而非抛错,作业评估(11.5)以此继续并把
+ * 状态记录下来。委托记录存储取 Trellis 真实落盘的 agent 间委托(task
+ * store,`~/.trellis/tasks/tasks.json`);委托记录到信号的映射设计未定,
+ * 本期只做源可用性探测,不派生信号内容。
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export function agentBridgeRecordsPath(homeDir) {
+    return join(homeDir, ".trellis", "tasks", "tasks.json");
+}
+/** 探测 agent-bridge 委托记录是否可用;永不抛错。 */
+export function probeAgentBridgeSource(homeDir) {
+    if (existsSync(agentBridgeRecordsPath(homeDir))) {
+        return {
+            source: "agent-bridge",
+            status: "available",
+            note: "agent-bridge 委托记录存在",
+        };
+    }
+    return {
+        source: "agent-bridge",
+        status: "unavailable",
+        note: "无 agent-bridge 委托存储,运行以其余信号源继续",
+    };
+}

package/dist/evolve/stateDir.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 进化状态目录(trellis-evolve 任务 10.4)。
+ *
+ * 路径按 8.1 定案:`~/.trellis/evolve/`,与 canonical 内容面(agents.md/
+ * skills/MCP 定义/memories)分离——进化子系统独占写入、只追加,`trellis
+ * sync` 等读面不消费它。其下按用途分子目录:
+ *   `signals/` recorder 按进程分文件追加的信号(11.1);
+ *   `archive/` 运行档案:提案/探针/verdict/备份会话标识/L2 比较记录;
+ *   `pending/` 待批提案存储(12.4)。
+ */
+export declare const EVOLVE_STATE_SUBDIRS: readonly ["signals", "archive", "pending"];
+export declare function evolveStateDir(homeDir: string): string;
+/** 幂等创建状态目录骨架(0700);只在 `~/.trellis/evolve/` 下落盘。 */
+export declare function ensureEvolveStateDir(homeDir: string): string;
+/**
+ * "加入 .gitignore 如适用":状态根本身位于 git work tree 时(如用户把
+ * `~/.trellis` 收进 dotfiles 仓库),把 `evolve/` 写进状态根的
+ * `.gitignore`,让只追加状态不进版本库;不在 work tree 内则什么都不
+ * 做(零副作用)。幂等,重复调用不产生重复条目。
+ */
+export declare function ensureStateGitignored(homeDir: string): "added" | "present" | "not-a-repo";

package/dist/evolve/stateDir.js

@@ -0,0 +1,56 @@
+/**
+ * 进化状态目录(trellis-evolve 任务 10.4)。
+ *
+ * 路径按 8.1 定案:`~/.trellis/evolve/`,与 canonical 内容面(agents.md/
+ * skills/MCP 定义/memories)分离——进化子系统独占写入、只追加,`trellis
+ * sync` 等读面不消费它。其下按用途分子目录:
+ *   `signals/` recorder 按进程分文件追加的信号(11.1);
+ *   `archive/` 运行档案:提案/探针/verdict/备份会话标识/L2 比较记录;
+ *   `pending/` 待批提案存储(12.4)。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const EVOLVE_STATE_SUBDIRS = ["signals", "archive", "pending"];
+export function evolveStateDir(homeDir) {
+    return join(homeDir, ".trellis", "evolve");
+}
+/** 幂等创建状态目录骨架(0700);只在 `~/.trellis/evolve/` 下落盘。 */
+export function ensureEvolveStateDir(homeDir) {
+    const root = evolveStateDir(homeDir);
+    for (const name of EVOLVE_STATE_SUBDIRS)
+        mkdirSync(join(root, name), { recursive: true, mode: 0o700 });
+    return root;
+}
+function findGitRoot(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * "加入 .gitignore 如适用":状态根本身位于 git work tree 时(如用户把
+ * `~/.trellis` 收进 dotfiles 仓库),把 `evolve/` 写进状态根的
+ * `.gitignore`,让只追加状态不进版本库;不在 work tree 内则什么都不
+ * 做(零副作用)。幂等,重复调用不产生重复条目。
+ */
+export function ensureStateGitignored(homeDir) {
+    const stateRoot = join(homeDir, ".trellis");
+    if (findGitRoot(stateRoot) === null)
+        return "not-a-repo";
+    const ignorePath = join(stateRoot, ".gitignore");
+    if (existsSync(ignorePath)) {
+        const existing = readFileSync(ignorePath, "utf-8");
+        const lines = existing.split("\n").map((line) => line.trim());
+        if (lines.some((line) => line === "evolve/" || line === "/evolve/" || line === "evolve"))
+            return "present";
+        appendFileSync(ignorePath, existing.endsWith("\n") || existing.length === 0 ? "evolve/\n" : "\nevolve/\n");
+        return "added";
+    }
+    appendFileSync(ignorePath, "evolve/\n");
+    return "added";
+}

package/dist/evolve/surface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TrellisSubstrate 的 `surface()`(trellis-evolve 任务 9.1)。
+ *
+ * 声明 Trellis 的可编辑树 schema —— 引擎只认识这个 schema 内的路径,
+ * 除此之外的目标(Class C:secret/凭据材料、MCP auth 配置、受管 agent
+ * 集合、自我进化自身配置、用户手写文件)根本不在 schema 里,引擎的
+ * `is_allowed` 对它们一律返回 false,不需要也不采信模型自报。
+ *
+ * 可编辑面恰好四类,与任务书一一对应:
+ *
+ *   - `agents.md`            —— 共享 instructions 段落
+ *   - `skills/<name>/`       —— skill 条目(SKILL.md + scripts/*)
+ *   - `mcp/routes.yaml`      —— MCP 路由(mode/每 agent 的 server 列表;
+ *                              注意 `mcp/servers.yaml` 不在 schema 内 ——
+ *                              server 定义与 auth 材料是 Class C)
+ *   - `memory/policy.yaml`   —— memory 策略(启用/范围策略本身,
+ *                              不是记忆内容)
+ *
+ * 静默失效模式(编辑"成功"但什么都不改变的形态,editor 契约必须知道):
+ *
+ *   1. 加了 skill 但没有触发线 —— Trellis 的 skill 按需加载,
+ *      `agents.md` 里没有触发线时新条目静默无效(trigger_hint /
+ *      autotrigger_file / trigger_line 三个字段就是为这个模式存在);
+ *   2. routes.yaml 里给某 agent 的路由其 scope 不含该 agent —— 渲染面
+ *      对该 agent 静默为空;
+ *   3. memory/policy.yaml 的策略改动只在 memory 已启用的安装上生效。
+ *
+ * 故意不收进 schema 的 harness2 类目:sub_agents(BenchSpec 的
+ * `allow_subagents` 默认 false,Trellis 探针任务不开)、plugin、hooks
+ * (Trellis 没有这两个概念)。root `scripts/` 保留 harness2 原语义
+ * (确定性辅助脚本),skill 脚本不编译(非 Python 约定)。
+ */
+import { type SurfaceSpec } from "@trellis/evolve-engine";
+export declare const TRELLIS_SURFACE: SurfaceSpec;

package/dist/evolve/surface.js

@@ -0,0 +1,72 @@
+/**
+ * TrellisSubstrate 的 `surface()`(trellis-evolve 任务 9.1)。
+ *
+ * 声明 Trellis 的可编辑树 schema —— 引擎只认识这个 schema 内的路径,
+ * 除此之外的目标(Class C:secret/凭据材料、MCP auth 配置、受管 agent
+ * 集合、自我进化自身配置、用户手写文件)根本不在 schema 里,引擎的
+ * `is_allowed` 对它们一律返回 false,不需要也不采信模型自报。
+ *
+ * 可编辑面恰好四类,与任务书一一对应:
+ *
+ *   - `agents.md`            —— 共享 instructions 段落
+ *   - `skills/<name>/`       —— skill 条目(SKILL.md + scripts/*)
+ *   - `mcp/routes.yaml`      —— MCP 路由(mode/每 agent 的 server 列表;
+ *                              注意 `mcp/servers.yaml` 不在 schema 内 ——
+ *                              server 定义与 auth 材料是 Class C)
+ *   - `memory/policy.yaml`   —— memory 策略(启用/范围策略本身,
+ *                              不是记忆内容)
+ *
+ * 静默失效模式(编辑"成功"但什么都不改变的形态,editor 契约必须知道):
+ *
+ *   1. 加了 skill 但没有触发线 —— Trellis 的 skill 按需加载,
+ *      `agents.md` 里没有触发线时新条目静默无效(trigger_hint /
+ *      autotrigger_file / trigger_line 三个字段就是为这个模式存在);
+ *   2. routes.yaml 里给某 agent 的路由其 scope 不含该 agent —— 渲染面
+ *      对该 agent 静默为空;
+ *   3. memory/policy.yaml 的策略改动只在 memory 已启用的安装上生效。
+ *
+ * 故意不收进 schema 的 harness2 类目:sub_agents(BenchSpec 的
+ * `allow_subagents` 默认 false,Trellis 探针任务不开)、plugin、hooks
+ * (Trellis 没有这两个概念)。root `scripts/` 保留 harness2 原语义
+ * (确定性辅助脚本),skill 脚本不编译(非 Python 约定)。
+ */
+import { makeSurfaceSpec } from "@trellis/evolve-engine";
+export const TRELLIS_SURFACE = makeSurfaceSpec({
+    name: "trellis",
+    always_on: ["agents.md", "mcp/routes.yaml", "memory/policy.yaml"],
+    always_on_max: 48_000,
+    always_on_cap_reason: "every always-on byte is injected into every managed agent's context on every session",
+    skill_dir: "skills",
+    skill_name_rule: "must_match",
+    trigger_hint: "Fix it by adding a trigger line naming `{name}` to agents.md, e.g. " +
+        '"When <the situation this skill handles>, load the `{name}` skill." ' +
+        "A skill with no trigger line is silently inert: Trellis loads skills " +
+        "on demand, so nothing references it.",
+    autotrigger_file: "agents.md",
+    trigger_line: "- When {desc}, load the `{name}` skill.\n",
+    subagent_requires_mode: false,
+    plugin_dir: null,
+    hooks_file: null,
+    stubs: [
+        [
+            "skills/README.md",
+            "<!-- Reusable capability entries, delivered to managed agents per " +
+                "scope. Add one as skills/<name>/SKILL.md with frontmatter `name:` " +
+                "matching the directory and a `description:`; helper files live under " +
+                "skills/<name>/scripts/. Inert until a trigger line in agents.md " +
+                "references it. -->\n",
+        ],
+        [
+            "mcp/README.md",
+            "<!-- MCP routing policy lives in mcp/routes.yaml (per-agent mode and " +
+                "server lists). Server definitions and auth material are NOT editable " +
+                "here — they are protected (Class C) targets. -->\n",
+        ],
+        [
+            "memory/README.md",
+            "<!-- Memory policy lives in memory/policy.yaml (enable/scope policy " +
+                "itself, not memory content). Changes take effect only where memory " +
+                "is enabled. -->\n",
+        ],
+    ],
+});

package/dist/evolve/trajectory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 会话记录 → 共享语法渲染(trellis-evolve 任务 9.3 的 read_trajectory)。
+ *
+ * Trellis 探针会话的捕获格式:probe launcher(13.3)写出的规范化 NDJSON
+ * 事件流,每行一个 JSON 对象:
+ *
+ *   {"type": "text",      "text": ...}                                  → [ASSISTANT]
+ *   {"type": "thinking",  "text": ...}                                  → [THINKING]
+ *   {"type": "tool_call", "name": ..., "input": ...,                    → [ACTION] name(args)
+ *                          "status": "ok"|"error",                      → [OBSERVATION] output
+ *                          "output"/"error": ...}                          或 [OBSERVATION ERROR]
+ *   {"type": "error",     "message": ...}                               → [ERROR]
+ *
+ * 渲染语义对齐 harness2 substrate 的 render_events(共享语法,substrate
+ * 各自实现):防御性逐行解析(非 JSON 行跳过)、`_clip` 截断标记
+ * `…(+N chars — render truncation)`、整体 max_chars 帽。Trellis 的
+ * args_trunc 默认 400(协议默认值)。
+ */
+export interface RenderSessionOptions {
+    obsTrunc: number;
+    maxChars: number;
+    argsTrunc?: number;
+}
+/** Render a captured session stream into the shared trajectory grammar. */
+export declare function renderSessionEvents(streamPath: string, opts: RenderSessionOptions): string;

package/dist/evolve/trajectory.js

@@ -0,0 +1,88 @@
+/**
+ * 会话记录 → 共享语法渲染(trellis-evolve 任务 9.3 的 read_trajectory)。
+ *
+ * Trellis 探针会话的捕获格式:probe launcher(13.3)写出的规范化 NDJSON
+ * 事件流,每行一个 JSON 对象:
+ *
+ *   {"type": "text",      "text": ...}                                  → [ASSISTANT]
+ *   {"type": "thinking",  "text": ...}                                  → [THINKING]
+ *   {"type": "tool_call", "name": ..., "input": ...,                    → [ACTION] name(args)
+ *                          "status": "ok"|"error",                      → [OBSERVATION] output
+ *                          "output"/"error": ...}                          或 [OBSERVATION ERROR]
+ *   {"type": "error",     "message": ...}                               → [ERROR]
+ *
+ * 渲染语义对齐 harness2 substrate 的 render_events(共享语法,substrate
+ * 各自实现):防御性逐行解析(非 JSON 行跳过)、`_clip` 截断标记
+ * `…(+N chars — render truncation)`、整体 max_chars 帽。Trellis 的
+ * args_trunc 默认 400(协议默认值)。
+ */
+import { readFileSync } from "node:fs";
+const truncMarker = (dropped) => `…(+${dropped} chars — render truncation)`;
+/** harness2 `_clip` 的等价物:去 NUL,超长截断并加渲染截断标记。 */
+function clip(value, cap) {
+    const s = (value === null || value === undefined ? "" : String(value)).replaceAll("\x00", "");
+    if (cap <= 0 || s.length <= cap)
+        return s;
+    return s.slice(0, cap) + truncMarker(s.length - cap);
+}
+/** Render a captured session stream into the shared trajectory grammar. */
+export function renderSessionEvents(streamPath, opts) {
+    const argsCap = Math.trunc(opts.argsTrunc ?? 400);
+    let raw;
+    try {
+        raw = readFileSync(streamPath, "utf-8");
+    }
+    catch (err) {
+        return `(failed to read trajectory: ${err instanceof Error ? err.message : String(err)})`;
+    }
+    const lines = [];
+    for (const ln of raw.split("\n")) {
+        const trimmed = ln.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (typeof ev !== "object" || ev === null || Array.isArray(ev))
+            continue;
+        const event = ev;
+        const type = event.type;
+        if (type === "text" || type === "assistant") {
+            const text = typeof event.text === "string" ? event.text : undefined;
+            if (text?.trim())
+                lines.push(`[ASSISTANT] ${clip(text, opts.obsTrunc)}`);
+        }
+        else if (type === "thinking" || type === "reasoning") {
+            const text = typeof event.text === "string" ? event.text : undefined;
+            if (text?.trim())
+                lines.push(`[THINKING] ${clip(text, opts.obsTrunc)}`);
+        }
+        else if (type === "tool_call" || type === "tool") {
+            const name = typeof event.name === "string" && event.name ? event.name : "tool";
+            const args = event.input !== undefined ? JSON.stringify(event.input) : "";
+            lines.push(`[ACTION] ${name}(${clip(args, argsCap)})`);
+            if (event.status === "error") {
+                lines.push(`[OBSERVATION ERROR] ${clip(event.error, opts.obsTrunc)}`);
+            }
+            else if (event.output !== undefined) {
+                lines.push(`[OBSERVATION] ${clip(event.output, opts.obsTrunc)}`);
+            }
+        }
+        else if (type === "error") {
+            lines.push(`[ERROR] ${clip(event.message, 300)}`);
+        }
+        // 未识别的 type:跳过(捕获格式向前兼容的余地)。
+    }
+    let rendered = lines.join("\n").trim();
+    if (!rendered)
+        return "(no parseable events in trajectory)";
+    if (rendered.length > opts.maxChars) {
+        const dropped = rendered.length - opts.maxChars;
+        rendered = rendered.slice(0, opts.maxChars) + "\n" + truncMarker(dropped);
+    }
+    return rendered;
+}

package/dist/evolve/treeToCanonical.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 可编辑树 → canonical staging 的布局映射(trellis-evolve 任务 9.2)。
+ *
+ * 树的四个可编辑类目落到 canonical 的对应物:
+ *
+ *   agents.md                  →  <home>/.trellis/agents.md           整文件替换
+ *   skills/<name>/**           →  <home>/.trellis/skills/<name>/**    原样落盘
+ *   mcp/routes.yaml            →  <home>/.trellis/mcp/servers.yaml    只替换 routes: 节
+ *   memory/policy.yaml         →  <home>/.trellis/scope.yaml          只替换 memories: 节
+ *
+ * 两个 section 文件的关键性质:servers.yaml 的 server 定义/auth 与
+ * scope.yaml 的 skills/agents 节都不在可编辑 schema 内(Class C / 托管
+ * 自有),所以落盘是节级 splice —— 解析目标文件、只替换对应顶层键、其余
+ * 内容(含注释)原样保留 —— 而不是整文件覆盖。
+ *
+ * 严格性约定:section 文件本身必须是可解析的 YAML(语法级严格,坏树是
+ * materialise 错误);section 内容语义由 canonical 加载器自行容错(语义级
+ * 宽松,坏路由在检查结果里显形而不是炸掉 staging)。
+ */
+import type { Tree } from "@trellis/evolve-engine";
+/** Replace (or, for empty/null section content, delete) one top-level key
+ * in a YAML file, preserving every other section byte-for-byte where the
+ * parser allows. Creates the file when absent. */
+export declare function spliceYamlSection(path: string, key: string, sectionContent: string): void;
+/** The tree rel paths this mapping knows how to place. Anything else is a
+ * bug in the caller (the engine's read_tree already filters by the
+ * surface schema) — refuse loudly rather than drop a file silently. */
+export declare function applyTreeToStaging(tree: Tree, stagingHome: string): void;

package/dist/evolve/treeToCanonical.js

@@ -0,0 +1,79 @@
+/**
+ * 可编辑树 → canonical staging 的布局映射(trellis-evolve 任务 9.2)。
+ *
+ * 树的四个可编辑类目落到 canonical 的对应物:
+ *
+ *   agents.md                  →  <home>/.trellis/agents.md           整文件替换
+ *   skills/<name>/**           →  <home>/.trellis/skills/<name>/**    原样落盘
+ *   mcp/routes.yaml            →  <home>/.trellis/mcp/servers.yaml    只替换 routes: 节
+ *   memory/policy.yaml         →  <home>/.trellis/scope.yaml          只替换 memories: 节
+ *
+ * 两个 section 文件的关键性质:servers.yaml 的 server 定义/auth 与
+ * scope.yaml 的 skills/agents 节都不在可编辑 schema 内(Class C / 托管
+ * 自有),所以落盘是节级 splice —— 解析目标文件、只替换对应顶层键、其余
+ * 内容(含注释)原样保留 —— 而不是整文件覆盖。
+ *
+ * 严格性约定:section 文件本身必须是可解析的 YAML(语法级严格,坏树是
+ * materialise 错误);section 内容语义由 canonical 加载器自行容错(语义级
+ * 宽松,坏路由在检查结果里显形而不是炸掉 staging)。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Document, parse as parseYaml, parseDocument } from "yaml";
+/** `routes:` 节的语义守卫:值必须是 {agent: {mode: direct|gateway|hub, servers?}}。
+ * 语法可解析但形状明显错误的候选仍写进 staging(canonical 加载器容错,
+ * 检查差集会显形);这里只拦"根本不是 map"的类别错误。 */
+function assertSectionIsMap(key, value) {
+    if (value !== null && (typeof value !== "object" || Array.isArray(value))) {
+        throw new Error(`tree section for "${key}" must be a YAML mapping, got ${Array.isArray(value) ? "array" : typeof value}`);
+    }
+}
+/** Replace (or, for empty/null section content, delete) one top-level key
+ * in a YAML file, preserving every other section byte-for-byte where the
+ * parser allows. Creates the file when absent. */
+export function spliceYamlSection(path, key, sectionContent) {
+    const value = parseYaml(sectionContent);
+    assertSectionIsMap(key, value);
+    const doc = existsSync(path) ? parseDocumentOrThrow(path) : new Document({});
+    if (value === null || value === undefined) {
+        doc.delete(key);
+    }
+    else {
+        doc.set(key, value);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(doc));
+}
+function parseDocumentOrThrow(path) {
+    const text = readFileSync(path, "utf-8");
+    const parsed = parseYaml(text);
+    if (parsed !== null && parsed !== undefined && (typeof parsed !== "object" || Array.isArray(parsed))) {
+        throw new Error(`${path} is not a YAML mapping at the top level`);
+    }
+    return parseDocument(text);
+}
+/** The tree rel paths this mapping knows how to place. Anything else is a
+ * bug in the caller (the engine's read_tree already filters by the
+ * surface schema) — refuse loudly rather than drop a file silently. */
+export function applyTreeToStaging(tree, stagingHome) {
+    const trellisRoot = join(stagingHome, ".trellis");
+    for (const [rel, content] of Object.entries(tree)) {
+        if (rel === "agents.md") {
+            writeFileSync(join(trellisRoot, "agents.md"), content);
+        }
+        else if (rel === "mcp/routes.yaml") {
+            spliceYamlSection(join(trellisRoot, "mcp", "servers.yaml"), "routes", content);
+        }
+        else if (rel === "memory/policy.yaml") {
+            spliceYamlSection(join(trellisRoot, "scope.yaml"), "memories", content);
+        }
+        else if (rel.startsWith("skills/")) {
+            const target = join(trellisRoot, rel);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content);
+        }
+        else {
+            throw new Error(`tree path "${rel}" is on the surface schema but has no canonical mapping`);
+        }
+    }
+}

package/dist/evolve/trellisSubstrate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * TrellisSubstrate(trellis-evolve 任务 9.1–9.3)。
+ *
+ * 引擎 Substrate 协议的 Trellis 实现。内部只经 `src/host/` 窄门面接入
+ * 托管(单向依赖:引擎包 + host 门面,见 10.3 的边界测试):
+ *
+ *   surface()         → TRELLIS_SURFACE(任务 9.1)
+ *   materialise()     → host 门面的 staging 上渲染候选树;真实 canonical
+ *                       逐字节不动(9.2)
+ *   preflight()       → 花钱前的 doctor 级自检;canonical 缺席或检查有
+ *                       发现时抛错,消息带修复命令;不启动任何模型链(9.2)
+ *   execute()         → 委托构造时供给的 launcher body 拉起探针会话,
+ *                       每 run_id 一个 run_dir;无 launcher 即报错(9.3)
+ *   read_trajectory() → 会话记录渲染为共享语法(9.3,见 trajectory.ts)
+ */
+import { type Install, type Launcher, type Path, type Substrate, type SurfaceSpec } from "@trellis/evolve-engine";
+export interface TrellisSubstrateOptions {
+    homeDir: string;
+    /** 进程观察到的 workspace root;null/缺省 = 只评全局层。 */
+    workspaceRoot?: string | null;
+    /** staging 落盘位置(测试缝,默认 OS tmpdir)。 */
+    tmpRoot?: string;
+    /** benchmark/探针侧供给的 launcher body(harness2 分工:substrate 拥有
+     * 表面与 staging,launcher 拥有 runner 选择、env 接线与读回位置;
+     * 每个 run_id 一个 run_dir 由 launcher 落地)。缺席时 execute 报错,
+     * 不会退化到任何隐式 spawn。 */
+    launcher?: Launcher;
+}
+export declare class TrellisSubstrate implements Substrate {
+    readonly name = "trellis";
+    private readonly homeDir;
+    private readonly workspaceRoot;
+    private readonly tmpRoot?;
+    private readonly launcher?;
+    /** fingerprint → staging,以便 execute 结束后释放 scratch。 */
+    private readonly stagings;
+    constructor(options: TrellisSubstrateOptions);
+    surface(): SurfaceSpec;
+    /**
+     * 把候选树渲染到 canonical 的 scratch 副本上。离 schema 的路径是
+     * materialise 错误而不是静默丢弃 —— 编辑写了什么就必须 staged 什么,
+     * 否则 verdict 在评一个与候选不一致的东西。
+     */
+    materialise(treeDir: Path, _spec: unknown, _ctx: Readonly<Record<string, string>>): Promise<Install>;
+    /** 释放 materialise 建立的 scratch(execute 结束后由调用方触发)。 */
+    releaseInstall(install: Install): void;
+    /**
+     * 花钱前自检:canonical 必须已初始化(否则修修复命令是 `trellis init`);
+     * host 检查必须干净(否则指向 `trellis doctor` / `trellis secrets
+     * audit`)。只读,不 spawn 任何模型链。
+     */
+    preflight(): Promise<void>;
+    /**
+     * 探针会话执行(harness2 原分工):委托给构造时供给的 launcher body,
+     * 每个 run_id 一个 run_dir 由 launcher 落地。substrate 自己不 spawn —
+     * 没有 launcher 就报错,不存在隐式默认 runner。
+     */
+    execute(taskRef: string, install: Install, runIds: readonly string[], timeout: number): Promise<Path[]>;
+    /** 会话记录渲染为共享语法(见 trajectory.ts 的捕获格式与截断语义)。 */
+    read_trajectory(streamPath: Path, opts: {
+        obs_trunc: number;
+        max_chars: number;
+        args_trunc?: number;
+    }): Promise<string>;
+}

package/dist/evolve/trellisSubstrate.js

@@ -0,0 +1,154 @@
+/**
+ * TrellisSubstrate(trellis-evolve 任务 9.1–9.3)。
+ *
+ * 引擎 Substrate 协议的 Trellis 实现。内部只经 `src/host/` 窄门面接入
+ * 托管(单向依赖:引擎包 + host 门面,见 10.3 的边界测试):
+ *
+ *   surface()         → TRELLIS_SURFACE(任务 9.1)
+ *   materialise()     → host 门面的 staging 上渲染候选树;真实 canonical
+ *                       逐字节不动(9.2)
+ *   preflight()       → 花钱前的 doctor 级自检;canonical 缺席或检查有
+ *                       发现时抛错,消息带修复命令;不启动任何模型链(9.2)
+ *   execute()         → 委托构造时供给的 launcher body 拉起探针会话,
+ *                       每 run_id 一个 run_dir;无 launcher 即报错(9.3)
+ *   read_trajectory() → 会话记录渲染为共享语法(9.3,见 trajectory.ts)
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { is_allowed, makeInstall, makeRunRequest, read_tree, } from "@trellis/evolve-engine";
+import { createStaging, readSurface, runChecks } from "../host/index.js";
+import { TRELLIS_SURFACE } from "./surface.js";
+import { applyTreeToStaging } from "./treeToCanonical.js";
+import { renderSessionEvents } from "./trajectory.js";
+/** preflight 的通过规则:doctor 发现除 `mcp-unreachable`(某台 server 没
+ * 应答握手是信息而不是环境病)之外都阻断;secrets audit 的任何发现都阻断
+ * (凭据字面值在场时不做任何探针);`sync --check` 的 pending 项不阻断 ——
+ * 未同步的渲染是常态,L1 的 verdict 差集自己会看 sync 条目。 */
+const PREFLIGHT_ALLOWED_DOCTOR_KINDS = new Set(["mcp-unreachable"]);
+export class TrellisSubstrate {
+    name = "trellis";
+    homeDir;
+    workspaceRoot;
+    tmpRoot;
+    launcher;
+    /** fingerprint → staging,以便 execute 结束后释放 scratch。 */
+    stagings = new Map();
+    constructor(options) {
+        this.homeDir = options.homeDir;
+        this.workspaceRoot = options.workspaceRoot ?? null;
+        if (options.tmpRoot !== undefined)
+            this.tmpRoot = options.tmpRoot;
+        if (options.launcher !== undefined)
+            this.launcher = options.launcher;
+    }
+    surface() {
+        return TRELLIS_SURFACE;
+    }
+    /**
+     * 把候选树渲染到 canonical 的 scratch 副本上。离 schema 的路径是
+     * materialise 错误而不是静默丢弃 —— 编辑写了什么就必须 staged 什么,
+     * 否则 verdict 在评一个与候选不一致的东西。
+     */
+    async materialise(treeDir, _spec, _ctx) {
+        const rejected = [];
+        const tree = await read_tree(TRELLIS_SURFACE, treeDir, { rejected });
+        if (rejected.length > 0) {
+            throw new Error(`tree contains paths outside the editable surface: ${rejected.sort().join(", ")}`);
+        }
+        for (const rel of Object.keys(tree)) {
+            if (!is_allowed(TRELLIS_SURFACE, rel)) {
+                throw new Error(`tree path "${rel}" is not on the editable surface`);
+            }
+        }
+        const staging = createStaging({
+            homeDir: this.homeDir,
+            workspaceRoot: this.workspaceRoot,
+            ...(this.tmpRoot !== undefined ? { tmpRoot: this.tmpRoot } : {}),
+        });
+        try {
+            applyTreeToStaging(tree, staging.homeDir);
+        }
+        catch (err) {
+            staging.dispose();
+            throw err;
+        }
+        const fingerprint = fingerprintTree(tree);
+        this.stagings.set(fingerprint, staging);
+        return makeInstall({
+            staging_dir: staging.root,
+            fingerprint,
+            // 只暴露 scratch 路径:真实 home/workspace 的路径字符串都不进
+            // Install —— 探针工作区不含工作区之外的用户数据,从数据结构上成立。
+            extras: {
+                home: staging.homeDir,
+                ...(staging.workspaceRoot ? { workspace: staging.workspaceRoot } : {}),
+            },
+        });
+    }
+    /** 释放 materialise 建立的 scratch(execute 结束后由调用方触发)。 */
+    releaseInstall(install) {
+        const staging = this.stagings.get(install.fingerprint);
+        if (staging) {
+            staging.dispose();
+            this.stagings.delete(install.fingerprint);
+        }
+    }
+    /**
+     * 花钱前自检:canonical 必须已初始化(否则修修复命令是 `trellis init`);
+     * host 检查必须干净(否则指向 `trellis doctor` / `trellis secrets
+     * audit`)。只读,不 spawn 任何模型链。
+     */
+    async preflight() {
+        try {
+            readSurface({ homeDir: this.homeDir, workspaceRoot: this.workspaceRoot });
+        }
+        catch {
+            throw new Error(`trellis-evolve preflight: no canonical source under ${join(this.homeDir, ".trellis")} — run \`trellis init\` first`);
+        }
+        const result = await runChecks({ homeDir: this.homeDir, workspaceRoot: this.workspaceRoot });
+        const failing = result.entries.filter((entry) => !(entry.source === "doctor" && PREFLIGHT_ALLOWED_DOCTOR_KINDS.has(entry.kind)) && entry.source !== "sync");
+        if (failing.length > 0) {
+            const bySource = new Map();
+            for (const entry of failing)
+                bySource.set(entry.source, (bySource.get(entry.source) ?? 0) + 1);
+            const summary = [...bySource.entries()].map(([source, n]) => `${source}: ${n}`).join(", ");
+            const remediation = [...bySource.keys()]
+                .map((source) => (source === "secrets" ? "trellis secrets audit" : "trellis doctor"))
+                .map((cmd) => `\`${cmd}\``)
+                .join(" / ");
+            const sample = failing.slice(0, 5).map((entry) => `  - ${entry.id}`).join("\n");
+            throw new Error(`trellis-evolve preflight: ${failing.length} check finding(s) on the live surface (${summary}) — inspect with ${remediation}:\n${sample}`);
+        }
+    }
+    /**
+     * 探针会话执行(harness2 原分工):委托给构造时供给的 launcher body,
+     * 每个 run_id 一个 run_dir 由 launcher 落地。substrate 自己不 spawn —
+     * 没有 launcher 就报错,不存在隐式默认 runner。
+     */
+    async execute(taskRef, install, runIds, timeout) {
+        if (!this.launcher) {
+            throw new Error("TrellisSubstrate was constructed without a launcher body; the probe adapter must supply one (it owns runner choice, env wiring and read-back locations)");
+        }
+        return this.launcher(makeRunRequest({ task_ref: taskRef, run_ids: runIds, timeout: Math.trunc(timeout) }), install);
+    }
+    /** 会话记录渲染为共享语法(见 trajectory.ts 的捕获格式与截断语义)。 */
+    async read_trajectory(streamPath, opts) {
+        return renderSessionEvents(streamPath, {
+            obsTrunc: opts.obs_trunc,
+            maxChars: opts.max_chars,
+            ...(opts.args_trunc !== undefined ? { argsTrunc: opts.args_trunc } : {}),
+        });
+    }
+}
+/** sha256 over the sorted (rel, content) pairs — digests the SOURCE tree,
+ * matching Install.fingerprint's contract. */
+function fingerprintTree(tree) {
+    const hash = createHash("sha256");
+    for (const rel of Object.keys(tree).sort()) {
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(tree[rel]);
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}