agent-trellis 0.19.0 → 0.21.0

package/dist/commands/mcpImport.js

@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadCanonicalSource, ensureGitignoreEntry, ensureShellEnvSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { deliveredName } from "../lib/secretEnv.js";
 import { openBackupSession } from "../lib/backup.js";
 import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
@@ -115,7 +116,7 @@ function semanticIdentity(def) {
         enabled: def.enabled,
         agents: def.agents ? sorted(def.agents) : undefined,
         staticEnv: def.staticEnv,
-        envKeys: sorted([...(def.env ?? []), ...Object.keys(def.envAliases ?? {})]),
+        envKeys: sorted([...(def.env ?? []).map(deliveredName), ...Object.keys(def.envAliases ?? {})]),
         headerKeys: sorted(Object.keys(def.headers ?? {})),
     });
 }

package/dist/commands/secretsAudit.d.ts

@@ -35,7 +35,7 @@ export interface SecretsFinding {
      * `~/.trellis/mcp/servers.yaml` itself (see module doc comment). */
     agent: AgentId | "environment" | "canonical";
     file: string;
-    kind: "literal-secret" | "unexpected-var-name" | "missing-env-value";
+    kind: "literal-secret" | "unexpected-var-name" | "missing-env-value" | "malformed-reference";
     detail: string;
 }
 export interface SecretsAuditReport {

package/dist/commands/secretsAudit.js

@@ -29,7 +29,7 @@ import { KiroAdapter } from "../adapters/kiro.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames, extractZcodeEnvVarNames } from "../lib/envVarNames.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
+import { parseEnvEntry, resolveSecretEnv } from "../lib/secretEnv.js";
 /** Only agents in `managedAgents` — a present-but-unmanaged agent's config
  * file is never even read (trellis-managed-agents), same restriction as
  * `sync`/`mcp sync`. pi has no static, generated MCP config file to audit
@@ -49,7 +49,7 @@ function auditedAgents(homeDir, managedAgents) {
  * a problem regardless of which agents' `servers.yaml` `agents:` field
  * would route it to (trellis-secrets-env-management design.md D3).
  */
-function findMissingEnvValues(servers, policy) {
+async function findMissingEnvValues(servers, policy) {
     const names = new Set();
     for (const def of Object.values(servers)) {
         for (const name of declaredEnvNames(def))
@@ -57,16 +57,39 @@ function findMissingEnvValues(servers, policy) {
     }
     if (names.size === 0)
         return [];
-    const resolved = resolveSecretEnv([...names], policy);
-    const source = policy.envFile ?? "process environment";
-    return [...names]
-        .filter((name) => !resolved[name])
-        .map((name) => ({
-        agent: "environment",
-        file: source,
-        kind: "missing-env-value",
-        detail: `"${name}" is declared by a canonical MCP server's env but has no resolvable value`,
-    }));
+    // Malformed `mxenv://` entries are findings in their own right — never
+    // skipped, never treated as bare names (mx-env-secret-source spec).
+    const entries = [...names];
+    const parsed = entries.map(parseEnvEntry);
+    const findings = [];
+    for (const p of parsed) {
+        if (p.kind === "invalid") {
+            findings.push({
+                agent: "environment",
+                file: policy.envFile ?? "process environment",
+                kind: "malformed-reference",
+                detail: `"${p.entry}" is not a valid mxenv://<profile>/<KEY> reference`,
+            });
+        }
+    }
+    const resolvable = entries.filter((_, i) => parsed[i].kind !== "invalid");
+    if (resolvable.length === 0)
+        return findings;
+    // Findings name the DELIVERED name (the KEY segment for a reference).
+    const resolved = await resolveSecretEnv(resolvable, policy);
+    for (const entry of resolvable) {
+        const p = parseEnvEntry(entry);
+        const delivered = p.kind === "invalid" ? entry : p.delivered;
+        if (!resolved[delivered]) {
+            findings.push({
+                agent: "environment",
+                file: p.kind === "ref" ? `the mxenv composition (profile "${p.profile}")` : (policy.envFile ?? "process environment"),
+                kind: "missing-env-value",
+                detail: `"${delivered}" is declared by a canonical MCP server's env but has no resolvable value`,
+            });
+        }
+    }
+    return findings;
 }
 /**
  * Reject-pattern-only scan of canonical's own `mcp/servers.yaml` (design.md
@@ -118,7 +141,7 @@ export async function collectSecretsAuditReport(opts = {}) {
         const content = readFileSync(file, "utf-8");
         findings.push(...auditFile(agent.id, file, content, canonical.secretsPolicy, agent.extractNames));
     }
-    findings.push(...findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
+    findings.push(...await findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
     findings.push(...auditCanonicalServersYaml(homeDir, canonical.secretsPolicy));
     return { findings };
 }

package/dist/evolve/agentView.d.ts

@@ -0,0 +1,32 @@
+/**
+ * agent 只读接口(trellis-evolve 任务 12.4,spec"pending 提案对 agent
+ * 可见")。
+ *
+ * 暴露给被进化 agent 的进化接口只有两类:读 pending 摘要(本模块)与
+ * 上报用户纠正(`report.ts`)。本模块**没有任何**批准、拒绝、应用或写
+ * 入操作,也不 re-export 它们 —— 批准只走管理面命令的交互式终端
+ * (spec"批准只走带外通道")。返回内容:摘要、证据与风险级别;文本经
+ * secrets 擦除(纵深,存储层已拒凭据形态内容),不含凭据材料、不含
+ * 编辑正文。
+ */
+import type { ProposalStatus } from "./pending.js";
+import type { RiskClass } from "./types.js";
+/** 证据的 agent 可见描述(只读;ref 为稳定标识,已擦除)。 */
+export interface AgentEvidenceView {
+    readonly kind: string;
+    readonly ref: string;
+}
+/** 一条 pending 提案的 agent 可见摘要。 */
+export interface AgentPendingSummary {
+    readonly id: string;
+    readonly summary: string;
+    readonly riskClass: RiskClass;
+    readonly status: ProposalStatus;
+    readonly evidence: readonly AgentEvidenceView[];
+    readonly createdAt: number;
+}
+/**
+ * 列出全部 pending 提案的只读摘要。存在几条返回几条(spec 场景:两条
+ * pending → 两条摘要、证据与风险级别)。只读:不建目录、不写档案。
+ */
+export declare function listPendingSummaries(homeDir: string): AgentPendingSummary[];

package/dist/evolve/agentView.js

@@ -0,0 +1,34 @@
+/**
+ * agent 只读接口(trellis-evolve 任务 12.4,spec"pending 提案对 agent
+ * 可见")。
+ *
+ * 暴露给被进化 agent 的进化接口只有两类:读 pending 摘要(本模块)与
+ * 上报用户纠正(`report.ts`)。本模块**没有任何**批准、拒绝、应用或写
+ * 入操作,也不 re-export 它们 —— 批准只走管理面命令的交互式终端
+ * (spec"批准只走带外通道")。返回内容:摘要、证据与风险级别;文本经
+ * secrets 擦除(纵深,存储层已拒凭据形态内容),不含凭据材料、不含
+ * 编辑正文。
+ */
+import { eraseSecrets } from "./erase.js";
+import { readProposalsByStatus } from "./pending.js";
+function evidenceRef(link) {
+    const raw = link.kind === "run" ? link.runId : link.kind === "doctor-finding" ? link.findingId : link.signalId;
+    return eraseSecrets(raw);
+}
+/**
+ * 列出全部 pending 提案的只读摘要。存在几条返回几条(spec 场景:两条
+ * pending → 两条摘要、证据与风险级别)。只读:不建目录、不写档案。
+ */
+export function listPendingSummaries(homeDir) {
+    return readProposalsByStatus(homeDir, "pending").map((record) => ({
+        id: record.id,
+        summary: eraseSecrets(record.proposal.summary),
+        riskClass: record.riskClass,
+        status: record.status,
+        evidence: record.proposal.evidence.map((link) => ({
+            kind: link.kind,
+            ref: evidenceRef(link),
+        })),
+        createdAt: record.createdAt,
+    }));
+}

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 {};