agent-trellis 0.5.2 → 0.6.2

package/dist/adapters/codex.js

@@ -83,7 +83,10 @@ export class CodexAdapter {
             });
         }
         for (const conflict of conflicts) {
-            items.push({ action: "conflict", kind: "mcp", target: configTomlPath, description: conflict.message });
+            const item = { action: "conflict", kind: "mcp", target: configTomlPath, description: conflict.message };
+            if (conflict.remediation)
+                item.remediation = conflict.remediation;
+            items.push(item);
         }
         const desiredNames = new Set(desired.map((d) => d.name));
         const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);

package/dist/adapters/jsonMcp.js

@@ -50,7 +50,10 @@ export function planJsonMcp(opts) {
         });
     }
     for (const conflict of conflicts) {
-        items.push({ action: "conflict", kind: "mcp", target: configPath, description: conflict.message });
+        const item = { action: "conflict", kind: "mcp", target: configPath, description: conflict.message };
+        if (conflict.remediation)
+            item.remediation = conflict.remediation;
+        items.push(item);
     }
     const desiredNames = new Set(desired.map((d) => d.name));
     for (const [name, expected] of Object.entries(ownership ?? {})) {

package/dist/adapters/kiro.js

@@ -97,7 +97,15 @@ export class KiroAdapter {
                 parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
             }
             catch {
-                return [{ action: "conflict", kind: "kiro-approved-env-vars", target: settingsPath, description: `${settingsPath} is not valid JSON — refusing to touch it` }];
+                return [
+                    {
+                        action: "conflict",
+                        kind: "kiro-approved-env-vars",
+                        target: settingsPath,
+                        description: `${settingsPath} is not valid JSON — refusing to touch it`,
+                        remediation: `fix or restore valid JSON at ${settingsPath} (a backup under ~/.trellis/backups/ may have the last version Trellis wrote), then re-run sync`,
+                    },
+                ];
             }
             const current = parsed[APPROVED_ENV_VARS_KEY];
             if (Array.isArray(current)) {

package/dist/adapters/mcpPlan.d.ts

@@ -18,6 +18,18 @@
  */
 import type { AgentId, McpConfig, McpServerDef, SecretsPolicy } from "../core/types.js";
 export declare const HUB_ENTRY_NAME = "trellis-hub";
+export declare const GATEWAY_ENTRY_NAME = "trellis-gateway";
+/** The command an agent spawns in gateway mode. Bare `trellis` rather than
+ * an absolute path: the entry has to keep working across reinstalls and
+ * version bumps, and every agent resolves it through the same PATH the
+ * user installed the CLI onto. */
+export declare const GATEWAY_COMMAND = "trellis";
+/**
+ * Gateway mode applies to every managed agent when `agents` is omitted —
+ * the expected normal case (design.md D14). An explicit list narrows it,
+ * letting some agents stay in direct or hub mode.
+ */
+export declare function isGatewayAgent(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[]): boolean;
 export interface DesiredMcpEntry {
     name: string;
     def: McpServerDef;
@@ -25,9 +37,28 @@ export interface DesiredMcpEntry {
 export interface McpConflict {
     name: string;
     message: string;
+    /** The concrete next action, distinct from `message`'s restatement of
+     * why (trellis-onboard-closed-loop design.md D7). */
+    remediation?: string;
 }
 export interface McpPlanResult {
     desired: DesiredMcpEntry[];
     conflicts: McpConflict[];
 }
+/**
+ * Exported so `migrate`'s own read path (`src/commands/migrate.ts`) can
+ * apply the identical check on the way *into* canonical, not just on the
+ * way out to an agent's native config. Found via real-machine dogfooding:
+ * `migrate --from kiro --only mcp` happily copied a real, live
+ * `MCPR_TOKEN` literal into `~/.trellis/mcp/servers.yaml` because this
+ * check previously existed only here, in `resolveMcpPlan` — canonical
+ * itself was never guarded, only the sync-out boundary was. A canonical
+ * file that briefly held a real secret before a later `mcp sync` refused
+ * to propagate it further already violates "never write a literal
+ * secret, ever" — the write already happened, in a file meant to be
+ * read, diffed, and committed as plain text. One shared implementation,
+ * not two that can drift, for the same reason `mcpConnect.ts`/
+ * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ */
+export declare function findLiteralSecret(def: McpServerDef): string | undefined;
 export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -20,10 +20,32 @@ import { isInScope } from "../core/adapter.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
+export const GATEWAY_ENTRY_NAME = "trellis-gateway";
+/** The command an agent spawns in gateway mode. Bare `trellis` rather than
+ * an absolute path: the entry has to keep working across reinstalls and
+ * version bumps, and every agent resolves it through the same PATH the
+ * user installed the CLI onto. */
+export const GATEWAY_COMMAND = "trellis";
+/**
+ * Gateway mode applies to every managed agent when `agents` is omitted —
+ * the expected normal case (design.md D14). An explicit list narrows it,
+ * letting some agents stay in direct or hub mode.
+ */
+export function isGatewayAgent(agentId, mcp, managedAgents) {
+    const gateway = mcp.gateway;
+    if (!gateway?.enabled)
+        return false;
+    if (gateway.agents)
+        return gateway.agents.includes(agentId);
+    return managedAgents.includes(agentId);
+}
 const CODEX_STDIO_URL_CRASH_NOTE = ' On Codex specifically, this crashes the entire process at startup ("url is not supported for stdio"), not just this one server — see docs/research.md.';
 function collisionMessage(name, agentId) {
     return `refusing to write MCP server "${name}": also appears in known_host_injected.${agentId === "codex" ? CODEX_STDIO_URL_CRASH_NOTE : ""}`;
 }
+function collisionRemediation(name) {
+    return `rename this server in servers.yaml, or remove "${name}" from known_host_injected if it's no longer actually host-injected on this machine`;
+}
 /**
  * Known-dangerous literal patterns (design.md D5) — mirrors
  * schema/secrets.policy.example.yaml's own examples. A narrow, hardcoded
@@ -35,7 +57,22 @@ const DANGEROUS_LITERAL_PATTERNS = [
     { label: "GitHub personal access token (ghp_)", pattern: /ghp_/ },
     { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ },
 ];
-function findLiteralSecret(def) {
+/**
+ * Exported so `migrate`'s own read path (`src/commands/migrate.ts`) can
+ * apply the identical check on the way *into* canonical, not just on the
+ * way out to an agent's native config. Found via real-machine dogfooding:
+ * `migrate --from kiro --only mcp` happily copied a real, live
+ * `MCPR_TOKEN` literal into `~/.trellis/mcp/servers.yaml` because this
+ * check previously existed only here, in `resolveMcpPlan` — canonical
+ * itself was never guarded, only the sync-out boundary was. A canonical
+ * file that briefly held a real secret before a later `mcp sync` refused
+ * to propagate it further already violates "never write a literal
+ * secret, ever" — the write already happened, in a file meant to be
+ * read, diffed, and committed as plain text. One shared implementation,
+ * not two that can drift, for the same reason `mcpConnect.ts`/
+ * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ */
+export function findLiteralSecret(def) {
     const candidates = [def.command, def.url, ...(def.args ?? []), ...Object.values(def.headers ?? {}), ...Object.values(def.staticEnv ?? {})].filter((v) => typeof v === "string");
     for (const candidate of candidates) {
         for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
@@ -69,9 +106,33 @@ function findUnresolvedEnvName(def, policy) {
     return names.find((name) => !resolved[name]);
 }
 export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+    // Checked before `hub`: only one entry can be "the" MCP entry for an
+    // agent, and gateway is the newer, purpose-built path (design.md D6).
+    // `hub` stays available, unchanged, for anyone pointing an agent at an
+    // externally-operated endpoint — including a different agent in the
+    // same canonical source.
+    if (isGatewayAgent(agentId, mcp, managedAgents)) {
+        if (mcp.knownHostInjected.includes(GATEWAY_ENTRY_NAME)) {
+            return {
+                desired: [],
+                conflicts: [{ name: GATEWAY_ENTRY_NAME, message: collisionMessage(GATEWAY_ENTRY_NAME, agentId), remediation: collisionRemediation(GATEWAY_ENTRY_NAME) }],
+            };
+        }
+        // Every per-server check (enabled, scope, literal secrets, unresolved
+        // env names, Codex's header shape) still runs — but at gateway
+        // *startup*, inside the subcommand, since no adapter sees an
+        // individual server in this mode (design.md D6).
+        return {
+            desired: [{ name: GATEWAY_ENTRY_NAME, def: { transport: "stdio", command: GATEWAY_COMMAND, args: ["mcp-gateway", "--agent", agentId] } }],
+            conflicts: [],
+        };
+    }
     if (mcp.hub) {
         if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
-            return { desired: [], conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId) }] };
+            return {
+                desired: [],
+                conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId), remediation: collisionRemediation(HUB_ENTRY_NAME) }],
+            };
         }
         return { desired: [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }], conflicts: [] };
     }
