agent-trellis 0.19.0 → 0.21.0

package/dist/adapters/claude-code.js

@@ -48,10 +48,10 @@ export class ClaudeCodeAdapter {
             canonicalRoot,
             kind: "instructions",
         });
-        const mcpItems = this.planMcp(canonical);
+        const mcpItems = await this.planMcp(canonical);
         return [...skillItems, ...instructionsItems, ...mcpItems];
     }
-    planMcp(canonical) {
+    async planMcp(canonical) {
         const configPath = join(this.homeDir, ".claude.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);

package/dist/adapters/codex.js

@@ -50,7 +50,7 @@ export class CodexAdapter {
             canonicalRoot: join(canonicalRoot, "skills"),
             kind: "skill",
         });
-        const mcpItems = this.planMcp(canonical);
+        const mcpItems = await this.planMcp(canonical);
         const configuredInstructionsPath = readInstructionsPath(join(this.homeDir, ".codex", "config.toml"));
         if (!configuredInstructionsPath) {
             // Codex has no `instructions` key set — not Trellis's to decide.
@@ -65,10 +65,10 @@ export class CodexAdapter {
         });
         return [...skillItems, ...instructionsItems, ...mcpItems];
     }
-    planMcp(canonical) {
+    async planMcp(canonical) {
         const configTomlPath = join(this.homeDir, ".codex", "config.toml");
         const content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
+        const { desired, conflicts } = await resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);

package/dist/adapters/jsonMcp.d.ts

@@ -29,7 +29,7 @@ export declare function planJsonMcp(opts: {
      * zero removal candidates. */
     ownership?: Record<string, unknown>;
     render?: JsonMcpEntryRenderer;
-}): AdapterPlanItem[];
+}): Promise<AdapterPlanItem[]>;
 /** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
  * file didn't exist) and deletes every `"remove"` item's key, returning
  * the object to stringify — every sibling top-level key on `parsed` is

package/dist/adapters/jsonMcp.js

@@ -30,10 +30,10 @@ export function renderJsonServerEntry(def) {
     }
     return entry;
 }
-export function planJsonMcp(opts) {
+export async function planJsonMcp(opts) {
     const { configPath, parsed, mcp, agentId, managedAgents, policy, ownership } = opts;
     const render = opts.render ?? ((def, _name) => renderJsonServerEntry(def));
-    const { desired, conflicts } = resolveMcpPlan(agentId, mcp, managedAgents, policy);
+    const { desired, conflicts } = await resolveMcpPlan(agentId, mcp, managedAgents, policy);
     const existingServers = parsed?.mcpServers ?? {};
     const items = [];
     for (const { name, def } of desired) {

package/dist/adapters/kimi-code.js

@@ -63,7 +63,7 @@ export class KimiCodeAdapter {
         const configPath = join(this.homeDir, ".kimi-code", "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
-        items.push(...planJsonMcp({
+        items.push(...(await planJsonMcp({
             configPath,
             parsed,
             mcp: globalLayerMcp(canonical),
@@ -72,7 +72,7 @@ export class KimiCodeAdapter {
             policy: canonical.secretsPolicy,
             ownership,
             render: renderKimiServerEntry,
-        }));
+        })));
         return items;
     }
     async apply(plan, backup) {

package/dist/adapters/kiro.js

@@ -18,6 +18,7 @@
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { deliveredName } from "../lib/secretEnv.js";
 import { isInScope } from "../core/adapter.js";
 import { usesNativeCapabilityDelivery } from "../core/types.js";
 import * as kiroProbe from "../probes/kiro.js";
@@ -64,11 +65,11 @@ export class KiroAdapter {
             canonicalRoot,
             kind: "instructions",
         });
-        const mcpItems = this.planMcp(canonical);
-        const approvedEnvVarsItems = this.planApprovedEnvVars(canonical);
+        const mcpItems = await this.planMcp(canonical);
+        const approvedEnvVarsItems = await this.planApprovedEnvVars(canonical);
         return [...skillItems, ...instructionsItems, ...mcpItems, ...approvedEnvVarsItems];
     }
-    planMcp(canonical) {
+    async planMcp(canonical) {
         const configPath = join(this.homeDir, ".kiro", "settings", "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
@@ -77,17 +78,18 @@ export class KiroAdapter {
     /** Names come from `resolveMcpPlan`, not a raw scan of `canonical.mcp.servers`
      * (design.md D2) — a server scoped away from Kiro, or refused for a
      * known_host_injected collision, never contributes a name here either. */
-    desiredApprovedEnvVars(canonical) {
-        const { desired } = resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
+    async desiredApprovedEnvVars(canonical) {
+        const { desired } = await resolveMcpPlan(this.id, globalLayerMcp(canonical), canonical.managedAgents, canonical.secretsPolicy);
         const names = new Set();
         for (const { def } of desired) {
+            // Approved list holds DELIVERED names (what renderers write), not raw entries.
             for (const name of declaredEnvNames(def))
-                names.add(name);
+                names.add(deliveredName(name));
         }
         return [...names];
     }
-    planApprovedEnvVars(canonical) {
-        const desired = this.desiredApprovedEnvVars(canonical);
+    async planApprovedEnvVars(canonical) {
+        const desired = await this.desiredApprovedEnvVars(canonical);
         if (desired.length === 0) {
             return [];
         }
@@ -188,7 +190,7 @@ export class KiroAdapter {
                 return [];
             }
         })();
-        for (const name of this.desiredApprovedEnvVars(canonical)) {
+        for (const name of await this.desiredApprovedEnvVars(canonical)) {
             if (!approved.includes(name)) {
                 mismatches.push(`env var "${name}" is needed by a canonical MCP server for kiro but missing from ${APPROVED_ENV_VARS_KEY}`);
             }

package/dist/adapters/mcpPlan.d.ts

@@ -91,4 +91,4 @@ export interface LiteralSecretMatch {
  * as before this function reported a field at all.
  */
 export declare function findLiteralSecret(def: McpServerDef): LiteralSecretMatch | undefined;
-export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): McpPlanResult;
+export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): Promise<McpPlanResult>;

package/dist/adapters/mcpPlan.js

@@ -20,7 +20,7 @@ import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
 import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
+import { parseEnvEntry, resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
 export const GATEWAY_ENTRY_NAME = "trellis";
 export const LEGACY_GATEWAY_ENTRY_NAME = "trellis-gateway";
@@ -138,14 +138,25 @@ export function findLiteralSecret(def) {
  * the target key it would have been written under
  * (trellis-migrate-env-var-alias).
  */
-function findUnresolvedEnvName(def, policy) {
+async function findUnresolvedEnvName(def, policy) {
     const names = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
     if (names.length === 0)
         return undefined;
-    const resolved = resolveSecretEnv(names, policy);
-    return names.find((name) => !resolved[name]);
+    // A malformed `mxenv://` entry conflicts here too — it is rejected input,
+    // never a silently-resolved bare name (mx-env-secret-source D6). The
+    // returned text is the DECLARED entry; resolution checks use delivered
+    // names (the `KEY` segment for a reference).
+    const parsed = names.map(parseEnvEntry);
+    const invalid = parsed.find((p) => p.kind === "invalid");
+    if (invalid)
+        return invalid.entry;
+    const resolved = await resolveSecretEnv(names, policy);
+    return names.find((name) => {
+        const p = parseEnvEntry(name);
+        return !resolved[p.kind === "invalid" ? name : p.delivered];
+    });
 }
-export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+export async function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
     const route = routeForAgent(agentId, mcp, managedAgents);
     const runtimeEnabled = capabilityDeliveryForAgent(agentId, mcp) !== "native";
     // Checked before `hub`: only one entry can be "the" MCP entry for an
@@ -161,7 +172,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
                 conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
-        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
+        const oauth = await planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         // Every ordinary per-server check (enabled, scope, literal secrets,
         // unresolved env names, Codex's header shape) still runs at gateway
         // startup. OAuth servers are the deliberate exception: they are written
@@ -237,7 +248,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
         // Runtime mode owns the agent-facing MCP edge. It resolves the same
         // direct/gateway-compatible upstream route at startup, so native
         // per-server entries are not duplicated here.
-        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
+        const oauth = await planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         return {
             desired: [{
                     name: RUNTIME_ENTRY_NAME,
@@ -246,14 +257,14 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts: oauth.conflicts,
         };
     }
-    const native = planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const native = await planDirectServers(agentId, mcp, managedAgents, policy, route);
     const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
     return {
         desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
         conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))],
     };
 }
-function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
+async function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
@@ -306,13 +317,25 @@ function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
             });
             continue;
         }
-        const unresolvedName = findUnresolvedEnvName(def, policy);
+        const unresolvedName = await findUnresolvedEnvName(def, policy);
         if (unresolvedName) {
-            const source = policy.envFile ?? "process environment";
+            const entry = parseEnvEntry(unresolvedName);
+            if (entry.kind === "invalid") {
+                conflicts.push({
+                    name,
+                    message: `refusing to write MCP server "${name}": its declared env entry "${unresolvedName}" is not a valid mxenv://<profile>/<KEY> reference (mx-env-secret-source)`,
+                    remediation: `fix the entry in servers.yaml to the mxenv://<profile>/<KEY> form or a plain variable name, then re-run mcp sync`,
+                });
+                continue;
+            }
+            const source = entry.kind === "ref"
+                ? `the mxenv composition (profile "${entry.profile}")`
+                : (policy.envFile ?? "process environment");
+            const remediationTarget = entry.kind === "ref" ? entry.key : unresolvedName;
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}": its declared env var "${unresolvedName}" has no resolvable value in ${source} — writing it now would silently break this server's connection once the agent starts it (trellis-mcp-static-env-and-disabled-servers)`,
-                remediation: `set "${unresolvedName}" in ${source}, or fix the name in servers.yaml if it was a typo, then re-run mcp sync`,
+                remediation: `set "${remediationTarget}" in ${source}, or fix the name in servers.yaml if it was a typo, then re-run mcp sync`,
             });
             continue;
         }

package/dist/adapters/pi.js

