agent-trellis 0.20.0 → 0.22.0

package/dist/lib/mcpConnect.js

@@ -14,8 +14,8 @@
  */
 import { Client, StreamableHTTPClientTransport, SSEClientTransport } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
-import { resolveSecretEnv } from "./secretEnv.js";
-import { extractTemplateVarNames } from "./envVarNames.js";
+import { deliveredName, isValidSecretVarName, parseEnvEntry, resolveSecretEntries, resolveSecretEnv } from "./secretEnv.js";
+import { extractTemplateVarNames, invalidHeaderTemplate, replaceTemplateVars } from "./envVarNames.js";
 export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 const FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1_000;
 /**
@@ -73,9 +73,20 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
     // of its own (like this bridge) would otherwise crash on parsing
     // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
-    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
+    //
+    // Entries may be `mxenv://` references: the resolved map is keyed by
+    // DELIVERED name (the `KEY` segment for a reference, the entry itself
+    // for a bare name), and the spawned server receives values under
+    // delivered names — never the raw reference text as a variable name
+    // (mx-env-secret-source spec).
+    const resolved = await resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
+    const namedEnv = Object.fromEntries((def.env ?? []).map((entry) => {
+        const delivered = deliveredName(entry);
+        return [delivered, resolved[delivered] ?? ""];
+    }));
+    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => {
+        return [targetKey, resolved[deliveredName(sourceName)] ?? ""];
+    }));
     const transport = new StdioClientTransport({
         command: def.command,
         args: def.args,
@@ -91,20 +102,34 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     });
     return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
-export function resolveHeaders(def, secretsPolicy) {
+export async function resolveHeaders(def, secretsPolicy) {
     if (!def.headers || Object.keys(def.headers).length === 0)
         return undefined;
+    const invalidHeader = invalidHeaderTemplate(def.headers);
+    if (invalidHeader !== undefined)
+        throw new Error(`[trellis] invalid reference template in header ${invalidHeader} — use \${VAR} or \${mxenv://<profile>/<KEY>}`);
     const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
+    for (const name of names) {
+        const entry = parseEnvEntry(name);
+        if (entry.kind === "invalid" || (entry.kind === "name" && !isValidSecretVarName(name))) {
+            throw new Error(`[trellis] invalid header reference: ${name} — expected a variable name or mxenv://<profile>/<KEY>`);
+        }
+    }
+    const resolved = await resolveSecretEntries(names, secretsPolicy);
     const result = {};
     for (const [key, template] of Object.entries(def.headers)) {
-        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
+        result[key] = replaceTemplateVars(template, (name) => {
+            if (parseEnvEntry(name).kind === "ref" && !resolved[name]) {
+                throw new Error(`[trellis] unresolved header reference: ${name}`);
+            }
+            return resolved[name] ?? "";
+        });
     }
     return result;
 }
 export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     const client = new Client(clientInfo, { capabilities: {}, versionNegotiation: { mode: "auto", probe: { timeoutMs } } });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     // authProvider is the SDK's per-request credential seam: `token()` runs
     // as each request's headers are assembled and its result overrides
     // `requestInit`'s Authorization — the alternative to burning a Bearer
@@ -118,7 +143,7 @@ export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, aut
 export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     // HTTP+SSE is a legacy transport; it cannot carry modern discovery.
     const client = new Client(clientInfo, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     const opts = {
         ...(headers ? { requestInit: { headers } } : {}),
         ...(authProvider ? { authProvider } : {}),

package/dist/lib/mcpMigrateRead.js

@@ -13,6 +13,7 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseEnvEntry } from "./secretEnv.js";
 import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
@@ -42,8 +43,19 @@ const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
  * independent derivations of it.
  */
 export function resolvedEnvTextMap(def) {
-    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
-    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]));
+    // `mxenv://` reference entries render as `${KEY}` under their DELIVERED
+    // name (the KEY segment) — the raw reference text never appears as a
+    // variable name in a native-client config (mx-env-secret-source spec).
+    const nameRefs = Object.fromEntries((def.env ?? []).map((entry) => {
+        const parsed = parseEnvEntry(entry);
+        const delivered = parsed.kind === "invalid" ? entry : parsed.delivered;
+        return [delivered, `\${${delivered}}`];
+    }));
+    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, source]) => {
+        const parsed = parseEnvEntry(source);
+        const delivered = parsed.kind === "invalid" ? source : parsed.delivered;
+        return [targetKey, `\${${delivered}}`];
+    }));
     return { ...nameRefs, ...aliasRefs, ...(def.staticEnv ?? {}) };
 }
 function splitJsonEnvMap(env) {

package/dist/lib/secretEnv.d.ts

@@ -4,9 +4,15 @@
  * `process.env[name]` lookup — so they can never disagree about where a
  * declared name's value comes from (design.md D1).
  *
- * Dependency-free by design, same as src/lib/envVarNames.ts: a full
- * dotenv library's quoting/escaping/interpolation rules are more than
- * this narrow need requires (design.md D4).
+ * Entries are either bare environment variable names (byte-identical
+ * legacy semantics: `env_file` sole-source when set, otherwise ambient
+ * `process.env`) or `mxenv://<profile>/<KEY>` references resolved
+ * through the `@morphixai/mxenv-core` SDK and delivered under the `KEY`
+ * segment (mx-env-secret-source spec). The dotenv half stays
+ * dependency-free — a full dotenv library's quoting/escaping/
+ * interpolation rules are more than this narrow need requires — while
+ * the reference grammar is owned by the SDK and never re-implemented
+ * here.
  */
 import type { SecretsPolicy } from "../core/types.js";
 import type { BackupSession } from "./backup.js";
@@ -17,12 +23,55 @@ import type { BackupSession } from "./backup.js";
 export declare function isValidSecretVarName(name: string): boolean;
 export declare function parseDotenv(content: string): Record<string, string>;
 /**
- * `policy.envFile` set: it is the SOLE source — a name absent from it
- * resolves to `undefined`, `process.env` is never consulted (a silent
- * fallback would defeat the isolation this exists to offer). Unset:
- * reads `process.env` directly, identical to every pre-existing caller.
+ * One declared `env` entry / `envAliases` source value, classified.
+ * Strict whole-string matching: an entry is a reference only when the
+ * entire entry is exactly one `mxenv://<profile>/<KEY>` (reconstructed
+ * from the SDK parser's match). Anything containing reference-shaped
+ * text that does not fully match — including the rejected legacy
+ * `mx-env://` scheme, which the SDK parser throws on — is `invalid`,
+ * never a silently-resolved bare name (mx-env-secret-source D6).
  */
-export declare function resolveSecretEnv(names: string[], policy: SecretsPolicy): Record<string, string | undefined>;
+export type SecretEnvEntry = {
+    kind: "ref";
+    profile: string;
+    key: string;
+    delivered: string;
+} | {
+    kind: "name";
+    delivered: string;
+} | {
+    kind: "invalid";
+    entry: string;
+};
+/** Delivered name for an entry (KEY segment for a reference, the entry
+ * itself otherwise; an invalid entry passes through unchanged so error
+ * paths can still name it). The single derivation every renderer and
+ * consumer uses — never re-derive from the raw text. */
+export declare function deliveredName(entry: string): string;
+export declare function parseEnvEntry(entry: string): SecretEnvEntry;
+/**
+ * `policy.envFile` set: it is the SOLE source for bare names — a name
+ * absent from it resolves to `undefined`, `process.env` is never
+ * consulted (a silent fallback would defeat the isolation this exists
+ * to offer). Unset: bare names read `process.env` directly, identical
+ * to every pre-existing caller. References NEVER consult `env_file` or
+ * ambient env: they resolve from the composed mxenv profile only, so a
+ * same-named ambient variable cannot shadow the composed value.
+ *
+ * Invalid entries reject the batch with a descriptive error; audit and
+ * the plan pre-check pre-classify to turn them into findings/conflicts
+ * before this point (the bridge only ever sees pre-checked defs).
+ * Compositions are cached per batch (one `ReferenceResolver` per call,
+ * not per name).
+ * Raw-entry keys preserve provenance when headers mix two profiles with
+ * the same KEY, or a reference and a bare name. Values stay in memory. */
+export declare function resolveSecretEntries(entries: string[], policy: SecretsPolicy): Promise<Record<string, string | undefined>>;
+export declare class SecretReferenceError extends Error {
+    readonly entry: string;
+    constructor(entry: string);
+}
+/** Compatibility view keyed by delivered name (KEY for a reference). */
+export declare function resolveSecretEnv(entries: string[], policy: SecretsPolicy): Promise<Record<string, string | undefined>>;
 export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict";
 /**
  * `trellis migrate`'s static-env secret extraction

package/dist/lib/secretEnv.js

@@ -4,12 +4,20 @@
  * `process.env[name]` lookup — so they can never disagree about where a
  * declared name's value comes from (design.md D1).
  *
- * Dependency-free by design, same as src/lib/envVarNames.ts: a full
- * dotenv library's quoting/escaping/interpolation rules are more than
- * this narrow need requires (design.md D4).
+ * Entries are either bare environment variable names (byte-identical
+ * legacy semantics: `env_file` sole-source when set, otherwise ambient
+ * `process.env`) or `mxenv://<profile>/<KEY>` references resolved
+ * through the `@morphixai/mxenv-core` SDK and delivered under the `KEY`
+ * segment (mx-env-secret-source spec). The dotenv half stays
+ * dependency-free — a full dotenv library's quoting/escaping/
+ * interpolation rules are more than this narrow need requires — while
+ * the reference grammar is owned by the SDK and never re-implemented
+ * here.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname } from "node:path";
+import { findMxEnvReferences, loadConfigLayers, ReferenceResolver } from "@morphixai/mxenv-core";
 const LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
 const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** The name half of LINE_RE, standing alone: what counts as a variable
@@ -34,22 +42,106 @@ export function parseDotenv(content) {
 function loadEnvFile(path) {
     return existsSync(path) ? parseDotenv(readFileSync(path, "utf-8")) : {};
 }
+/** Delivered name for an entry (KEY segment for a reference, the entry
+ * itself otherwise; an invalid entry passes through unchanged so error
+ * paths can still name it). The single derivation every renderer and
+ * consumer uses — never re-derive from the raw text. */
+export function deliveredName(entry) {
+    const parsed = parseEnvEntry(entry);
+    return parsed.kind === "invalid" ? entry : parsed.delivered;
+}
+export function parseEnvEntry(entry) {
+    if (entry.includes("://")) {
+        try {
+            const refs = findMxEnvReferences(entry);
+            if (refs.length === 1 && `mxenv://${refs[0].profile}/${refs[0].key}` === entry) {
+                return { kind: "ref", profile: refs[0].profile, key: refs[0].key, delivered: refs[0].key };
+            }
+        }
+        catch {
+            // legacy scheme rejection from the SDK parser — falls through to invalid
+        }
+        return { kind: "invalid", entry };
+    }
+    return { kind: "name", delivered: entry };
+}
 /**
- * `policy.envFile` set: it is the SOLE source — a name absent from it
- * resolves to `undefined`, `process.env` is never consulted (a silent
- * fallback would defeat the isolation this exists to offer). Unset:
- * reads `process.env` directly, identical to every pre-existing caller.
- */
-export function resolveSecretEnv(names, policy) {
+ * `policy.envFile` set: it is the SOLE source for bare names — a name
+ * absent from it resolves to `undefined`, `process.env` is never
+ * consulted (a silent fallback would defeat the isolation this exists
+ * to offer). Unset: bare names read `process.env` directly, identical
+ * to every pre-existing caller. References NEVER consult `env_file` or
+ * ambient env: they resolve from the composed mxenv profile only, so a
+ * same-named ambient variable cannot shadow the composed value.
+ *
+ * Invalid entries reject the batch with a descriptive error; audit and
+ * the plan pre-check pre-classify to turn them into findings/conflicts
+ * before this point (the bridge only ever sees pre-checked defs).
+ * Compositions are cached per batch (one `ReferenceResolver` per call,
+ * not per name).
+ * Raw-entry keys preserve provenance when headers mix two profiles with
+ * the same KEY, or a reference and a bare name. Values stay in memory. */
+export async function resolveSecretEntries(entries, policy) {
+    const parsed = entries.map(parseEnvEntry);
+    const invalid = parsed.find((p) => p.kind === "invalid");
+    if (invalid) {
+        throw new Error(`[trellis] invalid mxenv:// reference entry: ${invalid.entry} — expected mxenv://<profile>/<KEY>`);
+    }
     const result = {};
-    if (policy.envFile) {
-        const map = loadEnvFile(policy.envFile);
-        for (const name of names)
-            result[name] = map[name];
+    // Cache compositions once per batch; raw keys keep profiles distinct.
+    const refs = parsed.filter((p) => p.kind === "ref");
+    if (refs.length > 0) {
+        let resolver;
+        try {
+            resolver = new ReferenceResolver(loadConfigLayers({ cwd: homedir(), homeDir: homedir() }), {});
+        }
+        catch {
+            throw new SecretReferenceError(entries[parsed.indexOf(refs[0])]);
+        }
+        for (const ref of refs) {
+            const entry = `mxenv://${ref.profile}/${ref.key}`;
+            if (Object.hasOwn(result, entry))
+                continue;
+            try {
+                const { value } = await resolver.valueOf(ref.profile, ref.key);
+                result[entry] = value;
+            }
+            catch {
+                // Provider errors may contain credential material. Report only the
+                // reference, never propagate provider output to logs or audit.
+                throw new SecretReferenceError(entry);
+            }
+        }
     }
-    else {
-        for (const name of names)
-            result[name] = process.env[name];
+    const names = parsed.filter((p) => p.kind === "name");
+    if (names.length > 0) {
+        const fileMap = policy.envFile ? loadEnvFile(policy.envFile) : undefined;
+        for (const name of names) {
+            if (result[name.delivered] !== undefined)
+                continue;
+            result[name.delivered] = fileMap ? fileMap[name.delivered] : process.env[name.delivered];
+        }
+    }
+    return result;
+}
+export class SecretReferenceError extends Error {
+    entry;
+    constructor(entry) {
+        super(`[trellis] could not resolve mxenv reference ${entry} — check the profile, KEY and provider configuration`);
+        this.entry = entry;
+    }
+}
+/** Compatibility view keyed by delivered name (KEY for a reference). */
+export async function resolveSecretEnv(entries, policy) {
+    const values = await resolveSecretEntries(entries, policy);
+    const result = {};
+    // Preserve the existing delivered-name collision rules for env/envAliases.
+    const ordered = [...entries.filter((entry) => parseEnvEntry(entry).kind === "ref"),
+        ...entries.filter((entry) => parseEnvEntry(entry).kind !== "ref")];
+    for (const entry of ordered) {
+        const name = deliveredName(entry);
+        if (result[name] === undefined)
+            result[name] = values[entry];
     }
     return result;
 }

package/dist/lib/skillScope.d.ts

@@ -0,0 +1,14 @@
+import { type AgentId } from "../core/types.js";
+import { type ScopeSelectorRaw } from "./scopeSelection.js";
+export declare function registeredSkillScope(value: unknown): AgentId[];
+export declare function readSkillScopes(path: string): Record<string, unknown>;
+export declare function selectSkillScope(raw: ScopeSelectorRaw, managed: readonly AgentId[]): {
+    scope: AgentId[];
+} | {
+    error: string;
+};
+export declare function requestSkillScope(raw: ScopeSelectorRaw, managed: readonly AgentId[], interactive: boolean): Promise<{
+    scope: AgentId[];
+} | {
+    error: string;
+}>;

package/dist/lib/skillScope.js

@@ -0,0 +1,40 @@
+/** Skill scope is a registry, not an exceptions list. Unregistered or
+ * invalid entries stay paused until applicable agents are selected. */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "../core/types.js";
+import { resolveScopeSelection } from "./scopeSelection.js";
+import { canUseInteractivePicker, runMultiSelectPicker } from "./terminalPicker.js";
+export function registeredSkillScope(value) {
+    return Array.isArray(value) && value.every((id) => ALL_AGENTS.includes(id)) ? [...new Set(value)] : [];
+}
+export function readSkillScopes(path) {
+    if (!existsSync(path))
+        return {};
+    const doc = parseYaml(readFileSync(path, "utf8"));
+    if (doc?.skills === undefined)
+        return {};
+    if (typeof doc.skills !== "object" || doc.skills === null || Array.isArray(doc.skills)) {
+        throw new Error(`${path}: skills must be a map of skill names to agent lists`);
+    }
+    return doc.skills;
+}
+export function selectSkillScope(raw, managed) {
+    const selected = resolveScopeSelection(raw, managed);
+    if (!selected.ok)
+        return { error: selected.detail };
+    // Even "all" records today's set. Managing another agent later must
+    // never expand the compatibility decision made for an existing skill.
+    return { scope: selected.scope ?? [...managed] };
+}
+export async function requestSkillScope(raw, managed, interactive) {
+    if (raw.agents !== undefined || raw.all || raw.none)
+        return selectSkillScope(raw, managed);
+    if (!interactive || !canUseInteractivePicker()) {
+        return { error: "choose applicable agents with --agents <ids>, --all or --none; no scope is selected automatically" };
+    }
+    if (managed.length === 0)
+        return { error: "no managed agents — run trellis onboard, or use --none to import a paused skill" };
+    const indices = await runMultiSelectPicker([...managed], managed.map(() => false), undefined, "选择这个 skill 适用的 agent（不选则暂停分发）");
+    return indices === null ? { error: "skill import cancelled" } : { scope: indices.map((index) => managed[index]) };
+}

package/dist/lib/tomlSection.js

@@ -8,6 +8,7 @@
  * ever needs to recognize table headers and render a bounded, known
  * shape (`McpServerDef`), never general TOML.
  */
+import { deliveredName } from "./secretEnv.js";
 /**
  * Matches a TOML table header line, and *only* a table header line — the
  * entire trimmed line must be exactly `[key.path]` or `[[key.path]]`,
@@ -146,7 +147,7 @@ export function renderServerSection(name, def) {
         if (def.args && def.args.length > 0)
             lines.push(`args = ${tomlStringArray(def.args)}`);
         if (def.env && def.env.length > 0)
-            lines.push(`env_vars = ${tomlStringArray(def.env)}`);
+            lines.push(`env_vars = ${tomlStringArray(def.env.map(deliveredName))}`);
     }
     else {
         if (def.url)
@@ -160,7 +161,7 @@ export function renderServerSection(name, def) {
     // expands it from its own ambient environment, the same mechanism
     // `env_vars` already relies on for a same-named reference
     // (trellis-migrate-env-var-alias D3).
-    const aliasEntries = Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]);
+    const aliasEntries = Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${deliveredName(sourceName)}}`]);
     const staticEnvEntries = [...aliasEntries, ...Object.entries(def.staticEnv ?? {})];
     if (staticEnvEntries.length > 0) {
         lines.push(`[${envHeader(name)}]`);

package/dist/lib/workspace.js

@@ -12,6 +12,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { oauthClientMetadata } from "../core/types.js";
 import { fromServerDefYaml } from "../core/mcpServerDef.js";
+import { readSkillScopes, registeredSkillScope } from "./skillScope.js";
 export const WORKSPACE_DIR_NAME = ".agents";
 /** The only `config.json` schema version this implementation understands. */
 export const WORKSPACE_CONFIG_VERSION = 1;
@@ -103,6 +104,7 @@ export function loadWorkspaceLayer(workspaceDir, policy) {
         layer.instructionsFile = instructionsPath;
     }
     const skillsRoot = join(layerRoot, "skills");
+    const scopes = readSkillScopes(join(layerRoot, "scope.yaml"));
     let skillEntries = [];
     try {
         skillEntries = readdirSync(skillsRoot);
@@ -113,8 +115,11 @@ export function loadWorkspaceLayer(workspaceDir, policy) {
     for (const name of skillEntries) {
         const dir = join(skillsRoot, name);
         try {
-            if (statSync(dir).isDirectory())
-                layer.skills.push({ name, dir });
+            if (statSync(dir).isDirectory()) {
+                layer.skills.push({ name, dir, scope: registeredSkillScope(scopes[name]) });
+                if (!Object.hasOwn(scopes, name))
+                    diagnostics.push(`.agents/scope.yaml: skill "${name}" has no registered agents — Trellis distribution paused`);
+            }
         }
         catch {
             // unreadable/broken entry — skip, not a load failure

package/dist/lib/workspaceDoctor.d.ts

@@ -56,4 +56,4 @@ export interface WorkspaceDoctorSection {
     /** zcode's user-level-first deviation notices (empty otherwise). */
     precedenceWarnings: string[];
 }
-export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): WorkspaceDoctorSection | undefined;
+export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): Promise<WorkspaceDoctorSection | undefined>;

package/dist/lib/workspaceDoctor.js

@@ -11,7 +11,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { parse as parseToml } from "smol-toml";
-import { resolveSecretEnv } from "./secretEnv.js";
+import { deliveredName, parseEnvEntry, resolveSecretEnv } from "./secretEnv.js";
 import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
 const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
 function collectVarRefs(canonical) {
@@ -86,7 +86,7 @@ function unmarkedEntries(agentId, configPath, recorded) {
     }
     return { kind: "ok", names: names.filter((name) => recorded[name] === undefined) };
 }
-export function collectWorkspaceDoctorSection(canonical) {
+export async function collectWorkspaceDoctorSection(canonical) {
     const workspace = canonical.workspace;
     if (!workspace)
         return undefined;
@@ -101,8 +101,12 @@ export function collectWorkspaceDoctorSection(canonical) {
     // overridden.
     const tombstoned = workspace.shadowed.filter((entry) => entry.startsWith("mcp:") && canonical.mcp.servers[entry.slice(4)] === undefined);
     const refs = collectVarRefs(canonical);
-    const resolved = resolveSecretEnv([...new Set(refs.map((r) => r.name))], canonical.secretsPolicy);
-    const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
+    // Malformed `mxenv://` entries are unresolved as-is (they name themselves);
+    // they must never reach resolveSecretEnv, which rejects the batch.
+    const invalid = refs.filter((r) => parseEnvEntry(r.name).kind === "invalid");
+    const resolvableRefs = refs.filter((r) => parseEnvEntry(r.name).kind !== "invalid");
+    const resolved = await resolveSecretEnv([...new Set(resolvableRefs.map((r) => r.name))], canonical.secretsPolicy);
+    const unresolvedVars = [...invalid, ...resolvableRefs.filter((r) => resolved[deliveredName(r.name)] === undefined)];
     const manifest = loadWorkspaceRendered(workspace.root);
     const unmigrated = [];
     const tomlFindings = [];

package/dist/lib/workspaceMcp.d.ts

@@ -53,5 +53,5 @@ export declare function renderWorkspaceManifestEntry(agentId: AgentId, name: str
  * `applyWorkspaceMcp`; this exists only for adoption, where no delivery
  * write to that agent's file has happened yet. */
 export declare function recordWorkspaceRendered(workspaceRoot: string, agentId: AgentId, name: string, rendered: unknown, backup: BackupSession): void;
-export declare function planWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource): AdapterPlanItem[];
+export declare function planWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
 export declare function applyWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource, items: AdapterPlanItem[], backup: BackupSession): void;

package/dist/lib/workspaceMcp.js

@@ -140,7 +140,7 @@ export function recordWorkspaceRendered(workspaceRoot, agentId, name, rendered,
     mkdirSync(dirname(path), { recursive: true });
     backup.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
 }
-export function planWorkspaceMcp(agentId, canonical) {
+export async function planWorkspaceMcp(agentId, canonical) {
     const workspace = canonical.workspace;
     if (!workspace)
         return [];
@@ -151,7 +151,7 @@ export function planWorkspaceMcp(agentId, canonical) {
     const layer = (item) => ({ ...item, layer: "workspace" });
     if (agentId === "codex") {
         const content = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(agentId, mcp, canonical.managedAgents, canonical.secretsPolicy);
+        const { desired, conflicts } = await resolveMcpPlan(agentId, mcp, canonical.managedAgents, canonical.secretsPolicy);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);
@@ -183,13 +183,13 @@ export function planWorkspaceMcp(agentId, canonical) {
     }
     if (agentId === "zcode") {
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        const items = planZcodeMcp({ configPath, parsed, mcp, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership }).map(layer);
+        const items = (await planZcodeMcp({ configPath, parsed, mcp, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership })).map(layer);
         const servers = (parsed?.mcp?.servers ?? {});
         return guardUnmarkedOverwrite(items, (item) => servers[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
     }
     const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
     const render = agentId === "pi" ? piRenderer : undefined;
-    const planned = planJsonMcp({
+    const planned = (await planJsonMcp({
         configPath,
         parsed,
         mcp,
@@ -198,7 +198,7 @@ export function planWorkspaceMcp(agentId, canonical) {
         policy: canonical.secretsPolicy,
         ownership,
         ...(render ? { render } : {}),
-    }).map(layer);
+    })).map(layer);
     const existing = (parsed?.mcpServers ?? {});
     const guarded = guardUnmarkedOverwrite(planned, (item) => existing[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
     if (agentId !== "pi")