agent-trellis 0.19.0 → 0.20.0

package/dist/evolve/apply.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 应用与生效(trellis-evolve 任务 12.5)。
+ *
+ * 把**已批准**提案的全部编辑写入托管备份会话的同一会话内
+ * (spec"原子运行与回滚":一次运行的全部写入在同一备份会话,一次回滚
+ * 恢复运行前状态),并把备份会话标识记入运行档案(kind `apply-run`)。
+ *
+ * 采纳后的生效边界(spec"采纳的生效边界"):
+ *   - runtime 投递("events")的 agent:后续会话读取 canonical 时自然
+ *     生效,无需同步(9.4 定案:runtime provider 每请求实时读盘);
+ *   - 仅原生渲染("doctor-only")的 agent:触发渲染同步,报告同步结果。
+ *
+ * 同步经注入缝触发:`triggerSync` 由管理面/作业层注入 `runSync` 包装
+ * (消费者边界 10.3:本目录不 import `commands/*`),测试注入桩。缺省
+ * 未注入时只报告生效时点,不假装同步已经发生。
+ *
+ * 已应用查重以档案为准(apply-run 的 proposalIds):重复调用跳过,
+ * 不开第二个会话;部分失败的 HostEditError 批次照记档案(failed 标记,
+ * 不计入查重),提案不标已应用,重试重放(编辑幂等:write-file 整文件
+ * 写,remove-symlink 对已不存在目标视为成功)。
+ *
+ * 生效时点说明(effects)与同步结果随 apply-run 档案入档(trellis-
+ * evolve-review-fixes:此前算完即弃,报告不可回放)。同步触发失败收口
+ * 为效果文本并入档,不丢应用档案——编辑已写入,同步可人工补。
+ */
+/** 运行档案 kind:一次应用运行(含备份会话标识与提案集合)。 */
+export declare const APPLY_ARCHIVE_KIND = "apply-run";
+/** 与 host/levels 的 EvolveObservation 同语义:由调用方按 delivery
+ * 分类注入("events" = runtime 交付;"doctor-only" = 仅原生渲染)。 */
+export type ApplyObservation = "events" | "doctor-only";
+export interface ApplyAgent {
+    readonly agent: string;
+    readonly observation: ApplyObservation;
+}
+export interface AgentEffectiveness {
+    readonly agent: string;
+    readonly observation: ApplyObservation;
+    /** 人类可读的生效时点说明(应用后向用户展示)。 */
+    readonly effect: string;
+}
+export interface ApplyApprovedOptions {
+    readonly homeDir: string;
+    /** 托管 agent 及其交付形态;缺省空(只应用,不逐 agent 说明)。 */
+    readonly agents?: readonly ApplyAgent[];
+    /** 原生渲染 agent 的同步触发注入缝;存在 doctor-only agent 且本次
+     * 有编辑被应用时调用一次。返回值的 exitCode 进入结果与生效说明。 */
+    readonly triggerSync?: () => Promise<{
+        exitCode: number;
+    }>;
+    /** 时间源;缺省 Date.now(仅透传档案打戳用,档案自带 now 缺省)。 */
+    readonly now?: () => Date;
+}
+export interface ApplyApprovedResult {
+    /** 本次备份会话标识;无未应用的已批准提案时 null(不开会话)。 */
+    readonly runId: string | null;
+    readonly appliedProposalIds: string[];
+    readonly alreadyAppliedIds: string[];
+    readonly effects: AgentEffectiveness[];
+    /** 原生渲染同步的退出码;未触发为 null。 */
+    readonly syncExitCode: number | null;
+    /** 同步触发抛错时的错误文本(收口为效果文本,不中断应用);无为 null。 */
+    readonly syncError: string | null;
+    /** 应用前重校验不通过而跳过的提案 id(纵深防御,见实现注释)。 */
+    readonly skippedInvalidIds: string[];
+}
+/**
+ * 应用全部已批准且未应用的提案:编辑合并进**同一个**备份会话写入,
+ * 档案记会话标识,再按 agent 交付形态说明生效时点并对原生渲染 agent
+ * 触发同步。无事可做时零副作用(不开会话、不触发同步、不写档案)。
+ */
+export declare function applyApprovedProposals(options: ApplyApprovedOptions): Promise<ApplyApprovedResult>;

