agent-trellis 0.7.0 → 0.8.2

package/dist/commands/manage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Explicit lifecycle management for `~/.trellis/managed.yaml`.
+ *
+ * Onboarding stays additive: omission must never silently revoke Trellis's
+ * write authorization. Exact replacement and subtraction live here so they
+ * are deliberate, visible in shell history, dry-runnable, and recoverable.
+ */
+import type { AgentId } from "../core/types.js";
+export type ManageOperation = "list" | "set" | "add" | "remove";
+export interface ManagePlan {
+    operation: ManageOperation;
+    current: AgentId[];
+    desired: AgentId[];
+    added: AgentId[];
+    removed: AgentId[];
+    changed: boolean;
+}
+export interface ParsedManageArgs {
+    operation: ManageOperation;
+    ids?: string;
+    json: boolean;
+    dryRun: boolean;
+}
+export type ManagePlanResult = {
+    plan: ManagePlan;
+} | {
+    error: string;
+};
+export declare function parseManageArgs(argv: readonly string[]): ParsedManageArgs | {
+    error: string;
+};
+export declare function collectManagePlan(operation: ManageOperation, rawIds: string | undefined, homeDir?: string): ManagePlanResult;
+export declare function applyManagePlan(plan: ManagePlan, homeDir?: string): void;
+export declare function runManage(parsed: ParsedManageArgs, opts?: {
+    homeDir?: string;
+}): {
+    exitCode: number;
+    plan?: ManagePlan;
+};

package/dist/commands/manage.js

