agent-trellis 0.1.0 → 0.3.0

package/README.md

@@ -45,14 +45,29 @@ trellis onboard
 ```
 
 Creates canonical source, detects which of Claude Code/Codex/Kiro/pi are on
-this machine, picks a base agent to migrate from (auto-selected if only one
-is present; prompts if more than one — pass `--agent <id>` to skip the
-prompt), then runs `migrate` and `sync`. If no agent is detected, it prints
-each supported agent's real install command/URL and stops — it never
-installs anything itself. Add `--dry-run` to preview the whole thing with
-zero writes.
+this machine, then resolves two independent choices: a **migration source**
+(read from — auto-selected if only one present agent has real content,
+prompted with a numbered choice if more than one, skippable if starting
+fresh; pass `--agent <id>` to skip the prompt) and a **managed set** (written
+to — zero or more agents, chosen explicitly; pass `--manage <ids>` or
+`--manage none` to skip the prompt). The source is **not** managed by
+default — importing from Claude Code doesn't mean Trellis starts writing to
+Claude Code too, unless you explicitly include it. Selecting an agent that
+isn't installed yet (e.g. pi) is itself the authorization to install it —
+one confirmation, then a real `npm install -g <package>`; Kiro has no CLI
+package and is refused with its download URL instead. Once resolved, it
+runs `migrate`, `sync`, `mcp sync`, and `secrets audit` against the managed
+set — the whole onboarding path in one command, no follow-up commands to
+type by hand. If no agent is detected, it prints each supported agent's
+real install command/URL and stops — it never installs anything on its own
+initiative. Add `--dry-run` to preview the whole thing with zero writes.
 
-**Or step by step** (what `onboard` is actually doing under the hood):
+```
+trellis onboard --agent claude-code --manage pi
+```
+
+**Or step by step** (what `onboard` is actually doing under the hood, if you
+want to run any one stage on its own):
 
 **Already using Claude Code, Codex, Kiro, or pi and want to migrate what you
 already have?**
@@ -65,24 +80,46 @@ already have?**
    overwrites: an already-identical skill is reported and skipped, a genuine
    conflict is reported and left for you to resolve by hand. Add `--dry-run`
    to preview first.
-3. `trellis sync` — distributes canonical skills/instructions to every agent
-   present on this machine (including the ones you didn't migrate from).
-   Add `--dry-run` to preview first.
+3. `trellis sync` — distributes canonical skills/instructions to every
+   **managed** agent (`~/.trellis/managed.yaml` — empty by default; edit it
+   by hand or let `trellis onboard` write it). An agent that's merely present
+   but not managed is never touched. Add `--dry-run` to preview first.
 4. `trellis mcp sync` — distributes `~/.trellis/mcp/servers.yaml` (see
    [`schema/servers.example.yaml`](schema/servers.example.yaml)) to every
-   agent's native MCP config (create/repair only — see Known limitations).
-5. `trellis secrets audit` — fails non-zero if any agent's real config holds
-   a literal credential or an unexpected env var name.
-6. `trellis doctor` — read-only scan of every present agent's current state;
-   run any time to check for drift.
+   managed agent's native MCP config (create/repair only — see Known
+   limitations).
+5. `trellis secrets audit` — fails non-zero if any managed agent's real
+   config holds a literal credential or an unexpected env var name.
+6. `trellis doctor` — read-only scan of every present agent's current state
+   (managed or not); run any time to check for drift.
 
 **Starting from nothing?** Skip step 2 — `trellis init`'s placeholder
 `agents.md` and empty `skills/` are a fine starting point; edit them by hand.
 
+**Every real write `sync`/`mcp sync`/`onboard` perform is backed up
+first, automatically — no flag to opt in.** Before creating, repairing,
+or removing anything, each is recorded to a structured, timestamped run
+under `~/.trellis/backups/`, with enough information to invert it exactly.
+`trellis rollback` undoes one recorded run — omit a run id for the most
+recent one:
+
+```
+$ trellis rollback
+rollback 2026-09-13T04-52-18-727Z-mcp-sync
+✅ 3 restored, 0 conflict(s), 0 already reverted
+   - [restore] restore /Users/you/.claude.json to its content before this run (...)
+```
+
+If something else touched a path since the backed-up run, that one path
+is a `conflict` — reported, left untouched, never force-restored over —
+while every other path in the same rollback still restores. `--list`
+shows available runs without touching anything; `--dry-run` previews a
+restore with zero writes.
+
 ## Status
 
-**Early, pre-1.0.** All seven CLI commands above (`onboard`, `init`,
-`migrate`, `doctor`, `sync`, `mcp sync`, `secrets audit`) are implemented,
+**Early, pre-1.0.** All eight CLI commands above (`onboard`, `init`,
+`migrate`, `doctor`, `sync`, `mcp sync`, `secrets audit`, `rollback`) are implemented,
 unit-tested, and verified end-to-end against real Docker containers (never a
 developer's own dotfiles during development — see
 [`docs/architecture.md`](docs/architecture.md)'s testing philosophy). See
@@ -107,6 +144,21 @@ result is named future work, not built yet.
 - Automatic removal of an MCP server is deliberately unsupported (create/
   repair only) until an ownership-tracking mechanism exists — see
   `docs/roadmap.md`'s P2 note.
+- `~/.trellis/backups/` has no automatic pruning yet — every `sync`/
+  `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
 

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