package/dist/evolve/apply.js

@@ -0,0 +1,162 @@
+/**
+ * 应用与生效(trellis-evolve 任务 12.5)。
+ *
+ * 把**已批准**提案的全部编辑写入托管备份会话的同一会话内
+ * (spec"原子运行与回滚":一次运行的全部写入在同一备份会话,一次回滚
+ * 恢复运行前状态),并把备份会话标识记入运行档案(kind `apply-run`)。
+ *
+ * 采纳后的生效边界(spec"采纳的生效边界"):
+ *   - runtime 投递("events")的 agent:后续会话读取 canonical 时自然
+ *     生效,无需同步(9.4 定案:runtime provider 每请求实时读盘);
+ *   - 仅原生渲染("doctor-only")的 agent:触发渲染同步,报告同步结果。
+ *
+ * 同步经注入缝触发:`triggerSync` 由管理面/作业层注入 `runSync` 包装
+ * (消费者边界 10.3:本目录不 import `commands/*`),测试注入桩。缺省
+ * 未注入时只报告生效时点,不假装同步已经发生。
+ *
+ * 已应用查重以档案为准(apply-run 的 proposalIds):重复调用跳过,
+ * 不开第二个会话;部分失败的 HostEditError 批次照记档案(failed 标记,
+ * 不计入查重),提案不标已应用,重试重放(编辑幂等:write-file 整文件
+ * 写,remove-symlink 对已不存在目标视为成功)。
+ *
+ * 生效时点说明(effects)与同步结果随 apply-run 档案入档(trellis-
+ * evolve-review-fixes:此前算完即弃,报告不可回放)。同步触发失败收口
+ * 为效果文本并入档,不丢应用档案——编辑已写入,同步可人工补。
+ */
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+import { readProposalsByStatus } from "./pending.js";
+import { validateProposal } from "./validate.js";
+import { applyEdits, HostEditError } from "../host/index.js";
+/** 运行档案 kind:一次应用运行(含备份会话标识与提案集合)。 */
+export const APPLY_ARCHIVE_KIND = "apply-run";
+function appliedIdsFromArchive(homeDir) {
+    const applied = new Set();
+    for (const entry of readArchiveRecords(homeDir)) {
+        if (entry.kind !== APPLY_ARCHIVE_KIND)
+            continue;
+        const payload = entry.payload;
+        // 部分失败的批次(failed)不计入"已应用":重试按幂等重放全部编辑。
+        if (payload === null || payload.failed === true || !Array.isArray(payload.proposalIds))
+            continue;
+        for (const id of payload.proposalIds) {
+            if (typeof id === "string")
+                applied.add(id);
+        }
+    }
+    return applied;
+}
+function effectivenessFor(agent, syncExitCode, syncTriggered, syncError) {
+    if (agent.observation === "events") {
+        return {
+            agent: agent.agent,
+            observation: agent.observation,
+            effect: "后续会话读取 canonical 时自然生效(runtime 投递,无需同步)",
+        };
+    }
+    if (syncTriggered) {
+        return {
+            agent: agent.agent,
+            observation: agent.observation,
+            effect: `已触发渲染同步(exit ${String(syncExitCode ?? "?")}),同步完成后生效`,
+        };
+    }
+    if (syncError !== null) {
+        return {
+            agent: agent.agent,
+            observation: agent.observation,
+            effect: `触发渲染同步失败:${syncError};需运行 \`trellis sync\` 后生效`,
+        };
+    }
+    return {
+        agent: agent.agent,
+        observation: agent.observation,
+        effect: "需运行 `trellis sync` 后生效(本次未提供同步触发)",
+    };
+}
+/**
+ * 应用全部已批准且未应用的提案:编辑合并进**同一个**备份会话写入,
+ * 档案记会话标识,再按 agent 交付形态说明生效时点并对原生渲染 agent
+ * 触发同步。无事可做时零副作用(不开会话、不触发同步、不写档案)。
+ */
+export async function applyApprovedProposals(options) {
+    const { homeDir } = options;
+    const alreadyApplied = appliedIdsFromArchive(homeDir);
+    const approved = readProposalsByStatus(homeDir, "approved");
+    const appliedProposalIds = [];
+    const alreadyAppliedIds = [];
+    const skippedInvalidIds = [];
+    const edits = [];
+    for (const record of approved) {
+        if (alreadyApplied.has(record.id)) {
+            alreadyAppliedIds.push(record.id);
+            continue;
+        }
+        // 纵深防御:应用前重跑机械校验。pending 是可变磁盘状态,approve 只
+        // 翻 status 字段——入队时的白名单/路径穿越约束在这一步重放,磁盘
+        // 漂移或被改写的编辑到不了写入面。
+        const validation = validateProposal(record.proposal, { homeDir });
+        if (!validation.ok) {
+            skippedInvalidIds.push(record.id);
+            continue;
+        }
+        appliedProposalIds.push(record.id);
+        for (const edit of record.proposal.edits)
+            edits.push(edit);
+    }
+    if (appliedProposalIds.length === 0) {
+        return {
+            runId: null,
+            appliedProposalIds: [],
+            alreadyAppliedIds,
+            effects: [],
+            syncExitCode: null,
+            syncError: null,
+            skippedInvalidIds,
+        };
+    }
+    let runId;
+    try {
+        ({ runId } = await applyEdits({ homeDir, edits, command: "evolve-apply" }));
+    }
+    catch (err) {
+        if (err instanceof HostEditError) {
+            // 部分失败也落 apply-run 档案(failed 不计入已应用查重):runId
+            // 可经 `trellis rollback` 撤销已应用部分,审计不留空白。
+            appendArchiveRecord(homeDir, {
+                kind: APPLY_ARCHIVE_KIND,
+                payload: { runId: err.runId, proposalIds: appliedProposalIds, failed: true, error: err.message },
+            }, options.now ?? (() => new Date()));
+        }
+        throw err;
+    }
+    // 生效:原生渲染 agent 触发同步(runtime agent 无需——9.4 实时读取)。
+    // 同步失败收口为效果文本(syncError),不丢应用档案:编辑已写入,同步可人工补。
+    const agents = options.agents ?? [];
+    const needsSync = agents.some((a) => a.observation === "doctor-only");
+    let syncExitCode = null;
+    let syncTriggered = false;
+    let syncError = null;
+    if (needsSync && options.triggerSync !== undefined) {
+        try {
+            syncExitCode = (await options.triggerSync()).exitCode;
+            syncTriggered = true;
+        }
+        catch (err) {
+            syncError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const effects = agents.map((agent) => effectivenessFor(agent, syncExitCode, syncTriggered, syncError));
+    // 档案记会话标识 + 逐 agent 生效时点 + 同步结果(review-fixes ❌3:此前
+    // effects 算完即弃);单条 apply-run 记录承载全部应用元数据,报告回放同源。
+    appendArchiveRecord(homeDir, {
+        kind: APPLY_ARCHIVE_KIND,
+        payload: {
+            runId,
+            proposalIds: appliedProposalIds,
+            effects,
+            syncExitCode,
+            ...(syncError !== null ? { syncError } : {}),
+        },
+    }, options.now ?? (() => new Date()));
+    return { runId, appliedProposalIds, alreadyAppliedIds, effects, syncExitCode, syncError, skippedInvalidIds };
+}

package/dist/evolve/archive.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 运行档案写入器(trellis-evolve 任务 10.4)。
+ *
+ * `archive/records.jsonl` 只追加 JSONL:提案/探针/verdict/备份会话标识/
+ * L2 比较记录按发生顺序落行,永不覆盖、不重排、不去重。读取侧严格解析
+ * ——档案是治理审计数据,坏行必须带行号抛出而不是静默跳过。
+ *
+ * 记录格式:`{ kind, recordedAt, payload }`。`kind` 开放(各任务逐步收
+ * 敛:proposal/verdict/lesson/L2 比较等),`payload` 为 JSON 安全的具体
+ * 记录;`recordedAt` 由写入器打戳(ISO 8601)。
+ */
+export interface ArchiveRecord {
+    readonly kind: string;
+    readonly payload: unknown;
+}
+export interface ArchiveEntry extends ArchiveRecord {
+    readonly recordedAt: string;
+}
+export declare function archiveRecordsPath(homeDir: string): string;
+/** 只追加一条记录,返回落盘后的完整条目(含打戳)。 */
+export declare function appendArchiveRecord(homeDir: string, record: ArchiveRecord, now?: () => Date): ArchiveEntry;
+/** 读回全部档案条目;文件不存在返回 [](读取零副作用,不建目录)。 */
+export declare function readArchiveRecords(homeDir: string): ArchiveEntry[];

package/dist/evolve/archive.js

@@ -0,0 +1,58 @@
+/**
+ * 运行档案写入器(trellis-evolve 任务 10.4)。
+ *
+ * `archive/records.jsonl` 只追加 JSONL:提案/探针/verdict/备份会话标识/
+ * L2 比较记录按发生顺序落行,永不覆盖、不重排、不去重。读取侧严格解析
+ * ——档案是治理审计数据,坏行必须带行号抛出而不是静默跳过。
+ *
+ * 记录格式:`{ kind, recordedAt, payload }`。`kind` 开放(各任务逐步收
+ * 敛:proposal/verdict/lesson/L2 比较等),`payload` 为 JSON 安全的具体
+ * 记录;`recordedAt` 由写入器打戳(ISO 8601)。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { evolveStateDir } from "./stateDir.js";
+export function archiveRecordsPath(homeDir) {
+    return join(evolveStateDir(homeDir), "archive", "records.jsonl");
+}
+/** 只追加一条记录,返回落盘后的完整条目(含打戳)。 */
+export function appendArchiveRecord(homeDir, record, now = () => new Date()) {
+    const entry = { kind: record.kind, recordedAt: now().toISOString(), payload: record.payload };
+    mkdirSync(join(evolveStateDir(homeDir), "archive"), { recursive: true, mode: 0o700 });
+    // 单行约定:JSON.stringify 会把 payload 内的换行转义,行边界天然成立。
+    // 新建 0600:档案含提案内容(配置文件片段),不收世界可读。
+    appendFileSync(archiveRecordsPath(homeDir), JSON.stringify(entry) + "\n", { mode: 0o600 });
+    return entry;
+}
+/** 读回全部档案条目;文件不存在返回 [](读取零副作用,不建目录)。 */
+export function readArchiveRecords(homeDir) {
+    const path = archiveRecordsPath(homeDir);
+    if (!existsSync(path))
+        return [];
+    const entries = [];
+    const lines = readFileSync(path, "utf-8").split("\n");
+    for (const [index, line] of lines.entries()) {
+        // 末尾换行产生一条尾随空行,不算记录;中间空行是损坏。
+        if (line === "" && index === lines.length - 1)
+            continue;
+        if (line.trim() === "")
+            throw new Error(`archive: 第 ${index + 1} 行为空行(只追加档案不允许空行)`);
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`archive: 第 ${index + 1} 行不是合法 JSON`);
+        }
+        const entry = parsed;
+        if (typeof entry !== "object" ||
+            entry === null ||
+            typeof entry.kind !== "string" ||
+            typeof entry.recordedAt !== "string" ||
+            !("payload" in entry)) {
+            throw new Error(`archive: 第 ${index + 1} 行缺少 kind/recordedAt/payload`);
+        }
+        entries.push(entry);
+    }
+    return entries;
+}

