agent-trellis 0.9.1 → 0.11.0

package/dist/adapters/mcpPlan.d.ts

@@ -28,6 +28,11 @@ export declare const LEGACY_RUNTIME_ENTRY_NAME = "trellis-runtime";
  * user installed the CLI onto. */
 export declare const GATEWAY_COMMAND = "trellis";
 export declare const RUNTIME_COMMAND = "trellis";
+/** Either form of the OAuth classification counts — a strict equality
+ * check against the scalar would read the metadata-bearing object
+ * (`{ kind: oauth, client_id }`) as "not OAuth" and silently drop the
+ * routing it exists to carry (trellis-mcp-oauth-static-client design.md
+ * D1). */
 export declare function isOAuthMcpServer(def: McpServerDef): boolean;
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —

package/dist/adapters/mcpPlan.js

@@ -18,6 +18,7 @@
  */
 import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
+import { isOAuthAuth } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
@@ -31,8 +32,13 @@ export const LEGACY_RUNTIME_ENTRY_NAME = "trellis-runtime";
  * user installed the CLI onto. */
 export const GATEWAY_COMMAND = "trellis";
 export const RUNTIME_COMMAND = "trellis";
+/** Either form of the OAuth classification counts — a strict equality
+ * check against the scalar would read the metadata-bearing object
+ * (`{ kind: oauth, client_id }`) as "not OAuth" and silently drop the
+ * routing it exists to carry (trellis-mcp-oauth-static-client design.md
+ * D1). */
 export function isOAuthMcpServer(def) {
-    return def.auth === "oauth";
+    return isOAuthAuth(def.auth);
 }
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —

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 } 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";
@@ -131,9 +132,25 @@ Commands:
             --dry-run    preview without writing
             --json       machine-readable output, no report text
   mcp set <name> --auth oauth|none
-            Set or clear explicit OAuth classification; canonical only
+            Set or clear explicit OAuth classification; canonical only.
+            --auth oauth [--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);
+                         --client-secret-env is a variable NAME resolved via
+                         secrets.policy.yaml, never a secret value.
+                         A bare --auth oauth keeps existing client metadata;
+                         --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
@@ -161,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
@@ -429,9 +452,12 @@ async function main(argv) {
         }
         if (subcommand === "set") {
             const [name] = mcpRest;
-            const authIndex = mcpRest.indexOf("--auth");
-            const auth = authIndex >= 0 ? mcpRest[authIndex + 1] : undefined;
-            process.exitCode = runMcpSetAuth(name, auth, { json, dryRun }).exitCode;
+            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") {
@@ -455,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;
     }
@@ -489,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;
@@ -52,7 +53,22 @@ export declare function printReport(report: McpSyncReport, dryRun: boolean): voi
 export interface McpListEntry {
     name: string;
     transport: Transport;
+    /** Normalized: `oauth` in either the scalar or the object form reports as
+     * the scalar here — the listing reports classification, not metadata. */
     auth?: McpAuthMode;
+    /** 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:
+     * the id is public-by-design, but listing output stays stable if that
+     * 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;
@@ -68,6 +84,18 @@ export interface McpListEntry {
      * printed in full. */
     staticEnv?: Record<string, string>;
 }
+export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired";
+/**
+ * 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): {
+    authStatus: McpAuthStatus;
+    authExpiresAt?: number;
+};
 export declare function collectMcpListPlan(homeDir?: string): McpListEntry[];
 export declare function runMcpList(opts?: {
     homeDir?: string;
@@ -98,6 +126,7 @@ export interface McpAddRawArgs {
     enabled?: string;
 }
 export declare function parseMcpAddArgs(argv: readonly string[]): McpAddRawArgs;
+export declare function parseMcpSetArgs(argv: readonly string[]): McpSetAuthRawArgs;
 export type McpAddAction = "create" | "already-present" | "conflict" | "invalid-input";
 export interface McpAddPlan {
     name: string;
@@ -122,14 +151,84 @@ export interface McpSetAuthPlan {
     detail: string;
     def?: McpServerDef;
 }
-export declare function collectMcpSetAuthPlan(name: string | undefined, auth: string | undefined, homeDir?: string): McpSetAuthPlan;
-export declare function runMcpSetAuth(name: string | undefined, auth: string | undefined, opts?: {
+/** Raw, unvalidated CLI flag values for `mcp set` — same posture as
+ * `McpAddRawArgs`: the parser stays a dumb reader, validation lives in the
+ * plan collector. */
+export interface McpSetAuthRawArgs {
+    auth?: 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;
+    /** A variable NAME, never a secret value. */
+    clientSecretEnv?: string;
+}
+/**
+ * Sets or clears the OAuth classification, and optionally the
+ * pre-registered client metadata that goes with it
+ * (trellis-mcp-oauth-static-client tasks.md 3.1).
+ *
+ * Three rules the flag interaction has to get right:
+ *   - A bare `--auth oauth` is a re-classification, not a reset: an entry
+ *     that already carries a `client_id` keeps it. Silently dropping
+ *     metadata here would turn "make sure this is OAuth" into "break my
+ *     Figma setup", which is exactly the kind of invisible precedence
+ *     `mcp set` exists to avoid.
+ *   - `--auth none` is the reset — it strips the whole `auth` key,
+ *     metadata included, because that is the only reading of "none" that
+ *     leaves the file in a self-consistent state.
+ *   - `--client-id` / `--client-secret-env` require an explicit
+ *     `--auth oauth` in the same invocation. Implying it would make a
+ *     typo'd flag name mutate the classification.
+ */
+export declare function collectMcpSetAuthPlan(name: string | undefined, raw: McpSetAuthRawArgs, homeDir?: string): McpSetAuthPlan;
+export declare function runMcpSetAuth(name: string | undefined, raw: McpSetAuthRawArgs, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
 }): {
     exitCode: number;
 };
