agent-trellis 0.4.0 → 0.6.0

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

@@ -7,6 +7,7 @@
  * through untouched.
  */
 import { deepEqual } from "../lib/deepEqual.js";
+import { resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { resolveMcpPlan } from "./mcpPlan.js";
 /** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
  * expects — `env` names render as `${VAR}` references, `staticEnv`
@@ -23,8 +24,7 @@ export function renderJsonServerEntry(def) {
         return entry;
     }
     const entry = { type: "stdio", command: def.command, args: def.args ?? [] };
-    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
-    const env = { ...nameRefs, ...(def.staticEnv ?? {}) };
+    const env = resolvedEnvTextMap(def);
     if (Object.keys(env).length > 0) {
         entry.env = env;
     }
@@ -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,6 +37,9 @@ 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[];

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
@@ -53,18 +75,49 @@ function findLiteralSecret(def) {
  * proposal.md "Why"). Uses the identical `resolveSecretEnv` `secrets
  * audit`/the pi bridge already call, so this and a later `secrets audit`
  * run can never disagree about what resolves.
+ *
+ * `envAliases`' values are themselves source variable names needing the
+ * exact same resolution — checked in the same pass so a differently-named
+ * reference gets the same pre-write refusal `env` already has, naming the
+ * unresolved *source* name (what the caller must find a value for), not
+ * the target key it would have been written under
+ * (trellis-migrate-env-var-alias).
  */
 function findUnresolvedEnvName(def, policy) {
-    const names = def.env ?? [];
+    const names = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
     if (names.length === 0)
         return undefined;
     const resolved = resolveSecretEnv(names, 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: [] };
     }
@@ -78,7 +131,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);
@@ -86,6 +139,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;
         }
@@ -98,6 +152,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;
         }
@@ -107,6 +162,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 { runMemorySync } from "./commands/memory.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
 
@@ -77,6 +79,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)
@@ -104,6 +114,14 @@ Commands:
               or relation this didn't create.
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
+  memory extract
+            The reverse direction: read the same graph file's real,
+              non-Trellis entities (agent-accumulated content, never
+              Trellis's own) and write each as a new canonical
+              memories/*.md file — readable markdown, not meant to
+              round-trip byte-for-byte back through memory sync.
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   secrets audit
             Scan each present agent's real MCP config for leaked
             credentials and unexpected env var names
@@ -160,6 +178,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) {
@@ -200,7 +232,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;
     }
@@ -240,13 +283,18 @@ async function main(argv) {
     }
     if (command === "memory") {
         const [subcommand, ...memoryRest] = rest;
-        if (subcommand !== "sync") {
-            console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync\n`);
-            process.exitCode = 1;
+        const json = memoryRest.includes("--json");
+        const dryRun = memoryRest.includes("--dry-run");
+        if (subcommand === "sync") {
+            process.exitCode = runMemorySync({ json, dryRun }).exitCode;
             return;
         }
-        const { exitCode } = runMemorySync({ json: memoryRest.includes("--json"), dryRun: memoryRest.includes("--dry-run") });
-        process.exitCode = exitCode;
+        if (subcommand === "extract") {
+            process.exitCode = runMemoryExtraction({ json, dryRun }).exitCode;
+            return;
+        }
+        console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync|extract\n`);
+        process.exitCode = 1;
         return;
     }
     if (command === "secrets") {

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;
+}>;