agent-trellis 0.2.0 → 0.3.0

package/README.md

@@ -148,6 +148,18 @@ result is named future work, not built yet.
   `mcp sync`/`onboard` run that performs a real write adds one more run
   directory, with no cap. Delete old ones by hand for now.
 
+A canonical MCP server can also declare `enabled: false` (kept defined,
+never written to any agent) and `static_env` (a value that was never a
+secret — an email, an environment tag — written verbatim instead of
+resolved by name; still scanned against `reject_patterns` like every
+other literal field). Before ever writing a name-only `env` entry,
+`mcp sync` now checks it actually resolves through the same source
+`secrets audit` and the pi bridge use — an unresolvable name is refused
+as a conflict, not silently written and left to break that server's
+connection once the agent starts it. Both found via real-machine
+dogfooding, not a synthetic fixture — see
+[`schema/servers.example.yaml`](schema/servers.example.yaml).
+
 ## Design principles
 
 1. **One canonical source, many adapters.** Each agent's native config file is

package/dist/adapters/claude-code.d.ts

@@ -5,8 +5,9 @@
  * before the other three adapters commit to reusing `symlinkPlan.ts`.
  *
  * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
- * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
- * removal (D7).
+ * (trellis-mcp-sync-p2 design.md D4). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current entry is still exactly what Trellis itself last wrote.
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
 import type { CanonicalSource } from "../core/types.js";

package/dist/adapters/claude-code.js

@@ -5,8 +5,9 @@
  * before the other three adapters commit to reusing `symlinkPlan.ts`.
  *
  * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
- * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
- * removal (D7).
+ * (trellis-mcp-sync-p2 design.md D4). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current entry is still exactly what Trellis itself last wrote.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -14,7 +15,8 @@ import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
-import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "./jsonMcp.js";
+import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
 export class ClaudeCodeAdapter {
     homeDir;
     name = "Claude Code";
@@ -50,18 +52,29 @@ export class ClaudeCodeAdapter {
     planMcp(canonical) {
         const configPath = join(this.homeDir, ".claude.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents });
+        const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
     }
     async apply(plan, backup) {
         await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length === 0) {
+        const mcpWrites = plan.filter((item) => item.kind === "mcp" && (item.action === "create" || item.action === "remove"));
+        if (mcpWrites.length === 0) {
             return;
         }
-        const configPath = mcpCreates[0].target;
+        const configPath = mcpWrites[0].target;
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        const merged = applyJsonMcp(parsed, mcpCreates);
+        const merged = applyJsonMcp(parsed, mcpWrites);
         backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        let ownership = loadMcpOwnership(this.homeDir);
+        for (const item of mcpWrites) {
+            if (item.action === "create" && item.mcpWrite) {
+                ownership = recordOwned(ownership, this.id, item.mcpWrite.name, renderJsonServerEntry(item.mcpWrite.def));
+            }
+            else if (item.action === "remove" && item.mcpRemove) {
+                ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+            }
+        }
+        saveMcpOwnership(this.homeDir, ownership);
     }
     async verify(canonical) {
         const snapshot = await claudeCodeProbe.probe(this.homeDir);

package/dist/adapters/codex.d.ts

@@ -8,9 +8,12 @@
  *
  * MCP servers are written via `src/lib/tomlSection.ts`'s line-based
  * section splicer, never a TOML library (trellis-mcp-sync-p2 design.md
- * D1/D2 — both rejected with evidence) — create/repair only, no
- * automatic removal (D7: no ownership marker exists for a bare TOML key
- * the way a symlink's realpath provides for skills).
+ * D1/D2 — both rejected with evidence). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current section text is still exactly what Trellis itself last
+ * wrote — a bare TOML key has no ownership marker of its own the way a
+ * symlink's realpath provides for skills, so this ledger is what makes
+ * it provably safe.
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
 import type { CanonicalSource } from "../core/types.js";

package/dist/adapters/codex.js

@@ -8,9 +8,12 @@
  *
  * MCP servers are written via `src/lib/tomlSection.ts`'s line-based
  * section splicer, never a TOML library (trellis-mcp-sync-p2 design.md
- * D1/D2 — both rejected with evidence) — create/repair only, no
- * automatic removal (D7: no ownership marker exists for a bare TOML key
- * the way a symlink's realpath provides for skills).
+ * D1/D2 — both rejected with evidence). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current section text is still exactly what Trellis itself last
+ * wrote — a bare TOML key has no ownership marker of its own the way a
+ * symlink's realpath provides for skills, so this ledger is what makes
+ * it provably safe.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
@@ -20,7 +23,8 @@ import * as codexProbe from "../probes/codex.js";
 import { readInstructionsPath } from "../probes/codex.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
-import { currentServerSectionText, renderServerSection, upsertSection } from "../lib/tomlSection.js";
+import { currentServerSectionText, removeSection, renderServerSection, upsertSection } from "../lib/tomlSection.js";
+import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
 export class CodexAdapter {
     homeDir;
     name = "Codex";
@@ -62,7 +66,7 @@ export class CodexAdapter {
     planMcp(canonical) {
         const configTomlPath = join(this.homeDir, ".codex", "config.toml");
         const content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents);
+        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);
@@ -81,20 +85,47 @@ export class CodexAdapter {
         for (const conflict of conflicts) {
             items.push({ action: "conflict", kind: "mcp", target: configTomlPath, description: conflict.message });
         }
+        const desiredNames = new Set(desired.map((d) => d.name));
+        const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
+        for (const [name, expected] of Object.entries(ownership)) {
+            if (desiredNames.has(name))
+                continue; // still wanted — not a removal candidate
+            const current = currentServerSectionText(content, name);
+            if (current === null)
+                continue; // already gone
+            if (current !== expected)
+                continue; // hand-edited since Trellis wrote it — no longer ours to touch
+            items.push({
+                action: "remove",
+                kind: "mcp",
+                target: configTomlPath,
+                mcpRemove: { name },
+                description: `MCP server "${name}" removed from ${configTomlPath} — no longer in canonical`,
+            });
+        }
         return items;
     }
     async apply(plan, backup) {
         await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length === 0) {
+        const mcpWrites = plan.filter((item) => item.kind === "mcp" && (item.action === "create" || item.action === "remove"));
+        if (mcpWrites.length === 0) {
             return;
         }
-        const configTomlPath = mcpCreates[0].target;
+        const configTomlPath = mcpWrites[0].target;
         let content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
-        for (const item of mcpCreates) {
-            content = upsertSection(content, item.mcpWrite.name, item.mcpWrite.def);
+        let ownership = loadMcpOwnership(this.homeDir);
+        for (const item of mcpWrites) {
+            if (item.action === "create" && item.mcpWrite) {
+                content = upsertSection(content, item.mcpWrite.name, item.mcpWrite.def);
+                ownership = recordOwned(ownership, this.id, item.mcpWrite.name, renderServerSection(item.mcpWrite.name, item.mcpWrite.def));
+            }
+            else if (item.action === "remove" && item.mcpRemove) {
+                content = removeSection(content, item.mcpRemove.name);
+                ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+            }
         }
         backup.writeFile(configTomlPath, content);
+        saveMcpOwnership(this.homeDir, ownership);
     }
     async verify(canonical) {
         const snapshot = await codexProbe.probe(this.homeDir);

package/dist/adapters/jsonMcp.d.ts

@@ -6,11 +6,14 @@
  * round-trip is safe as long as every sibling top-level key is carried
  * through untouched.
  */
-import type { AgentId, McpConfig, McpServerDef } from "../core/types.js";
+import type { AgentId, McpConfig, McpServerDef, SecretsPolicy } from "../core/types.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
 /** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
- * expects — `env` values are always `${VAR}` references, never literals
- * (docs/research.md "Secrets"). */
+ * expects — `env` names render as `${VAR}` references, `staticEnv`
+ * entries render as their literal values, both in the same map (JSON's
+ * `env` object has no structural distinction between the two the way
+ * Codex's TOML does — see tomlSection.ts's two-table rendering)
+ * (trellis-mcp-static-env-and-disabled-servers design.md D4). */
 export declare function renderJsonServerEntry(def: McpServerDef): Record<string, unknown>;
 export declare function planJsonMcp(opts: {
     configPath: string;
@@ -18,8 +21,15 @@ export declare function planJsonMcp(opts: {
     mcp: McpConfig;
     agentId: AgentId;
     managedAgents: readonly AgentId[];
+    policy: SecretsPolicy;
+    /** This agent's own slice of `src/lib/mcpOwnership.ts`'s ledger — what
+     * Trellis itself last wrote for each name, keyed by name. Omit (or
+     * pass `{}`) to get today's create/repair/conflict-only behavior with
+     * zero removal candidates. */
+    ownership?: Record<string, unknown>;
 }): AdapterPlanItem[];
 /** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
- * file didn't exist), returning the object to stringify — every sibling
- * top-level key on `parsed` is spread through untouched. */
+ * file didn't exist) and deletes every `"remove"` item's key, returning
+ * the object to stringify — every sibling top-level key on `parsed` is
+ * spread through untouched. */
 export declare function applyJsonMcp(parsed: Record<string, unknown> | undefined, items: AdapterPlanItem[]): Record<string, unknown>;

package/dist/adapters/jsonMcp.js

@@ -6,29 +6,14 @@
  * round-trip is safe as long as every sibling top-level key is carried
  * through untouched.
  */
+import { deepEqual } from "../lib/deepEqual.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
-function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || b === null || typeof a !== typeof b)
-        return false;
-    if (Array.isArray(a) || Array.isArray(b)) {
-        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
-            return false;
-        return a.every((value, index) => deepEqual(value, b[index]));
-    }
-    if (typeof a === "object" && typeof b === "object") {
-        const aKeys = Object.keys(a);
-        const bKeys = Object.keys(b);
-        if (aKeys.length !== bKeys.length)
-            return false;
-        return aKeys.every((key) => deepEqual(a[key], b[key]));
-    }
-    return false;
-}
 /** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
- * expects — `env` values are always `${VAR}` references, never literals
- * (docs/research.md "Secrets"). */
+ * expects — `env` names render as `${VAR}` references, `staticEnv`
+ * entries render as their literal values, both in the same map (JSON's
+ * `env` object has no structural distinction between the two the way
+ * Codex's TOML does — see tomlSection.ts's two-table rendering)
+ * (trellis-mcp-static-env-and-disabled-servers design.md D4). */
 export function renderJsonServerEntry(def) {
     if (def.transport === "http" || def.transport === "sse") {
         const entry = { type: def.transport, url: def.url };
@@ -38,14 +23,16 @@ export function renderJsonServerEntry(def) {
         return entry;
     }
     const entry = { type: "stdio", command: def.command, args: def.args ?? [] };
-    if (def.env && def.env.length > 0) {
-        entry.env = Object.fromEntries(def.env.map((name) => [name, `\${${name}}`]));
+    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
+    const env = { ...nameRefs, ...(def.staticEnv ?? {}) };
+    if (Object.keys(env).length > 0) {
+        entry.env = env;
     }
     return entry;
 }
 export function planJsonMcp(opts) {
-    const { configPath, parsed, mcp, agentId, managedAgents } = opts;
-    const { desired, conflicts } = resolveMcpPlan(agentId, mcp, managedAgents);
+    const { configPath, parsed, mcp, agentId, managedAgents, policy, ownership } = opts;
+    const { desired, conflicts } = resolveMcpPlan(agentId, mcp, managedAgents, policy);
     const existingServers = parsed?.mcpServers ?? {};
     const items = [];
     for (const { name, def } of desired) {
@@ -65,20 +52,42 @@ export function planJsonMcp(opts) {
     for (const conflict of conflicts) {
         items.push({ action: "conflict", kind: "mcp", target: configPath, description: conflict.message });
     }
+    const desiredNames = new Set(desired.map((d) => d.name));
+    for (const [name, expected] of Object.entries(ownership ?? {})) {
+        if (desiredNames.has(name))
+            continue; // still wanted — not a removal candidate at all
+        const current = existingServers[name];
+        if (current === undefined)
+            continue; // already gone — nothing to remove, ledger is pruned separately
+        if (!deepEqual(current, expected))
+            continue; // hand-edited since Trellis wrote it — no longer ours to touch
+        items.push({
+            action: "remove",
+            kind: "mcp",
+            target: configPath,
+            mcpRemove: { name },
+            description: `MCP server "${name}" removed from ${configPath} — no longer in canonical`,
+        });
+    }
     return items;
 }
 /** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
- * file didn't exist), returning the object to stringify — every sibling
- * top-level key on `parsed` is spread through untouched. */
+ * file didn't exist) and deletes every `"remove"` item's key, returning
+ * the object to stringify — every sibling top-level key on `parsed` is
+ * spread through untouched. */
 export function applyJsonMcp(parsed, items) {
     const base = parsed ?? {};
     const existingServers = base.mcpServers ?? {};
     const mergedServers = { ...existingServers };
     for (const item of items) {
-        if (item.kind !== "mcp" || item.action !== "create" || !item.mcpWrite) {
+        if (item.kind !== "mcp")
             continue;
+        if (item.action === "create" && item.mcpWrite) {
+            mergedServers[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
+        }
+        else if (item.action === "remove" && item.mcpRemove) {
+            delete mergedServers[item.mcpRemove.name];
         }
-        mergedServers[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
     }
     return { ...base, mcpServers: mergedServers };
 }

package/dist/adapters/kiro.d.ts

@@ -3,8 +3,9 @@
  * symlinks, `~/.kiro/steering/CLAUDE.md` symlinked to canonical `agents.md`.
  *
  * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
- * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
- * removal (D7).
+ * (trellis-mcp-sync-p2 design.md D4). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current entry is still exactly what Trellis itself last wrote.
  *
  * Kiro's own `${VAR}` substitution (real, found by reading Kiro's
  * installed extension source — trellis-kiro-approved-env-vars design.md

package/dist/adapters/kiro.js

@@ -3,8 +3,9 @@
  * symlinks, `~/.kiro/steering/CLAUDE.md` symlinked to canonical `agents.md`.
  *
  * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
- * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
- * removal (D7).
+ * (trellis-mcp-sync-p2 design.md D4). Removal (trellis-mcp-lifecycle-
+ * parity) only happens when `src/lib/mcpOwnership.ts`'s ledger proves
+ * the current entry is still exactly what Trellis itself last wrote.
  *
  * Kiro's own `${VAR}` substitution (real, found by reading Kiro's
  * installed extension source — trellis-kiro-approved-env-vars design.md
@@ -20,9 +21,10 @@ import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
 import * as kiroProbe from "../probes/kiro.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
-import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "./jsonMcp.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
 import { declaredEnvNames } from "../lib/envVarNames.js";
+import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
 /** VS-Code-family global settings path. macOS only — see
  * trellis-kiro-approved-env-vars proposal.md Non-Goals: Linux/Windows
  * equivalents are the well-known convention but unverified against a
@@ -67,13 +69,14 @@ export class KiroAdapter {
     planMcp(canonical) {
         const configPath = join(this.homeDir, ".kiro", "settings", "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents });
+        const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership });
     }
     /** 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, canonical.mcp, canonical.managedAgents);
+        const { desired } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy);
         const names = new Set();
         for (const { def } of desired) {
             for (const name of declaredEnvNames(def))
@@ -117,13 +120,23 @@ export class KiroAdapter {
     }
     async apply(plan, backup) {
         await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"), backup);
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length > 0) {
-            const configPath = mcpCreates[0].target;
+        const mcpWrites = plan.filter((item) => item.kind === "mcp" && (item.action === "create" || item.action === "remove"));
+        if (mcpWrites.length > 0) {
+            const configPath = mcpWrites[0].target;
             const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-            const merged = applyJsonMcp(parsed, mcpCreates);
+            const merged = applyJsonMcp(parsed, mcpWrites);
             mkdirSync(dirname(configPath), { recursive: true });
             backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+            let ownership = loadMcpOwnership(this.homeDir);
+            for (const item of mcpWrites) {
+                if (item.action === "create" && item.mcpWrite) {
+                    ownership = recordOwned(ownership, this.id, item.mcpWrite.name, renderJsonServerEntry(item.mcpWrite.def));
+                }
+                else if (item.action === "remove" && item.mcpRemove) {
+                    ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+                }
+            }
+            saveMcpOwnership(this.homeDir, ownership);
         }
         const approvedEnvVarsCreate = plan.find((item) => item.kind === "kiro-approved-env-vars" && item.action === "create" && item.approvedEnvVars);
         if (approvedEnvVarsCreate) {

package/dist/adapters/mcpPlan.d.ts

@@ -6,12 +6,17 @@
  * each adapter turns this into plan items using its own read/write
  * mechanism (JSON merge vs. TOML section splice).
  *
- * No automatic removal here (design.md D7, trellis-mcp-sync-p2): unlike a
- * skill's symlink, a plain key has no ownership marker, so "not in
- * canonical anymore" can't be distinguished from "the user configured
- * this directly." Only create/repair + refuse.
+ * Removal is NOT decided here (design.md D7, trellis-mcp-sync-p2): unlike
+ * a skill's symlink, a plain key has no ownership marker of its own, so
+ * "not in canonical anymore" can't be distinguished from "the user
+ * configured this directly" from this function's storage-agnostic view
+ * alone. Each format-specific caller (`jsonMcp.ts`'s `planJsonMcp`,
+ * `codex.ts`'s own `planMcp`) computes removal candidates itself, against
+ * `src/lib/mcpOwnership.ts`'s ledger and that format's own current
+ * on-disk content (trellis-mcp-lifecycle-parity) — this function only
+ * ever returns create/repair + refuse.
  */
-import type { AgentId, McpConfig, McpServerDef } from "../core/types.js";
+import type { AgentId, McpConfig, McpServerDef, SecretsPolicy } from "../core/types.js";
 export declare const HUB_ENTRY_NAME = "trellis-hub";
 export interface DesiredMcpEntry {
     name: string;
@@ -25,4 +30,4 @@ export interface McpPlanResult {
     desired: DesiredMcpEntry[];
     conflicts: McpConflict[];
 }
-export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[]): McpPlanResult;
+export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -6,13 +6,19 @@
  * each adapter turns this into plan items using its own read/write
  * mechanism (JSON merge vs. TOML section splice).
  *
- * No automatic removal here (design.md D7, trellis-mcp-sync-p2): unlike a
- * skill's symlink, a plain key has no ownership marker, so "not in
- * canonical anymore" can't be distinguished from "the user configured
- * this directly." Only create/repair + refuse.
+ * Removal is NOT decided here (design.md D7, trellis-mcp-sync-p2): unlike
+ * a skill's symlink, a plain key has no ownership marker of its own, so
+ * "not in canonical anymore" can't be distinguished from "the user
+ * configured this directly" from this function's storage-agnostic view
+ * alone. Each format-specific caller (`jsonMcp.ts`'s `planJsonMcp`,
+ * `codex.ts`'s own `planMcp`) computes removal candidates itself, against
+ * `src/lib/mcpOwnership.ts`'s ledger and that format's own current
+ * on-disk content (trellis-mcp-lifecycle-parity) — this function only
+ * ever returns create/repair + refuse.
  */
 import { isInScope } from "../core/adapter.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
+import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
 const CODEX_STDIO_URL_CRASH_NOTE = ' On Codex specifically, this crashes the entire process at startup ("url is not supported for stdio"), not just this one server — see docs/research.md.';
 function collisionMessage(name, agentId) {
@@ -30,7 +36,7 @@ const DANGEROUS_LITERAL_PATTERNS = [
     { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ },
 ];
 function findLiteralSecret(def) {
-    const candidates = [def.command, def.url, ...(def.args ?? []), ...Object.values(def.headers ?? {})].filter((v) => typeof v === "string");
+    const candidates = [def.command, def.url, ...(def.args ?? []), ...Object.values(def.headers ?? {}), ...Object.values(def.staticEnv ?? {})].filter((v) => typeof v === "string");
     for (const candidate of candidates) {
         for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
             if (pattern.test(candidate)) {
@@ -40,7 +46,22 @@ function findLiteralSecret(def) {
     }
     return undefined;
 }
-export function resolveMcpPlan(agentId, mcp, managedAgents) {
+/**
+ * Name-only `env` entries that don't resolve to anything would otherwise
+ * be written and silently break the agent's connection to that server —
+ * found via real-machine dogfooding (trellis-mcp-static-env-and-disabled-servers
+ * proposal.md "Why"). Uses the identical `resolveSecretEnv` `secrets
+ * audit`/the pi bridge already call, so this and a later `secrets audit`
+ * run can never disagree about what resolves.
+ */
+function findUnresolvedEnvName(def, policy) {
+    const names = def.env ?? [];
+    if (names.length === 0)
+        return undefined;
+    const resolved = resolveSecretEnv(names, policy);
+    return names.find((name) => !resolved[name]);
+}
+export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
     if (mcp.hub) {
         if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
             return { desired: [], conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId) }] };
@@ -50,6 +71,9 @@ export function resolveMcpPlan(agentId, mcp, managedAgents) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
+        if (def.enabled === false) {
+            continue;
+        }
         if (!isInScope(agentId, def.agents, managedAgents)) {
             continue;
         }
@@ -77,6 +101,15 @@ export function resolveMcpPlan(agentId, mcp, managedAgents) {
             });
             continue;
         }
+        const unresolvedName = findUnresolvedEnvName(def, policy);
+        if (unresolvedName) {
+            const source = policy.envFile ?? "process environment";
+            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)`,
+            });
+            continue;
+        }
         desired.push({ name, def });
     }
     return { desired, conflicts };