agent-trellis 0.19.0 → 0.20.0

package/dist/evolve/l2.js

@@ -0,0 +1,81 @@
+/**
+ * L2 匿名前后对比记录协议(trellis-evolve 任务 13.1)。
+ *
+ * spec"匿名前后对比记录协议(L2)":内容类对比的比较记录以类型化档案
+ * 格式持久化——baseline 与候选各自的运行标识、冻结的交付物引用、按
+ * 任务设种子的匿名标识映射、选择器结果与失败收口的 verdict;base 保留在
+ * 比较中;记录格式表达两种收口:选中 baseline ⟹ 不采纳,选择器失败 ⟹
+ * invalid。本模块只定义记录格式与边界;选择器执行(运行比较与裁决)不
+ * 在本期范围。
+ *
+ * 匿名性:呈现给选择器的匿名标识(anonId)由任务种子 + 运行标识派生,
+ * 本身不含角色词;选择器视图(`presentL2Arms`)只给 anonId 与冻结交付
+ * 物引用,不带 role/runId。角色映射只存在于档案(审计用)。
+ */
+import { createHash } from "node:crypto";
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+/** 运行档案 kind:一条 L2 比较记录。 */
+export const L2_COMPARISON_ARCHIVE_KIND = "l2-comparison";
+/**
+ * 匿名标识:按任务种子 + 运行标识派生的稳定短哈希。构造上不可能
+ * 含角色词——呈现面与档案里的值同源,泄露面为零。
+ */
+export function anonArmId(taskSeeds, runId) {
+    const seedKey = taskSeeds
+        .map((entry) => `${entry.task}=${entry.seed}`)
+        .join("&");
+    const digest = createHash("sha256").update(`${seedKey}#${runId}`).digest("hex");
+    return `arm-${digest.slice(0, 16)}`;
+}
+function verdictFor(arms, selector) {
+    if (selector.status === "failed") {
+        return { kind: "invalid", reason: selector.reason };
+    }
+    const picked = arms.find((arm) => arm.anonId === selector.anonId);
+    if (picked === undefined) {
+        return { kind: "invalid", reason: `selector picked unknown arm ${selector.anonId}` };
+    }
+    // 任一臂未交付:无 artifacts 的臂视为未交付(design:不采纳收口)。
+    if (arms.some((arm) => arm.artifacts.length === 0)) {
+        return { kind: "invalid", reason: "arm-undelivered" };
+    }
+    if (picked.role === "baseline") {
+        return { kind: "not-adopted-baseline", anonId: picked.anonId };
+    }
+    return { kind: "adopt-candidate", anonId: picked.anonId };
+}
+/** 由臂与选择器结果构建完整记录(派生匿名映射 + 失败收口 verdict)。 */
+export function buildL2Comparison(input) {
+    const arms = input.arms.map((arm) => ({
+        anonId: anonArmId(input.taskSeeds, arm.runId),
+        runId: arm.runId,
+        role: arm.role,
+        artifacts: arm.artifacts,
+    }));
+    return {
+        comparisonId: input.comparisonId,
+        createdAt: input.createdAt,
+        taskSeeds: input.taskSeeds,
+        arms,
+        selector: input.selector,
+        verdict: verdictFor(arms, input.selector),
+    };
+}
+/** 追加一条比较记录到运行档案。 */
+export function appendL2Comparison(homeDir, record, now = () => new Date()) {
+    return appendArchiveRecord(homeDir, { kind: L2_COMPARISON_ARCHIVE_KIND, payload: record }, now);
+}
+/** 读回全部比较记录(档案读取,零副作用)。 */
+export function readL2Comparisons(homeDir) {
+    const records = [];
+    for (const entry of readArchiveRecords(homeDir)) {
+        if (entry.kind !== L2_COMPARISON_ARCHIVE_KIND)
+            continue;
+        records.push(entry.payload);
+    }
+    return records;
+}
+/** 选择器视图:只给匿名标识与冻结交付物引用——不带 role/runId。 */
+export function presentL2Arms(record) {
+    return record.arms.map((arm) => ({ anonId: arm.anonId, artifacts: arm.artifacts }));
+}