@@ -5,11 +5,13 @@
  * 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";
+import type { BackupSession } from "../lib/backup.js";
 export declare class ClaudeCodeAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Claude Code";
@@ -18,6 +20,6 @@ export declare class ClaudeCodeAdapter implements TrellisAdapter {
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
     private planMcp;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/claude-code.js

@@ -5,16 +5,18 @@
  * 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, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 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";
@@ -30,7 +32,7 @@ export class ClaudeCodeAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".claude", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -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 });
+        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) {
-        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length === 0) {
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
+        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);
-        writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        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);
@@ -69,7 +82,7 @@ export class ClaudeCodeAdapter {
             return { ok: false, mismatches: ["claude-code is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/codex.d.ts

@@ -8,12 +8,16 @@
  *
  * 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";
+import type { BackupSession } from "../lib/backup.js";
 export declare class CodexAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Codex";
@@ -22,6 +26,6 @@ export declare class CodexAdapter implements TrellisAdapter {
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
     private planMcp;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/codex.js

@@ -8,11 +8,14 @@
  *
  * 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, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
@@ -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";
@@ -36,7 +40,7 @@ export class CodexAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".agents", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -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);
+        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) {
-        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length === 0) {
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
+        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);
+            }
         }
-        writeFileSync(configTomlPath, content);
+        backup.writeFile(configTomlPath, content);
+        saveMcpOwnership(this.homeDir, ownership);
     }
     async verify(canonical) {
         const snapshot = await codexProbe.probe(this.homeDir);
@@ -102,7 +133,7 @@ export class CodexAdapter {
             return { ok: false, mismatches: ["codex is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/jsonMcp.d.ts

@@ -6,19 +6,30 @@
  * 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;
     parsed: Record<string, unknown> | undefined;
     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 } = opts;
-    const { desired, conflicts } = resolveMcpPlan(agentId, mcp);
+    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
@@ -16,6 +17,7 @@
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
 import type { CanonicalSource } from "../core/types.js";
+import type { BackupSession } from "../lib/backup.js";
 export declare class KiroAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Kiro";
@@ -29,6 +31,6 @@ export declare class KiroAdapter implements TrellisAdapter {
      * known_host_injected collision, never contributes a name here either. */
     private desiredApprovedEnvVars;
     private planApprovedEnvVars;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

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
@@ -14,15 +15,16 @@
  * adapter keeps that list a superset of every env name it references,
  * additive only.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 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
@@ -46,7 +48,7 @@ export class KiroAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".kiro", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -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 });
+        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);
+        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))
@@ -115,15 +118,25 @@ export class KiroAdapter {
             },
         ];
     }
-    async apply(plan) {
-        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"));
-        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
-        if (mcpCreates.length > 0) {
-            const configPath = mcpCreates[0].target;
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"), backup);
+        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 });
-            writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+            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) {
@@ -131,7 +144,7 @@ export class KiroAdapter {
             const parsed = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf-8")) : {};
             const merged = { ...parsed, [APPROVED_ENV_VARS_KEY]: approvedEnvVarsCreate.approvedEnvVars };
             mkdirSync(dirname(settingsPath), { recursive: true });
-            writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+            backup.writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
         }
     }
     async verify(canonical) {
@@ -140,7 +153,7 @@ export class KiroAdapter {
             return { ok: false, mismatches: ["kiro is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {