agent-trellis 0.10.0 → 0.12.0

package/dist/adapters/mcpPlan.d.ts

@@ -34,6 +34,7 @@ export declare const RUNTIME_COMMAND = "trellis";
  * routing it exists to carry (trellis-mcp-oauth-static-client design.md
  * D1). */
 export declare function isOAuthMcpServer(def: McpServerDef): boolean;
+export declare function isAgentOwnedOAuth(def: McpServerDef): boolean;
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,

package/dist/adapters/mcpPlan.js

@@ -18,7 +18,7 @@
  */
 import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
-import { isOAuthAuth } from "../core/types.js";
+import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
@@ -40,6 +40,9 @@ export const RUNTIME_COMMAND = "trellis";
 export function isOAuthMcpServer(def) {
     return isOAuthAuth(def.auth);
 }
+export function isAgentOwnedOAuth(def) {
+    return isOAuthMcpServer(def) && oauthOwner(def.auth) === "agent";
+}
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,
@@ -158,7 +161,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
                 conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
-        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isOAuthMcpServer);
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         // Every ordinary per-server check (enabled, scope, literal secrets,
         // unresolved env names, Codex's header shape) still runs at gateway
         // startup. OAuth servers are the deliberate exception: they are written
@@ -234,15 +237,21 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
         // Runtime mode owns the agent-facing MCP edge. It resolves the same
         // direct/gateway-compatible upstream route at startup, so native
         // per-server entries are not duplicated here.
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         return {
             desired: [{
                     name: RUNTIME_ENTRY_NAME,
                     def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
-                }],
-            conflicts: [],
+                }, ...oauth.desired],
+            conflicts: oauth.conflicts,
         };
     }
-    return planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const native = planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
+    return {
+        desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
+        conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))],
+    };
 }
 function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];

package/dist/cli.js

@@ -9,13 +9,14 @@ import { runInit } from "./commands/init.js";
 import { runMigrate } from "./commands/migrate.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
-import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
+import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, runMcpSetAuth, runMcpScope, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
+import { parseScopeArgs } from "./lib/scopeSelection.js";
 import { runMcpImport } from "./commands/mcpImport.js";
 import { parseMcpGatewayArgs, runMcpGateway, runMcpRuntime } from "./commands/mcpGateway.js";
 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 { runSkillList, runSkillAdd, runSkillRemove, runSkillScope, runSkillUpdateBuiltin } from "./commands/skill.js";
 import { runRemoteSkillAdd, runRemoteSkillList, runRemoteSkillUpdate } from "./commands/remoteSkill.js";
 import { collectMemoryList, runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseManageArgs, runManage } from "./commands/manage.js";
@@ -132,7 +133,7 @@ Commands:
             --json       machine-readable output, no report text
   mcp set <name> --auth oauth|none
             Set or clear explicit OAuth classification; canonical only.
-            --auth oauth [--client-id <id>] [--client-secret-env <NAME>]
+            --auth oauth [--auth-owner agent|trellis] [--client-id <id>] [--client-secret-env <NAME>]
                          pre-register a client for a provider that refuses
                          dynamic registration. --client-id is the PROVIDER's
                          published identifier (public by design);
@@ -142,6 +143,14 @@ Commands:
                          --auth none removes it along with the classification.
             --dry-run    preview the plan, write nothing
             --json       machine-readable output, no report text
+  mcp scope <name> --agents <ids> | --all | --none
+            Choose which managed agents reach a canonical MCP server, then
+            run the same sync as mcp sync. Exactly one selector is
+            required; ids must be managed agents. Selecting every managed
+            agent records no explicit scope, so a newly managed agent is
+            included. An entry Trellis did not write is never removed.
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   mcp auth <server-name>
             Authorize a remote (http/sse) MCP server that uses OAuth —
               opens a browser once, stores the result 0600 under
@@ -169,6 +178,12 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
+  skill scope <name> --agents <ids> | --all | --none
+            Choose which managed agents receive a canonical skill, then
+            sync it. Same selector rules as mcp scope; a built-in skill's
+            scope is not editable
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   skill update-builtin
             Refresh the package-owned trellis-runtime Skill in canonical
             source; existing native symlinks see the update
@@ -440,6 +455,11 @@ async function main(argv) {
             process.exitCode = runMcpSetAuth(name, parseMcpSetArgs(mcpRest), { json, dryRun }).exitCode;
             return;
         }
+        if (subcommand === "scope") {
+            const [name] = mcpRest;
+            process.exitCode = (await runMcpScope(name && !name.startsWith("--") ? name : undefined, parseScopeArgs(mcpRest), { json, dryRun })).exitCode;
+            return;
+        }
         if (subcommand === "remove") {
             const [name] = mcpRest;
             if (!name) {
@@ -461,7 +481,7 @@ async function main(argv) {
             process.exitCode = exitCode;
             return;
         }
-        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|remove <name>|auth <name>\n`);
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|scope <name>|remove <name>|auth <name>\n`);
         process.exitCode = 1;
         return;
     }
@@ -495,11 +515,16 @@ async function main(argv) {
             process.exitCode = (await runSkillRemove(name, { json, dryRun })).exitCode;
             return;
         }
