agent-trellis 0.8.0 → 0.9.0

package/dist/cli.js

@@ -16,12 +16,13 @@ import { runMcpAuth } from "./commands/mcpAuth.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
 import { runSkillList, runSkillAdd, runSkillRemove, runSkillUpdateBuiltin } from "./commands/skill.js";
-import { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
+import { runRemoteSkillAdd, runRemoteSkillList, runRemoteSkillUpdate } from "./commands/remoteSkill.js";
+import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseManageArgs, runManage } from "./commands/manage.js";
 import { runKimi } from "./commands/kimi.js";
 import { TRELLIS_VERSION } from "./lib/cliMetadata.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "memory", "manage", "kimi", "secrets", "rollback"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "add", "update", "memory", "manage", "kimi", "secrets", "rollback"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
@@ -90,6 +91,22 @@ Commands:
             Distribute skills/instructions to each agent (omit target for both)
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
+  add <github-source> --skill <name>
+            Import one GitHub-hosted Skill into ~/.trellis/skills/, record
+            immutable provenance, then sync it only to managed Agents.
+              --skill, -s <name>       required unless --list
+              --branch <ref>           Git branch, tag, or ref; default is
+                                       the source repository's default branch
+              --agent, -a <ids|*>      restrict delivery to managed Agent ids
+              --list                   show discovered Skills without import
+              --global, --yes          accepted skills-CLI compatibility flags
+              --dry-run                fetch and preview; write nothing
+              --json                   machine-readable output
+  update [skills...]
+            Safely refresh remotely tracked Skills. Refuses to overwrite a
+            canonical Skill edited since its recorded import.
+              --dry-run    preview writes only
+              --json       machine-readable output
   mcp sync  Distribute MCP servers to each agent's native config
               (create/repair, plus ownership-ledger-gated removal — an
               entry is only ever removed when it's still exactly what
@@ -130,8 +147,9 @@ Commands:
             upstream capabilities; existing mcp-gateway configs remain valid
             as a compatibility alias
   mcp remove <name>
-            Remove a canonical MCP server (canonical-side only — does
-              not touch any agent's already-synced native config)
+            Remove a canonical MCP server, then run the same sync as
+            mcp sync so every managed agent's Trellis-owned entry for
+            it is removed too
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
@@ -202,6 +220,31 @@ See docs/roadmap.md for what's built vs. planned.`);
 function printVersion() {
     console.log(TRELLIS_VERSION);
 }
+function remoteOptionValues(args, flags) {
+    const values = [];
+    const positions = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const matching = flags.find((flag) => arg === flag || arg.startsWith(`${flag}=`));
+        if (!matching)
+            continue;
+        positions.add(index);
+        if (arg.startsWith(`${matching}=`)) {
+            values.push(arg.slice(matching.length + 1));
+            continue;
+        }
+        const value = args[index + 1];
+        if (!value || value.startsWith("-"))
+            return { values, positions, error: `${matching} needs a value` };
+        positions.add(index + 1);
+        values.push(value);
+        index += 1;
+    }
+    return { values, positions };
+}
+function remotePositionals(args, consumed) {
+    return args.filter((arg, index) => !consumed.has(index) && !arg.startsWith("-"));
+}
 async function main(argv) {
     const [command, ...rest] = argv;
     if (!command || command === "--help" || command === "-h") {
@@ -310,6 +353,57 @@ async function main(argv) {
         process.exitCode = exitCode;
         return;
     }
+    if (command === "add") {
+        const skill = remoteOptionValues(rest, ["--skill", "-s"]);
+        const branch = remoteOptionValues(rest, ["--branch"]);
+        const agents = remoteOptionValues(rest, ["--agent", "-a"]);
+        const consumed = new Set([...skill.positions, ...branch.positions, ...agents.positions]);
+        const positionals = remotePositionals(rest, consumed);
+        const json = rest.includes("--json");
+        const prohibited = rest.find((arg) => /^(--copy|--project|--local)(?:=|$)/.test(arg));
+        if (prohibited) {
+            const detail = "Trellis remote Skills are always imported into ~/.trellis/skills; --copy and project-local installation are not supported.";
+            if (json)
+                console.log(JSON.stringify({ action: "invalid-options", detail }, null, 2));
+            else
+                console.error(detail);
+            process.exitCode = 1;
+            return;
+        }
+        if (skill.error || branch.error || agents.error || positionals.length !== 1) {
+            const detail = skill.error ?? branch.error ?? agents.error ?? "Usage: trellis add <github-source> --skill <name>";
+            if (json)
+                console.log(JSON.stringify({ action: "invalid-options", detail }, null, 2));
+            else
+                console.error(detail);
+            process.exitCode = 1;
+            return;
+        }
+        const source = positionals[0];
+        if (rest.includes("--list")) {
+            process.exitCode = (await runRemoteSkillList(source, { branch: branch.values[0], json })).exitCode;
+            return;
+        }
+        if (skill.values.length !== 1 || branch.values.length > 1) {
+            const detail = skill.values.length !== 1 ? "Use exactly one --skill value" : "Use at most one --branch value";
+            if (json)
+                console.log(JSON.stringify({ action: "invalid-options", detail }, null, 2));
+            else
+                console.error(detail);
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = (await runRemoteSkillAdd(source, skill.values[0], {
+            branch: branch.values[0], agents: agents.values, dryRun: rest.includes("--dry-run"), json,
+        })).exitCode;
+        return;
+    }
+    if (command === "update") {
+        const json = rest.includes("--json");
+        const names = rest.filter((arg) => !arg.startsWith("-"));
+        process.exitCode = (await runRemoteSkillUpdate(names, { dryRun: rest.includes("--dry-run"), json })).exitCode;
+        return;
+    }
     if (command === "mcp") {
         const [subcommand, ...mcpRest] = rest;
         const json = mcpRest.includes("--json");
@@ -325,12 +419,12 @@ async function main(argv) {
         }
         if (subcommand === "add") {
             const [name] = mcpRest;
-            process.exitCode = runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "import") {
             const [file] = mcpRest;
-            process.exitCode = runMcpImport(file, { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpImport(file, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "set") {
@@ -347,7 +441,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runMcpRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runMcpRemove(name, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "auth") {
@@ -382,7 +476,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillAdd(name, from, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "remove") {
@@ -392,7 +486,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = runSkillRemove(name, { json, dryRun }).exitCode;
+            process.exitCode = (await runSkillRemove(name, { json, dryRun })).exitCode;
             return;
         }
         if (subcommand === "update-builtin") {
@@ -407,6 +501,21 @@ async function main(argv) {
         const [subcommand, ...memoryRest] = rest;
         const json = memoryRest.includes("--json");
         const dryRun = memoryRest.includes("--dry-run");
+        if (subcommand === "list") {
+            const entries = collectMemoryList();
+            if (json) {
+                console.log(JSON.stringify(entries, null, 2));
+            }
+            else if (entries.length === 0) {
+                console.log("No memories in canonical source yet.");
+            }
+            else {
+                for (const { name, scope } of entries) {
+                    console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+                }
+            }
+            return;
+        }
         if (subcommand === "sync") {
             process.exitCode = runMemorySync({ json, dryRun }).exitCode;
             return;
@@ -415,7 +524,7 @@ async function main(argv) {
             process.exitCode = runMemoryExtraction({ json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync|extract\n`);
+        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory list|sync|extract\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/doctor.js

@@ -10,6 +10,7 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { ALL_AGENTS } from "../core/types.js";
@@ -76,6 +77,7 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         { agent: "kiro", run: () => kiroProbe.probe(homeDir, { probeMcp }) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
         { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir, { probeMcp }) },
+        { agent: "zcode", run: () => zcodeProbe.probe(homeDir, { probeMcp }) },
     ];
     // One agent erroring must not blank the other three's results.
     const settled = await Promise.allSettled(probeList.map((p) => p.run()));

package/dist/commands/init.d.ts

@@ -29,7 +29,7 @@ export interface InitReport {
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
  * retyping an equivalent one that could silently drift from this. */
-export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, or Kimi Code? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
+export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
 /**
  * Trellis never spawns an installer itself (global package installs are
  * exactly the kind of irreversible, system-wide action that needs the

package/dist/commands/init.js

@@ -16,6 +16,7 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 import { ALL_AGENTS } from "../core/types.js";
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
@@ -25,7 +26,7 @@ export const AGENTS_MD_TEMPLATE = `# Shared instructions
 Write what every agent should know here — communication preferences,
 project conventions, anything you'd otherwise repeat per agent.
 
-Already using Claude Code, Codex, Kiro, pi, or Kimi Code? \`trellis migrate --from
+Already using Claude Code, Codex, Kiro, pi, Kimi Code, or ZCode? \`trellis migrate --from
 <agent>\` imports its real instructions and skills instead of starting
 from this placeholder.
 `;
@@ -95,6 +96,7 @@ export const INSTALL_HINTS = {
     kiro: "https://kiro.dev/downloads/",
     pi: "npm install -g @earendil-works/pi-coding-agent",
     "kimi-code": "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
+    zcode: "https://zcode.z.ai/en/docs/install",
 };
 function ensureFile(path, template, write = true) {
     if (existsSync(path)) {
@@ -132,6 +134,7 @@ export async function collectInitReport(homeDir = homedir(), options = {}) {
         { agent: "kiro", run: () => kiroProbe.probe(homeDir) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
         { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir) },
+        { agent: "zcode", run: () => zcodeProbe.probe(homeDir) },
     ];
     const settled = await Promise.allSettled(probes.map((p) => p.run()));
     const agents = settled.map((result, index) => {

package/dist/commands/mcp.d.ts

@@ -5,10 +5,12 @@
  * 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";
@@ -128,29 +130,69 @@ export declare function runMcpSetAuth(name: string | undefined, auth: string | u
 }): {
     exitCode: number;
 };
-export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string): ServersYamlWriteResult;
+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";
@@ -19,6 +22,7 @@ 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),
@@ -26,6 +30,7 @@ const ADAPTER_FACTORY = {
     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). */
@@ -297,12 +302,48 @@ export function runMcpSetAuth(name, auth, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
-export function applyMcpAddPlan(plan, homeDir = homedir()) {
+export function applyMcpAddPlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "create" || !plan.def)
         return { ok: true };
-    return upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def);
+    return upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def, backup);
 }
-export function runMcpAdd(name, raw, opts = {}) {
+/**
+ * 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 {
@@ -312,37 +353,65 @@ export function runMcpAdd(name, raw, opts = {}) {
         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 (!result.ok)
-            writeError = result.error;
+    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) {
-        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 {
         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 {
@@ -352,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.`);
@@ -369,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.js

@@ -24,6 +24,7 @@ import { BuiltinRegistry, createRuntimeServer, UpstreamProvider } from "../lib/m
 import { McpStatusProvider } from "../lib/mcpStatusProvider.js";
 import { RuntimeControlProvider } from "../lib/runtimeControlProvider.js";
 import { TaskProvider } from "../lib/taskProvider.js";
+import { AgentBridgeProvider } from "../lib/agentBridgeProvider.js";
 import { RuntimeMemoryProvider } from "../lib/memoryProvider.js";
 import { SkillProvider } from "../lib/skillProvider.js";
 import { ALL_AGENTS } from "../core/types.js";
@@ -121,7 +122,7 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
             // process has no terminal to run one in (design.md D9).
             homeDir,
         });
-    const registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend), new TaskProvider(), new UpstreamProvider(backend)]);
+    const registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend), new TaskProvider(), new AgentBridgeProvider(), new UpstreamProvider(backend)]);
     const server = createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/commands/mcpImport.d.ts

@@ -6,6 +6,7 @@
  * read-only; plans never carry secret values.
  */
 import { type BackupSession } from "../lib/backup.js";
+import type { McpSyncReport } from "./mcp.js";
 export type McpImportAction = "create" | "already-present" | "duplicate" | "skipped" | "conflict" | "invalid-input";
 export interface McpImportItem {
     name: string;
@@ -18,10 +19,28 @@ export interface McpImportPlan {
 }
 export declare function collectMcpImportPlan(path: string, homeDir?: string): McpImportPlan;
 export declare function applyMcpImportPlan(path: string, homeDir?: string, backup?: BackupSession): McpImportPlan;
+export interface McpImportOutcome {
+    plan: McpImportPlan;
+    sync?: McpSyncReport;
+}
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller (trellis-gui's sidecar) gets the same
+ * structured result a JSON-mode CLI run prints, without scraping
+ * stdout or re-deriving the plan-then-apply-then-cascade-sync
+ * sequencing itself. Unlike `mcp add`/`mcp remove`, `applyMcpImportPlan`
+ * already opens its own backup session unconditionally (it always has,
+ * per design.md's original survey of `openBackupSession` call sites) —
+ * no tasks.md 3.5-style fix needed here.
+ */
+export declare function applyMcpImportWithSync(path: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+}): Promise<McpImportOutcome>;
 export declare function runMcpImport(path: string | undefined, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;