agent-trellis 0.20.0 → 0.22.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,6 @@ 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, options?: {
+    hosted?: boolean;
+}): Promise<McpPlanResult>;

package/dist/adapters/mcpPlan.js

@@ -20,7 +20,8 @@ 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 { deliveredName, isValidSecretVarName, parseEnvEntry, resolveSecretEntries, resolveSecretEnv, SecretReferenceError } from "../lib/secretEnv.js";
+import { extractTemplateVarNames, invalidHeaderTemplate } from "../lib/envVarNames.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
 export const GATEWAY_ENTRY_NAME = "trellis";
 export const LEGACY_GATEWAY_ENTRY_NAME = "trellis-gateway";
@@ -138,14 +139,38 @@ export function findLiteralSecret(def) {
  * the target key it would have been written under
  * (trellis-migrate-env-var-alias).
  */
-function findUnresolvedEnvName(def, policy) {
-    const names = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
+async function findUnresolvedEnvName(def, policy) {
+    const headerRefs = Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames)
+        .filter((entry) => !isValidSecretVarName(entry));
+    const envNames = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
+    const names = [...envNames, ...headerRefs];
     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 = names.find((entry, i) => parsed[i].kind === "invalid" || (headerRefs.includes(entry) && parsed[i].kind === "name"));
+    if (invalid !== undefined)
+        return invalid;
+    try {
+        // Retain env/envAliases' existing delivered-name collision behavior.
+        // Header references instead remain source-bound, with no bare-name fallback.
+        const env = await resolveSecretEnv(envNames, policy);
+        const missingEnv = envNames.find((entry) => !env[deliveredName(entry)]);
+        if (missingEnv !== undefined)
+            return missingEnv;
+        const headers = await resolveSecretEntries(headerRefs, policy);
+        return headerRefs.find((entry) => !headers[entry]);
+    }
+    catch (error) {
+        if (error instanceof SecretReferenceError)
+            return error.entry;
+        throw error;
+    }
 }
-export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+export async function resolveMcpPlan(agentId, mcp, managedAgents, policy, options = {}) {
     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 +186,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 +262,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 +271,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, undefined, options.hosted || agentId === "pi");
     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, hosted = false) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
@@ -293,12 +318,17 @@ function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
             });
             continue;
         }
+        const invalidHeader = invalidHeaderTemplate(def.headers);
+        if (invalidHeader !== undefined) {
+            conflicts.push({ name, message: `refusing to write MCP server "${name}": invalid reference template in header ${invalidHeader}`, remediation: "use ${VAR} or ${mxenv://<profile>/<KEY>} in headers" });
+            continue;
+        }
         // Codex has no generic headers concept — only the single
         // Authorization-bearer-token shape is expressible there
         // (trellis-mcp-transport-auth design.md D4). Any other shape is
         // refused for Codex specifically; every other in-scope agent for
         // the same server is unaffected (this loop runs once per agentId).
-        if (agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
+        if (!hosted && agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}" for codex: its "headers" field isn't the single { Authorization: "Bearer \${VAR}" } shape Codex's own config format can express — Codex has no generic headers concept, only \`bearer_token_env_var\`. Still written normally for every other in-scope agent.`,
@@ -306,13 +336,33 @@ function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
             });
             continue;
         }