+        if (subcommand === "scope") {
+            const [name] = skillRest;
+            process.exitCode = (await runSkillScope(name && !name.startsWith("--") ? name : undefined, parseScopeArgs(skillRest), { json, dryRun })).exitCode;
+            return;
+        }
         if (subcommand === "update-builtin") {
             process.exitCode = runSkillUpdateBuiltin({ json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|update-builtin\n`);
+        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>|scope <name> --agents <ids>|--all|--none|update-builtin\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/mcp.d.ts

@@ -15,6 +15,7 @@
 import { type ServersYamlWriteResult } from "../core/canonical.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
 import type { AgentId, McpAuthMode, McpConfig, McpServerDef, Transport } from "../core/types.js";
+import { type ScopeSelectorRaw } from "../lib/scopeSelection.js";
 import { type BackupSession } from "../lib/backup.js";
 export interface RunMcpSyncOptions {
     json?: boolean;
@@ -55,6 +56,12 @@ export interface McpListEntry {
     /** Normalized: `oauth` in either the scalar or the object form reports as
      * the scalar here — the listing reports classification, not metadata. */
     auth?: McpAuthMode;
+    authOwner?: "agent" | "trellis";
+    agentAuthorization?: Array<{
+        agent: AgentId;
+        status: "unknown";
+        instruction: string;
+    }>;
     /** Presence of pre-registered client metadata
      * (trellis-mcp-oauth-static-client task 3.2) — `true` when the object form
      * carries a `client_id`. A presence flag, deliberately not the id itself:
@@ -62,6 +69,12 @@ export interface McpListEntry {
      * ever changes and there is one less place a future secret-looking field
      * could leak through. */
     preRegisteredClient?: true;
+    /** State of the stored OAuth credential, for OAuth-classified servers only
+     * (trellis-scope-editing-and-auth-status design.md D6). It describes the
+     * credential, not the connection: an `authorized` server can still be down. */
+    authStatus?: McpAuthStatus;
+    /** Epoch ms, when the stored token advertises an expiry. */
+    authExpiresAt?: number;
     enabled: boolean;
     agents: readonly AgentId[];
     command?: string;
@@ -77,6 +90,18 @@ export interface McpListEntry {
      * printed in full. */
     staticEnv?: Record<string, string>;
 }
+export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired" | "unknown";
+/**
+ * Reads only the per-server token store and returns the state, never a
+ * token. Classification stays explicit — the caller only asks for servers
+ * already declared OAuth, so a stray token file never makes one. A server
+ * name that cannot be a token filename, or an unreadable file, simply has no
+ * credential: one odd entry must not take down the whole listing.
+ */
+export declare function mcpCredentialState(homeDir: string, serverName: string, resourceUrl?: string): {
+    authStatus: McpAuthStatus;
+    authExpiresAt?: number;
+};
 export declare function collectMcpListPlan(homeDir?: string): McpListEntry[];
 export declare function runMcpList(opts?: {
     homeDir?: string;
@@ -137,6 +162,7 @@ export interface McpSetAuthPlan {
  * plan collector. */
 export interface McpSetAuthRawArgs {
     auth?: string;
+    authOwner?: string;
     /** Public literal by design (design.md D2) — the one field it is fine to
      * pass on a command line. Never echoed back in output or errors. */
     clientId?: string;
@@ -169,6 +195,51 @@ export declare function runMcpSetAuth(name: string | undefined, raw: McpSetAuthR
 }): {
     exitCode: number;
 };
+export declare function applyMcpSetAuthWithSync(plan: McpSetAuthPlan, homeDir: string): Promise<{
+    plan: McpSetAuthPlan;
+    sync?: McpSyncReport;
+}>;
+export type McpScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface McpScopePlan {
+    name: string;
+    action: McpScopeAction;
+    detail: string;
+    /** Recorded as `agents:` on the entry; `undefined` removes the key so the
+     * server reaches every managed agent. */
+    scope?: AgentId[];
+    mode?: "all" | "none" | "explicit";
+    normalizedFromFull?: boolean;
+    effective?: readonly AgentId[];
+    /** Only set when action === "updated"; consumed by applyMcpScopeWithSync. */
+    def?: McpServerDef;
+}
+/**
+ * `mcp scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as
+ * `skill scope`, which is why both go through `resolveScopeSelection`.
+ */
+export declare function collectMcpScopePlan(name: string | undefined, raw: ScopeSelectorRaw, homeDir?: string): McpScopePlan;
+export interface McpScopeOutcome {
+    plan: McpScopePlan;
+    writeError?: string;
+    sync?: McpSyncReport;
+}
+/** Write inside a backup session, then the same `mcp sync` `add` / `remove`
+ * run. Removal of an entry from an agent narrowed away stays gated by the
+ * ownership ledger, so an entry Trellis did not write is never deleted
+ * (design.md D5). */
+export declare function applyMcpScopeWithSync(plan: McpScopePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<McpScopeOutcome>;
+export declare function runMcpScope(name: string | undefined, raw: ScopeSelectorRaw, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;
 export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string, backup?: BackupSession): ServersYamlWriteResult;
 export interface McpAddOutcome {
     plan: McpAddPlan;

package/dist/commands/mcp.js

@@ -16,8 +16,10 @@ 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, isOAuthAuth, oauthClientMetadata, resolveScope } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, oauthOwner, resolveScope } from "../core/types.js";
 import { isValidSecretVarName } from "../lib/secretEnv.js";
+import { isExpired, readToken } from "../lib/oauth/store.js";
+import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
@@ -114,6 +116,34 @@ export function printReport(report, dryRun) {
 function serversYamlPath(homeDir) {
     return join(homeDir, ".trellis", "mcp", "servers.yaml");
 }
+/**
+ * Reads only the per-server token store and returns the state, never a
+ * token. Classification stays explicit — the caller only asks for servers
+ * already declared OAuth, so a stray token file never makes one. A server
+ * name that cannot be a token filename, or an unreadable file, simply has no
+ * credential: one odd entry must not take down the whole listing.
+ */
+export function mcpCredentialState(homeDir, serverName, resourceUrl) {
+    let token;
+    try {
+        token = readToken(homeDir, serverName);
+    }
+    catch {
+        return { authStatus: "not-authorized" };
+    }
+    if (!token?.accessToken)
+        return { authStatus: "not-authorized" };
+    if (resourceUrl && token.resourceUrl) {
+        const resource = new URL(resourceUrl);
+        resource.hash = "";
+        if (token.resourceUrl !== resource.toString())
+            return { authStatus: "not-authorized" };
+    }
+    const expiry = token.expiresAt !== undefined ? { authExpiresAt: token.expiresAt } : {};
+    if (!isExpired(token))
+        return { authStatus: "authorized", ...expiry };
+    return { authStatus: token.refreshToken ? "refreshable" : "expired", ...expiry };
+}
 export function collectMcpListPlan(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
     return Object.entries(canonical.mcp.servers).map(([name, def]) => ({
@@ -121,6 +151,16 @@ export function collectMcpListPlan(homeDir = homedir()) {
         transport: def.transport,
         auth: isOAuthAuth(def.auth) ? "oauth" : undefined,
         preRegisteredClient: oauthClientMetadata(def.auth).clientId !== undefined ? true : undefined,
+        ...(isOAuthAuth(def.auth) ? {
+            authOwner: oauthOwner(def.auth),
+            ...(oauthOwner(def.auth) === "trellis" ? mcpCredentialState(homeDir, name, def.url) : {
+                authStatus: "unknown",
+                agentAuthorization: resolveScope(def.agents, canonical.managedAgents).map((agent) => ({
+                    agent, status: "unknown",
+                    instruction: agent === "codex" ? `codex mcp login ${name}` : agent === "claude-code" ? "Open Claude Code and use /mcp to authorize this server" : "Authorize this server in the Agent's MCP settings",
+                })),
+            }),
+        } : {}),
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -150,7 +190,7 @@ export function runMcpList(opts = {}) {
     else {
         for (const e of entries) {
             const scope = e.agents.length > 0 ? e.agents.join(", ") : "(no managed agent reaches it)";
-            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""}${e.preRegisteredClient ? ", pre-registered client" : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
+            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""}${e.preRegisteredClient ? ", pre-registered client" : ""}${e.authStatus ? `, credential: ${e.authStatus}` : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
             if (e.env && e.env.length > 0)
                 console.log(`   env: ${e.env.join(", ")} (values never read/printed)`);
             if (e.staticEnv)
@@ -186,6 +226,7 @@ export function parseMcpSetArgs(argv) {
         auth: flag("--auth"),
         clientId: flag("--client-id"),
         clientSecretEnv: flag("--client-secret-env"),
+        authOwner: flag("--auth-owner"),
     };
 }
 function parseCsv(raw) {
@@ -289,8 +330,10 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     const mode = raw.auth === "oauth" || raw.auth === "none" ? raw.auth : undefined;
     if (!name)
         return { name: "(none)", auth: (mode ?? "none"), action: "invalid-input", detail: "usage: trellis mcp set <name> --auth oauth|none [--client-id <id>] [--client-secret-env <NAME>]" };
-    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined;
-    const clientFlagsDetail = "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
+    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined || raw.authOwner !== undefined;
+    const clientFlagsDetail = raw.authOwner !== undefined
+        ? "--auth-owner requires an explicit --auth oauth in the same command"
+        : "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
     if (mode === undefined) {
         // Naming the missing --auth is the actionable error when that is what
         // the user was reaching for; otherwise report the invalid value itself.
@@ -304,6 +347,9 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     if (raw.clientId === "") {
         return { name, auth: mode, action: "invalid-input", detail: "--client-id must not be empty" };
     }
+    if (raw.authOwner !== undefined && raw.authOwner !== "agent" && raw.authOwner !== "trellis") {
+        return { name, auth: mode, action: "invalid-input", detail: "--auth-owner must be agent or trellis" };
+    }
     if (raw.clientSecretEnv !== undefined && !isValidSecretVarName(raw.clientSecretEnv)) {
         // The value is deliberately not echoed: a name-shaped field failing
         // this check is at best a typo and at worst a pasted credential
@@ -362,6 +408,7 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
             ...current,
             auth: {
                 kind: "oauth",
+                ...(raw.authOwner !== undefined ? { owner: raw.authOwner } : typeof current.auth === "object" && current.auth.owner !== undefined ? { owner: current.auth.owner } : {}),
                 ...(clientId !== undefined ? { clientId } : {}),
                 ...(clientSecretEnv !== undefined ? { clientSecretEnv } : {}),
             },
@@ -399,6 +446,100 @@ export function runMcpSetAuth(name, raw, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
+export async function applyMcpSetAuthWithSync(plan, homeDir) {
+    if (plan.action !== "updated" || !plan.def)
+        return { plan };
+    const backup = openBackupSession(homeDir, "mcp-auth-owner");
+    try {
+        const path = serversYamlPath(homeDir);
+        const result = upsertServerYaml(path, plan.name, plan.def, backup);
+        if (!result.ok)
+            throw new Error(result.error);
+        return { plan, sync: await collectMcpSyncReport({ homeDir, backupSession: backup }) };
+    }
+    finally {
+        backup.finalize();
+    }
+}
+/**
+ * `mcp scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as
+ * `skill scope`, which is why both go through `resolveScopeSelection`.
+ */
+export function collectMcpScopePlan(name, raw, homeDir = homedir()) {
+    if (!name)
+        return { name: "(none)", action: "invalid-input", detail: "usage: trellis mcp scope <name> --agents <ids> | --all | --none" };
+    const canonical = loadCanonicalSource(homeDir);
+    const selection = resolveScopeSelection(raw, canonical.managedAgents);
+    if (!selection.ok)
+        return { name, action: "invalid-input", detail: selection.detail };
+    const current = canonical.mcp.servers[name];
+    if (!current)
+        return { name, action: "not-found", detail: `no canonical MCP server named "${name}"` };
+    const base = {
+        name,
+        scope: selection.scope,
+        mode: selection.mode,
+        normalizedFromFull: selection.normalizedFromFull,
+        effective: resolveScope(selection.scope, canonical.managedAgents),
+    };
+    const summary = describeScope(selection.scope, canonical.managedAgents);
+    if (sameScope(current.agents, selection.scope)) {
+        return { ...base, action: "already-set", detail: `scope is already ${summary}` };
+    }
+    const { agents: _agents, ...withoutAgents } = current;
+    const def = selection.scope === undefined ? withoutAgents : { ...withoutAgents, agents: selection.scope };
+    const normalized = selection.normalizedFromFull ? " (every managed agent selected — recorded as the default, so a newly managed agent is included)" : "";
+    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}`, def };
+}
+/** Write inside a backup session, then the same `mcp sync` `add` / `remove`
+ * run. Removal of an entry from an agent narrowed away stays gated by the
+ * ownership ledger, so an entry Trellis did not write is never deleted
+ * (design.md D5). */
+export async function applyMcpScopeWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "updated" ? openBackupSession(homeDir, "mcp-scope") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "updated" && plan.def) {
+        const result = upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    let syncReport;
+    if (!writeError && plan.action === "updated" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runMcpScope(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let outcome;
+    try {
+        outcome = await applyMcpScopeWithSync(collectMcpScopePlan(name, raw, homeDir), { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const { plan, writeError, sync: syncReport } = outcome;
+    if (opts.json) {
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}mcp scope ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+        if (syncReport)
+            printReport(syncReport, opts.dryRun ?? false);
+    }
+    const failed = plan.action === "invalid-input" || plan.action === "not-found" || Boolean(writeError);
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
+}
 export function applyMcpAddPlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "create" || !plan.def)
         return { ok: true };

package/dist/commands/mcpAuth.d.ts

@@ -16,6 +16,11 @@ export interface RunMcpAuthOptions {
     homeDir?: string;
     /** Test seam — the real one launches the platform browser. */
     openBrowser?: (url: string) => void | Promise<void>;
+    signal?: AbortSignal;
+    onProgress?: (phase: "discovering" | "registering" | "waiting" | "exchanging" | "saving") => void;
+    timeoutMs?: number;
+    /** Used by the desktop; native grants belong to each Agent. */
+    requireHosted?: boolean;
 }
 export interface McpAuthResult {
     server: string;
@@ -26,3 +31,4 @@ export interface McpAuthResult {
 export declare function runMcpAuth(opts: RunMcpAuthOptions): Promise<{
     exitCode: number;
 }>;
+export declare function authorizeMcpServer(opts: RunMcpAuthOptions): Promise<McpAuthResult>;

package/dist/commands/mcpAuth.js

@@ -11,16 +11,17 @@
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { discoverAuthorizationServer, parseResourceMetadataUrl } from "../lib/oauth/discovery.js";
-import { authorize } from "../lib/oauth/flow.js";
+import { authorize, abortable } from "../lib/oauth/flow.js";
 import { ensureFreshToken } from "../lib/oauth/refresh.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 import { isExpired, readToken, tokenPath, writeToken } from "../lib/oauth/store.js";
-import { oauthClientMetadata } from "../core/types.js";
+import { withServerLock } from "../lib/oauth/lock.js";
+import { isOAuthAuth, oauthOwner, oauthClientMetadata } from "../core/types.js";
 export async function runMcpAuth(opts) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
     try {
-        result = await authorizeServer(opts, homeDir);
+        result = await authorizeMcpServer(opts);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -41,7 +42,9 @@ export async function runMcpAuth(opts) {
     }
     return { exitCode: 0 };
 }
-async function authorizeServer(opts, homeDir) {
+export async function authorizeMcpServer(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    opts.signal?.throwIfAborted();
     const canonical = loadCanonicalSource(homeDir);
     const def = canonical.mcp.servers[opts.serverName];
     if (!def) {
@@ -54,15 +57,21 @@ async function authorizeServer(opts, homeDir) {
         // flow that does not exist.
         throw new Error(`MCP server "${opts.serverName}" is a stdio server — OAuth applies to http/sse servers. Its credentials come from \`env\`/\`env_aliases\` and secrets.policy.yaml.`);
     }
+    if (opts.requireHosted && (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis" || def.enabled === false)) {
+        throw new Error("This connection is authorized by its Agent; choose explicit Trellis ownership before starting hosted authorization");
+    }
     const file = tokenPath(homeDir, opts.serverName);
+    const resourceUrl = new URL(def.url);
+    resourceUrl.hash = "";
     if (!opts.force) {
-        const existing = readToken(homeDir, opts.serverName);
+        const stored = readToken(homeDir, opts.serverName);
+        const existing = stored?.resourceUrl && stored.resourceUrl !== resourceUrl.toString() ? undefined : stored;
         if (existing && !isExpired(existing)) {
             // Re-running is a no-op rather than a fresh grant: rotating a
             // perfectly good credential is a way to break a working setup.
             return { server: opts.serverName, status: "already-valid", tokenFile: file, ...(existing.expiresAt ? { expiresAt: existing.expiresAt } : {}) };
         }
-        if (existing?.refreshToken) {
+        if (existing?.refreshToken && !opts.requireHosted) {
             // Expired but renewable — no browser needed.
             const refreshed = await ensureFreshToken(homeDir, opts.serverName);
             if (refreshed) {
@@ -70,7 +79,10 @@ async function authorizeServer(opts, homeDir) {
             }
         }
     }
-    const metadata = await discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def) });
+    opts.onProgress?.("discovering");
+    const fetchImpl = (url, init) => fetch(url, { ...init, signal: opts.signal });
+    const metadata = await abortable(discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def, opts.signal), fetchImpl }), opts.signal);
+    opts.signal?.throwIfAborted();
     if (!metadata) {
         throw new Error(`could not discover OAuth metadata for "${opts.serverName}" (${def.url}) — it may not use OAuth, or may not publish RFC 8414/9728 metadata`);
     }
@@ -90,12 +102,28 @@ async function authorizeServer(opts, homeDir) {
         clientSecret = value;
     }
     const token = await authorize(opts.serverName, metadata, {
+        signal: opts.signal,
+        resourceUrl: resourceUrl.toString(),
+        onProgress: opts.onProgress,
+        timeoutMs: opts.timeoutMs,
         ...(opts.openBrowser ? { openBrowser: opts.openBrowser } : {}),
         ...(metadata.scopesSupported?.length ? { scope: metadata.scopesSupported.join(" ") } : {}),
         ...(client.clientId !== undefined ? { clientId: client.clientId } : {}),
         ...(clientSecret !== undefined ? { clientSecret } : {}),
     });
-    writeToken(homeDir, opts.serverName, token);
+    opts.signal?.throwIfAborted();
+    // Serialize the final write with silent refreshes, without holding a lock
+    // while the user is in the browser. An older refresh cannot overwrite a new
+    // grant after it is committed.
+    opts.onProgress?.("saving");
+    await withServerLock(homeDir, opts.serverName, async () => {
+        opts.signal?.throwIfAborted();
+        const current = loadCanonicalSource(homeDir).mcp.servers[opts.serverName];
+        if (!current || current.url !== def.url || JSON.stringify(current.auth) !== JSON.stringify(def.auth) || current.enabled === false) {
+            throw new Error("The server's endpoint or authorization configuration changed; start authorization again");
+        }
+        writeToken(homeDir, opts.serverName, token);
+    });
     return { server: opts.serverName, status: "authorized", tokenFile: file, ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}) };
 }
 /**
@@ -113,9 +141,9 @@ function secretSourceLabel(policy) {
  * server directly, which beats probing well-known paths. Failure is not
  * an error: discovery falls back to probing.
  */
-async function probeWwwAuthenticate(def) {
+async function probeWwwAuthenticate(def, signal) {
     try {
-        const response = await fetch(def.url, { method: "GET" });
+        const response = await fetch(def.url, { method: "GET", signal });
         if (response.status !== 401)
             return null;
         const header = response.headers.get("www-authenticate");

package/dist/commands/mcpGateway.js

@@ -14,10 +14,10 @@
  * an in-process backend without this file, or any agent's config,
  * changing.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
-import { isGatewayAgent, isOAuthMcpServer, resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { isGatewayAgent, isAgentOwnedOAuth, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { LocalBackend } from "../lib/gatewayBackend.js";
 import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { BuiltinRegistry, createRuntimeServer, UpstreamProvider } from "../lib/mcpRuntime.js";
@@ -65,7 +65,9 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     const directRoutes = canonical.mcp.routes && route
         ? { ...canonical.mcp.routes, [agentId]: { mode: "direct", ...(route.servers ? { servers: route.servers } : {}) } }
         : canonical.mcp.routes;
-    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => !isOAuthMcpServer(def)));
+    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers)
+        .filter(([, def]) => !isAgentOwnedOAuth(def))
+        .map(([name, def]) => { const { auth: _auth, ...ordinary } = def; return [name, ordinary]; }));
     const direct = { ...canonical.mcp, servers: ordinaryServers, gateway: undefined, hub: undefined, routes: directRoutes, runtime: undefined };
     // The managed set is passed through unchanged, so an unmanaged agent
     // reaches nothing. Being spawned is NOT treated as consent here, which
@@ -80,7 +82,7 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     // user just said to stop involving.
     const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
     return {
-        upstreams: desired.map(({ name, def }) => ({ name, def })),
+        upstreams: desired.map(({ name }) => ({ name, def: canonical.mcp.servers[name] })),
         conflicts: conflicts.map((conflict) => conflict.message),
     };
 }
@@ -123,9 +125,7 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
             homeDir,
         });
     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);
+    const server = serveStdio(() => createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry));
     await waitForShutdown(registry, server);
     return { exitCode: 0 };
 }