+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,7 +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, resolveScope } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, 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";
@@ -113,12 +116,36 @@ 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) {
+    let token;
+    try {
+        token = readToken(homeDir, serverName);
+    }
+    catch {
+        return { authStatus: "not-authorized" };
+    }
+    if (!token?.accessToken)
+        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]) => ({
         name,
         transport: def.transport,
-        auth: def.auth,
+        auth: isOAuthAuth(def.auth) ? "oauth" : undefined,
+        preRegisteredClient: oauthClientMetadata(def.auth).clientId !== undefined ? true : undefined,
+        ...(isOAuthAuth(def.auth) ? mcpCredentialState(homeDir, name) : {}),
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -148,7 +175,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.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)
@@ -175,6 +202,17 @@ export function parseMcpAddArgs(argv) {
         enabled: flag("--enabled"),
     };
 }
+export function parseMcpSetArgs(argv) {
+    const flag = (name) => {
+        const i = argv.indexOf(name);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    return {
+        auth: flag("--auth"),
+        clientId: flag("--client-id"),
+        clientSecretEnv: flag("--client-secret-env"),
+    };
+}
 function parseCsv(raw) {
     if (!raw)
         return undefined;
@@ -254,12 +292,54 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     }
     return { name, action: "create", detail: "will add to servers.yaml", def };
 }
-export function collectMcpSetAuthPlan(name, auth, homeDir = homedir()) {
-    const mode = auth === "oauth" || auth === "none" ? auth : undefined;
+/**
+ * Sets or clears the OAuth classification, and optionally the
+ * pre-registered client metadata that goes with it
+ * (trellis-mcp-oauth-static-client tasks.md 3.1).
+ *
+ * Three rules the flag interaction has to get right:
+ *   - A bare `--auth oauth` is a re-classification, not a reset: an entry
+ *     that already carries a `client_id` keeps it. Silently dropping
+ *     metadata here would turn "make sure this is OAuth" into "break my
+ *     Figma setup", which is exactly the kind of invisible precedence
+ *     `mcp set` exists to avoid.
+ *   - `--auth none` is the reset — it strips the whole `auth` key,
+ *     metadata included, because that is the only reading of "none" that
+ *     leaves the file in a self-consistent state.
+ *   - `--client-id` / `--client-secret-env` require an explicit
+ *     `--auth oauth` in the same invocation. Implying it would make a
+ *     typo'd flag name mutate the classification.
+ */
+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" };
-    if (!mode)
-        return { name, auth: "none", action: "invalid-input", detail: `--auth must be "oauth" or "none" (got ${auth ?? "(missing)"})` };
+        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";
+    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.
+        if (hasClientFlags)
+            return { name, auth: "none", action: "invalid-input", detail: clientFlagsDetail };
+        return { name, auth: "none", action: "invalid-input", detail: `--auth must be "oauth" or "none" (got ${raw.auth ?? "(missing)"})` };
+    }
+    if (hasClientFlags && mode !== "oauth") {
+        return { name, auth: mode, action: "invalid-input", detail: clientFlagsDetail };
+    }
+    if (raw.clientId === "") {
+        return { name, auth: mode, action: "invalid-input", detail: "--client-id must not be empty" };
+    }
+    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
+        // (design.md D2).
+        return {
+            name,
+            auth: mode,
+            action: "invalid-input",
+            detail: "--client-secret-env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value",
+        };
+    }
     const canonical = loadCanonicalSource(homeDir);
     const current = canonical.mcp.servers[name];
     if (!current)