@@ -85,7 +146,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             continue;
         }
         if (mcp.knownHostInjected.includes(name)) {
-            conflicts.push({ name, message: collisionMessage(name, agentId) });
+            conflicts.push({ name, message: collisionMessage(name, agentId), remediation: collisionRemediation(name) });
             continue;
         }
         const secretLabel = findLiteralSecret(def);
@@ -93,6 +154,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+                remediation: `replace the literal value in servers.yaml with a \`\${VAR_NAME}\` reference and put the real value wherever secrets.policy.yaml resolves it from`,
             });
             continue;
         }
@@ -105,6 +167,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}" for codex: its "headers" field isn't the single { Authorization: "Bearer \${VAR}" } shape Codex's own config format can express — Codex has no generic headers concept, only \`bearer_token_env_var\`. Still written normally for every other in-scope agent.`,
+                remediation: `reduce this server's headers to a single Authorization bearer token for Codex, enable gateway mode for Codex (which resolves headers itself and never hits this check), or accept that this server stays unreachable from Codex`,
             });
             continue;
         }
@@ -114,6 +177,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}": its declared env var "${unresolvedName}" has no resolvable value in ${source} — writing it now would silently break this server's connection once the agent starts it (trellis-mcp-static-env-and-disabled-servers)`,
+                remediation: `set "${unresolvedName}" in ${source}, or fix the name in servers.yaml if it was a typo, then re-run mcp sync`,
             });
             continue;
         }