package/dist/evolve/lesson.d.ts

@@ -0,0 +1,57 @@
+/**
+ * lesson 记录(trellis-evolve 任务 12.6)。
+ *
+ * 被采纳的编辑产出一条 lesson(cue / 正文 / 证据链接 / 可选 confidence /
+ * 层作用域,类型见 types.ts)。spec"lesson 记录与上下文呈现":
+ *
+ *   - canonical 记忆已启用 → 经现有记忆管道写入(缺省内置写入器把
+ *     lesson 落成 canonical `memories/lesson-<id>.md`;调用方可注入
+ *     自有管道);
+ *   - 未启用 → 只留运行档案,运行不失败:返回 skipped 而非 failed;
+ *   - 后续提案只呈现匹配上下文的 lesson:全局 lesson 处处可见,
+ *     workspace lesson 只给该 workspace;对其他上下文仅作为升格审批
+ *     的跨项目佐证(单独出口,不混入提案上下文)。
+ *
+ * "记忆已启用"是调用方判定后的显式参数(共享 Memory MCP 的 on/off
+ * 属托管配置面,消费者不读 mcp 配置 —— 10.3 边界)。档案恒写:lesson
+ * 的审计源是运行档案,记忆管道是投递产物。
+ */
+import type { Lesson } from "./types.js";
+/** 运行档案 kind:一条 lesson。payload 即 Lesson 的 JSON 形态。 */
+export declare const LESSON_ARCHIVE_KIND = "lesson";
+export type LessonMemoryStatus = "written" | "skipped" | "failed";
+export interface RecordLessonOptions {
+    readonly homeDir: string;
+    readonly lesson: Lesson;
+    /** canonical 记忆是否已启用(调用方按托管配置判定)。 */
+    readonly memoryEnabled: boolean;
+    /** 记忆管道写入缝;缺省内置写入器落 `memories/lesson-<id>.md`。
+     * 抛错按 failed 收口(仍留档案),不拖垮运行。 */
+    readonly writeMemory?: (lesson: Lesson) => void;
+}
+export interface RecordLessonResult {
+    readonly memoryStatus: LessonMemoryStatus;
+    /** 内置写入器落盘的路径(注入自有管道时为 undefined)。 */
+    readonly memoryPath?: string;
+    /** 写入失败时的错误信息(仅 failed)。 */
+    readonly error?: string;
+}
+/**
+ * 记录一条 lesson:恒写运行档案;记忆已启用才走记忆管道(未启用
+ * skipped;管道抛错 failed 但运行不中断)。
+ */
+export declare function recordLesson(options: RecordLessonOptions): RecordLessonResult;
+/** 全部 lesson(档案读取;档案是 lesson 的审计源)。 */
+export declare function readAllLessons(homeDir: string): Lesson[];
+/**
+ * 提案上下文用:只呈现匹配上下文的 lesson——全局处处可见;workspace
+ * lesson 只给同一 workspace root;其他 workspace 的 lesson 不进提案
+ * 上下文(spec 场景:仓库 X 的 lesson 不原样进入 Y)。
+ */
+export declare function lessonsForContext(homeDir: string, workspaceRoot?: string): Lesson[];
+/**
+ * 升格审批的跨项目佐证:当前上下文之外的 workspace lesson(全局
+ * lesson 不在此列——它们本就处处可见)。仅供升格审批参考,绝不混入
+ * 提案生成上下文。
+ */
+export declare function lessonsAsCorroboration(homeDir: string, workspaceRoot?: string): Lesson[];

package/dist/evolve/lesson.js