@@ -0,0 +1,126 @@
+/**
+ * Explicit lifecycle management for `~/.trellis/managed.yaml`.
+ *
+ * Onboarding stays additive: omission must never silently revoke Trellis's
+ * write authorization. Exact replacement and subtraction live here so they
+ * are deliberate, visible in shell history, dry-runnable, and recoverable.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ALL_AGENTS } from "../core/types.js";
+import { openBackupSession } from "../lib/backup.js";
+function stableAgents(ids) {
+    const selected = new Set(ids);
+    return ALL_AGENTS.filter((id) => selected.has(id));
+}
+function parseAgentList(raw, allowNone) {
+    if (raw === undefined || raw.trim() === "") {
+        return { error: `agent list is required — use a comma-separated subset of ${ALL_AGENTS.join(", ")}${allowNone ? ", or none" : ""}` };
+    }
+    if (raw.trim().toLowerCase() === "none") {
+        return allowNone ? { agents: [] } : { error: '"none" is valid only for `trellis manage set none`' };
+    }
+    const tokens = raw.split(",").map((token) => token.trim()).filter(Boolean);
+    const invalid = tokens.filter((token) => !ALL_AGENTS.includes(token));
+    if (invalid.length > 0) {
+        return { error: `unknown agent id${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")} — expected ${ALL_AGENTS.join(", ")}` };
+    }
+    return { agents: stableAgents(tokens) };
+}
+export function parseManageArgs(argv) {
+    const [rawOperation, ...rest] = argv;
+    if (rawOperation !== "list" && rawOperation !== "set" && rawOperation !== "add" && rawOperation !== "remove") {
+        return { error: `unknown manage operation "${rawOperation ?? "(none)"}" — expected list, set, add, or remove` };
+    }
+    const unknownFlags = rest.filter((arg) => arg.startsWith("--") && arg !== "--json" && arg !== "--dry-run");
+    if (unknownFlags.length > 0)
+        return { error: `unknown manage flag "${unknownFlags[0]}"` };
+    const positional = rest.filter((arg) => !arg.startsWith("--"));
+    if (rawOperation === "list") {
+        if (positional.length > 0)
+            return { error: "manage list accepts no agent list" };
+    }
+    else if (positional.length !== 1) {
+        return { error: `manage ${rawOperation} requires exactly one comma-separated agent list` };
+    }
+    return {
+        operation: rawOperation,
+        ids: positional[0],
+        json: rest.includes("--json"),
+        dryRun: rest.includes("--dry-run"),
+    };
+}
+export function collectManagePlan(operation, rawIds, homeDir = homedir()) {
+    const current = stableAgents(loadCanonicalSource(homeDir).managedAgents);
+    if (operation === "list") {
+        return { plan: { operation, current, desired: current, added: [], removed: [], changed: false } };
+    }
+    const parsed = parseAgentList(rawIds, operation === "set");
+    if ("error" in parsed)
+        return parsed;
+    const requested = new Set(parsed.agents);
+    const desired = operation === "set"
+        ? stableAgents(requested)
+        : operation === "add"
+            ? stableAgents([...current, ...requested])
+            : stableAgents(current.filter((id) => !requested.has(id)));
+    const currentSet = new Set(current);
+    const desiredSet = new Set(desired);
+    const added = desired.filter((id) => !currentSet.has(id));
+    const removed = current.filter((id) => !desiredSet.has(id));
+    return {
+        plan: {
+            operation,
+            current,
+            desired,
+            added,
+            removed,
+            changed: added.length > 0 || removed.length > 0,
+        },
+    };
+}
+export function applyManagePlan(plan, homeDir = homedir()) {
+    if (!plan.changed || plan.operation === "list")
+        return;
+    const session = openBackupSession(homeDir, `manage-${plan.operation}`);
+    session.writeFile(join(homeDir, ".trellis", "managed.yaml"), `agents: [${plan.desired.join(", ")}]\n`);
+    session.finalize();
+}
+function displayAgents(agents) {
+    return agents.length > 0 ? agents.join(", ") : "(none)";
+}
+export function runManage(parsed, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectManagePlan(parsed.operation, parsed.ids, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if ("error" in result) {
+        console.error(result.error);
+        return { exitCode: 1 };
+    }
+    const { plan } = result;
+    if (!parsed.dryRun)
+        applyManagePlan(plan, homeDir);
+    if (parsed.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else if (parsed.operation === "list") {
+        console.log(`managed agents: ${displayAgents(plan.current)}`);
+    }
+    else {
+        console.log(`${parsed.dryRun ? "[dry run] " : ""}managed agents: ${displayAgents(plan.current)} -> ${displayAgents(plan.desired)}`);
+        if (!plan.changed)
+            console.log("  no change");
+        if (plan.added.length > 0)
+            console.log(`  added: ${plan.added.join(", ")}`);
+        if (plan.removed.length > 0)
+            console.log(`  detached: ${plan.removed.join(", ")} (native state preserved)`);
+    }
+    return { exitCode: 0, plan };
+}

package/dist/commands/mcp.d.ts

@@ -5,14 +5,16 @@
  * gated — remove), and reports what happened. Kept as a separate
  * command from bare `trellis sync` (skills/instructions) since the two
  * have different write mechanisms entirely, not because MCP removal is
- * unsafe (see `src/lib/mcpOwnership.ts`). `list`/`add`/`remove`
- * (trellis-canonical-cli-crud) are canonical-side only — an alternative
- * to hand-editing `~/.trellis/mcp/servers.yaml`, never touching any
- * agent's native config (that stays `sync`'s job).
+ * unsafe (see `src/lib/mcpOwnership.ts`). `add`/`remove` mutate the
+ * canonical source and then run the same sync `mcp sync` performs, so
+ * one command both edits the list and maps it onto the managed agents
+ * (removal propagates through the ownership ledger). `list` is
+ * read-only. All three are an alternative to hand-editing
+ * `~/.trellis/mcp/servers.yaml`.
  */
 import { type ServersYamlWriteResult } from "../core/canonical.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