package/dist/adapters/symlinkPlan.js

@@ -56,6 +56,9 @@ export function planSymlinks(opts) {
                     description: isForeign
                         ? `${path} exists as a symlink to ${readlinkSync(path)}, not owned by Trellis — left untouched`
                         : `${path} exists and is not a Trellis-managed symlink — left untouched`,
+                    remediation: isForeign
+                        ? `remove the existing symlink at ${path} if you want Trellis to manage it, then re-run sync — otherwise leave it, Trellis will not touch it`
+                        : `back up ${path}'s real content if you need it, remove the file, then re-run sync — Trellis will not overwrite or merge into an existing real file`,
                 });
                 continue;
             }

package/dist/cli.js

@@ -10,12 +10,14 @@ import { runMigrate } from "./commands/migrate.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
 import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, parseMcpAddArgs } from "./commands/mcp.js";
+import { parseMcpGatewayArgs, runMcpGateway } 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 } from "./commands/skill.js";
 import { runMemoryExtraction, runMemorySync } from "./commands/memory.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "skill", "memory", "secrets", "rollback"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "mcp-gateway", "skill", "memory", "secrets", "rollback"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
@@ -36,6 +38,16 @@ Commands:
                                     means "add nothing new this run"
                                     (required with no terminal to prompt
                                     in, e.g. --json)
