agent-trellis 0.14.1 → 0.15.1

package/dist/commands/mcp.d.ts

@@ -33,14 +33,23 @@ export interface RunMcpSyncOptions {
     /** Onboard-only seam — see RunSyncOptions.backupSession. Never a CLI
      * flag. */
     backupSession?: BackupSession;
+    /** Force global-only behavior even inside a workspace (`--global-only`). */
+    globalOnly?: boolean;
+    /** Explicit workspace root — the test/sandbox seam (see RunSyncOptions). */
+    workspaceDir?: string | null;
+    /** `--check`: plan only, write nothing, exit non-zero on any stale or
+     * missing rendered artifact (trellis-workspace-scope design D7). */
+    check?: boolean;
 }
 export interface AgentMcpSyncReport {
     agent: AgentId;
     present: boolean;
     items: AdapterPlanItem[];
+    warnings?: string[];
 }
 export interface McpSyncReport {
     reports: AgentMcpSyncReport[];
+    workspaceRoot?: string;
 }
 export declare function collectMcpSyncReport(opts?: RunMcpSyncOptions): Promise<McpSyncReport>;
 export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
@@ -49,7 +58,7 @@ export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
 /** Exported so `onboard` prints an mcp-sync report identically to running
  * `mcp sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export declare function printReport(report: McpSyncReport, dryRun: boolean): void;
+export declare function printReport(report: McpSyncReport, dryRun: boolean, check?: boolean): void;
 export interface McpListEntry {
     name: string;
     transport: Transport;
@@ -111,8 +120,9 @@ export declare function runMcpList(opts?: {
 };
 /** Raw, unvalidated CLI flag values — `collectMcpAddPlan` does the actual
  * parsing/validation. Kept as plain strings here so `parseMcpAddArgs`
- * stays a dumb `--flag value` reader, same posture as every other
- * command's own inline flag parsing in src/cli.ts. */
+ * stays a dumb `--flag value` reader. Both `--flag value` and
+ * `--flag=value` are accepted (see src/lib/cliArgs.ts — the `=` form used
+ * to be silently dropped). */
 export interface McpAddRawArgs {
     transport?: string;
     auth?: string;
@@ -130,6 +140,9 @@ export interface McpAddRawArgs {
     agents?: string;
     /** `"true"` or `"false"`. */
     enabled?: string;
+    /** `--*` tokens no flag claimed (typos, wrong command); `runMcpAdd`
+     * warns about them instead of letting them vanish silently. */
+    unknown?: string[];
 }
 export declare function parseMcpAddArgs(argv: readonly string[]): McpAddRawArgs;
 export declare function parseMcpSetArgs(argv: readonly string[]): McpSetAuthRawArgs;
@@ -147,8 +160,30 @@ export interface McpAddPlan {
  * write failure — design.md's open question, resolved in favor of
  * refusing early with a specific reason. No `--force`: an existing name
  * always refuses, ever (design.md D4).
+ *
+ * Split into two steps so `mcp add --workspace` reuses the identical
+ * flag validation/def construction and only swaps which file's existing
+ * entries it conflicts against (trellis-workspace-scope task 3.4):
+ * `buildMcpAddDef` is the pure part, `collectMcpAddPlan` adds the
+ * global-canonical existence check.
  */
+export declare function buildMcpAddDef(name: string | undefined, raw: McpAddRawArgs): {
+    ok: true;
+    name: string;
+    def: McpServerDef;
+} | {
+    ok: false;
+    plan: McpAddPlan;
+};
 export declare function collectMcpAddPlan(name: string | undefined, raw: McpAddRawArgs, homeDir?: string): McpAddPlan;
+/** The workspace twin of `collectMcpAddPlan` (trellis-workspace-scope
+ * task 3.4): identical validation, but the existence check runs against
+ * `.agents/config.json` — compared through the same snake_case
+ * serialization the file stores, so a re-add of the same definition is
+ * a clean "already-present" no-op. A global same-name entry is NOT a
+ * conflict here (workspace shadowing a global entry is a legal,
+ * documented merge outcome), just noted in the detail. */
+export declare function collectMcpAddWorkspacePlan(name: string | undefined, raw: McpAddRawArgs, workspaceRoot: string, homeDir?: string): McpAddPlan;
 export type McpSetAuthAction = "updated" | "already-set" | "not-found" | "invalid-input";
 export interface McpSetAuthPlan {
     name: string;
@@ -168,6 +203,8 @@ export interface McpSetAuthRawArgs {
     clientId?: string;
     /** A variable NAME, never a secret value. */
     clientSecretEnv?: string;
+    /** See `McpAddRawArgs.unknown`. */
+    unknown?: string[];
 }
 /**
  * Sets or clears the OAuth classification, and optionally the
@@ -269,10 +306,22 @@ export declare function applyMcpAddWithSync(plan: McpAddPlan, opts?: {
     dryRun?: boolean;
     backupSession?: BackupSession;
 }): Promise<McpAddOutcome>;
+/** Workspace twin of `applyMcpAddWithSync` (trellis-workspace-scope task
+ * 3.4): writes `.agents/config.json` instead of `servers.yaml`, then
+ * cascades the same mcp sync — which, run inside the workspace, renders
+ * only the project-level targets for the workspace layer (plus the usual
+ * global-layer targets; the agent does its own layering). */
+export declare function applyMcpAddWorkspaceWithSync(plan: McpAddPlan, workspaceRoot: string, 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;
+    workspace?: boolean;
+    workspaceDir?: string;
 }): Promise<{
     exitCode: number;
 }>;
@@ -299,10 +348,27 @@ export declare function applyMcpRemoveWithSync(plan: McpRemovePlan, opts?: {
     dryRun?: boolean;
     backupSession?: BackupSession;
 }): Promise<McpRemoveOutcome>;
+/** Workspace twin of `collectMcpRemovePlan`: presence is judged against
+ * `.agents/config.json` only — a global entry of the same name is this
+ * entry's shadow target, not a reason to touch the global file. */
+export declare function collectMcpRemoveWorkspacePlan(name: string, workspaceRoot: string): McpRemovePlan;
+/** Workspace twin of `applyMcpRemoveWithSync`: deletes the entry from
+ * `.agents/config.json` (backup-session wrapped), then cascades the same
+ * mcp sync — run inside the workspace, so `planWorkspaceMcp` sees the
+ * entry is gone and removes the rendered project-level copies (the
+ * ledger-gated propagation already exists; this command was the missing
+ * corner). A shadowed global entry simply takes effect again. */
+export declare function applyMcpRemoveWorkspaceWithSync(plan: McpRemovePlan, workspaceRoot: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpRemoveOutcome>;
 export declare function runMcpRemove(name: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
+    workspace?: boolean;
+    workspaceDir?: string;
 }): Promise<{
     exitCode: number;
 }>;

package/dist/commands/mcp.js

@@ -27,6 +27,11 @@ 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";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { applyWorkspaceMcp, planWorkspaceMcp, workspacePrecedenceWarnings } from "../lib/workspaceMcp.js";
+import { readWorkspaceConfigJson, removeWorkspaceServer, upsertWorkspaceServer } from "../lib/workspaceConfig.js";
+import { toServerDefYaml } from "../core/mcpServerDef.js";
+import { flagValue, unknownFlags } from "../lib/cliArgs.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
@@ -42,14 +47,16 @@ function buildAdapters(homeDir, managedAgents) {
 }
 export async function collectMcpSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const loaded = loadCanonicalSource(homeDir);
+    const workspaceDir = opts.globalOnly ? null : (opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd()));
+    const loaded = loadCanonicalSource({ homeDir, workspaceDir });
     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 writeMode = !opts.dryRun && !opts.check;
+    const ownSession = writeMode && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
     for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
@@ -57,14 +64,17 @@ export async function collectMcpSyncReport(opts = {}) {
             reports.push({ agent: adapter.id, present: false, items: [] });
             continue;
         }
-        const items = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
-        if (!opts.dryRun) {
-            await adapter.apply(items, backup);
+        const globalItems = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
+        const wsItems = planWorkspaceMcp(adapter.id, canonical);
+        if (writeMode) {
+            await adapter.apply(globalItems, backup);
+            applyWorkspaceMcp(adapter.id, canonical, wsItems, backup);
         }
-        reports.push({ agent: adapter.id, present: true, items });
+        const warnings = workspacePrecedenceWarnings(adapter.id, canonical);
+        reports.push({ agent: adapter.id, present: true, items: [...globalItems, ...wsItems], ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports };
+    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runMcpSync(opts = {}) {
     let report;
@@ -79,22 +89,31 @@ export async function runMcpSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report, opts.dryRun ?? false);
+        printReport(report, opts.dryRun ?? false, opts.check ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    if (opts.check) {
+        const hasPending = report.reports.some((r) => r.items.some((i) => i.action !== "conflict"));
+        return { exitCode: hasPending || hasConflict ? 1 : 0 };
+    }
     return { exitCode: hasConflict ? 1 : 0 };
 }
 /** Exported so `onboard` prints an mcp-sync report identically to running
  * `mcp sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export function printReport(report, dryRun) {
+export function printReport(report, dryRun, check = false) {
     if (dryRun)
         console.log("[dry run]");
+    if (check)
+        console.log("[check]");
+    if (report.workspaceRoot) {
+        console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
+    }
     if (report.reports.length === 0) {
         console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
         return;
     }
-    for (const { agent, present, items } of report.reports) {
+    for (const { agent, present, items, warnings } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
@@ -104,18 +123,27 @@ export function printReport(report, dryRun) {
         const conflicts = items.filter((i) => i.action === "conflict");
         if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
             console.log(`✅ ${agent} — already in sync`);
-            continue;
         }
-        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
-        console.log(`${icon} ${agent} — ${created.length} created/updated, ${removed.length} removed, ${conflicts.length} conflict(s)`);
-        for (const item of [...created, ...removed, ...conflicts]) {
-            console.log(`   - [${item.action}] ${item.description}`);
+        else {
+            const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+            console.log(`${icon} ${agent} — ${created.length} created/updated, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+            for (const item of [...created, ...removed, ...conflicts]) {
+                console.log(`   - [${item.action}]${item.layer === "workspace" ? " (workspace)" : ""} ${item.description}`);
+                // Conflicts carry the actionable fix (e.g. the unmarked-overwrite
+                // guard's "run migrate --workspace or remove the entry") — printing
+                // only the description would leave the user stuck at "left untouched".
+                if (item.remediation)
+                    console.log(`     → ${item.remediation}`);
+            }
+            // pi does not watch mcp.json (verified 2026-10-11): without this hint
+            // a changed config silently only takes effect on the next pi launch
+            // (trellis-pi-native-mcp-migration design.md D5).
+            if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
+                console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+            }
         }
-        // pi does not watch mcp.json (verified 2026-10-11): without this hint
-        // a changed config silently only takes effect on the next pi launch
-        // (trellis-pi-native-mcp-migration design.md D5).
-        if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
-            console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+        for (const warning of warnings ?? []) {
+            console.log(`   ⚠ ${warning}`);
         }
     }
 }
@@ -205,34 +233,39 @@ export function runMcpList(opts = {}) {
     }
     return { exitCode: 0 };
 }
+const MCP_ADD_KNOWN_FLAGS = [
+    "--transport", "--auth", "--command", "--args", "--url", "--headers",
+    "--env", "--static-env", "--agents", "--enabled",
+    "--workspace", "--dry-run", "--json",
+];
 export function parseMcpAddArgs(argv) {
-    const flag = (name) => {
-        const i = argv.indexOf(name);
-        return i >= 0 ? argv[i + 1] : undefined;
-    };
+    const unknown = unknownFlags(argv, MCP_ADD_KNOWN_FLAGS);
     return {
-        transport: flag("--transport"),
-        auth: flag("--auth"),
-        command: flag("--command"),
-        args: flag("--args"),
-        url: flag("--url"),
-        headers: flag("--headers"),
-        env: flag("--env"),
-        staticEnv: flag("--static-env"),
-        agents: flag("--agents"),
-        enabled: flag("--enabled"),
+        transport: flagValue(argv, "--transport"),
+        auth: flagValue(argv, "--auth"),
+        command: flagValue(argv, "--command"),
+        args: flagValue(argv, "--args"),
+        url: flagValue(argv, "--url"),
+        headers: flagValue(argv, "--headers"),
+        env: flagValue(argv, "--env"),
+        staticEnv: flagValue(argv, "--static-env"),
+        agents: flagValue(argv, "--agents"),
+        enabled: flagValue(argv, "--enabled"),
+        ...(unknown.length > 0 ? { unknown } : {}),
     };
 }
+const MCP_SET_KNOWN_FLAGS = [
+    "--auth", "--client-id", "--client-secret-env", "--auth-owner",
+    "--dry-run", "--json",
+];
 export function parseMcpSetArgs(argv) {
-    const flag = (name) => {
-        const i = argv.indexOf(name);
-        return i >= 0 ? argv[i + 1] : undefined;
-    };
+    const unknown = unknownFlags(argv, MCP_SET_KNOWN_FLAGS);
     return {
-        auth: flag("--auth"),
-        clientId: flag("--client-id"),
-        clientSecretEnv: flag("--client-secret-env"),
-        authOwner: flag("--auth-owner"),
+        auth: flagValue(argv, "--auth"),
+        clientId: flagValue(argv, "--client-id"),
+        clientSecretEnv: flagValue(argv, "--client-secret-env"),
+        authOwner: flagValue(argv, "--auth-owner"),
+        ...(unknown.length > 0 ? { unknown } : {}),
     };
 }
 function parseCsv(raw) {
@@ -260,37 +293,43 @@ const TRANSPORTS = ["stdio", "http", "sse"];
  * write failure — design.md's open question, resolved in favor of
  * refusing early with a specific reason. No `--force`: an existing name
  * always refuses, ever (design.md D4).
+ *
+ * Split into two steps so `mcp add --workspace` reuses the identical
+ * flag validation/def construction and only swaps which file's existing
+ * entries it conflicts against (trellis-workspace-scope task 3.4):
+ * `buildMcpAddDef` is the pure part, `collectMcpAddPlan` adds the
+ * global-canonical existence check.
  */
-export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
+export function buildMcpAddDef(name, raw) {
     if (!name) {
-        return { name: "(none)", action: "invalid-input", detail: "a name is required: trellis mcp add <name> --transport ..." };
+        return { ok: false, plan: { name: "(none)", action: "invalid-input", detail: "a name is required: trellis mcp add <name> --transport ..." } };
     }
     if (!raw.transport || !TRANSPORTS.includes(raw.transport)) {
-        return { name, action: "invalid-input", detail: `--transport must be one of: ${TRANSPORTS.join(", ")}` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--transport must be one of: ${TRANSPORTS.join(", ")}` } };
     }
     const transport = raw.transport;
     if (transport === "stdio" && !raw.command) {
-        return { name, action: "invalid-input", detail: "--transport stdio requires --command" };
+        return { ok: false, plan: { name, action: "invalid-input", detail: "--transport stdio requires --command" } };
     }
     if ((transport === "http" || transport === "sse") && !raw.url) {
-        return { name, action: "invalid-input", detail: `--transport ${transport} requires --url` };
+        return { ok: false, plan: { 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})` };
+        return { ok: false, plan: { 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" };
+        return { ok: false, plan: { 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) {
             if (!ALL_AGENTS.includes(id)) {
-                return { name, action: "invalid-input", detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` };
+                return { ok: false, plan: { name, action: "invalid-input", detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` } };
             }
         }
     }
     if (raw.enabled !== undefined && raw.enabled !== "true" && raw.enabled !== "false") {
-        return { name, action: "invalid-input", detail: `--enabled must be "true" or "false" (got ${raw.enabled})` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--enabled must be "true" or "false" (got ${raw.enabled})` } };
     }
     const def = {
         transport,
@@ -304,15 +343,46 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
         ...(raw.enabled !== undefined ? { enabled: raw.enabled === "true" } : {}),
         ...(agentsList ? { agents: agentsList } : {}),
     };
+    return { ok: true, name, def };
+}
+export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
+    const built = buildMcpAddDef(name, raw);
+    if (!built.ok)
+        return built.plan;
+    const def = built.def;
     const canonical = loadCanonicalSource(homeDir);
-    const existing = canonical.mcp.servers[name];
+    const existing = canonical.mcp.servers[built.name];
     if (existing) {
         if (JSON.stringify(existing) === JSON.stringify(def)) {
-            return { name, action: "already-present", detail: "canonical entry is already identical" };
+            return { name: built.name, action: "already-present", detail: "canonical entry is already identical" };
         }
-        return { name, action: "conflict", detail: `servers.yaml already has "${name}" with different settings — resolve by hand (no --force, design.md D4)` };
+        return { name: built.name, action: "conflict", detail: `servers.yaml already has "${built.name}" with different settings — resolve by hand (no --force, design.md D4)` };
     }
-    return { name, action: "create", detail: "will add to servers.yaml", def };
+    return { name: built.name, action: "create", detail: "will add to servers.yaml", def };
+}
+/** The workspace twin of `collectMcpAddPlan` (trellis-workspace-scope
+ * task 3.4): identical validation, but the existence check runs against
+ * `.agents/config.json` — compared through the same snake_case
+ * serialization the file stores, so a re-add of the same definition is
+ * a clean "already-present" no-op. A global same-name entry is NOT a
+ * conflict here (workspace shadowing a global entry is a legal,
+ * documented merge outcome), just noted in the detail. */
+export function collectMcpAddWorkspacePlan(name, raw, workspaceRoot, homeDir = homedir()) {
+    const built = buildMcpAddDef(name, raw);
+    if (!built.ok)
+        return built.plan;
+    const def = built.def;
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const existing = config.mcp?.servers?.[built.name];
+    if (existing) {
+        if (JSON.stringify(existing) === JSON.stringify(toServerDefYaml(def))) {
+            return { name: built.name, action: "already-present", detail: ".agents/config.json entry is already identical" };
+        }
+        return { name: built.name, action: "conflict", detail: `.agents/config.json already has "${built.name}" with different settings — resolve by hand (no --force)` };
+    }
+    const global = loadCanonicalSource(homeDir).mcp.servers[built.name];
+    const shadowNote = global ? ` (shadows the global "${built.name}" for this project)` : "";
+    return { name: built.name, action: "create", detail: `will add to .agents/config.json${shadowNote}`, def };
 }
 /**
  * Sets or clears the OAuth classification, and optionally the
@@ -427,6 +497,7 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
 }
 export function runMcpSetAuth(name, raw, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    warnUnknownFlags("mcp set", raw.unknown);
     let plan;
     try {
         plan = collectMcpSetAuthPlan(name, raw, homeDir);
@@ -587,8 +658,64 @@ export async function applyMcpAddWithSync(plan, opts = {}) {
     }
     return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
 }
+/** Workspace twin of `applyMcpAddWithSync` (trellis-workspace-scope task
+ * 3.4): writes `.agents/config.json` instead of `servers.yaml`, then
+ * cascades the same mcp sync — which, run inside the workspace, renders
+ * only the project-level targets for the workspace layer (plus the usual
+ * global-layer targets; the agent does its own layering). */
+export async function applyMcpAddWorkspaceWithSync(plan, workspaceRoot, 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;
+    if (!opts.dryRun && plan.action === "create" && plan.def) {
+        upsertWorkspaceServer(workspaceRoot, plan.name, plan.def, session);
+    }
+    ownSession?.finalize();
+    const planFailed = plan.action === "conflict" || plan.action === "invalid-input";
+    let syncReport;
+    if (!planFailed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+/** Warn about `--*` tokens the parser didn't claim — a typo like
+ * `--tranport http` must not exit 0 in silence. */
+function warnUnknownFlags(commandLabel, unknown) {
+    if (unknown && unknown.length > 0) {
+        console.error(`warning: ${commandLabel}: unrecognized flag(s) ${unknown.map((f) => `"${f}"`).join(", ")} — ignored`);
+    }
+}
 export async function runMcpAdd(name, raw, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    warnUnknownFlags("mcp add", raw.unknown);
+    if (opts.workspace) {
+        const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
+        if (!workspaceRoot) {
+            console.error("no .agents/ found here or above — run `trellis init --workspace` first (or pass --workspace from inside the repo)");
+            return { exitCode: 1 };
+        }
+        let plan;
+        try {
+            plan = collectMcpAddWorkspacePlan(name, raw, workspaceRoot, homeDir);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return { exitCode: 1 };
+        }
+        const { sync: syncReport } = await applyMcpAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
+        const planFailed = plan.action === "conflict" || plan.action === "invalid-input";
+        if (opts.json) {
+            console.log(JSON.stringify(syncReport ? { ...plan, workspace: workspaceRoot, sync: syncReport } : { ...plan, workspace: workspaceRoot }, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}mcp add ${plan.name} --workspace`);
+            console.log(`  [${plan.action}] ${plan.detail}`);
+            if (syncReport)
+                printReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: planFailed || syncConflict ? 1 : 0 };
+    }
     let plan;
     try {
         plan = collectMcpAddPlan(name, raw, homeDir);
@@ -655,8 +782,65 @@ export async function applyMcpRemoveWithSync(plan, opts = {}) {
     }
     return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
 }
+/** Workspace twin of `collectMcpRemovePlan`: presence is judged against
+ * `.agents/config.json` only — a global entry of the same name is this
+ * entry's shadow target, not a reason to touch the global file. */
+export function collectMcpRemoveWorkspacePlan(name, workspaceRoot) {
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    return { name, action: config.mcp?.servers?.[name] ? "removed" : "not-found" };
+}
+/** Workspace twin of `applyMcpRemoveWithSync`: deletes the entry from
+ * `.agents/config.json` (backup-session wrapped), then cascades the same
+ * mcp sync — run inside the workspace, so `planWorkspaceMcp` sees the
+ * entry is gone and removes the rendered project-level copies (the
+ * ledger-gated propagation already exists; this command was the missing
+ * corner). A shadowed global entry simply takes effect again. */
+export async function applyMcpRemoveWorkspaceWithSync(plan, workspaceRoot, 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;
+    if (!opts.dryRun && plan.action === "removed") {
+        removeWorkspaceServer(workspaceRoot, plan.name, session);
+    }
+    ownSession?.finalize();
+    const planFailed = plan.action === "not-found";
+    let syncReport;
+    if (!planFailed && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
 export async function runMcpRemove(name, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    if (opts.workspace) {
+        const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
+        if (!workspaceRoot) {
+            console.error("no .agents/ found here or above — run `trellis init --workspace` first (or pass --workspace from inside the repo)");
+            return { exitCode: 1 };
+        }
+        let plan;
+        try {
+            plan = collectMcpRemoveWorkspacePlan(name, workspaceRoot);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return { exitCode: 1 };
+        }
+        const { sync: syncReport } = await applyMcpRemoveWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
+        if (opts.json) {
+            console.log(JSON.stringify(syncReport ? { ...plan, workspace: workspaceRoot, sync: syncReport } : { ...plan, workspace: workspaceRoot }, null, 2));
+        }
+        else if (plan.action === "not-found") {
+            console.error(`"${name}" is not in the workspace layer (${workspaceRoot}/.agents/config.json) — nothing to remove.`);
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}removed MCP server "${name}" from ${workspaceRoot}/.agents/config.json.`);
+            if (syncReport)
+                printReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: plan.action === "not-found" || syncConflict ? 1 : 0 };
+    }
     let plan;
     try {
         plan = collectMcpRemovePlan(name, homeDir);
@@ -680,7 +864,22 @@ export async function runMcpRemove(name, opts = {}) {
         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.`);
+        // A name that lives only in the workspace layer used to get this same
+        // blunt message (found by the v0.15.0 real-machine smoke test) —
+        // point at the flag instead of implying the entry doesn't exist.
+        let workspaceHint = "";
+        const workspaceRoot = opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd());
+        if (workspaceRoot) {
+            try {
+                if (readWorkspaceConfigJson(workspaceRoot).mcp?.servers?.[name]) {
+                    workspaceHint = ` here, but it exists in the workspace layer — re-run with --workspace to remove it from ${workspaceRoot}/.agents/config.json`;
+                }
+            }
+            catch {
+                // An unreadable workspace config must not mask the primary answer.
+            }
+        }
+        console.error(`"${name}" is not a canonical MCP server${workspaceHint} — nothing to remove.`);
     }
     else if (writeError) {
         console.error(`  write failed: ${writeError}`);

package/dist/commands/mcpGateway.js

@@ -28,16 +28,16 @@ import { AgentBridgeProvider } from "../lib/agentBridgeProvider.js";
 import { RuntimeMemoryProvider } from "../lib/memoryProvider.js";
 import { SkillProvider } from "../lib/skillProvider.js";
 import { ALL_AGENTS, isOAuthAuth } from "../core/types.js";
+import { flagValue } from "../lib/cliArgs.js";
 const CLIENT_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
 const SERVER_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
 const RUNTIME_CLIENT_INFO = { name: "trellis-mcp-runtime", version: "0.0.0" };
 const RUNTIME_SERVER_INFO = { name: "trellis-mcp-runtime", version: "0.0.0" };
 export function parseMcpGatewayArgs(argv) {
-    const index = argv.indexOf("--agent");
-    if (index === -1 || index === argv.length - 1) {
+    const value = flagValue(argv, "--agent");
+    if (value === undefined) {
         return { error: `mcp-gateway requires --agent <${ALL_AGENTS.join("|")}>` };
     }
-    const value = argv[index + 1];
     if (!ALL_AGENTS.includes(value)) {
         return { error: `unknown agent "${value}" — expected one of ${ALL_AGENTS.join(", ")}` };
     }

package/dist/commands/migrate.d.ts

@@ -7,6 +7,18 @@
 import type { AgentId, McpServerDef } from "../core/types.js";
 import type { BackupSession } from "../lib/backup.js";
 import { type NativeMemoryCandidate, type NativeMemoryDiscovery } from "../lib/nativeMemory.js";
+/** Where a `staticEnv` literal secret's real value goes when
+ * `secrets.policy.yaml` doesn't already have its own `env_file`
+ * (trellis-migrate-extract-static-env-secrets design.md D3) — a sibling
+ * of `servers.yaml`, so "the mcp stuff" stays one directory rather than
+ * a second, disconnected location. `~`-form for what gets written into
+ * `secrets.policy.yaml` itself (portable across machines); resolved form
+ * for real file I/O. */
+export declare const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+/** Exported for `migrate --workspace` (trellis-workspace-scope task 4.2) —
+ * its staticEnv extraction lands in the same default store under the same
+ * naming scheme, never a second location. */
+export declare function defaultLocalSecretsEnvFilePath(homeDir: string): string;
 export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict" | "extract-secret";
 /** Internal kind naming, unchanged since before `--only` existed
  * (trellis-migrate-category-selection design.md D2) — the CLI-facing