agent-trellis 0.15.0 → 0.16.0

package/dist/cli.js

@@ -24,6 +24,7 @@ import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./command
 import { parseManageArgs, runManage } from "./commands/manage.js";
 import { runKimi } from "./commands/kimi.js";
 import { TRELLIS_VERSION } from "./lib/cliMetadata.js";
+import { flagValue } from "./lib/cliArgs.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
 const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "mcp-runtime", "skill", "add", "update", "memory", "manage", "kimi", "secrets", "rollback"];
 function printUsage() {
@@ -193,6 +194,9 @@ Commands:
             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
+              --workspace  remove from .agents/config.json instead of
+                           servers.yaml (a shadowed global entry takes
+                           effect again, it is not deleted)
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
@@ -325,31 +329,15 @@ async function main(argv) {
         return;
     }
     if (command === "onboard") {
-        const agentIndex = rest.indexOf("--agent");
-        const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;
-        const manageIndex = rest.indexOf("--manage");
-        const manage = manageIndex >= 0 ? rest[manageIndex + 1] : undefined;
-        const mcpModeIndex = rest.indexOf("--mcp-mode");
-        const mcpMode = mcpModeIndex >= 0 ? rest[mcpModeIndex + 1] : undefined;
-        const hubUrlIndex = rest.indexOf("--hub-url");
-        const hubUrl = hubUrlIndex >= 0 ? rest[hubUrlIndex + 1] : undefined;
-        const gatewayAgentsIndex = rest.indexOf("--gateway-agents");
-        const gatewayAgents = gatewayAgentsIndex >= 0 ? rest[gatewayAgentsIndex + 1] : undefined;
-        const memoryIndex = rest.indexOf("--memory");
-        const memory = memoryIndex >= 0 ? rest[memoryIndex + 1] : undefined;
-        const memoryMigrateIndex = rest.indexOf("--memory-migrate");
-        const memoryMigrate = memoryMigrateIndex >= 0 ? rest[memoryMigrateIndex + 1] : undefined;
-        const selectionIndex = rest.indexOf("--selection");
-        const selectionFile = selectionIndex >= 0 ? rest[selectionIndex + 1] : undefined;
         const { exitCode } = await runOnboard({
-            agent,
-            manage,
-            mcpMode,
-            hubUrl,
-            gatewayAgents,
-            memory,
-            memoryMigrate,
-            selectionFile,
+            agent: flagValue(rest, "--agent"),
+            manage: flagValue(rest, "--manage"),
+            mcpMode: flagValue(rest, "--mcp-mode"),
+            hubUrl: flagValue(rest, "--hub-url"),
+            gatewayAgents: flagValue(rest, "--gateway-agents"),
+            memory: flagValue(rest, "--memory"),
+            memoryMigrate: flagValue(rest, "--memory-migrate"),
+            selectionFile: flagValue(rest, "--selection"),
             dryRun: rest.includes("--dry-run"),
             json: rest.includes("--json"),
         });
@@ -369,21 +357,16 @@ async function main(argv) {
                 if (rest[i] === "--choose" && rest[i + 1] !== undefined)
                     choose.push(rest[i + 1]);
             }
-            const dedupIndex = rest.indexOf("--dedup");
             const { exitCode } = await runMigrateWorkspace({
                 choose,
-                dedup: dedupIndex >= 0 ? rest[dedupIndex + 1] : undefined,
+                dedup: flagValue(rest, "--dedup"),
                 dryRun: rest.includes("--dry-run"),
                 json: rest.includes("--json"),
             });
             process.exitCode = exitCode;
             return;
         }
-        const fromIndex = rest.indexOf("--from");
-        const from = fromIndex >= 0 ? rest[fromIndex + 1] : undefined;
-        const onlyIndex = rest.indexOf("--only");
-        const only = onlyIndex >= 0 ? rest[onlyIndex + 1] : undefined;
-        const { exitCode } = await runMigrate({ from, only, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
+        const { exitCode } = await runMigrate({ from: flagValue(rest, "--from"), only: flagValue(rest, "--only"), dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
         process.exitCode = exitCode;
         return;
     }
@@ -511,7 +494,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = (await runMcpRemove(name, { json, dryRun })).exitCode;
+            process.exitCode = (await runMcpRemove(name, { json, dryRun, workspace: mcpRest.includes("--workspace") })).exitCode;
             return;
         }
         if (subcommand === "renew") {
@@ -544,8 +527,7 @@ async function main(argv) {
         }
         if (subcommand === "add") {
             const [name] = skillRest;
-            const fromIndex = skillRest.indexOf("--from");
-            const from = fromIndex >= 0 ? skillRest[fromIndex + 1] : undefined;
+            const from = flagValue(skillRest, "--from");
             if (!name || !from) {
                 console.error("Usage: trellis skill add <name> --from <path>");
                 process.exitCode = 1;

package/dist/commands/doctor.d.ts

@@ -15,7 +15,7 @@ import { type WorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
  * machine.
  */
 export declare const DEFAULT_KNOWN_HOST_INJECTED: readonly string[];
-export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "oauth-expired" | "mcp-unreachable";
+export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "oauth-expired" | "mcp-unreachable" | "workspace-toml-invalid";
 export interface Finding {
     kind: FindingKind;
     /** Omitted for a finding that names more than one agent (drift). */

package/dist/commands/doctor.js

@@ -44,6 +44,10 @@ const EXIT_NONZERO_KINDS = new Set([
     // exists to catch *before* the session does (trellis-mcp-oauth-renew
     // design.md D4).
     "oauth-expired",
+    // A project-level Codex config that fails TOML parsing will fail the
+    // *agent*'s own startup regardless of ownership — catch it here before
+    // the next session does (trellis-doctor-workspace-toml-validation).
+    "workspace-toml-invalid",
 ]);
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -120,7 +124,53 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
             // canonical has not been initialized yet.
         }
     }
-    const workspace = canonical?.workspace ? collectWorkspaceDoctorSection(canonical) : undefined;
+    // Workspace attribution runs whenever a workspace root is in scope —
+    // even when `~/.trellis/` itself failed to load or has never been
+    // initialized. The spec's third scenario: a user managing only project
+    // skills in `.agents/skills/` without a global Trellis install still
+    // gets project-level config validation
+    // (trellis-doctor-workspace-toml-validation design.md D5). When the
+    // canonical source is absent we synthesize the minimal workspace layer
+    // with every map empty — provenance is moot without a global layer, but
+    // `collectWorkspaceDoctorSection`'s per-file inspection is what we want.
+    let workspace;
+    if (canonical?.workspace) {
+        workspace = collectWorkspaceDoctorSection(canonical);
+    }
+    else {
+        const workspaceRoot = workspaceDir != null ? findWorkspaceRoot(workspaceDir) : null;
+        if (workspaceRoot) {
+            // `managedAgents` is driven by `~/.trellis/managed.yaml`, which is
+            // absent in this branch — sweep every known agent so codex's TOML
+            // file is still inspected (otherwise an empty list would skip the
+            // file entirely and the spec's scenario-3 finding would never fire).
+            const minimal = {
+                instructionsFile: "",
+                managedAgents: ALL_AGENTS,
+                skills: [],
+                agents: [],
+                memories: [],
+                mcp: { servers: {}, knownHostInjected: [] },
+                secretsPolicy: { allowedVars: [], rejectPatterns: [] },
+                diagnostics: [],
+                workspace: { root: workspaceRoot, mcpProvenance: {}, mcpGlobalServers: {}, skillProvenance: {}, globalSkills: [], shadowed: [] },
+            };
+            workspace = collectWorkspaceDoctorSection(minimal);
+        }
+    }
+    // Workspace TOML findings become top-level findings so the exit code
+    // and `--json` consumers see them alongside cross-agent findings, not
+    // only inside the workspace section. They keep `agent: "codex"` — the
+    // file layout tells us which agent the file breaks.
+    if (workspace) {
+        for (const finding of workspace.tomlFindings) {
+            findings.push({
+                kind: "workspace-toml-invalid",
+                agent: finding.agent,
+                message: `${finding.path}${finding.line !== undefined ? `:${finding.line}${finding.column !== undefined ? `:${finding.column}` : ""}` : ""} — ${finding.reason} (not rendered by Trellis; fix by hand)`,
+            });
+        }
+    }
     const oauth = canonical ? collectOAuthHealth(homeDir, canonical) : [];
     findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots), ...oauth.flatMap((entry) => (entry.status === "valid" ? [] : [oauthFinding(entry)])));
     return { snapshots, findings, ...(oauth.length > 0 ? { oauth } : {}), ...(workspace ? { workspace } : {}) };
@@ -395,6 +445,10 @@ export function printReport(report) {
         for (const hint of ws.unmigrated) {
             console.log(`   ⚠ ${hint.path} holds ${hint.entries.length} entr${hint.entries.length === 1 ? "y" : "ies"} Trellis didn't render (${hint.entries.join(", ")}) — run \`trellis migrate --workspace\``);
         }
+        for (const finding of ws.tomlFindings) {
+            const location = finding.line !== undefined ? `:${finding.line}${finding.column !== undefined ? `:${finding.column}` : ""}` : "";
+            console.log(`   ⚠ ${finding.path}${location} — ${finding.reason} (not rendered by Trellis — fix by hand and re-run \`trellis doctor\`)`);
+        }
         for (const warning of ws.precedenceWarnings) {
             console.log(`   ⚠ ${warning}`);
         }

package/dist/commands/mcp.d.ts

@@ -120,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;
@@ -139,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;
@@ -199,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
@@ -342,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

@@ -29,8 +29,9 @@ 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, upsertWorkspaceServer } from "../lib/workspaceConfig.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),
@@ -232,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) {
@@ -491,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);
@@ -671,8 +678,16 @@ export async function applyMcpAddWorkspaceWithSync(plan, workspaceRoot, opts = {
     }
     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) {
@@ -767,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);
@@ -792,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/lib/cliArgs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared CLI flag readers. Every command historically rolled its own
+ * `argv.indexOf("--flag")` lookup — which silently ignores the equally
+ * common `--flag=value` form (real incident, found by the v0.15.0
+ * real-machine smoke test: `mcp add --args=-y,…` exited 0 with the args
+ * silently dropped from canonical). These helpers accept both forms, and
+ * `unknownFlags` catches typos instead of letting them vanish.
+ */
+/** Value of `--name <value>` or `--name=<value>`; undefined when absent.
+ * The space form returns the next token verbatim (even one starting with
+ * `-`), matching the historical `indexOf` behavior. First occurrence wins,
+ * same as `indexOf`. */
+export declare function flagValue(argv: readonly string[], name: string): string | undefined;
+/** `--*` tokens none of `known` claims. Non-flag tokens (positionals,
+ * values) are never flags; a `--name=value` token is classified by its
+ * name part, so a known flag in `=` form is not "unknown". */
+export declare function unknownFlags(argv: readonly string[], known: readonly string[]): string[];

package/dist/lib/cliArgs.js

@@ -0,0 +1,36 @@
+/**
+ * Shared CLI flag readers. Every command historically rolled its own
+ * `argv.indexOf("--flag")` lookup — which silently ignores the equally
+ * common `--flag=value` form (real incident, found by the v0.15.0
+ * real-machine smoke test: `mcp add --args=-y,…` exited 0 with the args
+ * silently dropped from canonical). These helpers accept both forms, and
+ * `unknownFlags` catches typos instead of letting them vanish.
+ */
+/** Value of `--name <value>` or `--name=<value>`; undefined when absent.
+ * The space form returns the next token verbatim (even one starting with
+ * `-`), matching the historical `indexOf` behavior. First occurrence wins,
+ * same as `indexOf`. */
+export function flagValue(argv, name) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === name)
+            return argv[i + 1];
+        if (token.startsWith(`${name}=`))
+            return token.slice(name.length + 1);
+    }
+    return undefined;
+}
+/** `--*` tokens none of `known` claims. Non-flag tokens (positionals,
+ * values) are never flags; a `--name=value` token is classified by its
+ * name part, so a known flag in `=` form is not "unknown". */
+export function unknownFlags(argv, known) {
+    const result = [];
+    for (const token of argv) {
+        if (!token.startsWith("--"))
+            continue;
+        const key = token.split("=", 1)[0];
+        if (!known.includes(key))
+            result.push(token);
+    }
+    return result;
+}