+              --mcp-mode <direct|hub|gateway>
+                                    change the MCP mode; omit to leave
+                                    whatever's already configured
+                                    untouched (never prompted)
+              --hub-url <url>       required with --mcp-mode hub
+              --gateway-agents <ids>
+                                    optional with --mcp-mode gateway;
+                                    omit for every managed agent
+              --memory <on|off>     enable/disable the shared memory MCP
+                                    server; omit to leave it untouched
               --dry-run             preview the whole flow, write nothing
               --json                machine-readable output, no report text
   init      Create ~/.trellis/ with a minimal valid skeleton if missing
@@ -77,6 +89,14 @@ Commands:
               [--enabled true|false]
               --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
+              ~/.trellis/mcp/oauth/. A still-valid token is a no-op; an
+              expired one is refreshed without a browser. The gateway
+              refreshes silently on its own and never prompts.
+              --force   re-authorize even if the stored token is valid
+              --json    machine-readable output, no report text
   mcp remove <name>
             Remove a canonical MCP server (canonical-side only — does
               not touch any agent's already-synced native config)
@@ -145,7 +165,24 @@ async function main(argv) {
         const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;
         const manageIndex = rest.indexOf("--manage");
         const manage = manageIndex >= 0 ? rest[manageIndex + 1] : undefined;
-        const { exitCode } = await runOnboard({ agent, manage, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
+        const mcpModeIndex = rest.indexOf("--mcp-mode");
+        const mcpMode = mcpModeIndex >= 0 ? rest[mcpModeIndex + 1] : undefined;
+        const hubUrlIndex = rest.indexOf("--hub-url");
+        const hubUrl = hubUrlIndex >= 0 ? rest[hubUrlIndex + 1] : undefined;
+        const gatewayAgentsIndex = rest.indexOf("--gateway-agents");
+        const gatewayAgents = gatewayAgentsIndex >= 0 ? rest[gatewayAgentsIndex + 1] : undefined;
+        const memoryIndex = rest.indexOf("--memory");
+        const memory = memoryIndex >= 0 ? rest[memoryIndex + 1] : undefined;
+        const { exitCode } = await runOnboard({
+            agent,
+            manage,
+            mcpMode,
+            hubUrl,
+            gatewayAgents,
+            memory,
+            dryRun: rest.includes("--dry-run"),
+            json: rest.includes("--json"),
+        });
         process.exitCode = exitCode;
         return;
     }
@@ -168,6 +205,20 @@ async function main(argv) {
         process.exitCode = exitCode;
         return;
     }
+    // Spawned by an agent, never typed by a person: stdout is the MCP
+    // protocol stream for the rest of this process's life, so nothing here
+    // may print to it (trellis-mcp-gateway-hosting design.md D2).
+    if (command === "mcp-gateway") {
+        const parsed = parseMcpGatewayArgs(rest);
+        if ("error" in parsed) {
+            console.error(parsed.error);
+            process.exitCode = 1;
+            return;
+        }
+        const { exitCode } = await runMcpGateway({ agentId: parsed.agentId });
+        process.exitCode = exitCode;
+        return;
+    }
     if (command === "sync") {
         const { target, unknownArg } = parseSyncArgs(rest);
         if (unknownArg) {
@@ -208,7 +259,18 @@ async function main(argv) {
             process.exitCode = runMcpRemove(name, { json, dryRun }).exitCode;
             return;
         }
-        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|remove <name>\n`);
+        if (subcommand === "auth") {
+            const [serverName] = mcpRest;
+            if (!serverName || serverName.startsWith("--")) {
+                console.error("Usage: trellis mcp auth <server-name>");
+                process.exitCode = 1;
+                return;
+            }
+            const { exitCode } = await runMcpAuth({ serverName, force: mcpRest.includes("--force"), json });
+            process.exitCode = exitCode;
+            return;
+        }
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|remove <name>|auth <name>\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/doctor.d.ts

@@ -57,9 +57,15 @@ export declare function resolveKnownHostInjected(opts: RunDoctorOptions): readon
 export declare function runDoctor(opts?: RunDoctorOptions): Promise<{
     exitCode: number;
 }>;
-/** Exported separately from `runDoctor` so tests can assert on findings
- * without capturing stdout. */
-export declare function collectDoctorReport(knownHostInjected?: readonly string[], probeMcp?: boolean): Promise<DoctorReport>;
+/**
+ * Exported separately from `runDoctor` so tests can assert on findings
+ * without capturing stdout — and, since trellis-onboard-closed-loop,
+ * so `trellis onboard` can call this against the scratch home its own
+ * tests use. `homeDir` defaults to the real `~` so `runDoctor`'s
+ * existing call site (which now passes `opts.homeDir`, itself normally
+ * `undefined`) is unaffected.
+ */
+export declare function collectDoctorReport(homeDir?: string, knownHostInjected?: readonly string[], probeMcp?: boolean): Promise<DoctorReport>;
 /**
  * Within one agent, across all of its skill roots: any realpath reached by
  * more than one entry, where at least one of those entries is NOT a
@@ -86,3 +92,7 @@ export declare function detectCrossAgentDrift(snapshots: AgentSnapshot[]): Findi
 export declare function detectCaseMismatches(snapshots: AgentSnapshot[]): Finding[];
 export declare function detectParseDiagnostics(snapshots: AgentSnapshot[]): Finding[];
 export declare function detectMcpUnreachable(snapshots: AgentSnapshot[]): Finding[];
+/** Exported so `trellis onboard` can reuse it verbatim for its own final
+ * stage (trellis-onboard-closed-loop) rather than a second copy of this
+ * formatting. */
+export declare function printReport(report: DoctorReport): void;

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@
  * current state against each other, the same manual process used
  * throughout docs/research.md's investigation, now formalized.
  */
+import { homedir } from "node:os";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
@@ -47,24 +48,30 @@ export function resolveKnownHostInjected(opts) {
     }
 }
 export async function runDoctor(opts = {}) {
-    const report = await collectDoctorReport(resolveKnownHostInjected(opts), opts.probeMcp);
+    const report = await collectDoctorReport(opts.homeDir, resolveKnownHostInjected(opts), opts.probeMcp);
     const exitCode = report.findings.some((f) => EXIT_NONZERO_KINDS.has(f.kind)) ? 1 : 0;
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printTable(report);
+        printReport(report);
     }
     return { exitCode };
 }
-/** Exported separately from `runDoctor` so tests can assert on findings
- * without capturing stdout. */
-export async function collectDoctorReport(knownHostInjected = DEFAULT_KNOWN_HOST_INJECTED, probeMcp = false) {
+/**
+ * Exported separately from `runDoctor` so tests can assert on findings
+ * without capturing stdout — and, since trellis-onboard-closed-loop,
+ * so `trellis onboard` can call this against the scratch home its own
+ * tests use. `homeDir` defaults to the real `~` so `runDoctor`'s
+ * existing call site (which now passes `opts.homeDir`, itself normally
+ * `undefined`) is unaffected.
+ */
+export async function collectDoctorReport(homeDir = homedir(), knownHostInjected = DEFAULT_KNOWN_HOST_INJECTED, probeMcp = false) {
     const probeList = [
-        { agent: "claude-code", run: () => claudeCodeProbe.probe(undefined, { probeMcp }) },
-        { agent: "codex", run: () => codexProbe.probe(undefined, { probeMcp }) },
-        { agent: "kiro", run: () => kiroProbe.probe(undefined, { probeMcp }) },
-        { agent: "pi", run: piProbe.probe },
+        { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir, { probeMcp }) },
+        { agent: "codex", run: () => codexProbe.probe(homeDir, { probeMcp }) },
+        { agent: "kiro", run: () => kiroProbe.probe(homeDir, { probeMcp }) },
+        { agent: "pi", run: () => piProbe.probe(homeDir) },
     ];
     // One agent erroring must not blank the other three's results.
     const settled = await Promise.allSettled(probeList.map((p) => p.run()));
@@ -226,7 +233,10 @@ export function detectMcpUnreachable(snapshots) {
     }
     return findings;
 }
-function printTable(report) {
+/** Exported so `trellis onboard` can reuse it verbatim for its own final
+ * stage (trellis-onboard-closed-loop) rather than a second copy of this
+ * formatting. */
+export function printReport(report) {
     const byAgent = new Map();
     const crossAgent = [];
     for (const finding of report.findings) {

package/dist/commands/mcpAuth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `trellis mcp auth <server-name>` — the one piece of the OAuth story
+ * that genuinely requires a human (trellis-mcp-gateway-hosting design.md
+ * D9).
+ *
+ * The initial authorization-code exchange needs a real browser and a
+ * loopback callback, so it only makes sense as an explicit, one-time
+ * command. Everything after it — silently refreshing an expired token —
+ * happens inside the gateway, which never reaches this file.
+ */
+export interface RunMcpAuthOptions {
+    serverName: string;
+    /** Re-authorize even when a valid token is already stored. */
+    force?: boolean;
+    json?: boolean;
+    homeDir?: string;
+    /** Test seam — the real one launches the platform browser. */
+    openBrowser?: (url: string) => void | Promise<void>;
+}
+export interface McpAuthResult {
+    server: string;
+    status: "authorized" | "already-valid" | "refreshed";
+    tokenFile: string;
+    expiresAt?: number;
+}
+export declare function runMcpAuth(opts: RunMcpAuthOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/mcpAuth.js

@@ -0,0 +1,99 @@
+/**
+ * `trellis mcp auth <server-name>` — the one piece of the OAuth story
+ * that genuinely requires a human (trellis-mcp-gateway-hosting design.md
+ * D9).
+ *
+ * The initial authorization-code exchange needs a real browser and a
+ * loopback callback, so it only makes sense as an explicit, one-time
+ * command. Everything after it — silently refreshing an expired token —
+ * happens inside the gateway, which never reaches this file.
+ */
+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 { ensureFreshToken } from "../lib/oauth/refresh.js";
+import { isExpired, readToken, tokenPath, writeToken } from "../lib/oauth/store.js";
+export async function runMcpAuth(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = await authorizeServer(opts, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        const detail = result.expiresAt ? ` (expires ${new Date(result.expiresAt).toISOString()})` : "";
+        const verb = result.status === "already-valid"
+            ? "already has a valid token"
+            : result.status === "refreshed"
+                ? "token refreshed"
+                : "authorized";
+        console.log(`✅ ${result.server} — ${verb}${detail}`);
+        console.log(`   credentials: ${result.tokenFile}`);
+    }
+    return { exitCode: 0 };
+}
+async function authorizeServer(opts, homeDir) {
+    const canonical = loadCanonicalSource(homeDir);
+    const def = canonical.mcp.servers[opts.serverName];
+    if (!def) {
+        throw new Error(`no MCP server named "${opts.serverName}" in ~/.trellis/mcp/servers.yaml`);
+    }
+    if (!def.url) {
+        // stdio servers authenticate through `env`/`envAliases`, which is a
+        // different mechanism entirely — there is nothing to authorize here,
+        // and pretending otherwise would send someone hunting for a browser
+        // 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.`);
+    }
+    const file = tokenPath(homeDir, opts.serverName);
+    if (!opts.force) {
+        const existing = readToken(homeDir, opts.serverName);
+        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) {
+            // Expired but renewable — no browser needed.
+            const refreshed = await ensureFreshToken(homeDir, opts.serverName);
+            if (refreshed) {
+                return { server: opts.serverName, status: "refreshed", tokenFile: file, ...(refreshed.expiresAt ? { expiresAt: refreshed.expiresAt } : {}) };
+            }
+        }
+    }
+    const metadata = await discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def) });
+    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`);
+    }
+    const token = await authorize(opts.serverName, metadata, {
+        ...(opts.openBrowser ? { openBrowser: opts.openBrowser } : {}),
+        ...(metadata.scopesSupported?.length ? { scope: metadata.scopesSupported.join(" ") } : {}),
+    });
+    writeToken(homeDir, opts.serverName, token);
+    return { server: opts.serverName, status: "authorized", tokenFile: file, ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}) };
+}
+/**
+ * An unauthenticated request to the resource, purely to read its
+ * `WWW-Authenticate` challenge — the server naming its own authorization
+ * server directly, which beats probing well-known paths. Failure is not
+ * an error: discovery falls back to probing.
+ */
+async function probeWwwAuthenticate(def) {
+    try {
+        const response = await fetch(def.url, { method: "GET" });
+        if (response.status !== 401)
+            return null;
+        const header = response.headers.get("www-authenticate");
+        return parseResourceMetadataUrl(header) ? header : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/mcpGateway.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `trellis mcp-gateway --agent <id>` — the stdio MCP server an agent
+ * spawns in gateway mode (trellis-mcp-gateway-hosting).
+ *
+ * Not a user-facing command in the usual sense: nobody types this. An
+ * agent's own MCP client spawns it exactly the way it spawns any other
+ * stdio server, talks to it for the session, and closes the pipe on exit
+ * (design.md D2). There is no daemon, no lifecycle command, and nothing
+ * for the user to notice.
+ *
+ * This file depends on `GatewayBackend` and nothing below it — no
+ * connection, no transport, no server definition (design.md D11). That is
+ * what lets v2 point the same stdio edge at one shared service instead of
+ * an in-process backend without this file, or any agent's config,
+ * changing.
+ */
+import { loadCanonicalSource } from "../core/canonical.js";
+import { type GatewayBackend, type UpstreamSpec } from "../lib/gatewayBackend.js";
+import type { AgentId } from "../core/types.js";
+export interface RunMcpGatewayOptions {
+    agentId: AgentId;
+    /** Test seams, exactly as every other Trellis entry point exposes them. */
+    homeDir?: string;
+    connectTimeoutMs?: number;
+    /** Injected so tests can drive the protocol edge without real upstreams,
+     * and so v2 can substitute a forwarding backend (design.md D11). */
+    backendFactory?: (upstreams: UpstreamSpec[], homeDir: string) => Promise<GatewayBackend>;
+}
+export declare function parseMcpGatewayArgs(argv: readonly string[]): {
+    agentId: AgentId;
+} | {
+    error: string;
+};
+/**
+ * The in-scope upstream set for this agent, resolved through the very same
+ * `resolveMcpPlan` that direct mode uses — per-server `agents:` scope,
+ * `enabled: false`, host-injected collisions, literal-secret refusals and
+ * unresolved `env` names all apply here identically, because it is
+ * literally the same function (design.md D6).
+ *
+ * The one thing that must be stripped is gateway mode itself: asking
+ * `resolveMcpPlan` for this agent's plan while gateway mode is on would
+ * answer "one entry, pointing at the gateway" — the gateway being told to
+ * connect to itself. Resolving against a gateway-less view of the same
+ * canonical gives the set gateway mode replaced.
+ */
+export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): {
+    upstreams: UpstreamSpec[];
+    conflicts: string[];
+};
+export declare function runMcpGateway(opts: RunMcpGatewayOptions): Promise<{
+    exitCode: number;
+}>;