-        const unresolvedName = findUnresolvedEnvName(def, policy);
-        if (unresolvedName) {
-            const source = policy.envFile ?? "process environment";
+        const unresolvedName = await findUnresolvedEnvName(def, policy);
+        if (unresolvedName !== undefined) {
+            const entry = parseEnvEntry(unresolvedName);
+            if (entry.kind === "invalid" || !isValidSecretVarName(unresolvedName) && entry.kind === "name") {
+                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;
+        }
+        if (!hosted && Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames).some((entry) => parseEnvEntry(entry).kind === "ref")) {
+            conflicts.push({
+                name,
+                message: `refusing to write MCP server "${name}": mxenv header references require Trellis gateway/runtime delivery; native clients cannot resolve them`,
+                remediation: `enable gateway/runtime delivery for ${agentId}, keeping transport and headers in servers.yaml`,
             });
             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

@@ -118,7 +118,7 @@ Commands:
               --skill, -s <name>       required unless --list
               --branch <ref>           Git branch, tag, or ref; default is
                                        the source repository's default branch
-              --agent, -a <ids|*>      restrict delivery to managed Agent ids
+              --agent, -a <ids|*|none> choose applicable managed Agents
               --list                   show discovered Skills without import
               --global, --yes          accepted skills-CLI compatibility flags
               --dry-run                fetch and preview; write nothing
@@ -205,19 +205,22 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
-            List canonical skills with resolved scope
+            List canonical skills; unregistered skills are paused
+              --agent <id>  filter by agent and show actual delivery status
               --json    machine-readable output, no report text
   skill add <name> --from <path>
             Import a real skill directory into canonical (refuses on
               an existing name with different content, no overwrite)
               --workspace  copy into .agents/skills/ instead of canonical
+              --agents <ids> | --all | --none
+                           required without an interactive terminal
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
   skill scope <name> --agents <ids> | --all | --none
             Choose which managed agents receive a canonical skill, then
-            sync it. Same selector rules as mcp scope; a built-in skill's
-            scope is not editable
+            sync it. --all records today's managed set; newly managed
+            agents need explicit registration. Built-in scope is not editable
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill update-builtin
@@ -527,7 +530,7 @@ async function main(argv) {
         const json = skillRest.includes("--json");
         const dryRun = skillRest.includes("--dry-run");
         if (subcommand === "list") {
-            process.exitCode = runSkillList({ json }).exitCode;
+            process.exitCode = runSkillList({ json, agent: flagValue(skillRest, "--agent") }).exitCode;
             return;
         }
         if (subcommand === "add") {
@@ -538,7 +541,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = (await runSkillAdd(name, from, { json, dryRun, workspace: skillRest.includes("--workspace") })).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun, workspace: skillRest.includes("--workspace"), selection: parseScopeArgs(skillRest) })).exitCode;
             return;
         }
         if (subcommand === "remove") {

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, { hosted: true });
     // 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/migrate.js

@@ -19,7 +19,7 @@ import { deepEqual } from "../lib/deepEqual.js";
 import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, readKimiCodeMcpDefs, readZcodeMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { findLiteralSecret } from "../adapters/mcpPlan.js";
-import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, validateSkillScopeYaml, writeSecretsPolicyExtraction, writeSkillScopeYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 import { discoverNativeMemory, MAX_NATIVE_MEMORY_BYTES, renderNativeMemory } from "../lib/nativeMemory.js";
 /** Where a `staticEnv` literal secret's real value goes when
@@ -390,6 +390,11 @@ function copyDirectoryThroughBackup(sourceDir, destDir, backup) {
 }
 export function applyMigratePlan(plan, homeDir = homedir(), backup) {
     const canonicalRoot = join(homeDir, ".trellis");
+    if (plan.items.some((item) => item.kind === "skill" && item.action === "create")) {
+        const validation = validateSkillScopeYaml(join(canonicalRoot, "scope.yaml"));
+        if (!validation.ok)
+            throw new Error(validation.error);
+    }
     for (const item of plan.items) {
         if (item.action !== "create" && item.action !== "reclassify" && item.action !== "extract-secret")
             continue;
@@ -400,6 +405,11 @@ export function applyMigratePlan(plan, homeDir = homedir(), backup) {
                 copyDirectoryThroughBackup(item.sourceDir, dest, backup);
             else
                 cpSync(item.sourceDir, dest, { recursive: true });
+            // Migration proves applicability to its source agent only. Sharing
+            // with other agents is a separate, explicit compatibility decision.
+            const scope = writeSkillScopeYaml(join(canonicalRoot, "scope.yaml"), item.name, [plan.agent], backup);
+            if (!scope.ok)
+                throw new Error(scope.error);
         }
         else if (item.kind === "instructions" && item.sourceContent !== undefined) {
             mkdirSync(canonicalRoot, { recursive: true });