package/dist/evolve/erase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * secrets 擦除(trellis-evolve 任务 11.1)。
+ *
+ * 信号写入前,所有字符串字段经此擦除(11.2 的用户纠正文本同样如此)。
+ * 模式取已知凭据形态:API token 前缀、Bearer 头、key=value 凭据赋值、
+ * PEM 私钥块。不承诺穷尽 —— 主防线是事件层根本不收载荷,这里是纵深。
+ */
+/** 对单个字符串字段做 secrets 擦除;非敏感内容原样保留。 */
+export declare function eraseSecrets(text: string): string;
+/** 对记录中所有字符串值递归擦除(载荷级防御)。 */
+export declare function eraseSecretsDeep(value: unknown): unknown;
+/**
+ * 凭据形态**字面值**检测(12.2 的 workspace 可提交约束):先把
+ * `${VAR}` 引用挖掉(合法引用不算字面值),再用与擦除同源的凭据形态
+ * 模式判定剩余文本。命中即 true —— 只认形态,不承诺穷尽。
+ */
+export declare function containsCredentialLiteral(text: string): boolean;

package/dist/evolve/erase.js

@@ -0,0 +1,65 @@
+/**
+ * secrets 擦除(trellis-evolve 任务 11.1)。
+ *
+ * 信号写入前,所有字符串字段经此擦除(11.2 的用户纠正文本同样如此)。
+ * 模式取已知凭据形态:API token 前缀、Bearer 头、key=value 凭据赋值、
+ * PEM 私钥块。不承诺穷尽 —— 主防线是事件层根本不收载荷,这里是纵深。
+ */
+const PATTERNS = [
+    // OpenAI / Anthropic 风格:sk-...、sk-ant-...
+    [/sk-[A-Za-z0-9_-]{8,}/g, "[REDACTED]"],
+    // GitHub token:ghp_/gho_/ghs_/ghr_/github_pat_
+    [/gh[pousr]_[A-Za-z0-9]{16,}/g, "[REDACTED]"],
+    [/github_pat_[A-Za-z0-9_]{20,}/g, "[REDACTED]"],
+    // AWS access key id
+    [/AKIA[0-9A-Z]{12,}/g, "[REDACTED]"],
+    // JWT(三段 base64url,header 恒以 eyJ 开头)
+    [/eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "[REDACTED]"],
+    // Slack token:xoxb/xoxp/xoxa/xoxs/xoxr
+    [/xox[bpasr]-[A-Za-z0-9-]{8,}/g, "[REDACTED]"],
+    // Bearer 头
+    [/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/g, "Bearer [REDACTED]"],
+    // key=value / key: value 凭据赋值形态(值若是 Bearer/Basic 头留给上面
+    // 的 Bearer 规则处理,避免只吃掉 scheme 词、漏掉真实 token)。
+    [
+        /((?:api[_-]?key|apikey|token|secret|password|passwd|credential|authorization|access[_-]?key)["']?\s*[:=]\s*["']?)(?!(?:Bearer|Basic|Token)\b)[^\s"'&;,]{4,}/gi,
+        "$1[REDACTED]",
+    ],
+    // PEM 私钥块
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED]"],
+];
+/** 对单个字符串字段做 secrets 擦除;非敏感内容原样保留。 */
+export function eraseSecrets(text) {
+    let out = text;
+    for (const [pattern, replacement] of PATTERNS)
+        out = out.replace(pattern, replacement);
+    return out;
+}
+/** 对记录中所有字符串值递归擦除(载荷级防御)。 */
+export function eraseSecretsDeep(value) {
+    if (typeof value === "string")
+        return eraseSecrets(value);
+    if (Array.isArray(value))
+        return value.map(eraseSecretsDeep);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, v] of Object.entries(value))
+            out[key] = eraseSecretsDeep(v);
+        return out;
+    }
+    return value;
+}
+/** `${VAR}` 引用(workspace 可提交约束明确允许)。 */
+const VAR_REF = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/g;
+/**
+ * 凭据形态**字面值**检测(12.2 的 workspace 可提交约束):先把
+ * `${VAR}` 引用挖掉(合法引用不算字面值),再用与擦除同源的凭据形态
+ * 模式判定剩余文本。命中即 true —— 只认形态,不承诺穷尽。
+ */
+export function containsCredentialLiteral(text) {
+    const withoutRefs = text.replace(VAR_REF, "");
+    return PATTERNS.some(([pattern]) => {
+        pattern.lastIndex = 0;
+        return pattern.test(withoutRefs);
+    });
+}