@@ -267,19 +347,61 @@ export function collectMcpSetAuthPlan(name, auth, homeDir = homedir()) {
     if (mode === "oauth" && !current.url) {
         return { name, auth: mode, action: "invalid-input", detail: "auth: oauth requires an http or sse MCP server" };
     }
-    const next = mode === "oauth" ? { ...current, auth: "oauth" } : (() => {
+    // Same load-time guard as `assertAuthMetadataClean`, applied at write
+    // time so an offending value never reaches the file in the first place.
+    const offending = [
+        ["client-id", raw.clientId],
+        ["client-secret-env", raw.clientSecretEnv],
+    ].find(([, value]) => value !== undefined && canonical.secretsPolicy.rejectPatterns.some((pattern) => pattern.test(value)));
+    if (offending) {
+        return {
+            name,
+            auth: mode,
+            action: "invalid-input",
+            detail: `--${offending[0]} matches a secrets.policy.yaml reject pattern — client-id must be the provider-published id, client-secret-env a variable name; the offending value is intentionally not printed`,
+        };
+    }
+    let next;
+    if (mode === "none") {
         const { auth: _auth, ...withoutAuth } = current;
-        return withoutAuth;
-    })();
+        next = withoutAuth;
+    }
+    else if (!hasClientFlags && isOAuthAuth(current.auth)) {
+        // Already classified and no new metadata: a true no-op. Rewriting the
+        // scalar into a metadata-less object here would churn the file to say
+        // exactly what it already said (design.md D1 makes them equivalent).
+        next = current;
+    }
+    else if (!hasClientFlags) {
+        // Newly classified, nothing to record — the scalar is the documented
+        // shorthand, so write the smaller of two equivalent forms.
+        next = { ...current, auth: "oauth" };
+    }
+    else {
+        const existing = oauthClientMetadata(current.auth);
+        // Per-field override, not replacement: `--client-id` alone keeps a
+        // `client_secret_env` that is already configured.
+        const clientId = raw.clientId ?? existing.clientId;
+        const clientSecretEnv = raw.clientSecretEnv ?? existing.clientSecretEnv;
+        next = {
+            ...current,
+            auth: {
+                kind: "oauth",
+                ...(clientId !== undefined ? { clientId } : {}),
+                ...(clientSecretEnv !== undefined ? { clientSecretEnv } : {}),
+            },
+        };
+    }
     if (JSON.stringify(current) === JSON.stringify(next))
         return { name, auth: mode, action: "already-set", detail: `auth is already ${mode}`, def: next };
-    return { name, auth: mode, action: "updated", detail: `set auth to ${mode}`, def: next };
+    const changed = hasClientFlags ? " and client metadata" : "";
+    return { name, auth: mode, action: "updated", detail: `set auth to ${mode}${changed}`, def: next };
 }
-export function runMcpSetAuth(name, auth, opts = {}) {
+export function runMcpSetAuth(name, raw, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     let plan;
     try {
-        plan = collectMcpSetAuthPlan(name, auth, homeDir);
+        plan = collectMcpSetAuthPlan(name, raw, homeDir);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -302,6 +424,85 @@ export function runMcpSetAuth(name, auth, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
+/**
+ * `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.js

@@ -13,7 +13,9 @@ import { loadCanonicalSource } from "../core/canonical.js";
 import { discoverAuthorizationServer, parseResourceMetadataUrl } from "../lib/oauth/discovery.js";
 import { authorize } 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";
 export async function runMcpAuth(opts) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
@@ -72,13 +74,39 @@ async function authorizeServer(opts, homeDir) {
     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`);
     }
+    // Pre-registered client metadata from canonical (design.md D3): a
+    // `client_id` here means the RFC 7591 step is skipped entirely, which is
+    // the only way to authorize against a provider that refuses registration.
+    // The secret is resolved by NAME through the same policy machinery `env`
+    // uses, and the resolved value never leaves this call — it goes straight
+    // into `authorize`, which pairs it with the grant it persists.
+    const client = oauthClientMetadata(def.auth);
+    let clientSecret;
+    if (client.clientSecretEnv) {
+        const { [client.clientSecretEnv]: value } = resolveSecretEnv([client.clientSecretEnv], canonical.secretsPolicy);
+        if (value === undefined) {
+            throw new Error(`auth.client_secret_env is "${client.clientSecretEnv}", but no value for that variable was found in ${secretSourceLabel(canonical.secretsPolicy)} — set it there, or drop the field if this provider issues a public client`);
+        }
+        clientSecret = value;
+    }
     const token = await authorize(opts.serverName, metadata, {
         ...(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);
     return { server: opts.serverName, status: "authorized", tokenFile: file, ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}) };
 }
+/**
+ * Names where a declared secret was looked for, so an unresolvable name
+ * points at the file to edit. Mirrors `resolveSecretEnv`'s own two
+ * sources: an explicit `env_file` is the sole source when set, otherwise
+ * the ambient process environment.
+ */
+function secretSourceLabel(policy) {
+    return policy.envFile ? `${policy.envFile} (secrets.policy.yaml env_file)` : "the process environment (no env_file is set in secrets.policy.yaml)";
+}
 /**
  * An unauthenticated request to the resource, purely to read its
  * `WWW-Authenticate` challenge — the server naming its own authorization