agent-trellis 0.9.1 → 0.10.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,7 +9,7 @@ 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, parseMcpAddArgs, parseMcpSetArgs } from "./commands/mcp.js";
 import { runMcpImport } from "./commands/mcpImport.js";
 import { parseMcpGatewayArgs, runMcpGateway, runMcpRuntime } from "./commands/mcpGateway.js";
 import { runMcpAuth } from "./commands/mcpAuth.js";
@@ -131,7 +131,15 @@ 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 auth <server-name>
@@ -429,9 +437,7 @@ 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 === "remove") {

package/dist/commands/mcp.d.ts

@@ -52,7 +52,16 @@ 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;
     enabled: boolean;
     agents: readonly AgentId[];
     command?: string;
@@ -98,6 +107,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,8 +132,37 @@ 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;

package/dist/commands/mcp.js

@@ -16,7 +16,8 @@ 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 { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
@@ -118,7 +119,8 @@ export function collectMcpListPlan(homeDir = 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,
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -148,7 +150,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.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 +177,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 +267,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 +322,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));

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

package/dist/core/canonical.d.ts

@@ -10,13 +10,23 @@ import type { BackupSession } from "../lib/backup.js";
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
  * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
- * below; every other field happens to already be a single word, so no
- * server-def field needed this treatment before
- * (trellis-mcp-static-env-and-disabled-servers, trellis-migrate-env-var-alias).
+ * below, and `auth`'s object form carries `client_id`/`client_secret_env`
+ * the same way (trellis-mcp-static-env-and-disabled-servers,
+ * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client).
  */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases"> & {
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
     static_env?: Record<string, string>;
     env_aliases?: Record<string, string>;
+    auth?: McpAuthYaml;
+};
+/** The on-disk `auth`: the `oauth` scalar exactly as before, or the object
+ * form whose keys are snake_case like every other multi-word key in
+ * `.trellis/*.yaml`. Values are `unknown` until `fromAuthYaml` validates
+ * them — a YAML cast is optimistic, validation is this module's job. */
+type McpAuthYaml = string | {
+    kind?: unknown;
+    client_id?: unknown;
+    client_secret_env?: unknown;
 };
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`
@@ -127,13 +137,6 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * `export` prefix of its own.
  */
 export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
-/**
- * `homeDir` defaults to the real `~` and is only ever overridden for tests
- * and `scripts/sandbox.sh` — the same seam P0's probes use
- * (src/probes/*.ts) and for the same reason: never touch a developer's
- * real dotfiles from a test. It is not a workspace/project root — see
- * specs/canonical-source-loading's global-only requirement, which this
- * parameter does not weaken.
- */
+/** Load the global canonical source from the supplied home directory. */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
 export {};

package/dist/core/canonical.js

@@ -8,26 +8,75 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
-import { ALL_AGENTS } from "./types.js";
-function fromServerDefYaml(def) {
-    const { static_env, env_aliases, ...rest } = def;
+import { ALL_AGENTS, oauthClientMetadata } from "./types.js";
+import { isValidSecretVarName } from "../lib/secretEnv.js";
+function fromServerDefYaml(serverName, def) {
+    const { static_env, env_aliases, auth, ...rest } = def;
     const out = { ...rest };
     if (static_env)
         out.staticEnv = static_env;
     if (env_aliases)
         out.envAliases = env_aliases;
+    if (auth !== undefined)
+        out.auth = fromAuthYaml(serverName, auth);
+    return out;
+}
+/**
+ * `auth` translation and shape validation
+ * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
+ * object form share one discriminator — `kind: oauth` — and the object
+ * accepts exactly `kind`, `client_id`, `client_secret_env`. Everything
+ * else is refused here at load, naming the field but never echoing the
+ * value: an invalid `client_secret_env` is at best a typo, at worst a
+ * pasted secret.
+ */
+function fromAuthYaml(serverName, auth) {
+    if (auth === "oauth")
+        return "oauth";
+    if (typeof auth !== "object" || auth === null) {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
+    }
+    const { kind, client_id, client_secret_env, ...extra } = auth;
+    const unknownKey = Object.keys(extra)[0];
+    if (unknownKey !== undefined) {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, client_id, client_secret_env`);
+    }
+    if (kind !== "oauth") {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
+    }
+    if (client_id !== undefined && typeof client_id !== "string") {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_id must be a string`);
+    }
+    if (client_secret_env !== undefined && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
+    }
+    const out = { kind: "oauth" };
+    if (typeof client_id === "string")
+        out.clientId = client_id;
+    if (typeof client_secret_env === "string")
+        out.clientSecretEnv = client_secret_env;
     return out;
 }
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`
  * for an omitted optional. */
 export function toServerDefYaml(def) {
-    const { staticEnv, envAliases, ...rest } = def;
+    const { staticEnv, envAliases, auth, ...rest } = def;
     const out = { ...rest };
     if (staticEnv)
         out.static_env = staticEnv;
     if (envAliases)
         out.env_aliases = envAliases;
+    if (auth !== undefined) {
+        out.auth =
+            typeof auth === "string"
+                ? auth
+                : {
+                    kind: auth.kind,
+                    ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
+                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
+                };
+    }
     for (const key of Object.keys(out)) {
         if (out[key] === undefined)
             delete out[key];
@@ -83,7 +132,7 @@ function loadServersYaml(path) {
         return { servers: {}, knownHostInjected: [] };
     }
     const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
-    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
+    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(name, def)]));
     return {
         servers,
         knownHostInjected: parsed.known_host_injected ?? [],
@@ -452,7 +501,7 @@ export function ensureShellEnvSource(rcPath, envFilePath, backup) {
  * all managed agents by default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
 /** Missing file and `agents: []` both resolve to `[]` — zero managed
- * agents (D1), never "everyone." An unrecognized id is dropped with a
+ * agents, never "everyone." An unrecognized id is dropped with a
  * diagnostic, same posture as an unrecognized scope.yaml agent id. */
 function loadManagedYaml(path, diagnostics) {
     if (!existsSync(path)) {
@@ -480,17 +529,36 @@ function validAgentIds(scope) {
     return scope.every((id) => ALL_AGENTS.includes(id));
 }
 /**
- * `homeDir` defaults to the real `~` and is only ever overridden for tests
- * and `scripts/sandbox.sh` — the same seam P0's probes use
- * (src/probes/*.ts) and for the same reason: never touch a developer's
- * real dotfiles from a test. It is not a workspace/project root — see
- * specs/canonical-source-loading's global-only requirement, which this
- * parameter does not weaken.
+ * Load-time literal-value scan for OAuth client metadata
+ * (trellis-mcp-oauth-static-client task 1.2). `secrets audit` reports
+ * whole-file pattern hits as findings; this check goes further for the
+ * two fields a pasted secret is most likely to reach and refuses the
+ * load outright — the offending server and field are named, the value
+ * never printed.
  */
+function assertAuthMetadataClean(mcp, policy) {
+    for (const [name, def] of Object.entries(mcp.servers)) {
+        const meta = oauthClientMetadata(def.auth);
+        const fields = [
+            ["client_id", meta.clientId],
+            ["client_secret_env", meta.clientSecretEnv],
+        ];
+        for (const [field, value] of fields) {
+            if (value === undefined)
+                continue;
+            for (const pattern of policy.rejectPatterns) {
+                if (pattern.test(value)) {
+                    throw new Error(`mcp/servers.yaml: "${name}" auth.${field} 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`);
+                }
+            }
+        }
+    }
+}
+/** Load the global canonical source from the supplied home directory. */
 export function loadCanonicalSource(homeDir = homedir()) {
     const root = trellisRoot(homeDir);
     if (!existsSync(root)) {
-        throw new Error(`No canonical source at ${root}. Create it before running trellis sync — see docs/architecture.md's canonical schema.`);
+        throw new Error(`No canonical source at ${root}. Run trellis init before trellis sync.`);
     }
     const diagnostics = [];
     const managedAgents = loadManagedYaml(join(root, "managed.yaml"), diagnostics);
@@ -527,17 +595,17 @@ export function loadCanonicalSource(homeDir = homedir()) {
             }
         }
     }
+    const mcp = loadServersYaml(join(root, "mcp", "servers.yaml"));
+    const secretsPolicy = loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir);
+    assertAuthMetadataClean(mcp, secretsPolicy);
     return {
         instructionsFile: join(root, "agents.md"),
         managedAgents,
         skills,
         agents,
         memories,
-        mcp: loadServersYaml(join(root, "mcp", "servers.yaml")),
-        // P2's pre-write guard (src/adapters/mcpPlan.ts) uses its own narrow,
-        // hardcoded floor instead of this field — see design.md D1 in
-        // trellis-secrets-audit-p3.
-        secretsPolicy: loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir),
+        mcp,
+        secretsPolicy,
         diagnostics,
     };
 }