@@ -114,7 +114,7 @@ export class PiAdapter {
             kind: "instructions",
         });
         if (supportsNativeMcp(this.versionProbe())) {
-            return [...skillItems, ...instructionsItems, ...this.planNativeMcp(canonical)];
+            return [...skillItems, ...instructionsItems, ...await this.planNativeMcp(canonical)];
         }
         const { file: bridgeFile, symlinkName } = resolveBridgeFile();
         const extensionItems = planSymlinks({
@@ -139,12 +139,12 @@ export class PiAdapter {
      * apply, and a bare skills/instructions sync can neither remove the
      * bridge early nor resurrect it afterwards.
      */
-    planNativeMcp(canonical) {
+    async planNativeMcp(canonical) {
         const agentDir = join(this.homeDir, ".pi", "agent");
         const configPath = join(agentDir, "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
-        const items = planJsonMcp({
+        const items = (await planJsonMcp({
             configPath,
             parsed,
             mcp: globalLayerMcp(canonical),
@@ -153,7 +153,7 @@ export class PiAdapter {
             policy: canonical.secretsPolicy,
             ownership,
             render: piRenderer,
-        }).map((item) => {
+        })).map((item) => {
             // pi speaks stdio and streamable HTTP only — an sse server gets an
             // honest conflict instead of an entry pi could never connect.
             const write = item.mcpWrite;
@@ -251,7 +251,7 @@ export class PiAdapter {
             // definition drift. The plan only ever names Trellis-owned entries
             // (the ownership ledger gates removals), so user-authored servers
             // can never surface here.
-            for (const item of this.planNativeMcp(canonical)) {
+            for (const item of await this.planNativeMcp(canonical)) {
                 if (item.action === "create" && item.mcpWrite) {
                     mismatches.push(`mcp.json entry "${item.mcpWrite.name}" is missing or differs from canonical — run trellis mcp sync`);
                 }

package/dist/adapters/zcode.d.ts

@@ -16,7 +16,7 @@ export declare function planZcodeMcp(opts: {
     managedAgents: readonly import("../core/types.js").AgentId[];
     policy: SecretsPolicy;
     ownership: JsonRecord;
-}): AdapterPlanItem[];
+}): Promise<AdapterPlanItem[]>;
 export declare function applyZcodeMcp(parsed: JsonRecord | undefined, items: readonly AdapterPlanItem[]): JsonRecord;
 export declare class ZcodeAdapter implements TrellisAdapter {
     private readonly homeDir;

package/dist/adapters/zcode.js

@@ -29,8 +29,8 @@ function record(value) {
 function zcodeServers(parsed) {
     return record(record(parsed?.mcp).servers);
 }
-export function planZcodeMcp(opts) {
-    const { desired, conflicts } = resolveMcpPlan("zcode", opts.mcp, opts.managedAgents, opts.policy);
+export async function planZcodeMcp(opts) {
+    const { desired, conflicts } = await resolveMcpPlan("zcode", opts.mcp, opts.managedAgents, opts.policy);
     const existing = zcodeServers(opts.parsed);
     const items = [];
     for (const { name, def } of desired) {
@@ -136,14 +136,14 @@ export class ZcodeAdapter {
             canonicalRoot,
             kind: "instructions",
         }));
-        items.push(...planZcodeMcp({
+        items.push(...(await planZcodeMcp({
             configPath: profile.configPath,
             parsed,
             mcp: globalLayerMcp(canonical),
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
             ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
-        }));
+        })));
         const current = currentSkillControls(parsed);
         const ownership = loadZcodeSettingsOwnership(this.homeDir);
         if (runtimeOnly && (current.featuresSkill !== false || current.skillsEnabled !== false)) {
@@ -214,14 +214,14 @@ export class ZcodeAdapter {
         for (const name of desiredNativeSkills)
             if (!actualNativeSkills.has(name))
                 mismatches.push(`skill "${name}" is missing on ZCode`);
-        const expectedMcp = planZcodeMcp({
+        const expectedMcp = (await planZcodeMcp({
             configPath: profile.configPath,
             parsed: readConfig(profile.configPath),
             mcp: globalLayerMcp(canonical),
             managedAgents: canonical.managedAgents,
             policy: canonical.secretsPolicy,
             ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
-        }).filter((item) => item.action === "create" || item.action === "conflict");
+        })).filter((item) => item.action === "create" || item.action === "conflict");
         mismatches.push(...expectedMcp.map((item) => item.description));
         if (!snapshot.instructionsFile?.isSymlink || snapshot.instructionsFile.target !== canonical.instructionsFile)
             mismatches.push("shared instructions are not linked into ~/.zcode/AGENTS.md");

package/dist/cli.js

@@ -18,6 +18,10 @@ import { runMcpAuth } from "./commands/mcpAuth.js";
 import { runMcpRenew } from "./commands/mcpRenew.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
+// consumer-wiring(8.7):`trellis evolve` 管理面挂载。这条 import 是
+// 托管层仅有的消费者接线,登记在 test/unit/hostingIndependence.test.ts
+// 的 CONSUMER_WIRING;物理移出自我进化时与下文 evolve 分支一并删除。
+import { runEvolveCommand } from "./commands/evolve.js";
 import { runSkillList, runSkillAdd, runSkillRemove, runSkillScope, runSkillUpdateBuiltin } from "./commands/skill.js";
 import { runRemoteSkillAdd, runRemoteSkillList, runRemoteSkillUpdate } from "./commands/remoteSkill.js";
 import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./commands/memory.js";
@@ -26,7 +30,7 @@ import { runKimi } from "./commands/kimi.js";
 import { TRELLIS_VERSION } from "./lib/cliMetadata.js";
 import { flagValue } from "./lib/cliArgs.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "add", "update", "memory", "manage", "kimi", "secrets", "rollback"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "add", "update", "memory", "manage", "kimi", "secrets", "rollback", "evolve"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
@@ -625,6 +629,13 @@ async function main(argv) {
         process.exitCode = exitCode;
         return;
     }
+    if (command === "evolve") {
+        // 自我进化管理面(trellis-evolve 12.4):批准仅限交互式终端,由
+        // runEvolveCommand 内部检测;argv 原样传入,不拼 shell。
+        const { exitCode } = await runEvolveCommand(rest);
+        process.exitCode = exitCode;
+        return;
+    }
     console.error(`\`trellis ${command}\` is not implemented yet — this is a pre-alpha scaffold.\nSee docs/roadmap.md for status.`);
     process.exitCode = 1;
 }

package/dist/commands/doctor.d.ts

@@ -8,6 +8,7 @@ import { loadCanonicalSource } from "../core/canonical.js";
 import type { AgentId, AgentSnapshot, CanonicalSource } from "../core/types.js";
 import { type VersionExecutor } from "../lib/cliEntrypoints.js";
 import { type WorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
+import { type EvolveLevelSection } from "../host/levels.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -74,6 +75,13 @@ export interface DoctorReport {
     /** Per-entry layer attribution when a `.agents/` workspace layer
      * participated (trellis-workspace-scope task 3.5). */
     workspace?: WorkspaceDoctorSection;
+    /** Self-evolution levels when `~/.trellis/evolve.yaml` has any explicit
+     * setting (trellis-evolve task 10.2). Absent when unconfigured — a
+     * machine that never enabled evolution sees byte-identical output. */
+    evolve?: EvolveLevelSection;
+    /** Pending proposal count (trellis-evolve task 12.4; spec: doctor SHALL
+     * list it). Present when > 0 or the evolve section is shown. Read-only. */
+    evolvePending?: number;
 }
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -129,7 +137,7 @@ export declare function detectMcpUnreachable(snapshots: AgentSnapshot[]): Findin
 /** Compares runtime entries against the same canonical MCP plan that sync
  * uses. Only missing Trellis-owned runtime edges are reported; extra
  * user-authored MCP entries remain outside doctor ownership. */
-export declare function detectRuntimeDrift(snapshots: AgentSnapshot[], canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): Finding[];
+export declare function detectRuntimeDrift(snapshots: AgentSnapshot[], canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): Promise<Finding[]>;
 /** Exported so `trellis onboard` can reuse it verbatim for its own final
  * stage (trellis-onboard-closed-loop) rather than a second copy of this
  * formatting. */

package/dist/commands/doctor.js

@@ -4,6 +4,8 @@
  * current state against each other, the same manual process used
  * throughout docs/research.md's investigation, now formalized.
  */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
@@ -13,12 +15,43 @@ import * as kimiCodeProbe from "../probes/kimi-code.js";
 import * as zcodeProbe from "../probes/zcode.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
-import { ALL_AGENTS, isOAuthAuth, oauthOwner } from "../core/types.js";
+import { ALL_AGENTS, capabilityDeliveryForAgent, isOAuthAuth, oauthOwner } from "../core/types.js";
 import { classifyStoredToken, remediationFor } from "../lib/oauth/renew.js";
 import { readToken } from "../lib/oauth/store.js";
 import { findWorkspaceRoot } from "../lib/workspace.js";
 import { detectCliVersionSplit, findCliEntrypoints } from "../lib/cliEntrypoints.js";
 import { collectWorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
+import { describeEvolveLevels, loadEvolveLevelPolicy, } from "../host/levels.js";
+/**
+ * Pending proposal count via the on-disk data contract (8.1 状态目录 /
+ * 12.4 pending 存储:`~/.trellis/evolve/pending/<safeId>.json`,记录含
+ * `status` 字段)。doctor 属托管层,只读数据、不 import 自我进化代码,
+ * 物理移出消费者后 doctor 仍自洽(目录不存在 → 0)。
+ */
+function countPendingProposalRecords(homeDir) {
+    const dir = join(homeDir, ".trellis", "evolve", "pending");
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, name), "utf-8"));
+            if (parsed.status === "pending")
+                count += 1;
+        }
+        catch {
+            // 坏文件不阻塞 doctor 扫描。
+        }
+    }
+    return count;
+}
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -145,7 +178,7 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
     // `collectWorkspaceDoctorSection`'s per-file inspection is what we want.
     let workspace;
     if (canonical?.workspace) {
-        workspace = collectWorkspaceDoctorSection(canonical);
+        workspace = await collectWorkspaceDoctorSection(canonical);
     }
     else {
         const workspaceRoot = workspaceDir != null ? findWorkspaceRoot(workspaceDir) : null;
@@ -165,7 +198,7 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
                 diagnostics: [],
                 workspace: { root: workspaceRoot, mcpProvenance: {}, mcpGlobalServers: {}, skillProvenance: {}, globalSkills: [], shadowed: [] },
             };
-            workspace = collectWorkspaceDoctorSection(minimal);
+            workspace = await collectWorkspaceDoctorSection(minimal);
         }
     }
     // Workspace TOML findings become top-level findings so the exit code
@@ -182,8 +215,40 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         }
     }
     const oauth = canonical ? collectOAuthHealth(homeDir, canonical) : [];
-    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots), ...oauth.flatMap((entry) => (entry.status === "valid" ? [] : [oauthFinding(entry)])));
-    return { snapshots, findings, ...(oauth.length > 0 ? { oauth } : {}), ...(workspace ? { workspace } : {}) };
+    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? await detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots), ...oauth.flatMap((entry) => (entry.status === "valid" ? [] : [oauthFinding(entry)])));
+    // 分级开启(trellis-evolve 10.2):级别策略是显式用户选择,读取零副作用。
+    // 未配置(或全空)时整段缺席 —— 从未开启自我进化的机器输出与未安装时
+    // 一致;损坏的策略文件不拖垮扫描,降级为段内诊断呈现。
+    let evolve;
+    try {
+        const policy = loadEvolveLevelPolicy(homeDir);
+        // 整段只在存在显式设置时出现(与未安装时输出一致);托管 agent 的
+        // 列表只是展示面,不构成出现理由。
+        const hasExplicitSetting = policy.defaultLevel !== undefined || Object.keys(policy.agents).length > 0 || Object.keys(policy.workspaces).length > 0;
+        if (hasExplicitSetting) {
+            // 11.4:观测形态按 capability delivery 分类——runtime 交付
+            // ("mcp"/"both")的 agent 走 gateway 事件观察;仅原生渲染
+            // ("native"/未配置)只有 doctor/sync 信号。
+            const observationOf = (agent) => canonical !== undefined && capabilityDeliveryForAgent(agent, canonical.mcp) !== "native"
+                ? "events"
+                : "doctor-only";
+            evolve = describeEvolveLevels(policy, (canonical?.managedAgents ?? []).map((agent) => ({ agent, observation: observationOf(agent) })));
+        }
+    }
+    catch (err) {
+        evolve = { agents: [], workspaces: [], diagnostics: [err.message] };
+    }
+    // 12.4:pending 提案数量(spec "trellis doctor SHALL 同样列出")。
+    // 只读状态目录;未开启进化且无存储时为 0,输出保持零噪音。
+    const evolvePending = countPendingProposalRecords(homeDir);
+    return {
+        snapshots,
+        findings,
+        ...(oauth.length > 0 ? { oauth } : {}),
+        ...(workspace ? { workspace } : {}),
+        ...(evolve ? { evolve } : {}),
+        ...(evolve || evolvePending > 0 ? { evolvePending } : {}),
+    };
 }
 /**
  * Read-only OAuth credential health (trellis-mcp-oauth-renew design.md
@@ -362,12 +427,12 @@ export function detectMcpUnreachable(snapshots) {
 /** Compares runtime entries against the same canonical MCP plan that sync
  * uses. Only missing Trellis-owned runtime edges are reported; extra
  * user-authored MCP entries remain outside doctor ownership. */
-export function detectRuntimeDrift(snapshots, canonical) {
+export async function detectRuntimeDrift(snapshots, canonical) {
     const findings = [];
     for (const snap of snapshots) {
         if (!snap.present || !canonical.managedAgents.includes(snap.agent) || snap.agent === "pi")
             continue;
-        const expected = resolveMcpPlan(snap.agent, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy).desired
+        const expected = (await resolveMcpPlan(snap.agent, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy)).desired
             .map((entry) => entry.name)
             .filter((name) => name === RUNTIME_ENTRY_NAME || name === GATEWAY_ENTRY_NAME);
         const actual = new Set(snap.mcpServers.map((server) => server.name));
@@ -463,4 +528,24 @@ export function printReport(report) {
             console.log(`   ⚠ ${warning}`);
         }
     }
+    if (report.evolve) {
+        const ev = report.evolve;
+        console.log(`\nSelf-evolution (evolve.yaml):`);
+        if (ev.defaultLevel !== undefined)
+            console.log(`   default level: ${ev.defaultLevel}`);
+        for (const entry of ev.agents) {
+            console.log(`   agent ${entry.agent}: ${entry.level} (${entry.observation})`);
+        }
+        for (const entry of ev.workspaces) {
+            console.log(`   workspace ${entry.root}: ${entry.level}`);
+        }
+        for (const diagnostic of ev.diagnostics) {
+            console.log(`   ⚠ ${diagnostic}`);
+        }
+        console.log(`   pending proposals: ${report.evolvePending ?? 0}`);
+    }
+    else if ((report.evolvePending ?? 0) > 0) {
+        // 无级别配置但有 pending 存储:同样列出(spec SHALL),单行提示。
+        console.log(`\nSelf-evolution: ${report.evolvePending} pending proposal(s) — run \`trellis evolve pending\``);
+    }
 }

package/dist/commands/evolve.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 自我进化管理面命令(trellis-evolve 任务 12.4)。
+ *
+ * 消费者归属(8.7):本文件是自我进化子系统的一部分,物理移出消费者时
+ * 与 src/evolve/**、CLI 挂载(src/cli.ts 的 CONSUMER_WIRING 接线行)一并
+ * 删除;hostingIndependence.test.ts 的 CONSUMER_OWNED/CONSUMER_WIRING
+ * 登记了这条移出清单。
+ *
+ * `trellis evolve <status | report | pending | approve | reject | apply | run | import | enable | disable | rollback>`
+ *
+ * 批准只走这里,且**仅限交互式终端**(spec"批准只走带外通道"):非交互
+ * 环境一律拒绝,提案保持 pending。不存在任何 `--yes` / `--confirm` 之类的
+ * 非交互批准捷径 —— agent 传入的"确认"参数不构成批准,加了也只会被当
+ * 未知参数忽略。循环副作用边界:除 `run`(唯一命令行触发入口,手动
+ * 触发一次运行)外的命令不写信号、不触发观察/提案/probe。approve
+ * 决策后**立即应用**(spec"批准即应用与显式应用入口":持单飞作业锁经
+ * 备份会话写入,锁忙暂缓并告知);apply 幂等应用全部已批准未应用的编辑
+ * (失败重试与滞留消化入口);reject 只做状态迁移 + 档案;enable/disable
+ * 写 canonical 级别策略,并按 design 8.1 同步扩展清单条目——级别升至
+ * observe 及以上时写入、置回 off 时移除;rollback 转发既有备份会话回滚。
+ */
+import { type ApplyAgent } from "../evolve/apply.js";
+export interface EvolveCommandOptions {
+    /** 测试/sandbox 注入缝;缺省用户 HOME。永不作为 CLI 标志暴露。 */
+    readonly homeDir?: string;
+    /** TTY 检测缝;缺省 stdin+stdout 同时为 TTY。 */
+    readonly isTTY?: boolean;
+    /** 时间源(毫秒);缺省 Date.now。 */
+    readonly now?: () => number;
+    /** 应用阶段的 agent 分类(测试/sandbox 注入缝;缺省按 delivery 分类)。 */
+    readonly applyAgents?: readonly ApplyAgent[];
+    /** 原生渲染同步触发缝(测试注入;缺省 host `triggerRenderSync`)。 */
+    readonly triggerSync?: () => Promise<{
+        exitCode: number;
+    }>;
+}
+/**
+ * 管理面命令入口。`args` 为 `evolve` 之后的 argv(子命令 + 参数),
+ * 由 cli 原样传入 —— 不经 shell 拼接。
+ */
+export declare function runEvolveCommand(args: readonly string[], options?: EvolveCommandOptions): Promise<{
+    exitCode: number;
+}>;