agent-trellis 0.5.2 → 0.6.2

package/dist/pi-bridge/index.d.ts

@@ -12,7 +12,12 @@
  * this bridge actually uses are declared here.
  */
 import type { TSchema } from "typebox";
+import { withTimeout } from "../lib/mcpConnect.js";
 import { toPiContent } from "./schemaTranslate.js";
+/** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
+ * importing it from the module it was written against — proving the
+ * extraction changed nothing it could observe. */
+export { withTimeout };
 interface PiToolResult {
     content: ReturnType<typeof toPiContent>;
     details: unknown;
@@ -28,14 +33,6 @@ interface PiExtensionAPI {
     registerTool(tool: PiToolDefinition): void;
     on?(event: "session_shutdown", handler: () => Promise<void> | void): void;
 }
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
 /**
  * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
  * overridable for tests, same seam every other Trellis entry point
@@ -45,4 +42,3 @@ export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, m
  * `factory(pi)` — what pi actually does — works unchanged).
  */
 export default function trellisMcpBridge(pi: PiExtensionAPI, homeDir?: string, connectTimeoutMs?: number): Promise<void>;
-export {};

package/dist/pi-bridge/index.js

@@ -11,109 +11,17 @@
  * from Trellis's own install tree). Only the handful of fields/methods
  * this bridge actually uses are declared here.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveMcpPlan } from "../adapters/mcpPlan.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
-import { extractTemplateVarNames } from "../lib/envVarNames.js";
+import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { ALL_AGENTS } from "../core/types.js";
 import { bridgedToolName, toParametersSchema, toPiContent } from "./schemaTranslate.js";
+/** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
+ * importing it from the module it was written against — proving the
+ * extraction changed nothing it could observe. */
+export { withTimeout };
 const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