-import type { AgentId, McpServerDef, Transport } from "../core/types.js";
+import type { AgentId, McpAuthMode, McpConfig, McpServerDef, Transport } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
 export interface RunMcpSyncOptions {
     json?: boolean;
@@ -24,6 +26,9 @@ export interface RunMcpSyncOptions {
     /** Onboard-only seam — see RunSyncOptions.managedAgents. Never a CLI
      * flag. */
     managedAgents?: readonly AgentId[];
+    /** Onboard-only canonical MCP override used to preview a route selection
+     * before writing it to servers.yaml. */
+    mcp?: McpConfig;
     /** Onboard-only seam — see RunSyncOptions.backupSession. Never a CLI
      * flag. */
     backupSession?: BackupSession;
@@ -47,6 +52,7 @@ export declare function printReport(report: McpSyncReport, dryRun: boolean): voi
 export interface McpListEntry {
     name: string;
     transport: Transport;
+    auth?: McpAuthMode;
     enabled: boolean;
     agents: readonly AgentId[];
     command?: string;
@@ -75,6 +81,7 @@ export declare function runMcpList(opts?: {
  * command's own inline flag parsing in src/cli.ts. */
 export interface McpAddRawArgs {
     transport?: string;
+    auth?: string;
     command?: string;
     /** Comma-separated. */
     args?: string;
@@ -107,29 +114,85 @@ export interface McpAddPlan {
  * always refuses, ever (design.md D4).
  */
 export declare function collectMcpAddPlan(name: string | undefined, raw: McpAddRawArgs, homeDir?: string): McpAddPlan;
-export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string): ServersYamlWriteResult;
-export declare function runMcpAdd(name: string | undefined, raw: McpAddRawArgs, opts?: {
+export type McpSetAuthAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface McpSetAuthPlan {
+    name: string;
+    auth: "oauth" | "none";
+    action: McpSetAuthAction;
+    detail: string;
+    def?: McpServerDef;
+}
+export declare function collectMcpSetAuthPlan(name: string | undefined, auth: string | undefined, homeDir?: string): McpSetAuthPlan;
+export declare function runMcpSetAuth(name: string | undefined, auth: string | undefined, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
 }): {
     exitCode: number;
 };
+export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string, backup?: BackupSession): ServersYamlWriteResult;
+export interface McpAddOutcome {
+    plan: McpAddPlan;
+    writeError?: string;
+    sync?: McpSyncReport;
+}
+/**
+ * The apply-and-cascade-sync orchestration `runMcpAdd` used to do inline
+ * and only expose via a console.log'd payload — split out so a
+ * non-CLI caller (trellis-gui's sidecar) can get the same structured
+ * result a JSON-mode CLI run prints, without scraping stdout or
+ * re-deriving the same sequencing itself (trellis-gui design.md
+ * Decision 1). Behavior-preserving: `runMcpAdd` below is now a thin
+ * wrapper over this plus its own printing, same as every other command
+ * in this file already splits compute from CLI I/O.
+ *
+ * Opens its own backup session around the direct `servers.yaml` write
+ * when the caller doesn't already have one open — this canonical write
+ * used to be the one path in this file that bypassed backup/rollback
+ * entirely (trellis-gui tasks.md 3.5 found this empirically: a real `mcp
+ * add` left zero trace in `trellis rollback --list`). Mirrors the
+ * `ownSession` pattern `collectMcpSyncReport` below already uses for
+ * exactly the same reason.
+ */
+export declare function applyMcpAddWithSync(plan: McpAddPlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpAddOutcome>;
+export declare function runMcpAdd(name: string | undefined, raw: McpAddRawArgs, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;
 export type McpRemoveAction = "removed" | "not-found";
 export interface McpRemovePlan {
     name: string;
     action: McpRemoveAction;
 }
-/** Canonical-side only — never touches an agent's native config. Making
- * an already-synced agent forget it is `mcp sync`'s own removal-
- * propagation gap, tracked separately (roadmap.md P14), not this
- * command's job. */
+/** Canonical plan only — `runMcpRemove` follows a real removal with the
+ * same sync `mcp sync` performs, which propagates the deletion to every
+ * agent whose entry the ownership ledger proves Trellis wrote
+ * (trellis-mcp-lifecycle-parity, roadmap P14). */
 export declare function collectMcpRemovePlan(name: string, homeDir?: string): McpRemovePlan;
-export declare function applyMcpRemovePlan(plan: McpRemovePlan, homeDir?: string): ServersYamlWriteResult;
+export declare function applyMcpRemovePlan(plan: McpRemovePlan, homeDir?: string, backup?: BackupSession): ServersYamlWriteResult;
+export interface McpRemoveOutcome {
+    plan: McpRemovePlan;
+    writeError?: string;
+    sync?: McpSyncReport;
+}
+/** See `applyMcpAddWithSync`'s doc comment — same split, same reason, same
+ * own-backup-session fix. */
+export declare function applyMcpRemoveWithSync(plan: McpRemovePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpRemoveOutcome>;
 export declare function runMcpRemove(name: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;

package/dist/commands/mcp.js

@@ -5,12 +5,15 @@
  * gated — remove), and reports what happened. Kept as a separate
  * command from bare `trellis sync` (skills/instructions) since the two
  * have different write mechanisms entirely, not because MCP removal is
- * unsafe (see `src/lib/mcpOwnership.ts`). `list`/`add`/`remove`
- * (trellis-canonical-cli-crud) are canonical-side only — an alternative
- * to hand-editing `~/.trellis/mcp/servers.yaml`, never touching any
- * agent's native config (that stays `sync`'s job).
+ * unsafe (see `src/lib/mcpOwnership.ts`). `add`/`remove` mutate the
+ * canonical source and then run the same sync `mcp sync` performs, so
+ * one command both edits the list and maps it onto the managed agents
+ * (removal propagates through the ownership ledger). `list` is
+ * read-only. All three are an alternative to hand-editing
+ * `~/.trellis/mcp/servers.yaml`.
  */
 import { homedir } from "node:os";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { loadCanonicalSource, upsertServerYaml, removeServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS, resolveScope } from "../core/types.js";
@@ -18,12 +21,16 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
+import { KimiCodeAdapter } from "../adapters/kimi-code.js";
+import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
+    "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
+    zcode: (homeDir) => new ZcodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — see src/commands/sync.ts's
  * own copy of this same restriction (trellis-managed-agents). */
@@ -33,7 +40,11 @@ function buildAdapters(homeDir, managedAgents) {
 export async function collectMcpSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     const loaded = loadCanonicalSource(homeDir);
-    const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
+    const canonical = {
+        ...loaded,
+        ...(opts.managedAgents ? { managedAgents: opts.managedAgents } : {}),
+        ...(opts.mcp ? { mcp: opts.mcp } : {}),
+    };
     const reports = [];
     const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
@@ -107,6 +118,7 @@ export function collectMcpListPlan(homeDir = homedir()) {
     return Object.entries(canonical.mcp.servers).map(([name, def]) => ({
         name,
         transport: def.transport,
+        auth: def.auth,
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -136,7 +148,7 @@ export function runMcpList(opts = {}) {
     else {
         for (const e of entries) {
             const scope = e.agents.length > 0 ? e.agents.join(", ") : "(no managed agent reaches it)";
-            console.log(`${e.name} (${e.transport})${e.enabled ? "" : " [disabled]"} — ${scope}`);
+            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
             if (e.env && e.env.length > 0)
                 console.log(`   env: ${e.env.join(", ")} (values never read/printed)`);
             if (e.staticEnv)
@@ -152,6 +164,7 @@ export function parseMcpAddArgs(argv) {
     };
     return {
         transport: flag("--transport"),
+        auth: flag("--auth"),
         command: flag("--command"),
         args: flag("--args"),
         url: flag("--url"),
@@ -202,6 +215,12 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     if ((transport === "http" || transport === "sse") && !raw.url) {
         return { name, action: "invalid-input", detail: `--transport ${transport} requires --url` };
     }
+    if (raw.auth !== undefined && raw.auth !== "oauth") {
+        return { name, action: "invalid-input", detail: `--auth must be "oauth" when provided (got ${raw.auth})` };
+    }
+    if (raw.auth === "oauth" && transport === "stdio") {
+        return { name, action: "invalid-input", detail: "--auth oauth requires an http or sse MCP server" };
+    }
     const agentsList = parseCsv(raw.agents);
     if (agentsList) {
         for (const id of agentsList) {
@@ -215,6 +234,7 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     }
     const def = {
         transport,
+        ...(raw.auth === "oauth" ? { auth: "oauth" } : {}),
         ...(raw.command ? { command: raw.command } : {}),
         ...(parseCsv(raw.args) ? { args: parseCsv(raw.args) } : {}),
         ...(raw.url ? { url: raw.url } : {}),
@@ -234,52 +254,164 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     }
     return { name, action: "create", detail: "will add to servers.yaml", def };
 }
-export function applyMcpAddPlan(plan, homeDir = homedir()) {
-    if (plan.action !== "create" || !plan.def)
-        return { ok: true };
-    return upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def);
+export function collectMcpSetAuthPlan(name, auth, homeDir = homedir()) {
+    const mode = auth === "oauth" || auth === "none" ? auth : undefined;
+    if (!name)
+        return { name: "(none)", auth: (mode ?? "none"), action: "invalid-input", detail: "usage: trellis mcp set <name> --auth oauth|none" };
+    if (!mode)
+        return { name, auth: "none", action: "invalid-input", detail: `--auth must be "oauth" or "none" (got ${auth ?? "(missing)"})` };
+    const canonical = loadCanonicalSource(homeDir);
+    const current = canonical.mcp.servers[name];
+    if (!current)
+        return { name, auth: mode, action: "not-found", detail: `no canonical MCP server named "${name}"` };
+    if (mode === "oauth" && !current.url) {
+        return { name, auth: mode, action: "invalid-input", detail: "auth: oauth requires an http or sse MCP server" };
+    }
+    const next = mode === "oauth" ? { ...current, auth: "oauth" } : (() => {
+        const { auth: _auth, ...withoutAuth } = current;
+        return withoutAuth;
+    })();
+    if (JSON.stringify(current) === JSON.stringify(next))
+        return { name, auth: mode, action: "already-set", detail: `auth is already ${mode}`, def: next };
+    return { name, auth: mode, action: "updated", detail: `set auth to ${mode}`, def: next };
 }
-export function runMcpAdd(name, raw, opts = {}) {
+export function runMcpSetAuth(name, auth, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     let plan;
     try {
-        plan = collectMcpAddPlan(name, raw, homeDir);
+        plan = collectMcpSetAuthPlan(name, auth, homeDir);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
         return { exitCode: 1 };
     }
     let writeError;
-    if (!opts.dryRun && plan.action === "create") {
-        const result = applyMcpAddPlan(plan, homeDir);
+    if (!opts.dryRun && plan.action === "updated" && plan.def) {
+        const result = upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def);
         if (!result.ok)
             writeError = result.error;
     }
     if (opts.json) {
         console.log(JSON.stringify(writeError ? { ...plan, writeError } : plan, null, 2));
     }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}mcp set ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+    }
+    return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
+}
+export function applyMcpAddPlan(plan, homeDir = homedir(), backup) {
+    if (plan.action !== "create" || !plan.def)
+        return { ok: true };
+    return upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def, backup);
+}
+/**
+ * The apply-and-cascade-sync orchestration `runMcpAdd` used to do inline
+ * and only expose via a console.log'd payload — split out so a
+ * non-CLI caller (trellis-gui's sidecar) can get the same structured
+ * result a JSON-mode CLI run prints, without scraping stdout or
+ * re-deriving the same sequencing itself (trellis-gui design.md
+ * Decision 1). Behavior-preserving: `runMcpAdd` below is now a thin
+ * wrapper over this plus its own printing, same as every other command
+ * in this file already splits compute from CLI I/O.
+ *
+ * Opens its own backup session around the direct `servers.yaml` write
+ * when the caller doesn't already have one open — this canonical write
+ * used to be the one path in this file that bypassed backup/rollback
+ * entirely (trellis-gui tasks.md 3.5 found this empirically: a real `mcp
+ * add` left zero trace in `trellis rollback --list`). Mirrors the
+ * `ownSession` pattern `collectMcpSyncReport` below already uses for
+ * exactly the same reason.
+ */
+export async function applyMcpAddWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "mcp-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "create") {
+        const result = applyMcpAddPlan(plan, homeDir, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    const planFailed = plan.action === "conflict" || plan.action === "invalid-input" || Boolean(writeError);
+    let syncReport;
+    if (!planFailed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runMcpAdd(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let plan;
+    try {
+        plan = collectMcpAddPlan(name, raw, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    let outcome;
+    try {
+        outcome = await applyMcpAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const { writeError, sync: syncReport } = outcome;
+    if (opts.json) {
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
+    }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}mcp add ${plan.name}`);
         console.log(`  [${plan.action}] ${plan.detail}`);
         if (writeError)
             console.error(`  write failed: ${writeError}`);
+        if (syncReport)
+            printReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "conflict" || plan.action === "invalid-input" || writeError ? 1 : 0 };
+    const planFailed = plan.action === "conflict" || plan.action === "invalid-input" || Boolean(writeError);
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: planFailed || syncConflict ? 1 : 0 };
 }
-/** Canonical-side only — never touches an agent's native config. Making
- * an already-synced agent forget it is `mcp sync`'s own removal-
- * propagation gap, tracked separately (roadmap.md P14), not this
- * command's job. */
+/** Canonical plan only — `runMcpRemove` follows a real removal with the
+ * same sync `mcp sync` performs, which propagates the deletion to every
+ * agent whose entry the ownership ledger proves Trellis wrote
+ * (trellis-mcp-lifecycle-parity, roadmap P14). */
 export function collectMcpRemovePlan(name, homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
     return { name, action: canonical.mcp.servers[name] ? "removed" : "not-found" };
 }
-export function applyMcpRemovePlan(plan, homeDir = homedir()) {
+export function applyMcpRemovePlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "removed")
         return { ok: true };
-    return removeServerYaml(serversYamlPath(homeDir), plan.name);
+    return removeServerYaml(serversYamlPath(homeDir), plan.name, backup);
+}
+/** See `applyMcpAddWithSync`'s doc comment — same split, same reason, same
+ * own-backup-session fix. */
+export async function applyMcpRemoveWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "removed" ? openBackupSession(homeDir, "mcp-remove") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "removed") {
+        const result = applyMcpRemovePlan(plan, homeDir, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    const planFailed = plan.action === "not-found" || Boolean(writeError);
+    let syncReport;
+    if (!planFailed && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
 }
-export function runMcpRemove(name, opts = {}) {
+export async function runMcpRemove(name, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     let plan;
     try {
@@ -289,14 +421,19 @@ export function runMcpRemove(name, opts = {}) {
         console.error(err instanceof Error ? err.message : String(err));
         return { exitCode: 1 };
     }
-    let writeError;
-    if (!opts.dryRun && plan.action === "removed") {
-        const result = applyMcpRemovePlan(plan, homeDir);
-        if (!result.ok)
-            writeError = result.error;
+    let outcome;
+    try {
+        outcome = await applyMcpRemoveWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
     }
+    const { writeError, sync: syncReport } = outcome;
+    const planFailed = plan.action === "not-found" || Boolean(writeError);
     if (opts.json) {
-        console.log(JSON.stringify(writeError ? { ...plan, writeError } : plan, null, 2));
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
     }
     else if (plan.action === "not-found") {
         console.error(`"${name}" is not a canonical MCP server — nothing to remove.`);
@@ -306,6 +443,9 @@ export function runMcpRemove(name, opts = {}) {
     }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}removed MCP server "${name}" from canonical source.`);
+        if (syncReport)
+            printReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "not-found" || writeError ? 1 : 0 };
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: planFailed || syncConflict ? 1 : 0 };
 }

package/dist/commands/mcpGateway.d.ts

@@ -51,3 +51,9 @@ export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pic
 export declare function runMcpGateway(opts: RunMcpGatewayOptions): Promise<{
     exitCode: number;
 }>;
+/** The first-class runtime entrypoint. mcp-gateway remains a compatibility
+ * alias for existing native agent config, but both edges use the same
+ * provider registry and backend construction path. */
+export declare function runMcpRuntime(opts: RunMcpGatewayOptions): Promise<{
+    exitCode: number;
+}>;