package/dist/evolve/extension.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 进化订阅者型扩展的 `activate` 包装(design 8.1 定案的装载契约;trees
+ * 11.1/11.5 的生产接线)。
+ *
+ * 装载契约:模块导出 `activate(ctx)` 返回 `{ providers?, subscribers? }`,
+ * 由 `~/.trellis/mcp/extensions.yaml` 的清单条目(进化启用命令写入)
+ * 指向本模块;gateway 启动时动态 import 并装载。契约的结构形状与
+ * `src/lib/hostExtensions.ts` 的 `HostExtension*` 一致——import 边界
+ * (10.3)不允许 `src/evolve/` 引 `src/lib/*`,这里以结构类型对接,
+ * 由装载集成测试证明形状兼容。
+ *
+ * 订阅者按级别(activate 时解析,本进程恒定——gateway 按会话拉起):
+ *   - `off`:零订阅者(结构上零副作用;清单条目本应在置 off 时被移除,
+ *     此处是防御)。
+ *   - `observe` 及以上:recorder(事件 → 信号,enabled 恒真——级别已判)。
+ *   - `propose`/`auto-A`:另有触发器订阅者(会话结束判定拉起作业、会话
+ *     启动补偿判定)。observe 是"只采集信号",不拉起作业。
+ */
+import type { HostEvent } from "../host/hostEvents.js";
+/** 清单条目 id(进化启用命令写入 `~/.trellis/mcp/extensions.yaml` 用)。 */
+export declare const EVOLVE_EXTENSION_ID = "evolve";
+/** 装载契约的结构形状(与 src/lib/hostExtensions.ts 同形,不 import)。 */
+interface ActivateContext {
+    readonly homeDir: string;
+    readonly agent: string;
+    readonly workspaceRoot: string | null;
+}
+interface Activation {
+    readonly subscribers?: ReadonlyArray<(event: HostEvent) => void>;
+}
+export declare function activate(context: ActivateContext): Activation;
+/**
+ * 清单条目的 `load` 模块说明符:本模块的绝对路径(dist 的 .js;经 tsx
+ * 直跑源码时为 .ts,动态 import 都能吃)。进化启用命令写清单时取此值。
+ */
+export declare function evolveExtensionLoadSpecifier(): string;
+export {};

package/dist/evolve/extension.js

@@ -0,0 +1,63 @@
+/**
+ * 进化订阅者型扩展的 `activate` 包装(design 8.1 定案的装载契约;trees
+ * 11.1/11.5 的生产接线)。
+ *
+ * 装载契约:模块导出 `activate(ctx)` 返回 `{ providers?, subscribers? }`,
+ * 由 `~/.trellis/mcp/extensions.yaml` 的清单条目(进化启用命令写入)
+ * 指向本模块;gateway 启动时动态 import 并装载。契约的结构形状与
+ * `src/lib/hostExtensions.ts` 的 `HostExtension*` 一致——import 边界
+ * (10.3)不允许 `src/evolve/` 引 `src/lib/*`,这里以结构类型对接,
+ * 由装载集成测试证明形状兼容。
+ *
+ * 订阅者按级别(activate 时解析,本进程恒定——gateway 按会话拉起):
+ *   - `off`:零订阅者(结构上零副作用;清单条目本应在置 off 时被移除,
+ *     此处是防御)。
+ *   - `observe` 及以上:recorder(事件 → 信号,enabled 恒真——级别已判)。
+ *   - `propose`/`auto-A`:另有触发器订阅者(会话结束判定拉起作业、会话
+ *     启动补偿判定)。observe 是"只采集信号",不拉起作业。
+ */
+import { fileURLToPath } from "node:url";
+import { loadEvolveLevelPolicy, resolveEvolveLevel } from "../host/levels.js";
+import { createSignalRecorder } from "./recorder.js";
+import { maybeLaunchOnSessionEnd, maybeLaunchOnSessionStart } from "./trigger.js";
+/** 清单条目 id(进化启用命令写入 `~/.trellis/mcp/extensions.yaml` 用)。 */
+export const EVOLVE_EXTENSION_ID = "evolve";
+function levelAt(context) {
+    const policy = loadEvolveLevelPolicy(context.homeDir);
+    return resolveEvolveLevel(policy, {
+        agent: context.agent,
+        workspaceRoot: context.workspaceRoot,
+    });
+}
+export function activate(context) {
+    const level = levelAt(context);
+    if (level === "off")
+        return {};
+    const recorder = createSignalRecorder({
+        homeDir: context.homeDir,
+        enabled: () => true,
+    });
+    const subscribers = [recorder.handle];
+    if (level !== "observe") {
+        const policy = loadEvolveLevelPolicy(context.homeDir);
+        const options = {
+            homeDir: context.homeDir,
+            enabled: () => true,
+            ...(policy.trigger !== undefined ? { limits: policy.trigger } : {}),
+        };
+        subscribers.push((event) => {
+            if (event.kind === "session_end")
+                maybeLaunchOnSessionEnd(options);
+            else if (event.kind === "session_start")
+                maybeLaunchOnSessionStart(options);
+        });
+    }
+    return { subscribers };
+}
+/**
+ * 清单条目的 `load` 模块说明符:本模块的绝对路径(dist 的 .js;经 tsx
+ * 直跑源码时为 .ts,动态 import 都能吃)。进化启用命令写清单时取此值。
+ */
+export function evolveExtensionLoadSpecifier() {
+    return fileURLToPath(import.meta.url);
+}

package/dist/evolve/gate.d.ts

@@ -0,0 +1,95 @@
+/**
+ * L1 doctor-oracle 前闸(trellis-evolve 任务 12.1)。
+ *
+ * 两副职责:
+ *
+ * 1. **提案类域分派**:仅 `L1_CONFIG_KINDS` 白名单内的配置类提案进入
+ *    提案通道;内容类提案本期不产出(等 L2 选择器执行落地)。design D8
+ *    "L1 适用域的判定由 L4 治理层按 kind 白名单执行"——本模块就是该判定
+ *    点,12.2 的机械校验对提案 kind 的准入与此同源。
+ * 2. **确定性候选 verdict 差集**:对真实 baseline 与 staging 候选各运行
+ *    一组结构化检查(doctor findings、`sync --check`、secrets audit),
+ *    按 (稳定 id, 层归属) 集合差判定。在 L1 适用域内该差集是**唯一
+ *    verdict**,配置类提案不运行引擎评分链。
+ *
+ * 可采纳判据(design D8,从严):无新条目 ∧ 全部目标条目被消除 ∧ 其余
+ * 条目不变(未声明的消除也算变化)。目标条目 = 提案 evidence 中
+ * `doctor-finding` 链接的 `findingId`(即 CheckEntry.id);`Proposal.target`
+ * 本身是被编辑面的锚点(spec:"目标为某 MCP server auth 块"、"目标路径
+ * 位于某仓库的 .agents/ 内"),不是检查条目——两者职责分开,本闸只消费
+ * findingId。目标条目不在 baseline 时"无法确认修复",按不采纳收口。
+ *
+ * staging 复现层分裂:`createStaging` 拷 scratch 全局 HOME + 临时
+ * workspace root(墓碑生效),提案 edits 由本模块把真实面绝对路径重定位
+ * 到 scratch(越界不采纳);baseline 与候选都带 `logicalWorkspaceRoot`
+ * 归一化,条目比较键含层归属(`workspace(<root>)` 与全局不混)。
+ *
+ * 失败收口(Risks 8):staging/应用/测量任何意外错误一律"不采纳",
+ * 测量结果记 `unknown`(空条目集,绝不表示为零分或通过);域外提案同样
+ * 不采纳。全部判定都写入运行档案(kind `"verdict"`,含 baseline 与
+ * candidate 两份完整测量)。
+ */
+import type { EvidenceLink, Proposal, Verdict, VerdictEntry } from "./types.js";
+import { type ApplyEditsOptions, type ApplyEditsResult, type CheckResult, type CreateStagingOptions, type RunChecksOptions, type Staging } from "../host/index.js";
+/** 档案 kind:一次 L1 verdict(两份完整测量 + 判定原因)。 */
+export declare const VERDICT_ARCHIVE_KIND = "verdict";
+/**
+ * L1 适用域:配置类 kind 白名单(design D8)。名单内提案进入提案通道,
+ * L1 差集作唯一 verdict;名单外(含内容类——skill/记忆/指令正文等)本
+ * 期不产出提案,等 L2 选择器执行落地。命名与 12.2 rule-based/editor
+ * 提案的产出侧保持一致。
+ */
+export declare const L1_CONFIG_KINDS: ReadonlySet<string>;
+export interface ProposalDomainDispatch {
+    readonly domain: "config" | "content";
+    /** 仅配置类进入提案通道;内容类本期不产出。 */
+    readonly entersProposalChannel: boolean;
+    readonly note: string;
+}
+/** 提案类域分派:白名单内 = 配置类(进通道),其余 = 内容类(不产出)。 */
+export declare function dispatchProposalDomain(kind: string): ProposalDomainDispatch;
+/**
+ * 条目比较键:(稳定 id, 层归属)。"条目 SHALL 带着层归属参与比较"——
+ * 同一 id 在全局层与 workspace 层是两条不同记录,不互相抵消。
+ */
+export declare function entryKey(entry: VerdictEntry): string;
+export interface VerdictDiff {
+    /** 候选有、baseline 没有(引入的回归)。 */
+    readonly introduced: VerdictEntry[];
+    /** baseline 有、候选没有(被消除的条目)。 */
+    readonly resolved: VerdictEntry[];
+}
+/** 按 (id, layer) 做集合差;message 不参与比较(host/checks.ts 契约)。 */
+export declare function diffVerdictEntries(baseline: readonly VerdictEntry[], candidate: readonly VerdictEntry[]): VerdictDiff;
+/** 提案 evidence 中的目标条目(evidence 的 doctor-finding.findingId
+ * 即 CheckEntry.id;`Proposal.target` 是编辑面锚点,不在此列)。 */
+export declare function doctorFindingTargetIds(evidence: readonly EvidenceLink[]): string[];
+export interface EvaluateL1Options {
+    /** 真实面 HOME(档案也写在这里的 `~/.trellis/evolve/`)。 */
+    readonly homeDir: string;
+    /** 被测上下文的 workspace root;缺省/null = 纯全局上下文。 */
+    readonly workspaceRoot?: string | null;
+    readonly proposal: Proposal;
+    /** 注入缝(场景测试的强制报错收口);缺省走 host 真实实现。 */
+    readonly runChecksFn?: (options: RunChecksOptions) => Promise<CheckResult>;
+    readonly createStagingFn?: (options: CreateStagingOptions) => Staging;
+    readonly applyEditsFn?: (options: ApplyEditsOptions) => Promise<ApplyEditsResult>;
+    /** 时间源(毫秒);缺省 Date.now(档案打戳)。 */
+    readonly now?: () => number;
+}
+export interface L1GateResult {
+    readonly decision: "acceptable" | "not-acceptable";
+    readonly reason: string;
+    readonly domain: "config" | "content";
+    readonly verdict: Verdict;
+    readonly targetIds: readonly string[];
+    /** 引入的新条目(不可采纳时入档)。 */
+    readonly introduced: readonly VerdictEntry[];
+    readonly resolvedIds: readonly string[];
+}
+/**
+ * L1 前闸完整判定:域分派 → staging 副本(层分裂复现)→ edits 重定位并
+ * 应用 → baseline/候选各跑三组结构化检查 → (id, layer) 差集 → 判定并
+ * 入档。任何意外错误按"不采纳"收口、测量记 unknown;不吞掉入档写失败。
+ */
+export declare function evaluateL1Proposal(options: EvaluateL1Options): Promise<L1GateResult>;