-const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export function withTimeout(promise, timeoutMs, message) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
-    });
-}
-/**
- * A timed-out (or otherwise failed) connect attempt must not leak the
- * transport's own resources — for `StdioClientTransport` specifically,
- * an unclosed transport means an orphaned child process that outlives
- * this failed attempt indefinitely (confirmed by a real leaked
- * subprocess during this change's own test run). `transport.close()` is
- * best-effort: a transport that never fully connected may itself error
- * on close, but the original connect failure is what the caller needs
- * to see, not a secondary cleanup error.
- */
-async function connectWithCleanup(client, transport, timeoutMs, message) {
-    try {
-        await withTimeout(client.connect(transport), timeoutMs, message);
-        return client;
-    }
-    catch (err) {
-        try {
-            await transport.close();
-        }
-        catch {
-            // best-effort; the original connect failure is what matters
-        }
-        throw err;
-    }
-}
-async function connectStdio(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const envAliases = def.envAliases ?? {};
-    // `envAliases`' values are source variable names — resolved through the
-    // exact same call as `env`'s own names, never delivered as the raw
-    // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
-    // of its own (like this bridge) would otherwise crash on parsing
-    // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
-    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
-    const transport = new StdioClientTransport({
-        command: def.command,
-        args: def.args,
-        // staticEnv merges last: a literal, intentionally-plain value (an
-        // email, an environment tag) always wins over an unresolved name-only
-        // entry's empty-string fallback for the same key — though in practice
-        // resolveMcpPlan's D6 refusal never lets an unresolved name reach
-        // this point at all (trellis-mcp-static-env-and-disabled-servers).
-        env: { ...getDefaultEnvironment(), ...namedEnv, ...aliasEnv, ...(def.staticEnv ?? {}) },
-    });
-    return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-function resolveHeaders(def, secretsPolicy) {
-    if (!def.headers || Object.keys(def.headers).length === 0)
-        return undefined;
-    const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
-    const result = {};
-    for (const [key, template] of Object.entries(def.headers)) {
-        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
-    }
-    return result;
-}
-async function connectHttp(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-async function connectSse(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
 function registerServerTools(pi, serverName, client, timeoutMs) {
     return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => {
         for (const tool of result.tools) {
@@ -178,15 +86,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            if (def.transport === "http") {
-                client = await connectHttp(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else if (def.transport === "sse") {
-                client = await connectSse(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else {
-                client = await connectStdio(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
+            client = await connectServer(def, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
         }
         catch (err) {
             // One unreachable/misconfigured (including permanently hanging —

package/dist/pi-bridge/schemaTranslate.d.ts

@@ -51,5 +51,11 @@ export declare function toParametersSchema(inputSchema: unknown): TSchema;
  * (design.md D3). */
 export declare function toPiContent(items: McpContentItem[]): PiContent[];
 /** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
-export declare function bridgedToolName(serverName: string, toolName: string): string;
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
+ *
+ * Now one implementation shared with the gateway's own aggregation rather
+ * than two identical ones: the naming convention is the contract between
+ * a prefixed name and the server it routes to, and two copies of it could
+ * drift into routing tools to the wrong upstream
+ * (trellis-mcp-gateway-hosting design.md D3). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/pi-bridge/schemaTranslate.js

@@ -34,7 +34,11 @@ export function toPiContent(items) {
     });
 }
 /** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
-export function bridgedToolName(serverName, toolName) {
-    return `${serverName}__${toolName}`;
-}
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
+ *
+ * Now one implementation shared with the gateway's own aggregation rather
+ * than two identical ones: the naming convention is the contract between
+ * a prefixed name and the server it routes to, and two copies of it could
+ * drift into routing tools to the wrong upstream
+ * (trellis-mcp-gateway-hosting design.md D3). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/docs/architecture.md

@@ -176,9 +176,13 @@ regardless of hub mode.
 ## MCP hub mode
 
 Every agent's MCP surface can be either N direct server definitions
-(default) or one static entry pointing at a single HTTP endpoint — set
-`mcp.hub.url` in `mcp/servers.yaml` to switch (see
-`schema/servers.example.yaml`). Nothing about *what* runs behind that URL
+(default) or one static entry pointing at a single HTTP endpoint — `mcp.hub.url`
+in `mcp/servers.yaml` is the field, but the supported way to set it is
+`trellis onboard --mcp-mode hub --hub-url <url>` (trellis-onboard-mcp-mode),
+not hand-editing the file: onboard's own writer clears any conflicting
+`gateway` block for you and is the same command that later turns hub mode
+back off again (`--mcp-mode direct`). `schema/servers.example.yaml` still
+documents the raw field shape for reference. Nothing about *what* runs behind that URL
 is part of Trellis's design: a self-hosted
 [mcp-hub](https://github.com/ravitemer/mcp-hub) instance, a hosted
 mcp-router account, anything else speaking MCP over HTTP all look
@@ -234,32 +238,111 @@ one header simply can't reach Codex through Trellis, and is refused
 there (not silently dropped) while still reaching every other agent.
 
 **Real OAuth** (browser redirect, short-lived access token, refresh
-token) is not implemented anywhere in Trellis, on purpose. All three
-native-config agents already have their own real, working flow for it:
-
-- Claude Code: `claude mcp add --client-id/--client-secret/--callback-port`
-- Codex: a dedicated `codex mcp login`/`codex mcp logout` pair
-- Kiro: `oauth`/`oauthScopes` fields in its own real
-  `~/.kiro/settings/mcp.json` schema
-
-pi has none of this — its bridge is Trellis's own code, and the MCP
-SDK's `authProvider: OAuthClientProvider` option is a full
-redirect-and-refresh flow that doesn't fit a synchronously-loaded
-extension's lifecycle. A remote server that requires real OAuth simply
-isn't reachable through the pi bridge today — a real, stated limitation,
-not something papered over with a partial implementation.
+token) was, for most of this project's life, deliberately not built:
+all three native-config agents already have their own working flow —
+Claude Code's `claude mcp add --client-id/--client-secret/--callback-port`,
+Codex's `codex mcp login`/`logout` pair, Kiro's `oauth`/`oauthScopes`
+fields — and pi, whose bridge is Trellis's own code, simply couldn't
+reach such a server at all.
+
+That changed with gateway mode (below), which made it unavoidable: in
+gateway mode the agent connects to Trellis, and Trellis connects to the
+remote server, so the agent's own OAuth flow is no longer on the path.
+Trellis now implements the client half itself — discovery (RFC 8414 /
+RFC 9728), dynamic client registration (RFC 7591), authorization code
+with PKCE S256 (RFC 7636), and the refresh grant — in `src/lib/oauth/`.
+
+Two rules shape it, both from the constraint that the gateway is spawned
+silently by an agent with no terminal attached:
+
+- **Only `trellis mcp auth <server>` ever opens a browser.** It is run by
+  a human, once. The gateway never initiates an interactive flow under
+  any circumstance; a server with no stored credential is skipped the
+  same way an unreachable one is.
+- **Refreshing is silent, and serialized by a lock.** A `refresh_token`
+  grant needs neither a browser nor a callback, so the gateway does it
+  at connect time. The lock (`~/.trellis/mcp/oauth/<name>.lock`) exists
+  because most authorization servers rotate the refresh token and
+  invalidate its predecessor — two concurrent refreshes would leave one
+  party holding a credential that is already dead.
+
+Tokens live one-file-per-server at `~/.trellis/mcp/oauth/<name>.json`,
+mode 0600, never in `servers.yaml` and never in the OS keychain (macOS's
+`security add-generic-password` fails with exit 152/154 in exactly the
+non-interactive, no-GUI-session context the gateway runs in — measured,
+not assumed).
+
+In direct mode nothing here applies: each agent keeps using its own
+native OAuth flow, exactly as before.
+
+## MCP gateway mode
+
+Gateway mode collapses an agent's MCP config to one entry, like hub mode
+— but what sits behind it is a local subprocess Trellis owns
+(`trellis mcp-gateway --agent <id>`), not a URL someone operates. Turn it
+on with `trellis onboard --mcp-mode gateway` (optionally
+`--gateway-agents <ids>` to narrow it to specific agents instead of every
+managed agent); `trellis onboard --mcp-mode direct` turns it back off.
+The underlying fields (`mcp.gateway.enabled`/`.agents` in
+`mcp/servers.yaml`) are what onboard's writer sets — hand-editing them is
+unsupported now that a real command exists for it
+(trellis-onboard-mcp-mode). Selecting `hub` instead always clears
+`gateway`, and vice versa (a mode selector, not two independently
+toggleable fields) — see "MCP hub mode" above for why onboard treats them
+as one mutually-exclusive choice rather than exposing the field-level
+"both set, gateway wins" flexibility `resolveMcpPlan` itself still
+tolerates for anyone who reaches this state some other way.
+
+**Lifecycle: there isn't one.** The agent spawns it like any other stdio
+MCP server and it exits when the session ends. No daemon, no
+start/stop/status command, nothing to monitor. Two things make that
+true rather than aspirational:
+
+- The gateway watches its own stdin for EOF and tears everything down.
+  The MCP SDK's `StdioServerTransport` binds only `'data'` and
+  `'error'`, so it never reports EOF, and POSIX re-parents orphans to
+  launchd rather than killing them — without explicit teardown every
+  session would leak a gateway plus its whole upstream set, forever.
+- Upstream failures are isolated. One server that is unreachable,
+  misconfigured, or permanently hanging is logged and skipped; every
+  other server's tools are still served.
+
+**What it does:** resolves the same in-scope server set direct mode
+would have written for that agent (same `resolveMcpPlan`, so per-server
+`agents:` scope, `enabled: false`, host-injected collisions,
+literal-secret refusals and unresolved `env` names all behave
+identically), connects each one, and exposes their tools as
+`<server>__<tool>`. Secrets resolve through `resolveSecretEnv` exactly as
+in direct mode — the gateway introduces no second path by which a value
+could reach disk.
+
+**What it changes for the agents:** Codex's single-`bearer_token_env_var`
+limitation stops applying, because Codex no longer receives any server's
+`headers` — the gateway holds them. Remote servers needing real OAuth
+become reachable from every agent, including pi, for the same reason.
+
+**The seam.** `src/commands/mcpGateway.ts` depends on a `GatewayBackend`
+interface and nothing below it — never a connection, transport, or
+server definition. Today the only implementation connects upstreams
+in-process, one gateway per agent session. The confirmed direction is a
+single shared service holding one connection set for all agents, with
+the per-session process becoming a thin client forwarding over a Unix
+socket, speaking MCP itself (so no second protocol to own). That is a
+substitution at one construction site: the entry written into each
+agent's config is identical either way, so converging later requires no
+re-sync and nothing the user notices.
 
 ## What Trellis explicitly does not build
 
-- An MCP aggregator/gateway's actual routing/proxy logic (hub mode above
-  lets you point every agent at one, but Trellis doesn't implement one)
-- Real OAuth for remote MCP servers (browser redirect, token storage,
-  refresh) — every agent that has its own native flow keeps using it;
-  see "Static header auth vs. real OAuth" above
+- A resident MCP gateway daemon. Gateway mode above is a per-session
+  subprocess with no lifecycle; hub mode points at something you operate.
+  Neither is a service Trellis starts, supervises, or keeps running.
 - A memory backend (defaults to `@modelcontextprotocol/server-memory`,
-  documented in `schema/servers.example.yaml`; mem0/OpenMemory and
-  totalrecallai-class semantic-search servers documented as opt-in
-  upgrades — see docs/research.md "Shared memory")
+  turned on with `trellis onboard --memory on` (trellis-onboard-mcp-mode)
+  rather than hand-editing `servers.yaml`, documented in
+  `schema/servers.example.yaml`; mem0/OpenMemory and totalrecallai-class
+  semantic-search servers documented as opt-in upgrades — see
+  docs/research.md "Shared memory")
 - A secret vault (reads `${VAR}` from whatever the environment already
   provides — `~/.config/agent-env/secrets.env`, 1Password's `op run`,
   anything that populates `process.env` before an adapter's generated

package/docs/getting-started.md

@@ -16,9 +16,15 @@ $ trellis onboard
 ```
 
 Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
-then resolves two independent choices before running `migrate`, `sync`,
-`mcp sync`, `memory sync`, and `secrets audit` — the whole onboarding path,
-no follow-up commands to type by hand:
+then resolves two interactive choices and two flag-only ones before running
+`migrate`, `sync`, `mcp sync`, `memory sync`, `secrets audit`, and a final
+health scan — the whole onboarding path, no follow-up commands to type by
+hand, and no need to run `trellis doctor` separately to know whether it
+actually worked. This is also the one command for reconfiguring an
+already-onboarded machine later: every one of the four choices below reads
+what's already there first, so a bare `trellis onboard` re-run changes
+nothing about them, and re-running with a new flag value updates exactly
+that.
 
 1. **Migration source** — read from, at most one, never written back to.
    "Real content" means skills, custom instructions, *or* real MCP servers
@@ -43,11 +49,36 @@ no follow-up commands to type by hand:
    Selecting an agent that isn't installed yet is itself the authorization to
    install it (one confirmation, then a real `npm install -g <package>`);
    Kiro has no CLI package and is refused with its download URL instead.
+3. **MCP mode** — direct (the default), hub, or gateway. Flag-only, never
+   prompted: pass `--mcp-mode direct|hub|gateway` to change it (`--hub-url
+   <url>` is required with `hub`; `--gateway-agents <ids>` is optional with
+   `gateway`, omitted meaning every managed agent). Omitting `--mcp-mode`
+   entirely leaves whatever's already configured untouched — on a fresh
+   machine that's direct, on one you've already switched that's whatever
+   you last set — so a plain `trellis onboard` re-run never resets it. This
+   is the only supported way to turn gateway or hub mode on or off; there's
+   no reason to hand-edit `~/.trellis/mcp/servers.yaml`'s `hub`/`gateway`
+   keys directly.
+4. **The shared memory server** — off by default. Pass `--memory on` to add
+   the default `@modelcontextprotocol/server-memory` definition (refused if
+   a host on this machine already injects a connector named `memory` — see
+   [`trellis memory sync`](#trellis-memory-sync) below) or
+   `--memory off` to remove it. Omitting `--memory` preserves whatever's
+   already configured, same rule as MCP mode. Turning it on and seeing it
+   actually reach every managed agent and get populated from canonical
+   `memories/*.md` happens in the very same run — no second command needed.
+
+Both flags print a one-line status on a real terminal (`mcp mode: direct
+(unchanged) — pass --mcp-mode hub|gateway to change`, or `memory: on
+(changed from off)`) so they stay discoverable without turning into a
+prompt you have to answer on every run.
 
 ```
 $ trellis onboard --agent claude-code --manage pi
 Using claude-code as the migration source (--agent).
 Managed agents: pi
+mcp mode: direct (unchanged) — pass --mcp-mode direct|hub|gateway to change
+memory: off (unchanged) — pass --memory on to change
 
 migrate --from claude-code
   [create] skill "my-skill" — will copy from /Users/you/.claude/skills/my-skill
@@ -65,16 +96,73 @@ memory sync
 
 secrets audit
   ✅ no findings — every present agent's real config and every declared env var passed all checks
+
+health scan (trellis doctor)
+  ✅ no findings
+
+verdict
+✅ nothing needs attention — every stage completed cleanly and verified
+exit code: 0 — nothing blocked this run
 ```
 
 No agent named `claude-code` appears in the `sync`/`mcp sync` output above —
 it's present and was the migration source, but it isn't managed, so it's
 never even probed as a sync target, not just left with zero items.
 
+**The `verdict` block is always the last thing printed**, including on a
+run that had nothing wrong — the exit code and the last line on screen
+always agree, so a conflict earlier in the run can never be hidden behind
+a later stage's own unrelated success line. Every conflict from every
+stage is collected there, each with a concrete next action, not just a
+restatement of what went wrong:
+
+```
+verdict
+❌ 1 blocking issue(s):
+   - [sync/claude-code] ~/.claude/CLAUDE.md exists and is not a Trellis-managed symlink — left untouched
+     → back up ~/.claude/CLAUDE.md's real content if you need it, remove the file, then re-run sync
+exit code: 1 — at least one blocking issue above
+```
+
+**A real (non-`--dry-run`) run verifies its own writes**, immediately
+after making them — a dry-run re-plan of `sync`/`mcp sync` against exactly
+what was just written, checked for anything still outstanding. This is
+what actually answers "did this take effect," distinct from the health
+scan below it: `trellis doctor`'s own checks compare agents against each
+other and never read canonical, so they cannot prove a write held — only
+a re-plan against canonical can. If a write somehow didn't hold (a
+filesystem permission problem, a race), it surfaces in the verdict as its
+own `blocked` item, separate from whatever the write's own stage reported.
+
+**The health scan is `trellis doctor` itself**, run at the end against
+every agent (not just the ones this run manages) — so a genuinely new
+problem this run happened to create or reveal shows up without a separate
+`trellis doctor` invocation. It never spawns a configured MCP server to
+check it (`--probe-mcp` is never passed): the worst possible moment to
+start reaching real external services with real credentials is a user's
+first-ever run of this command. A finding about an agent this run doesn't
+manage is shown, labelled as such, and doesn't fail the run — onboard
+didn't touch that agent, so its drift isn't this run's problem to fix.
+
+On a real terminal, each stage prints a `[n/6] <stage>` progress line to
+stderr as it starts — `sync`/`mcp sync` spawn real processes and can take
+a few seconds, and this keeps the screen from going silent while that
+happens. It never appears on stdout, so `trellis onboard > report.txt`
+still captures exactly the report and verdict, nothing else; it's silent
+entirely under `--json` or when stdout isn't a real terminal.
+
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
 sync/memory sync, including what would be written to
-`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit is
-always read-only, with or without the flag).
+`~/.trellis/managed.yaml` and to `servers.yaml`'s mode/memory keys — with
+zero writes anywhere (secrets audit and
+the health scan are always read-only, with or without the flag; the
+write-verification step above has nothing to check on a dry run and is
+skipped entirely). On a real terminal, a `--dry-run` ends by offering to
+apply the plan you just read — "No" is the highlighted default, so Enter
+declines; accepting re-plans against current state and applies for real,
+rather than replaying the exact preview you saw (state may have changed
+while you were reading it). `--json` and non-interactive runs are never
+offered anything.
 
 **A managed agent's own real content still isn't overwritten.** If you
 explicitly include the source in `--manage`, sync still never overwrites
@@ -315,7 +403,8 @@ below.
 Distributes `~/.trellis/mcp/servers.yaml` to every **managed** agent's
 native MCP config — same restriction as `sync`, see above. See [`schema/servers.example.yaml`](../schema/servers.example.yaml)
 for the full documented shape — server definitions, per-agent scoping,
-known-host-injected collision avoidance, and hub mode.
+known-host-injected collision avoidance, hub mode, and gateway mode
+(below).
 
 ```
 $ trellis mcp sync
@@ -367,6 +456,63 @@ unexpanded `${SOURCE_NAME}` text to any agent with no `${VAR}` runtime
 of its own — which is exactly what broke pi's Notion connection before
 this field existed.
 
+## Gateway mode — one entry per agent instead of N
+
+Add this to `servers.yaml` and every managed agent's config collapses to
+a single MCP entry:
+
+```yaml
+gateway:
+  enabled: true
+```
+
+Then re-run `trellis mcp sync`. Instead of one native entry per server,
+each agent gets one stdio entry pointing at `trellis mcp-gateway`. The
+agent spawns it like any other stdio MCP server; it connects out to your
+servers, and exits when the session ends. There is nothing to start,
+stop, or monitor.
+
+Your servers' tools appear to the agent as `<server>__<tool>` — the
+`gitlab` server's `search` becomes `gitlab__search`.
+
+Add `agents: [claude-code, codex]` under `gateway:` to narrow it, leaving
+the rest in direct mode. Gateway mode and `hub` are independent; both can
+be set, and gateway wins for any agent it covers.
+
+Two things stop being problems in gateway mode. Codex can normally only
+express a single `Authorization: Bearer ${VAR}` header, so a server
+needing more than one was refused for Codex — in gateway mode Codex never
+sees any server's headers, so it just works. And remote servers requiring
+real OAuth become reachable from every agent, including pi.
+
+### `trellis mcp auth <server-name>`
+
+For a remote (`http`/`sse`) server that uses OAuth, authorize it once:
+
+```
+$ trellis mcp auth notion-remote
+✅ notion-remote — authorized (expires 2026-09-16T11:24:03.000Z)
+   credentials: ~/.trellis/mcp/oauth/notion-remote.json
+```
+
+This opens your browser, completes the flow, and stores the result 0600
+under `~/.trellis/mcp/oauth/` — never in `servers.yaml`, so canonical
+stays safe to read, diff, and commit.
+
+Run it once per server. After that the gateway refreshes the token
+silently whenever it expires; it never opens a browser and never prompts,
+because it is spawned by an agent with no terminal attached. Re-running
+this command when the stored token is still valid does nothing (`--force`
+overrides); when it has expired but is renewable, it refreshes without a
+browser.
+
+If a server has no stored credential, the gateway skips that one server
+and keeps serving every other — it does not fail to start.
+
+This command only applies to `http`/`sse` servers. stdio servers get
+their credentials from `env`/`env_aliases` as described above; running
+`mcp auth` on one tells you so rather than opening a pointless browser.
+
 ## `trellis memory sync`
 
 Ingests `~/.trellis/memories/*.md` into the actual on-disk file
@@ -375,7 +521,10 @@ the gap between "memory entries exist in canonical" and "the running
 memory server actually knows about them." Requires a `memory` server in
 `servers.yaml` with `static_env.MEMORY_FILE_PATH` set explicitly (see
 [`schema/servers.example.yaml`](../schema/servers.example.yaml)); without
-one, this is a no-op, not an error.
+one, this is a no-op, not an error. `trellis onboard --memory on` is the
+easiest way to get that entry there — no hand-editing `servers.yaml`
+required — and this stage is already chained into `onboard`, so enabling
+it and syncing real canonical content into it happens in one run.
 
 ```
 $ trellis memory sync