agent-trellis 0.20.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/commands/doctor.d.ts

@@ -137,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

@@ -178,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;
@@ -198,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
@@ -215,7 +215,7 @@ 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)])));
+    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):级别策略是显式用户选择,读取零副作用。
     // 未配置(或全空)时整段缺席 —— 从未开启自我进化的机器输出与未安装时
     // 一致;损坏的策略文件不拖垮扫描,降级为段内诊断呈现。
@@ -427,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));

package/dist/commands/mcp.js

@@ -65,7 +65,7 @@ export async function collectMcpSyncReport(opts = {}) {
             continue;
         }
         const globalItems = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
-        const wsItems = planWorkspaceMcp(adapter.id, canonical);
+        const wsItems = await planWorkspaceMcp(adapter.id, canonical);
         if (writeMode) {
             await adapter.apply(globalItems, backup);
             applyWorkspaceMcp(adapter.id, canonical, wsItems, backup);

package/dist/commands/mcpAuth.js

@@ -114,7 +114,7 @@ export async function authorizeMcpServer(opts) {
     const client = oauthClientMetadata(def.auth);
     let clientSecret;
     if (client.clientSecretEnv) {
-        const { [client.clientSecretEnv]: value } = resolveSecretEnv([client.clientSecretEnv], canonical.secretsPolicy);
+        const { [client.clientSecretEnv]: value } = await resolveSecretEnv([client.clientSecretEnv], canonical.secretsPolicy);
         if (value === undefined) {
             throw new Error(`auth.client_secret_env is "${client.clientSecretEnv}", but no value for that variable was found in ${secretSourceLabel(canonical.secretsPolicy)} — set it there, or drop the field if this provider issues a public client`);
         }

package/dist/commands/mcpGateway.d.ts

@@ -46,11 +46,11 @@ export declare function parseMcpGatewayArgs(argv: readonly string[]): {
  * connect to itself. Resolving against a gateway-less view of the same
  * canonical gives the set gateway mode replaced.
  */
-export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): {
+export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): Promise<{
     upstreams: UpstreamSpec[];
     oauthServers: string[];
     conflicts: string[];
-};
+}>;
 export declare function runMcpGateway(opts: RunMcpGatewayOptions): Promise<{
     exitCode: number;
 }>;

package/dist/commands/mcpGateway.js

@@ -59,7 +59,7 @@ export function parseMcpGatewayArgs(argv) {
  * connect to itself. Resolving against a gateway-less view of the same
  * canonical gives the set gateway mode replaced.
  */
-export function resolveGatewayUpstreams(agentId, canonical) {
+export async function resolveGatewayUpstreams(agentId, canonical) {
     const route = canonical.mcp.routes?.[agentId];
     const hubActive = route ? route.mode === "hub" : Boolean(canonical.mcp.hub) && !isGatewayAgent(agentId, canonical.mcp, canonical.managedAgents);
     if (hubActive) {
@@ -90,7 +90,7 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     // ownership-gated removal clears it. Serving that stale entry would hand
     // every server, and every secret resolved into it, to the one agent the
     // user just said to stop involving.
-    const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    const { desired, conflicts } = await resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
     // Agent-owned OAuth servers bypass the gateway as direct entries, so no
     // connection state exists for them here — but Trellis owns the token
     // store, so `trellis.mcp.status` reports their credential health for
@@ -101,7 +101,7 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     const agentOwnedServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => isAgentOwnedOAuth(def)));
     const oauthServers = Object.keys(agentOwnedServers).length === 0
         ? []
-        : resolveMcpPlan(agentId, { ...direct, servers: agentOwnedServers }, canonical.managedAgents, canonical.secretsPolicy).desired.map(({ name }) => name);
+        : (await resolveMcpPlan(agentId, { ...direct, servers: agentOwnedServers }, canonical.managedAgents, canonical.secretsPolicy)).desired.map(({ name }) => name);
     return {
         upstreams: desired.map(({ name }) => ({ name, def: canonical.mcp.servers[name] })),
         oauthServers,
@@ -131,7 +131,7 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
         console.error(`trellis-mcp-gateway: ${err instanceof Error ? err.message : String(err)}`);
         return { exitCode: 1 };
     }
-    const { upstreams, oauthServers, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
+    const { upstreams, oauthServers, conflicts } = await resolveGatewayUpstreams(opts.agentId, canonical);
     for (const message of conflicts) {
         console.error(`trellis-mcp-gateway: ${message}`);
     }

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/lib/envVarNames.js

@@ -22,7 +22,14 @@ export function extractTemplateVarNames(value) {
  * same answer to "what names does this def reference," not two
  * separately-maintained collections. */
 export function declaredEnvNames(def) {
+    // RAW entries, including `envAliases` sources (mx-env-secret-source
+    // secrets-audit delta): consumers that RESOLVE must see the original
+    // `mxenv://` text so references go through composition, then look the
+    // result up by delivered name; consumers that want the delivered NAMES
+    // map through `deliveredName` at their own use site (e.g. Kiro).
     const names = new Set(def.env ?? []);
+    for (const source of Object.values(def.envAliases ?? {}))
+        names.add(source);
     for (const value of Object.values(def.headers ?? {})) {
         for (const name of extractTemplateVarNames(value))
             names.add(name);

package/dist/lib/mcpConnect.d.ts

@@ -45,7 +45,7 @@ export declare function connectWithCleanup<T, TTransport extends {
     connect(transport: TTransport): Promise<unknown>;
 }, transport: TTransport, timeoutMs: number, message: string): Promise<T>;
 export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
-export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
+export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Promise<Record<string, string> | undefined>;
 export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 /**