@@ -0,0 +1,97 @@
+/**
+ * lesson 记录(trellis-evolve 任务 12.6)。
+ *
+ * 被采纳的编辑产出一条 lesson(cue / 正文 / 证据链接 / 可选 confidence /
+ * 层作用域,类型见 types.ts)。spec"lesson 记录与上下文呈现":
+ *
+ *   - canonical 记忆已启用 → 经现有记忆管道写入(缺省内置写入器把
+ *     lesson 落成 canonical `memories/lesson-<id>.md`;调用方可注入
+ *     自有管道);
+ *   - 未启用 → 只留运行档案,运行不失败:返回 skipped 而非 failed;
+ *   - 后续提案只呈现匹配上下文的 lesson:全局 lesson 处处可见,
+ *     workspace lesson 只给该 workspace;对其他上下文仅作为升格审批
+ *     的跨项目佐证(单独出口,不混入提案上下文)。
+ *
+ * "记忆已启用"是调用方判定后的显式参数(共享 Memory MCP 的 on/off
+ * 属托管配置面,消费者不读 mcp 配置 —— 10.3 边界)。档案恒写:lesson
+ * 的审计源是运行档案,记忆管道是投递产物。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+/** 运行档案 kind:一条 lesson。payload 即 Lesson 的 JSON 形态。 */
+export const LESSON_ARCHIVE_KIND = "lesson";
+function defaultWriteMemory(homeDir, lesson) {
+    const dir = join(homeDir, ".trellis", "memories");
+    mkdirSync(dir, { recursive: true });
+    // lesson.id 已带 `lesson-` 前缀(产出方约定),文件名直接用 id。
+    const path = join(dir, `${lesson.id}.md`);
+    const evidenceLines = lesson.evidence.map((link) => {
+        const ref = link.kind === "run" ? link.runId : link.kind === "doctor-finding" ? link.findingId : link.signalId;
+        return `- ${link.kind}:${ref}`;
+    });
+    const confidenceLine = lesson.confidence !== undefined ? `confidence: ${lesson.confidence}\n` : "";
+    const layerLine = lesson.layer.kind === "global"
+        ? "layer: global"
+        : `layer: workspace(${lesson.layer.root})`;
+    writeFileSync(path, `# ${lesson.cue}\n\n${lesson.body}\n\n${layerLine}\n${confidenceLine}\nevidence:\n${evidenceLines.join("\n")}\n`, "utf-8");
+    return path;
+}
+/**
+ * 记录一条 lesson:恒写运行档案;记忆已启用才走记忆管道(未启用
+ * skipped;管道抛错 failed 但运行不中断)。
+ */
+export function recordLesson(options) {
+    const { homeDir, lesson, memoryEnabled } = options;
+    appendArchiveRecord(homeDir, { kind: LESSON_ARCHIVE_KIND, payload: lesson });
+    if (!memoryEnabled) {
+        return { memoryStatus: "skipped" };
+    }
+    try {
+        if (options.writeMemory !== undefined) {
+            options.writeMemory(lesson);
+            return { memoryStatus: "written" };
+        }
+        const memoryPath = defaultWriteMemory(homeDir, lesson);
+        return { memoryStatus: "written", memoryPath };
+    }
+    catch (err) {
+        return { memoryStatus: "failed", error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function lessonLayerMatches(lesson, workspaceRoot) {
+    const layer = lesson.layer;
+    if (layer.kind === "global")
+        return true;
+    return workspaceRoot !== undefined && layer.root === workspaceRoot;
+}
+/** 全部 lesson(档案读取;档案是 lesson 的审计源)。 */
+export function readAllLessons(homeDir) {
+    const lessons = [];
+    for (const entry of readArchiveRecords(homeDir)) {
+        if (entry.kind !== LESSON_ARCHIVE_KIND)
+            continue;
+        lessons.push(entry.payload);
+    }
+    return lessons;
+}
+/**
+ * 提案上下文用:只呈现匹配上下文的 lesson——全局处处可见;workspace
+ * lesson 只给同一 workspace root;其他 workspace 的 lesson 不进提案
+ * 上下文(spec 场景:仓库 X 的 lesson 不原样进入 Y)。
+ */
+export function lessonsForContext(homeDir, workspaceRoot) {
+    return readAllLessons(homeDir).filter((lesson) => lessonLayerMatches(lesson, workspaceRoot));
+}
+/**
+ * 升格审批的跨项目佐证:当前上下文之外的 workspace lesson(全局
+ * lesson 不在此列——它们本就处处可见)。仅供升格审批参考,绝不混入
+ * 提案生成上下文。
+ */
+export function lessonsAsCorroboration(homeDir, workspaceRoot) {
+    return readAllLessons(homeDir).filter((lesson) => {
+        if (lesson.layer.kind === "global")
+            return false;
+        return workspaceRoot === undefined || lesson.layer.root !== workspaceRoot;
+    });
+}

package/dist/evolve/pending.d.ts

@@ -0,0 +1,69 @@
+/**
+ * pending 提案存储与状态机(trellis-evolve 任务 12.4)。
+ *
+ * 存储在状态目录 `~/.trellis/evolve/pending/`(10.4 的规划子目录):
+ * 一提案一 JSON 文件,状态 `pending → approved | rejected` 只经管理面
+ * 命令变更(批准仅限交互式终端,见 `src/commands/evolve.ts`)。agent
+ * 侧的只读视图在 `agentView.ts` —— 暴露面物理分离,批准/应用能力不在
+ * agent 可达模块里(spec"批准只走带外通道")。
+ *
+ * 决策写运行档案(`proposal-decision`),与提案/verdict 同一条只追加
+ * 审计链;存储文件本身是可变状态(提案状态迁移),不是档案。
+ */
+import type { Proposal, RiskClass } from "./types.js";
+/** 提案状态:待批 → 已批准(待应用)/ 已拒绝。 */
+export type ProposalStatus = "pending" | "approved" | "rejected";
+/** 档案 kind:管理面批准/拒绝决策。 */
+export declare const PROPOSAL_DECISION_ARCHIVE_KIND = "proposal-decision";
+/** pending 存储中的一条提案记录(提案 + 分类结果 + 状态)。 */
+export interface PendingRecord {
+    readonly id: string;
+    readonly status: ProposalStatus;
+    readonly riskClass: RiskClass;
+    /** 12.3 分类器命中的规则 id(审计用;不采信 proposal 自报)。 */
+    readonly riskRuleId: string;
+    readonly proposal: Proposal;
+    readonly createdAt: number;
+    /** 决策时间(毫秒);未决策为 null。 */
+    readonly decidedAt: number | null;
+}
+/** pending 存储目录(只在状态目录下落盘)。 */
+export declare function pendingRecordsDir(homeDir: string): string;
+/** 提案 id → 文件名(路径安全字符;保留可读前缀)。 */
+export declare function safeProposalFileName(id: string): string;
+/**
+ * 入队一条提案(状态 pending)。分类结果由调用方经 12.3 分类器算出后
+ * 传入 —— 存储层不重算,只留审计痕迹。
+ */
+export declare function enqueueProposal(options: {
+    readonly homeDir: string;
+    readonly proposal: Proposal;
+    readonly riskClass: RiskClass;
+    readonly riskRuleId: string;
+    readonly now?: () => number;
+}): PendingRecord;
+/** 读回全部提案记录(按 id 排序;目录不存在返回 [],读取零副作用)。 */
+export declare function readPendingRecords(homeDir: string): PendingRecord[];
+/** 按状态过滤。 */
+export declare function readProposalsByStatus(homeDir: string, status: ProposalStatus): PendingRecord[];
+/** 单条读取;不存在返回 null。 */
+export declare function readPendingRecord(homeDir: string, id: string): PendingRecord | null;
+export type ProposalDecision = "approved" | "rejected";
+export type DecideProposalResult = {
+    readonly ok: true;
+    readonly record: PendingRecord;
+} | {
+    readonly ok: false;
+    readonly error: "not-found" | "already-decided";
+};
+/**
+ * 管理面决策(仅 `src/commands/evolve.ts` 的交互式批准路径调用;agent
+ * 可达面没有本函数)。写状态迁移 + 档案 `proposal-decision`;重复决策
+ * 拒绝(状态机单向)。
+ */
+export declare function decideProposal(options: {
+    readonly homeDir: string;
+    readonly id: string;
+    readonly decision: ProposalDecision;
+    readonly now?: () => number;
+}): DecideProposalResult;

package/dist/evolve/pending.js

@@ -0,0 +1,116 @@
+/**
+ * pending 提案存储与状态机(trellis-evolve 任务 12.4)。
+ *
+ * 存储在状态目录 `~/.trellis/evolve/pending/`(10.4 的规划子目录):
+ * 一提案一 JSON 文件,状态 `pending → approved | rejected` 只经管理面
+ * 命令变更(批准仅限交互式终端,见 `src/commands/evolve.ts`)。agent
+ * 侧的只读视图在 `agentView.ts` —— 暴露面物理分离,批准/应用能力不在
+ * agent 可达模块里(spec"批准只走带外通道")。
+ *
+ * 决策写运行档案(`proposal-decision`),与提案/verdict 同一条只追加
+ * 审计链;存储文件本身是可变状态(提案状态迁移),不是档案。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { appendArchiveRecord } from "./archive.js";
+import { evolveStateDir } from "./stateDir.js";
+/**
+ * 原子写 pending 记录(tmp + rename,新建 0600):pending 是可变磁盘
+ * 状态,半写的 JSON 会让 `readPendingRecords` 整体抛错(status/pending/
+ * 作业全受影响)。本目录只依赖 host 门面与 node 内置(边界 10.3),
+ * 助手就地实现,不引 src/lib。
+ */
+function writeRecordAtomic(path, record) {
+    const temporary = join(dirname(path), `.atomic-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`);
+    writeFileSync(temporary, JSON.stringify(record, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    renameSync(temporary, path);
+}
+/** 档案 kind:管理面批准/拒绝决策。 */
+export const PROPOSAL_DECISION_ARCHIVE_KIND = "proposal-decision";
+/** pending 存储目录(只在状态目录下落盘)。 */
+export function pendingRecordsDir(homeDir) {
+    return join(evolveStateDir(homeDir), "pending");
+}
+/** 提案 id → 文件名(路径安全字符;保留可读前缀)。 */
+export function safeProposalFileName(id) {
+    const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
+    return safe === "" || safe === "." || safe === ".." ? "proposal" : safe;
+}
+function pendingFilePath(homeDir, id) {
+    return join(pendingRecordsDir(homeDir), `${safeProposalFileName(id)}.json`);
+}
+function readRecordFile(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed.id !== "string" || typeof parsed.status !== "string") {
+        throw new Error(`pending: ${path} 形态不符(缺 id/status)`);
+    }
+    return parsed;
+}
+/**
+ * 入队一条提案(状态 pending)。分类结果由调用方经 12.3 分类器算出后
+ * 传入 —— 存储层不重算,只留审计痕迹。
+ */
+export function enqueueProposal(options) {
+    const now = (options.now ?? Date.now)();
+    const record = {
+        id: options.proposal.id,
+        status: "pending",
+        riskClass: options.riskClass,
+        riskRuleId: options.riskRuleId,
+        proposal: options.proposal,
+        createdAt: now,
+        decidedAt: null,
+    };
+    mkdirSync(pendingRecordsDir(options.homeDir), { recursive: true, mode: 0o700 });
+    writeRecordAtomic(pendingFilePath(options.homeDir, record.id), record);
+    return record;
+}
+/** 读回全部提案记录(按 id 排序;目录不存在返回 [],读取零副作用)。 */
+export function readPendingRecords(homeDir) {
+    const dir = pendingRecordsDir(homeDir);
+    if (!existsSync(dir))
+        return [];
+    const records = [];
+    for (const name of readdirSync(dir).sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        records.push(readRecordFile(join(dir, name)));
+    }
+    return records.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/** 按状态过滤。 */
+export function readProposalsByStatus(homeDir, status) {
+    return readPendingRecords(homeDir).filter((record) => record.status === status);
+}
+/** 单条读取;不存在返回 null。 */
+export function readPendingRecord(homeDir, id) {
+    const path = pendingFilePath(homeDir, id);
+    if (!existsSync(path))
+        return null;
+    return readRecordFile(path);
+}
+/**
+ * 管理面决策(仅 `src/commands/evolve.ts` 的交互式批准路径调用;agent
+ * 可达面没有本函数)。写状态迁移 + 档案 `proposal-decision`;重复决策
+ * 拒绝(状态机单向)。
+ */
+export function decideProposal(options) {
+    const existing = readPendingRecord(options.homeDir, options.id);
+    if (existing === null)
+        return { ok: false, error: "not-found" };
+    if (existing.status !== "pending")
+        return { ok: false, error: "already-decided" };
+    const now = (options.now ?? Date.now)();
+    const record = { ...existing, status: options.decision, decidedAt: now };
+    writeRecordAtomic(pendingFilePath(options.homeDir, record.id), record);
+    appendArchiveRecord(options.homeDir, {
+        kind: PROPOSAL_DECISION_ARCHIVE_KIND,
+        payload: {
+            proposalId: record.id,
+            decision: options.decision,
+            riskClass: record.riskClass,
+            riskRuleId: record.riskRuleId,
+        },
+    }, () => new Date(now));
+    return { ok: true, record };
+}

package/dist/evolve/probeWorkspace.d.ts

@@ -0,0 +1,57 @@
+/**
+ * probe 工作区隔离 helper(trellis-evolve 任务 13.3)。
+ *
+ * 探针会话必须跑在隔离环境里:mkdtemp 工作区(探针自己写文件)、staging
+ * 渲染配置(agent 配置面经 host 门面 `createStaging` 渲染进 scratch home,
+ * 真实 home 与 agent 原生配置逐字节不变)、重定向 agent 配置 HOME(spawn
+ * env 的 HOME/XDG 指向 scratch home,探针不读用户真实配置)。probe 启动
+ * 规格经 `assertNoBypassFlags` 断言不含任何审批/沙盒绕过标志(与 7.2 引擎
+ * 侧 spawn 规格同一禁令:D12 不使用 bypass 标志)。
+ *
+ * 本模块只交付隔离与断言;选择器执行与探针任务集不在本期范围。
+ */
+/**
+ * 审批/沙盒绕过标志词面:命中即拒绝。与引擎侧 7.2 断言
+ * (proposer spawn 规格)同一禁令——harness2 的
+ * `--dangerously-bypass-approvals-and-sandbox` 不采纳。
+ */
+export declare const PROBE_FORBIDDEN_FLAG: RegExp;
+/** probe 启动规格:argv + 重定向 agent 配置 HOME 的 env。 */
+export interface ProbeSpawnSpec {
+    readonly argv: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * 断言 argv 不含任何审批/沙盒绕过标志(含则抛错并点名)。
+ * 命令参数以 argv 数组传递,永不拼 shell 字符串——断言也因此只看词面。
+ */
+export declare function assertNoBypassFlags(argv: readonly string[]): void;
+/** 重定向 agent 配置 HOME 的 spawn env(配置面只从隔离 home 读)。 */
+export declare function probeEnv(homeDir: string): Record<string, string>;
+/** 构造 probe 启动规格:先断言无绕过标志,再绑定重定向 env。 */
+export declare function probeSpawnSpec(argv: readonly string[], homeDir: string): ProbeSpawnSpec;
+export interface CreateProbeWorkspaceOptions {
+    /** 源(真实)home——只读,配置面渲染进隔离;绝不写回。 */
+    homeDir: string;
+    /** 可选:把真实 workspace 树也渲染进隔离(默认不复制,探针工作区空白)。 */
+    workspaceRoot?: string | null;
+    /** 隔离树的落点;缺省 OS 临时目录。 */
+    tmpRoot?: string;
+}
+export interface ProbeWorkspace {
+    /** 全部隔离内容的根(mkdtemp);dispose() 整树删除,可重复调用。 */
+    readonly root: string;
+    /** 重定向后的 agent 配置 HOME(staging 渲染配置的 scratch home)。 */
+    readonly homeDir: string;
+    /** 探针会话的工作区(空白 mkdtemp 目录)。 */
+    readonly workspaceDir: string;
+    /** probe 启动 env(HOME/XDG 重定向到隔离 home)。 */
+    readonly env: Readonly<Record<string, string>>;
+    dispose(): void;
+}
+/**
+ * 三件套一次到位:mkdtemp 工作区 + staging 渲染配置 + 重定向 HOME env。
+ * staging 复制面被 NATIVE_CHECK_SURFACE 约束(凭据形态永不进隔离树,
+ * 与 morphix-env 边界一致)。
+ */
+export declare function createProbeWorkspace(options: CreateProbeWorkspaceOptions): ProbeWorkspace;

package/dist/evolve/probeWorkspace.js

@@ -0,0 +1,69 @@
+/**
+ * probe 工作区隔离 helper(trellis-evolve 任务 13.3)。
+ *
+ * 探针会话必须跑在隔离环境里:mkdtemp 工作区(探针自己写文件)、staging
+ * 渲染配置(agent 配置面经 host 门面 `createStaging` 渲染进 scratch home,
+ * 真实 home 与 agent 原生配置逐字节不变)、重定向 agent 配置 HOME(spawn
+ * env 的 HOME/XDG 指向 scratch home,探针不读用户真实配置)。probe 启动
+ * 规格经 `assertNoBypassFlags` 断言不含任何审批/沙盒绕过标志(与 7.2 引擎
+ * 侧 spawn 规格同一禁令:D12 不使用 bypass 标志)。
+ *
+ * 本模块只交付隔离与断言;选择器执行与探针任务集不在本期范围。
+ */
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { createStaging } from "../host/index.js";
+/**
+ * 审批/沙盒绕过标志词面:命中即拒绝。与引擎侧 7.2 断言
+ * (proposer spawn 规格)同一禁令——harness2 的
+ * `--dangerously-bypass-approvals-and-sandbox` 不采纳。
+ */
+export const PROBE_FORBIDDEN_FLAG = /dangerous|bypass|skip-permissions|yolo/i;
+/**
+ * 断言 argv 不含任何审批/沙盒绕过标志(含则抛错并点名)。
+ * 命令参数以 argv 数组传递,永不拼 shell 字符串——断言也因此只看词面。
+ */
+export function assertNoBypassFlags(argv) {
+    for (const arg of argv) {
+        if (PROBE_FORBIDDEN_FLAG.test(arg)) {
+            throw new Error(`probe 规格含审批/沙盒绕过标志: ${arg}`);
+        }
+    }
+}
+/** 重定向 agent 配置 HOME 的 spawn env(配置面只从隔离 home 读)。 */
+export function probeEnv(homeDir) {
+    return {
+        HOME: homeDir,
+        XDG_CONFIG_HOME: join(homeDir, ".config"),
+    };
+}
+/** 构造 probe 启动规格:先断言无绕过标志,再绑定重定向 env。 */
+export function probeSpawnSpec(argv, homeDir) {
+    assertNoBypassFlags(argv);
+    return { argv, env: probeEnv(homeDir) };
+}
+/**
+ * 三件套一次到位:mkdtemp 工作区 + staging 渲染配置 + 重定向 HOME env。
+ * staging 复制面被 NATIVE_CHECK_SURFACE 约束(凭据形态永不进隔离树,
+ * 与 morphix-env 边界一致)。
+ */
+export function createProbeWorkspace(options) {
+    const staging = createStaging({
+        homeDir: options.homeDir,
+        workspaceRoot: options.workspaceRoot ?? null,
+        tmpRoot: options.tmpRoot,
+    });
+    const workspaceDir = mkdtempSync(join(staging.root, "probe-workspace-"));
+    mkdirSync(join(workspaceDir, ".config"), { recursive: true });
+    return {
+        root: staging.root,
+        homeDir: staging.homeDir,
+        workspaceDir,
+        env: probeEnv(staging.homeDir),
+        dispose() {
+            // staging.dispose 删整树(workspaceDir 在其内),安全幂等。
+            staging.dispose();
+            rmSync(staging.root, { recursive: true, force: true });
+        },
+    };
+}

package/dist/evolve/propose.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 提案通道选择与 rule-based fallback(trellis-evolve 任务 12.2)。
+ *
+ * 正常通道是 editor(agent-bridge `runDelegatedCall` 委派或 spawn 本机
+ * CLI);委派/spawn 双不可用时,doctor finding 形态的信号走 rule-based
+ * 提案 —— 对有显而易见机械修复的 finding kind 直接构造提案,不调模型。
+ * 本期唯一定义的机械修复:`workspace-toml-invalid` 把解析失败行注释掉
+ * (TOML 有注释语法且 doctor 消息带行号;JSON 无注释语法、无行号的
+ * 情形返回 null,不硬造)。
+ *
+ * rule-based 产出的提案是草稿:仍要过 12.2 机械校验与 12.1 的 L1 前闸,
+ * 是否真的修好由 verdict 差集说话,不在这里担保。`riskClass` 只是占位
+ * ("B"),12.3 按 kind+target 重算,不采信自报。
+ */
+import type { CheckEntry } from "../host/index.js";
+import type { Proposal, Signal } from "./types.js";
+/** 提案通道可用性:委派(agent-bridge)与 spawn(本机 CLI)各一票。 */
+export interface ProposalChannelAvailability {
+    readonly delegate: boolean;
+    readonly spawn: boolean;
+}
+/**
+ * 通道选择:任一通道可用走 editor;双不可用才降级 rule-based。
+ * rule-based 不是"更好的编辑",是无模型可用时对机械可修 finding 的兜底。
+ */
+export declare function selectProposalChannel(availability: ProposalChannelAvailability): "editor" | "rule-based";
+/** doctor finding 形态信号:stableId 以 `doctor:` 开头(= CheckEntry.id)。 */
+export declare function isDoctorFindingSignal(signal: Pick<Signal, "stableId">): boolean;
+export interface TomlFindingLocator {
+    readonly path: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly reason: string;
+}
+/** 解析 workspace-toml-invalid 的消息 → 路径/行/列/原因;形态不符返回 null。 */
+export declare function parseTomlFindingMessage(message: string): TomlFindingLocator | null;
+export interface RuleBasedOptions {
+    /** 缺省 `rule-<findingId>`;调用方要确定性 id 时注入。 */
+    readonly id?: string;
+    /** 时间源(毫秒);缺省 Date.now。 */
+    readonly now?: () => number;
+    /** 读原文注入缝(测试可免写盘);缺省读真实文件。 */
+    readonly readFile?: (path: string) => string;
+}
+/**
+ * 对单条检查条目构造 rule-based 提案;没有显而易见机械修复时返回 null。
+ * `workspace-toml-invalid`:失败行行首加 `# ` 注释(行已注释/空行时没
+ * 有可注释的目标,返回 null 不硬造)。
+ */
+export declare function ruleBasedProposal(entry: CheckEntry, options?: RuleBasedOptions): Proposal | null;
+export interface RuleBasedProposeOptions {
+    readonly signals: readonly Signal[];
+    readonly findings: readonly CheckEntry[];
+    readonly availability: ProposalChannelAvailability;
+    readonly now?: () => number;
+    readonly readFile?: (path: string) => string;
+}
+export interface RuleBasedProposeResult {
+    readonly channel: "editor" | "rule-based";
+    /** 产出的草稿提案(仍待机械校验与 L1 前闸)。 */
+    readonly proposals: readonly Proposal[];
+    /** 无法机械修复的 doctor finding(带原因,便于档案/日志)。 */
+    readonly skipped: readonly {
+        readonly findingId: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * 信号 → rule-based 提案:只在 rule-based 通道消费 doctor finding 形态
+ * 信号(按 stableId 对齐 findings);editor 通道由 editor 产出提案,本
+ * 函数不代劳(channel 透传,proposals 为空)。
+ */
+export declare function proposeFromSignals(options: RuleBasedProposeOptions): RuleBasedProposeResult;