package/dist/lib/scopeSelection.d.ts

@@ -27,7 +27,7 @@ export type ScopeSelection = {
     detail: string;
 };
 export declare const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
-/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+/** Shared reader — accepts `--agents <ids>` and `--agents=<ids>`. */
 export declare function parseScopeArgs(argv: readonly string[]): ScopeSelectorRaw;
 export declare function resolveScopeSelection(raw: ScopeSelectorRaw, managed: readonly AgentId[]): ScopeSelection;
 /** Order-insensitive equality between the scope on disk and the one about to

package/dist/lib/scopeSelection.js

@@ -6,12 +6,13 @@
  * disagree about what a given selection means.
  */
 import { ALL_AGENTS } from "../core/types.js";
+import { flagValue } from "./cliArgs.js";
 export const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
-/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+/** Shared reader — accepts `--agents <ids>` and `--agents=<ids>`. */
 export function parseScopeArgs(argv) {
-    const i = argv.indexOf("--agents");
+    const agents = flagValue(argv, "--agents");
     return {
-        ...(i >= 0 ? { agents: argv[i + 1] ?? "" } : {}),
+        ...(agents !== undefined ? { agents } : {}),
         all: argv.includes("--all"),
         none: argv.includes("--none"),
     };

package/dist/lib/workspaceConfig.d.ts

@@ -1,7 +1,8 @@
 /**
  * Write-side helpers for the workspace layer (trellis-workspace-scope
  * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
- * upserting a server into `.agents/config.json` (`mcp add --workspace`).
+ * upserting/removing a server in `.agents/config.json`
+ * (`mcp add --workspace` / `mcp remove --workspace`).
  *
  * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
  * same file, same schema, one validator (via `toServerDefYaml`, so a
@@ -31,6 +32,11 @@ export declare function writeWorkspaceConfigJson(workspaceRoot: string, config:
  * the shared YAML/JSON translator. `version` is filled in when absent —
  * an existing file's version (and any unknown keys) is preserved. */
 export declare function upsertWorkspaceServer(workspaceRoot: string, name: string, def: McpServerDef, backup?: BackupSession): void;
+/** Delete `mcp.servers.<name>`, preserving every other key (unknown keys
+ * included, same posture as the upsert). Returns false — and writes
+ * nothing — when the entry isn't there. The follow-up `mcp sync` is what
+ * propagates the deletion to the rendered project-level files. */
+export declare function removeWorkspaceServer(workspaceRoot: string, name: string, backup?: BackupSession): boolean;
 export interface WorkspaceScaffoldFile {
     path: string;
     action: "create" | "already-present";

package/dist/lib/workspaceConfig.js

@@ -1,7 +1,8 @@
 /**
  * Write-side helpers for the workspace layer (trellis-workspace-scope
  * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
- * upserting a server into `.agents/config.json` (`mcp add --workspace`).
+ * upserting/removing a server in `.agents/config.json`
+ * (`mcp add --workspace` / `mcp remove --workspace`).
  *
  * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
  * same file, same schema, one validator (via `toServerDefYaml`, so a
@@ -59,6 +60,24 @@ export function upsertWorkspaceServer(workspaceRoot, name, def, backup) {
     };
     writeWorkspaceConfigJson(workspaceRoot, next, backup);
 }
+/** Delete `mcp.servers.<name>`, preserving every other key (unknown keys
+ * included, same posture as the upsert). Returns false — and writes
+ * nothing — when the entry isn't there. The follow-up `mcp sync` is what
+ * propagates the deletion to the rendered project-level files. */
+export function removeWorkspaceServer(workspaceRoot, name, backup) {
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const servers = config.mcp?.servers;
+    if (!servers || !(name in servers))
+        return false;
+    const nextServers = { ...servers };
+    delete nextServers[name];
+    const next = {
+        ...config,
+        mcp: { ...(config.mcp ?? {}), servers: nextServers },
+    };
+    writeWorkspaceConfigJson(workspaceRoot, next, backup);
+    return true;
+}
 /** Exported for `migrate --workspace`: a `.agents/AGENTS.md` holding
  * exactly this template is treated as still-empty scaffolding that an
  * instructions import may replace, not as user content to conflict on. */

package/dist/lib/workspaceDoctor.d.ts

@@ -20,6 +20,19 @@ export interface WorkspaceUnmigratedHint {
     /** Entry names present in the file with no Trellis manifest record. */
     entries: string[];
 }
+/** One parse-level failure when inspecting an agent's project MCP file.
+ * Distinct from `parse-diagnostic` (agent-global probes). Even when Trellis
+ * has never rendered into this file, a project file that breaks the agent's
+ * own startup is exactly what doctor exists to surface
+ * (trellis-doctor-workspace-toml-validation). */
+export interface WorkspaceTomlFinding {
+    agent: AgentId;
+    path: string;
+    /** Parser's 1-based line and column of the failure, when known. */
+    line?: number;
+    column?: number;
+    reason: string;
+}
 export interface WorkspaceDoctorSection {
     root: string;
     mcp: WorkspaceLayerEntry[];
@@ -38,6 +51,8 @@ export interface WorkspaceDoctorSection {
         name: string;
     }[];
     unmigrated: WorkspaceUnmigratedHint[];
+    /** Parse-level failures on workspace agent MCP files (usually empty). */
+    tomlFindings: WorkspaceTomlFinding[];
     /** zcode's user-level-first deviation notices (empty otherwise). */
     precedenceWarnings: string[];
 }

package/dist/lib/workspaceDoctor.js

@@ -10,6 +10,7 @@
  * from the already-loaded canonical source and file reads only.
  */
 import { existsSync, readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
 import { resolveSecretEnv } from "./secretEnv.js";
 import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
 const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
@@ -36,15 +37,36 @@ function collectVarRefs(canonical) {
     return refs;
 }
 /** Entry names a JSON `mcpServers` file / Codex TOML / zcode nested
- * config holds beyond what the in-repo manifest records Trellis
- * rendering. Regex-parses Codex TOML section headers — doctor only
- * needs names for a hint, not a full TOML AST. */
+ * config holds beyond what the in-repo manifest records Trellis rendering.
+ *
+ * The Codex branch TOML-parses the file first — syntactically invalid TOML
+ * is indistinguishable from valid TOML to the section-header regex, but is
+ * fatal to Codex's own startup, so it is surfaced as `invalid` and never
+ * turned into an unmigrated hint. The parsed AST is discarded on success:
+ * header extraction keeps using the existing regex to avoid changing edge
+ * semantics (dotted quoted keys, single-quoted keys) that the regex was
+ * already validated against — smol-toml is used parse-only, never
+ * round-tripped, respecting lib/tomlSection.ts's write-path constraint. */
 function unmarkedEntries(agentId, configPath, recorded) {
     if (!existsSync(configPath))
-        return [];
+        return { kind: "ok", names: [] };
     let names = [];
     if (agentId === "codex") {
         const content = readFileSync(configPath, "utf-8");
+        try {
+            parseToml(content);
+        }
+        catch (err) {
+            const tomLError = err;
+            const reason = tomLError.message?.split("\n")[0] ?? String(err);
+            return {
+                kind: "invalid",
+                path: configPath,
+                ...(typeof tomLError.line === "number" ? { line: tomLError.line } : {}),
+                ...(typeof tomLError.column === "number" ? { column: tomLError.column + 1 } : {}),
+                reason,
+            };
+        }
         const re = /^\[mcp_servers\.([^\]]+)\]\s*$/gm;
         let match;
         while ((match = re.exec(content)) !== null)
@@ -59,10 +81,10 @@ function unmarkedEntries(agentId, configPath, recorded) {
             names = Object.keys(servers);
         }
         catch {
-            return []; // unparsable file is the sync guard's finding, not doctor's
+            return { kind: "ok", names: [] }; // unparsable file is the sync guard's finding, not doctor's
         }
     }
-    return names.filter((name) => recorded[name] === undefined);
+    return { kind: "ok", names: names.filter((name) => recorded[name] === undefined) };
 }
 export function collectWorkspaceDoctorSection(canonical) {
     const workspace = canonical.workspace;
@@ -83,12 +105,17 @@ export function collectWorkspaceDoctorSection(canonical) {
     const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
     const manifest = loadWorkspaceRendered(workspace.root);
     const unmigrated = [];
+    const tomlFindings = [];
     for (const agentId of canonical.managedAgents) {
         const configPath = workspaceMcpConfigPath(agentId, workspace.root);
-        const entries = unmarkedEntries(agentId, configPath, manifest.mcp?.[agentId] ?? {});
-        if (entries.length > 0)
-            unmigrated.push({ agent: agentId, path: configPath, entries });
+        const result = unmarkedEntries(agentId, configPath, manifest.mcp?.[agentId] ?? {});
+        if (result.kind === "invalid") {
+            tomlFindings.push({ agent: agentId, path: result.path, ...(result.line !== undefined ? { line: result.line } : {}), ...(result.column !== undefined ? { column: result.column } : {}), reason: result.reason });
+            continue; // never report an unparseable file's entries as unmigrated — spec req 2
+        }
+        if (result.names.length > 0)
+            unmigrated.push({ agent: agentId, path: configPath, entries: result.names });
     }
     const precedenceWarnings = canonical.managedAgents.flatMap((id) => workspacePrecedenceWarnings(id, canonical));
-    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, precedenceWarnings };
+    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, tomlFindings, precedenceWarnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -64,6 +64,7 @@
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@modelcontextprotocol/server": "^2.3.1",
+    "smol-toml": "^1.9.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   }