package/dist/core/types.d.ts

@@ -6,6 +6,29 @@
  */
 export type Transport = "stdio" | "http" | "sse";
 export type McpAuthMode = "oauth";
+/**
+ * Object form of the OAuth classification (trellis-mcp-oauth-static-client
+ * design.md D1). `kind` is the only discriminator; `client_id` is a public
+ * literal by design; `client_secret_env` is a variable NAME resolved
+ * through the secrets policy at authorization time. There is deliberately
+ * no field for a secret value in any form.
+ */
+export interface McpAuthConfig {
+    kind: McpAuthMode;
+    clientId?: string;
+    clientSecretEnv?: string;
+}
+/** True when `auth` classifies the server as OAuth, in either form. Every
+ * former `def.auth === "oauth"` check must go through this now that the
+ * object form exists — a strict-equality check would silently strip the
+ * OAuth routing from metadata-bearing servers. */
+export declare function isOAuthAuth(auth: McpAuthMode | McpAuthConfig | undefined): boolean;
+/** The pre-registered client metadata a classification carries. A scalar
+ * carries none — both forms route identically (design.md D1). */
+export declare function oauthClientMetadata(auth: McpAuthMode | McpAuthConfig | undefined): {
+    clientId?: string;
+    clientSecretEnv?: string;
+};
 export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code" | "zcode";
 export declare const ALL_AGENTS: readonly AgentId[];
 /**
@@ -28,8 +51,11 @@ export declare function resolveScope(scope: Scope, managedAgents: readonly Agent
 export interface McpServerDef {
     transport: Transport;
     /** Explicit authorization classification. Absence means ordinary MCP;
-     * Trellis never infers OAuth from a URL or a transient 401. */
-    auth?: McpAuthMode;
+     * Trellis never infers OAuth from a URL or a transient 401. The scalar
+     * form and a metadata-less object are equivalent — metadata extends the
+     * authorization flow, it never changes routing
+     * (trellis-mcp-oauth-static-client design.md D1). */
+    auth?: McpAuthMode | McpAuthConfig;
     /** stdio only */
     command?: string;
     args?: string[];

package/dist/core/types.js

@@ -4,6 +4,25 @@
  * for what a "canonical source" object looks like in memory; the YAML/MD
  * files on disk are its serialization, not the other way around.
  */
+/** True when `auth` classifies the server as OAuth, in either form. Every
+ * former `def.auth === "oauth"` check must go through this now that the
+ * object form exists — a strict-equality check would silently strip the
+ * OAuth routing from metadata-bearing servers. */
+export function isOAuthAuth(auth) {
+    return auth === "oauth" || (typeof auth === "object" && auth !== null && auth.kind === "oauth");
+}
+/** The pre-registered client metadata a classification carries. A scalar
+ * carries none — both forms route identically (design.md D1). */
+export function oauthClientMetadata(auth) {
+    if (typeof auth !== "object" || auth === null)
+        return {};
+    const meta = {};
+    if (auth.clientId !== undefined)
+        meta.clientId = auth.clientId;
+    if (auth.clientSecretEnv !== undefined)
+        meta.clientSecretEnv = auth.clientSecretEnv;
+    return meta;
+}
 export const ALL_AGENTS = [
     "claude-code",
     "codex",