agent-trellis 0.17.1 → 0.19.0

package/dist/lib/gatewayBackend.d.ts

@@ -17,8 +17,9 @@
  */
 import type { McpServerDef, SecretsPolicy } from "../core/types.js";
 import { type McpClientInfo } from "./mcpConnect.js";
+import type { FetchLike } from "./oauth/discovery.js";
 import { type AggregatedTool } from "./mcpToolRegistry.js";
-import type { Resource, ReadResourceResult } from "@modelcontextprotocol/client";
+import type { AuthProvider, Resource, ReadResourceResult } from "@modelcontextprotocol/client";
 import type { SkillEntry } from "./skillManifest.js";
 export interface GatewayBackend {
     /** Every tool available through this backend, under its aggregated name. */
@@ -40,7 +41,11 @@ export interface UpstreamSpec {
     name: string;
     def: McpServerDef;
 }
-export type UpstreamStatusKind = "ready" | "auth-required" | "unavailable" | "timeout" | "degraded";
+/** `reconnecting` is the transient state between a detected session
+ * invalidation and the recovery outcome (spec: an upstream whose MCP
+ * session is invalidated mid-session is recovered alone, with a status
+ * that never claims ready in the meantime). */
+export type UpstreamStatusKind = "ready" | "auth-required" | "unavailable" | "timeout" | "degraded" | "reconnecting";
 export interface UpstreamStatus {
     name: string;
     transport: "stdio" | "http" | "sse";
@@ -74,6 +79,10 @@ export interface LocalBackendOptions {
      * no terminal attached (design.md D9).
      */
     homeDir?: string;
+    /** How long a server whose mid-session recovery failed refuses automatic
+     * re-attempts, so a down upstream cannot trigger a reconnect storm. Test
+     * seam; defaults to `SESSION_RECOVERY_COOLDOWN_MS`. */
+    sessionRecoveryCooldownMs?: number;
 }
 /**
  * v1's backend: connects each upstream itself and aggregates the result.
@@ -86,9 +95,26 @@ export interface LocalBackendOptions {
  */
 export declare class LocalBackend implements GatewayBackend {
     private readonly warn;
+    private readonly sessionCooldownMs;
     private readonly registry;
+    /** server name → the client currently serving that upstream. Keyed by
+     * name (not a Set of clients) because recovery swaps the client under a
+     * stable name and callTool must ask "is this still the client I called?"
+     * by comparing against the current registration. */
     private readonly connected;
     private readonly statuses;
+    /** Saved at connect time so a mid-session recovery can rebuild the
+     * upstream through `addUpstream` itself — the recovery path IS the
+     * startup path, and inherits its OAuth resolution and special cases
+     * (mcp-router) wholesale instead of growing a parallel one. */
+    private readonly upstreamConfigs;
+    /** server name → in-flight session recovery; one recovery per server at
+     * a time, every racing caller awaits the same promise. */
+    private readonly recoveries;
+    /** server name → cooldown expiry; a recently failed recovery is not
+     * re-attempted until it lapses, so a down upstream sees one reconnect
+     * attempt per window, not a storm. */
+    private readonly sessionCooldowns;
     private closed;
     private readonly resources;
     private constructor();
@@ -102,8 +128,68 @@ export declare class LocalBackend implements GatewayBackend {
     getSkill(uri: string): Promise<SkillEntry | undefined>;
     listStatus(): readonly UpstreamStatus[];
     close(): Promise<void>;
-    private closeUpstream;
+    private closeClient;
+    /** A dead grant surfaces mid-session: this upstream's calls now fail,
+     * but its tools stay registered and every other upstream keeps serving.
+     * The credential resolves per request, so the human's re-authorization
+     * takes effect on the next call — no session restart required. */
+    private markCredentialFailure;
+    private restoreIfAuthRequired;
+    /** The pre-call hard failure for a server inside its recovery cooldown. */
+    private sessionCooldownBlock;
+    private enterSessionCooldown;
+    /** Join the server's in-flight recovery, or start exactly one. */
+    private ensureSessionRecovered;
+    /** Drop and rebuild one upstream through the exact startup path
+     * (`addUpstream`), keeping the old client connected until the fresh
+     * registration serves — so a failed recovery still surfaces the old
+     * session errors that re-trigger recovery after the cooldown, and the
+     * replaced connection is never closed before its successor exists. */
+    private reconnectUpstream;
+    /** The retried request failed on the fresh session too: an honest
+     * terminal state plus a cooldown — never a stale ready (D4). */
+    private markRetrySessionFailure;
+    /** Upstream-originated failures name their server (spec: call errors
+     * name the failing upstream server). */
+    private upstreamCallError;
 }
+/**
+ * How long a server whose session recovery failed refuses automatic
+ * re-attempts. Fixed by design: a reconnect storm against a down upstream
+ * buys nothing; the honest failure state plus this window is the v1
+ * answer, to be revisited with real-world data.
+ */
+export declare const SESSION_RECOVERY_COOLDOWN_MS = 30000;
+/**
+ * Whether an upstream error means "your MCP session no longer exists".
+ *
+ * The official TypeScript server SDK rejects an unknown session with HTTP
+ * 404 carrying the JSON-RPC error "Session not found", and pairs 401/403
+ * with -32000 for authentication rejections — so 401/403 gate the match
+ * out first, and an auth rejection can never enter recovery. The body
+ * reaches us inside the client SDK's `Error POSTing to endpoint: …`
+ * wrapper, so a word match covers custom upstream wordings (the real-world
+ * one says "MCP session no longer exists"). Real-machine verification
+ * (2026-10-23) showed custom upstreams also answer with other non-auth
+ * statuses — a 400 carrying that same -32000 body took the plain
+ * `SdkHttpError` path, not the enveloped `ProtocolError` one — hence the
+ * status gate is "not an auth rejection" rather than "exactly 404". A
+ * stray non-auth response that merely mentions "session" costs one
+ * idempotent-safe reconnect+retry, an acceptable price for covering every
+ * upstream wording. The `ProtocolError` branch covers the HTTP-200
+ * JSON-RPC error case, where the client SDK parses the envelope and
+ * rejects with the upstream's error code instead.
+ */
+export declare function isSessionInvalidation(err: unknown): boolean;
+/**
+ * Whether the gateway manages the OAuth credential for this definition:
+ * Trellis-owned OAuth, and no explicit `Authorization` header — someone
+ * who wrote one in canonical meant it, and silently overriding it with a
+ * stored token would be the kind of invisible precedence that is
+ * impossible to debug. Both `withOAuthHeader` and the per-request
+ * `AuthProvider` attach on exactly this predicate.
+ */
+export declare function oauthAttachApplies(def: McpServerDef): boolean;
 /**
  * Attaches a stored OAuth token, refreshing it first if it has expired.
  *
@@ -112,8 +198,37 @@ export declare class LocalBackend implements GatewayBackend {
  * OAuth at all, or one whose credential lives in `headers` already, and
  * neither should be disturbed.
  *
- * An explicit `Authorization` header in canonical wins. Someone who wrote
- * one meant it, and silently overriding it with a stored token would be
- * the kind of invisible precedence that is impossible to debug.
+ * An explicit `Authorization` header in canonical wins.
  */
 export declare function withOAuthHeader(name: string, def: McpServerDef, homeDir: string): Promise<McpServerDef>;
+/**
+ * The early-refresh window on the gateway's per-request path. Minute-scale
+ * on purpose: a request that passes the freshness check must not carry a
+ * token that dies mid-flight. `store.ts`'s 60s default is untouched —
+ * `mcp auth`/`mcp renew` don't have this problem.
+ */
+export declare const GATEWAY_REFRESH_SKEW_MS = 300000;
+export interface TrellisAuthProviderOptions {
+    homeDir: string;
+    serverName: string;
+    /** Test seam; defaults to the gateway window. */
+    skewMs?: number;
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    /** Fired when pre-request resolution produced a credential while this
+     * server sat in auth-required — the backend restores its status. */
+    onCredentialRecovered?: () => void;
+    /** Fired when the 401-forced refresh failed — the backend marks this
+     * server auth-required with the OAuth remediation. */
+    onCredentialFailure?: (err: unknown) => void;
+}
+/**
+ * The SDK `AuthProvider` for one Trellis-owned OAuth upstream: `token()`
+ * runs as each outbound request's headers are assembled, so credentials
+ * resolve per request instead of once at connect time.
+ *
+ * Every read goes back to the token file with no memory cache — that is
+ * what makes a refresh by `trellis mcp auth` in another terminal take
+ * effect on the very next request of a running gateway (D6).
+ */
+export declare function trellisAuthProvider(opts: TrellisAuthProviderOptions): AuthProvider;

package/dist/lib/gatewayBackend.js

@@ -18,9 +18,10 @@
 import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { connectServer } from "./mcpConnect.js";
 import { withTimeout } from "./mcpConnect.js";
-import { ensureFreshToken } from "./oauth/refresh.js";
+import { ensureFreshToken, forceRefresh, RefreshError } from "./oauth/refresh.js";
 import { readToken } from "./oauth/store.js";
 import { McpToolRegistry } from "./mcpToolRegistry.js";
+import { ProtocolError, SdkHttpError } from "@modelcontextprotocol/client";
 import { UpstreamResources } from "./upstreamResources.js";
 /**
  * v1's backend: connects each upstream itself and aggregates the result.
@@ -33,24 +34,47 @@ import { UpstreamResources } from "./upstreamResources.js";
  */
 export class LocalBackend {
     warn;
+    sessionCooldownMs;
     registry = new McpToolRegistry();
-    connected = new Set();
+    /** server name → the client currently serving that upstream. Keyed by
+     * name (not a Set of clients) because recovery swaps the client under a
+     * stable name and callTool must ask "is this still the client I called?"
+     * by comparing against the current registration. */
+    connected = new Map();
     statuses = new Map();
+    /** Saved at connect time so a mid-session recovery can rebuild the
+     * upstream through `addUpstream` itself — the recovery path IS the
+     * startup path, and inherits its OAuth resolution and special cases
+     * (mcp-router) wholesale instead of growing a parallel one. */
+    upstreamConfigs = new Map();
+    /** server name → in-flight session recovery; one recovery per server at
+     * a time, every racing caller awaits the same promise. */
+    recoveries = new Map();
+    /** server name → cooldown expiry; a recently failed recovery is not
+     * re-attempted until it lapses, so a down upstream sees one reconnect
+     * attempt per window, not a storm. */
+    sessionCooldowns = new Map();
     closed = false;
     resources;
-    constructor(warn, timeoutMs) {
+    constructor(warn, timeoutMs, sessionCooldownMs) {
         this.warn = warn;
+        this.sessionCooldownMs = sessionCooldownMs;
         this.resources = new UpstreamResources(timeoutMs, warn);
     }
     static async connect(upstreams, options) {
         const warn = options.onWarning ?? ((message) => console.error(message));
-        const backend = new LocalBackend(warn, options.connectTimeoutMs);
+        const backend = new LocalBackend(warn, options.connectTimeoutMs, options.sessionRecoveryCooldownMs ?? SESSION_RECOVERY_COOLDOWN_MS);
         await Promise.all(upstreams.map((upstream) => backend.addUpstream(upstream, options)));
         return backend;
     }
-    async addUpstream({ name, def }, options) {
+    async addUpstream({ name, def }, options, replaceOf) {
+        this.upstreamConfigs.set(name, { spec: { name, def }, options });
         const transport = def.transport === "http" || def.transport === "sse" ? def.transport : "stdio";
-        this.statuses.set(name, { name, transport, status: "unavailable", detail: "connecting" });
+        // A recovery set `reconnecting` before calling us; a first connect
+        // reports "connecting". The recovery's status stays until the outcome.
+        if (replaceOf === undefined) {
+            this.statuses.set(name, { name, transport, status: "unavailable", detail: "connecting" });
+        }
         let effectiveDef = def;
         if (options.homeDir && def.url) {
             try {
@@ -65,16 +89,42 @@ export class LocalBackend {
                 return;
             }
         }
+        // Per-request credential resolution: the SDK calls token() as each
+        // request's headers are assembled, so a token refreshed here — by this
+        // process, or written to disk by `trellis mcp auth` in another
+        // terminal — affects the very next request, no restart. The static
+        // header from withOAuthHeader stays as the connect-time fallback.
+        // (A mid-session recovery rebuilds this provider, so its `lastIssued`
+        // starts empty again: the first post-recovery 401 force-refreshes with
+        // no previous-token guard — at most one extra rotation, and safe,
+        // because forceRefresh re-reads the token file under its lock.)
+        const authProvider = options.homeDir && (transport === "http" || transport === "sse") && oauthAttachApplies(def)
+            ? trellisAuthProvider({
+                homeDir: options.homeDir,
+                serverName: name,
+                onCredentialRecovered: () => this.restoreIfAuthRequired(name),
+                onCredentialFailure: (err) => this.markCredentialFailure(name, transport, err),
+            })
+            : undefined;
         let client;
         try {
-            client = await connectServer(effectiveDef, options.secretsPolicy, options.connectTimeoutMs, options.clientInfo);
+            client = await connectServer(effectiveDef, options.secretsPolicy, options.connectTimeoutMs, options.clientInfo, authProvider);
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to connect to MCP server "${name}": ${errorText(err)}`);
+            // A failed recovery keeps the replaced client: its dead session is
+            // what keeps surfacing the error that re-triggers recovery once the
+            // cooldown expires — close-after-success, never orphaned mid-failure.
+            if (replaceOf !== undefined)
+                this.connected.set(name, replaceOf);
             this.statuses.set(name, failureStatus(name, def, err));
             return;
         }
-        this.connected.add(client);
+        this.connected.set(name, client);
+        // Routes (and any skill registrations) a previous incarnation of this
+        // source left behind would route reads at the replaced client — forget
+        // the source entirely; the fresh registration re-adds its routes below.
+        this.resources.removeSource(name);
         let tools;
         try {
             const result = client.getServerCapabilities()?.tools
@@ -84,11 +134,19 @@ export class LocalBackend {
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to list tools for MCP server "${name}": ${errorText(err)}`);
-            await this.closeUpstream(client);
+            this.connected.delete(name);
+            if (replaceOf !== undefined)
+                this.connected.set(name, replaceOf);
+            await this.closeClient(client);
             this.statuses.set(name, failureStatus(name, def, err));
             return;
         }
-        const { skipped } = this.registry.add(name, client, tools);
+        // A recovery swaps this server's whole registration: its previous
+        // candidates are dropped first, so a changed upstream tool set is
+        // reflected exactly rather than accumulated.
+        const { skipped } = replaceOf !== undefined
+            ? this.registry.replace(name, client, tools)
+            : this.registry.add(name, client, tools);
         this.resources.add(name, client);
         for (const collided of skipped) {
             this.warn(`trellis-mcp-gateway: tool "${collided}" from server "${name}" collides with an already-registered tool and was skipped`);
@@ -109,12 +167,63 @@ export class LocalBackend {
         else {
             this.statuses.set(name, { name, transport, status: "ready", toolCount: tools.length, detail: `connected; ${tools.length} tool(s) available` });
         }
+        // The fresh registration serves; only now is the replaced client
+        // retired. Callers mid-flight on it finish against it — their stale
+        // session errors are guarded in callTool and never start a second
+        // recovery — and a failed recovery left the old client connected.
+        if (replaceOf !== undefined)
+            await this.closeClient(replaceOf);
     }
     async listTools() {
         return this.registry.listTools();
     }
     async callTool(name, args) {
-        return this.registry.callTool(name, args);
+        let target = this.registry.resolve(name);
+        if (!target)
+            throw new Error(`unknown tool "${name}"`);
+        // A server inside its recovery cooldown fails hard and immediately:
+        // its automatic recovery is known to be failing, and a reconnect
+        // storm against a down upstream buys nothing (D3).
+        const blocked = this.sessionCooldownBlock(target.serverName);
+        if (blocked)
+            throw blocked;
+        // A recovery already in flight — started by a concurrent caller.
+        // Wait it out and aim at whatever registration it lands.
+        const pending = this.recoveries.get(target.serverName);
+        if (pending) {
+            await pending;
+            target = this.registry.resolve(name);
+            if (!target)
+                throw new Error(`unknown tool "${name}"`);
+        }
+        try {
+            return await target.upstream.callTool({ name: target.toolName, arguments: args });
+        }
+        catch (err) {
+            const { serverName } = target;
+            if (this.closed || !isSessionInvalidation(err))
+                throw this.upstreamCallError(serverName, err);
+            // A completed recovery already replaced the client this error came
+            // from (a racing caller's reconnect won): the stale error must not
+            // start a second recovery — just aim at the fresh registration.
+            const current = this.connected.get(serverName);
+            if (current === undefined || current === target.upstream) {
+                await this.ensureSessionRecovered(serverName, err);
+            }
+            const retried = this.registry.resolve(name);
+            if (!retried)
+                throw new Error(`unknown tool "${name}"`);
+            try {
+                return await retried.upstream.callTool({ name: retried.toolName, arguments: args });
+            }
+            catch (retryErr) {
+                // The fresh session failed the same way: an honest terminal state
+                // plus a cooldown — never a stale ready (D4).
+                if (isSessionInvalidation(retryErr))
+                    this.markRetrySessionFailure(retried.serverName, retryErr);
+                throw this.upstreamCallError(retried.serverName, retryErr);
+            }
+        }
     }
     listResources() { return this.resources.listResources(); }
     readResource(uri) { return this.resources.readResource(uri); }
@@ -127,12 +236,11 @@ export class LocalBackend {
         if (this.closed)
             return;
         this.closed = true;
-        const pending = [...this.connected];
+        const pending = [...this.connected.values()];
         this.connected.clear();
-        await Promise.all(pending.map((client) => this.closeUpstream(client)));
+        await Promise.all(pending.map((client) => this.closeClient(client)));
     }
-    async closeUpstream(client) {
-        this.connected.delete(client);
+    async closeClient(client) {
         try {
             await client.close();
         }
@@ -141,6 +249,185 @@ export class LocalBackend {
             this.warn(`trellis-mcp-gateway: failed to close MCP client: ${errorText(err)}`);
         }
     }
+    /** A dead grant surfaces mid-session: this upstream's calls now fail,
+     * but its tools stay registered and every other upstream keeps serving.
+     * The credential resolves per request, so the human's re-authorization
+     * takes effect on the next call — no session restart required. */
+    markCredentialFailure(name, transport, err) {
+        const previous = this.statuses.get(name);
+        this.statuses.set(name, {
+            name,
+            transport,
+            status: "auth-required",
+            toolCount: previous?.toolCount,
+            detail: errorText(err).slice(0, 300),
+            remediationKind: "oauth",
+            requiresHuman: true,
+            requiresSessionRestart: false,
+            remediation: `run \`trellis mcp auth ${name}\` in a human terminal — the running gateway picks the new credential up on its next request`,
+        });
+        this.warn(`trellis-mcp-gateway: MCP server "${name}" needs re-authorization: ${errorText(err)}`);
+    }
+    restoreIfAuthRequired(name) {
+        const current = this.statuses.get(name);
+        if (!current || current.status !== "auth-required")
+            return;
+        this.statuses.set(name, {
+            ...current,
+            status: "ready",
+            detail: `credential recovered; ${current.toolCount ?? 0} tool(s) available`,
+            remediation: undefined,
+            remediationKind: undefined,
+            requiresHuman: undefined,
+            requiresSessionRestart: undefined,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Mid-session recovery (spec: an upstream whose MCP session is invalidated
+    // is recovered alone, in flight — restart is the remediation of last
+    // resort, not the default)
+    // ---------------------------------------------------------------------------
+    /** The pre-call hard failure for a server inside its recovery cooldown. */
+    sessionCooldownBlock(serverName) {
+        const until = this.sessionCooldowns.get(serverName);
+        if (until === undefined || Date.now() >= until)
+            return undefined;
+        return new Error(sessionRecoveryHint(serverName, "a recovery attempt failed recently and its cooldown has not expired"));
+    }
+    enterSessionCooldown(serverName) {
+        this.sessionCooldowns.set(serverName, Date.now() + this.sessionCooldownMs);
+    }
+    /** Join the server's in-flight recovery, or start exactly one. */
+    ensureSessionRecovered(serverName, trigger) {
+        const blocked = this.sessionCooldownBlock(serverName);
+        if (blocked)
+            return Promise.reject(blocked);
+        const existing = this.recoveries.get(serverName);
+        if (existing)
+            return existing;
+        const pending = this.reconnectUpstream(serverName, trigger);
+        this.recoveries.set(serverName, pending);
+        const cleanup = () => {
+            if (this.recoveries.get(serverName) === pending)
+                this.recoveries.delete(serverName);
+        };
+        pending.then(cleanup, cleanup);
+        return pending;
+    }
+    /** Drop and rebuild one upstream through the exact startup path
+     * (`addUpstream`), keeping the old client connected until the fresh
+     * registration serves — so a failed recovery still surfaces the old
+     * session errors that re-trigger recovery after the cooldown, and the
+     * replaced connection is never closed before its successor exists. */
+    async reconnectUpstream(serverName, trigger) {
+        const config = this.upstreamConfigs.get(serverName);
+        if (!config)
+            throw new Error(sessionRecoveryHint(serverName, "no saved connection config exists for it"));
+        // Preserve the tool count through reconnecting and failure: Agents
+        // reasoning about capability see the same number on both sides of a
+        // recovery, whatever its outcome (a success overwrites it with the
+        // fresh count inside addUpstream).
+        const toolCount = this.statuses.get(serverName)?.toolCount;
+        this.statuses.set(serverName, {
+            name: serverName,
+            transport: transportOf(config.spec.def),
+            status: "reconnecting",
+            toolCount,
+            detail: `MCP session invalidated; reconnecting (${errorText(trigger).slice(0, 160)})`,
+        });
+        try {
+            await this.addUpstream(config.spec, config.options, this.connected.get(serverName));
+        }
+        catch (err) {
+            // addUpstream isolates its own failures into statuses; reaching here
+            // is a bug guard, not the expected failure path.
+            this.statuses.set(serverName, { ...failureStatus(serverName, config.spec.def, err), toolCount, remediation: sessionRestartRemediation(serverName) });
+            this.enterSessionCooldown(serverName);
+            throw new Error(sessionRecoveryHint(serverName, errorText(err)));
+        }
+        const status = this.statuses.get(serverName);
+        if (status?.status === "ready" || status?.status === "degraded") {
+            this.sessionCooldowns.delete(serverName);
+            return;
+        }
+        // A failed recovery already landed in its classified failure status;
+        // sharpen its remediation to the restart hint and open the cooldown.
+        this.statuses.set(serverName, { ...status, toolCount, remediation: sessionRestartRemediation(serverName) });
+        this.enterSessionCooldown(serverName);
+        throw new Error(sessionRecoveryHint(serverName, status?.detail ?? "the reconnect failed"));
+    }
+    /** The retried request failed on the fresh session too: an honest
+     * terminal state plus a cooldown — never a stale ready (D4). */
+    markRetrySessionFailure(serverName, err) {
+        const config = this.upstreamConfigs.get(serverName);
+        const previous = this.statuses.get(serverName);
+        const base = config
+            ? failureStatus(serverName, config.spec.def, err)
+            : {
+                name: serverName,
+                transport: "http",
+                status: "unavailable",
+                detail: errorText(err).slice(0, 300),
+                requiresHuman: true,
+                requiresSessionRestart: true,
+            };
+        this.statuses.set(serverName, {
+            ...base,
+            toolCount: previous?.toolCount,
+            remediation: sessionRestartRemediation(serverName),
+        });
+        this.enterSessionCooldown(serverName);
+    }
+    /** Upstream-originated failures name their server (spec: call errors
+     * name the failing upstream server). */
+    upstreamCallError(serverName, err) {
+        return new Error(`upstream "${serverName}" tool call failed: ${errorText(err)}`, err instanceof Error ? { cause: err } : undefined);
+    }
+}
+/**
+ * How long a server whose session recovery failed refuses automatic
+ * re-attempts. Fixed by design: a reconnect storm against a down upstream
+ * buys nothing; the honest failure state plus this window is the v1
+ * answer, to be revisited with real-world data.
+ */
+export const SESSION_RECOVERY_COOLDOWN_MS = 30_000;
+function transportOf(def) {
+    if (def.transport === "sse")
+        return "sse";
+    return def.url ? "http" : "stdio";
+}
+function sessionRestartRemediation(serverName) {
+    return `restart the Agent session to re-establish the MCP session for "${serverName}"`;
+}
+function sessionRecoveryHint(serverName, reason) {
+    return `upstream "${serverName}" MCP session invalidated and automatic recovery failed (${reason}) — ${sessionRestartRemediation(serverName)}`;
+}
+/**
+ * Whether an upstream error means "your MCP session no longer exists".
+ *
+ * The official TypeScript server SDK rejects an unknown session with HTTP
+ * 404 carrying the JSON-RPC error "Session not found", and pairs 401/403
+ * with -32000 for authentication rejections — so 401/403 gate the match
+ * out first, and an auth rejection can never enter recovery. The body
+ * reaches us inside the client SDK's `Error POSTing to endpoint: …`
+ * wrapper, so a word match covers custom upstream wordings (the real-world
+ * one says "MCP session no longer exists"). Real-machine verification
+ * (2026-10-23) showed custom upstreams also answer with other non-auth
+ * statuses — a 400 carrying that same -32000 body took the plain
+ * `SdkHttpError` path, not the enveloped `ProtocolError` one — hence the
+ * status gate is "not an auth rejection" rather than "exactly 404". A
+ * stray non-auth response that merely mentions "session" costs one
+ * idempotent-safe reconnect+retry, an acceptable price for covering every
+ * upstream wording. The `ProtocolError` branch covers the HTTP-200
+ * JSON-RPC error case, where the client SDK parses the envelope and
+ * rejects with the upstream's error code instead.
+ */
+export function isSessionInvalidation(err) {
+    if (err instanceof SdkHttpError)
+        return err.status !== 401 && err.status !== 403 && /session/i.test(err.message);
+    if (err instanceof ProtocolError)
+        return err.code === -32000 && /session/i.test(err.message);
+    return false;
 }
 function failureStatus(name, def, error) {
     const detail = errorText(error).slice(0, 300);
@@ -189,6 +476,18 @@ function failureStatus(name, def, error) {
                 : `check that \`${def.command ?? "the MCP command"}\` is installed and responsive`,
     };
 }
+/**
+ * Whether the gateway manages the OAuth credential for this definition:
+ * Trellis-owned OAuth, and no explicit `Authorization` header — someone
+ * who wrote one in canonical meant it, and silently overriding it with a
+ * stored token would be the kind of invisible precedence that is
+ * impossible to debug. Both `withOAuthHeader` and the per-request
+ * `AuthProvider` attach on exactly this predicate.
+ */
+export function oauthAttachApplies(def) {
+    return isOAuthAuth(def.auth) && oauthOwner(def.auth) === "trellis"
+        && !Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
+}
 /**
  * Attaches a stored OAuth token, refreshing it first if it has expired.
  *
@@ -197,15 +496,10 @@ function failureStatus(name, def, error) {
  * OAuth at all, or one whose credential lives in `headers` already, and
  * neither should be disturbed.
  *
- * An explicit `Authorization` header in canonical wins. Someone who wrote
- * one meant it, and silently overriding it with a stored token would be
- * the kind of invisible precedence that is impossible to debug.
+ * An explicit `Authorization` header in canonical wins.
  */
 export async function withOAuthHeader(name, def, homeDir) {
-    if (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis")
-        return def;
-    const hasExplicitAuth = Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
-    if (hasExplicitAuth)
+    if (!oauthAttachApplies(def))
         return def;
     const stored = readToken(homeDir, name);
     const resource = new URL(def.url);
@@ -217,6 +511,68 @@ export async function withOAuthHeader(name, def, homeDir) {
         return def;
     return { ...def, headers: { ...(def.headers ?? {}), Authorization: `Bearer ${token.accessToken}` } };
 }
+/**
+ * The early-refresh window on the gateway's per-request path. Minute-scale
+ * on purpose: a request that passes the freshness check must not carry a
+ * token that dies mid-flight. `store.ts`'s 60s default is untouched —
+ * `mcp auth`/`mcp renew` don't have this problem.
+ */
+export const GATEWAY_REFRESH_SKEW_MS = 300_000;
+/**
+ * The SDK `AuthProvider` for one Trellis-owned OAuth upstream: `token()`
+ * runs as each outbound request's headers are assembled, so credentials
+ * resolve per request instead of once at connect time.
+ *
+ * Every read goes back to the token file with no memory cache — that is
+ * what makes a refresh by `trellis mcp auth` in another terminal take
+ * effect on the very next request of a running gateway (D6).
+ */
+export function trellisAuthProvider(opts) {
+    let lastIssued;
+    return {
+        token: async () => {
+            try {
+                const token = await ensureFreshToken(opts.homeDir, opts.serverName, {
+                    skewMs: opts.skewMs ?? GATEWAY_REFRESH_SKEW_MS,
+                    fetchImpl: opts.fetchImpl,
+                    now: opts.now,
+                });
+                if (!token)
+                    return undefined;
+                lastIssued = token.accessToken;
+                opts.onCredentialRecovered?.();
+                return token.accessToken;
+            }
+            catch {
+                // The pre-request credential check must never abort the request
+                // pipeline (D3): send whatever is stored — possibly stale — and
+                // let the server's 401 path decide the outcome.
+                return readToken(opts.homeDir, opts.serverName)?.accessToken;
+            }
+        },
+        onUnauthorized: async () => {
+            // The server just rejected a token that looked fine locally; the
+            // expiry check is exactly what must be bypassed. The transport
+            // retries the request once after this resolves — and when this
+            // throws instead, the SDK propagates the error to this one call
+            // as-is (pinned by test), so the message names the way out.
+            try {
+                await forceRefresh(opts.homeDir, opts.serverName, {
+                    previousAccessToken: lastIssued,
+                    fetchImpl: opts.fetchImpl,
+                    now: opts.now,
+                });
+            }
+            catch (err) {
+                opts.onCredentialFailure?.(err);
+                const base = err instanceof Error ? err.message : String(err);
+                throw new RefreshError(base.includes("trellis mcp auth")
+                    ? base
+                    : `${base} — run \`trellis mcp auth ${opts.serverName}\` in a human terminal; the running gateway picks the new credential up on its next request`, err instanceof RefreshError ? err.oauthError : undefined);
+            }
+        },
+    };
+}
 function errorText(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/lib/mcpConnect.d.ts

@@ -12,7 +12,7 @@
  * which servers are in scope, or knows what a tool is; callers isolate
  * failures in whatever way suits them.
  */
-import { Client } from "@modelcontextprotocol/client";
+import { Client, type AuthProvider } from "@modelcontextprotocol/client";
 import type { McpServerDef, SecretsPolicy } from "../core/types.js";
 /** What an MCP upstream is told this client is. Each consumer passes its
  * own so an upstream's logs name the thing that actually connected. */
@@ -46,11 +46,11 @@ export declare function connectWithCleanup<T, TTransport extends {
 }, transport: TTransport, timeoutMs: number, message: string): Promise<T>;
 export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
 export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
-export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
-export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
+export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
+export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 /**
  * Transport dispatch, matching the original bridge's own ordering: `http`
  * and `sse` are explicit, everything else (including an absent
  * `transport`) is stdio — a default the canonical schema relies on.
  */
-export declare function connectServer(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
+export declare function connectServer(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;

package/dist/lib/mcpConnect.js

@@ -102,17 +102,27 @@ export function resolveHeaders(def, secretsPolicy) {
     }
     return result;
 }
-export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo) {
+export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     const client = new Client(clientInfo, { capabilities: {}, versionNegotiation: { mode: "auto", probe: { timeoutMs } } });
     const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
+    // authProvider is the SDK's per-request credential seam: `token()` runs
+    // as each request's headers are assembled and its result overrides
+    // `requestInit`'s Authorization — the alternative to burning a Bearer
+    // into the static headers once at connect time.
+    const opts = {
+        ...(headers ? { requestInit: { headers } } : {}),
+        ...(authProvider ? { authProvider } : {}),
+    };
     return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
-export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo) {
+export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     // HTTP+SSE is a legacy transport; it cannot carry modern discovery.
     const client = new Client(clientInfo, { capabilities: {} });
     const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
+    const opts = {
+        ...(headers ? { requestInit: { headers } } : {}),
+        ...(authProvider ? { authProvider } : {}),
+    };
     return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
 /**
@@ -120,10 +130,10 @@ export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo) {
  * and `sse` are explicit, everything else (including an absent
  * `transport`) is stdio — a default the canonical schema relies on.
  */
-export function connectServer(def, secretsPolicy, timeoutMs, clientInfo) {
+export function connectServer(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     if (def.transport === "http")
-        return connectHttp(def, secretsPolicy, timeoutMs, clientInfo);
+        return connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider);
     if (def.transport === "sse")
-        return connectSse(def, secretsPolicy, timeoutMs, clientInfo);
+        return connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider);
     return connectStdio(def, secretsPolicy, timeoutMs, clientInfo);
 }

package/dist/lib/mcpToolRegistry.d.ts

@@ -82,6 +82,16 @@ export declare class McpToolRegistry {
      * aggregated, with no special-casing here.
      */
     add(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
+    /**
+     * Swap one server's entire registration — the mid-session recovery path.
+     * Every candidate the server previously contributed is dropped before the
+     * fresh tool set is added, so a changed upstream tool set is reflected
+     * exactly rather than accumulated. Exposed names are re-allocated across
+     * the whole registry, so a name this server frees may be re-assigned
+     * deterministically to another server's colliding tool — accepted drift,
+     * pinned by the spec scenario.
+     */
+    replace(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
     private exposedNameFor;
     /** Every registered tool, under its prefixed name, in registration
      * order. Each tool's own `description`/`inputSchema` and any additional

package/dist/lib/mcpToolRegistry.js

@@ -127,6 +127,25 @@ export class McpToolRegistry {
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
     }
+    /**
+     * Swap one server's entire registration — the mid-session recovery path.
+     * Every candidate the server previously contributed is dropped before the
+     * fresh tool set is added, so a changed upstream tool set is reflected
+     * exactly rather than accumulated. Exposed names are re-allocated across
+     * the whole registry, so a name this server frees may be re-assigned
+     * deterministically to another server's colliding tool — accepted drift,
+     * pinned by the spec scenario.
+     */
+    replace(serverName, upstream, tools) {
+        const kept = this.candidates.filter((candidate) => candidate.serverName !== serverName);
+        this.candidates.length = 0;
+        this.candidates.push(...kept);
+        for (const tool of tools)
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+        this.rebuild();
+        const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
+        return { added, skipped: [] };
+    }
     exposedNameFor(serverName, toolName) {
         for (const [name, entry] of this.entries) {
             if (entry.serverName === serverName && entry.toolName === toolName)

package/dist/lib/oauth/refresh.d.ts

@@ -33,4 +33,19 @@ export declare class RefreshError extends Error {
  * would hide a revoked grant.
  */
 export declare function ensureFreshToken(homeDir: string, serverName: string, opts?: RefreshOptions): Promise<StoredToken | undefined>;
+export interface ForceRefreshOptions extends RefreshOptions {
+    /** The access token the caller last saw rejected (e.g. by a 401). When
+     * the stored credential already holds a different access token, another
+     * process refreshed in between and that result is returned as-is. */
+    previousAccessToken?: string;
+}
+/**
+ * Refreshes regardless of expiry — the 401 recovery path.
+ *
+ * The server just rejected a token that still looks unexpired locally
+ * (revoked early, clock skew, a stale read), so `ensureFreshToken`'s
+ * freshness check is exactly the thing that must be bypassed. Everything
+ * else matches it: per-server lock, in-lock re-read, rotation persisted.
+ */
+export declare function forceRefresh(homeDir: string, serverName: string, opts?: ForceRefreshOptions): Promise<StoredToken>;
 export declare function performRefresh(serverName: string, token: StoredToken, opts?: RefreshOptions): Promise<StoredToken>;

package/dist/lib/oauth/refresh.js

@@ -53,6 +53,36 @@ export async function ensureFreshToken(homeDir, serverName, opts = {}) {
         return refreshed;
     }, { timeoutMs: opts.lockTimeoutMs, now });
 }
+/**
+ * Refreshes regardless of expiry — the 401 recovery path.
+ *
+ * The server just rejected a token that still looks unexpired locally
+ * (revoked early, clock skew, a stale read), so `ensureFreshToken`'s
+ * freshness check is exactly the thing that must be bypassed. Everything
+ * else matches it: per-server lock, in-lock re-read, rotation persisted.
+ */
+export async function forceRefresh(homeDir, serverName, opts = {}) {
+    const existing = readToken(homeDir, serverName);
+    if (!existing) {
+        throw new RefreshError(`OAuth token for "${serverName}" is gone — run \`trellis mcp auth ${serverName}\``);
+    }
+    return withServerLock(homeDir, serverName, async () => {
+        // Re-read inside the lock. With the expiry check gone, "someone else
+        // got here first" can only be detected by identity: if the stored
+        // access token is no longer the one we saw rejected, a concurrent
+        // refresh already fixed things and rotating again would kill its
+        // result.
+        const current = readToken(homeDir, serverName) ?? existing;
+        if (opts.previousAccessToken !== undefined && current.accessToken !== opts.previousAccessToken)
+            return current;
+        if (!current.refreshToken) {
+            throw new RefreshError(`OAuth token for "${serverName}" has no refresh token — run \`trellis mcp auth ${serverName}\``);
+        }
+        const refreshed = await performRefresh(serverName, current, opts);
+        writeToken(homeDir, serverName, refreshed);
+        return refreshed;
+    }, { timeoutMs: opts.lockTimeoutMs, now: opts.now });
+}
 export async function performRefresh(serverName, token, opts = {}) {
     const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000) }));
     const now = opts.now ?? Date.now;

package/dist/lib/upstreamResources.d.ts

@@ -13,6 +13,11 @@ export declare class UpstreamResources {
     private readonly files;
     constructor(timeoutMs: number, warn: (message: string) => void);
     add(source: string, client: Client): void;
+    /** Forget one source entirely: its client and every file route it
+     * registered. Called before a source is re-added mid-session — stale
+     * routes would otherwise route reads at the closed previous client
+     * (`listResources`/`listSkills` re-register the fresh client's routes). */
+    removeSource(source: string): void;
     private skillsEnabled;
     private isolated;
     listResources(): Promise<Resource[]>;

package/dist/lib/upstreamResources.js

@@ -54,6 +54,16 @@ export class UpstreamResources {
         this.warn = warn;
     }
     add(source, client) { this.clients.set(source, client); }
+    /** Forget one source entirely: its client and every file route it
+     * registered. Called before a source is re-added mid-session — stale
+     * routes would otherwise route reads at the closed previous client
+     * (`listResources`/`listSkills` re-register the fresh client's routes). */
+    removeSource(source) {
+        this.clients.delete(source);
+        for (const [uri, route] of this.files)
+            if (route.source === source)
+                this.files.delete(uri);
+    }
     skillsEnabled(client) {
         return Boolean(client.getServerCapabilities()?.resources && client.getDiscoverResult()?.capabilities.extensions?.[EXTENSION]);
     }

package/dist/pi-bridge/bundle.js

@@ -45929,10 +45929,13 @@ function resolveHeaders(def, secretsPolicy) {
   }
   return result;
 }
-async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo) {
+async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
   const client = new Client(clientInfo, { capabilities: {}, versionNegotiation: { mode: "auto", probe: { timeoutMs } } });
   const headers = resolveHeaders(def, secretsPolicy);
-  const opts = headers ? { requestInit: { headers } } : void 0;
+  const opts = {
+    ...headers ? { requestInit: { headers } } : {},
+    ...authProvider ? { authProvider } : {}
+  };
   return connectWithCleanup(
     client,
     new StreamableHTTPClientTransport(new URL(def.url), opts),
@@ -45940,10 +45943,13 @@ async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo) {
     `connect timed out after ${timeoutMs}ms`
   );
 }
-async function connectSse(def, secretsPolicy, timeoutMs, clientInfo) {
+async function connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
   const client = new Client(clientInfo, { capabilities: {} });
   const headers = resolveHeaders(def, secretsPolicy);
-  const opts = headers ? { requestInit: { headers } } : void 0;
+  const opts = {
+    ...headers ? { requestInit: { headers } } : {},
+    ...authProvider ? { authProvider } : {}
+  };
   return connectWithCleanup(
     client,
     new SSEClientTransport(new URL(def.url), opts),
@@ -45951,9 +45957,9 @@ async function connectSse(def, secretsPolicy, timeoutMs, clientInfo) {
     `connect timed out after ${timeoutMs}ms`
   );
 }
-function connectServer(def, secretsPolicy, timeoutMs, clientInfo) {
-  if (def.transport === "http") return connectHttp(def, secretsPolicy, timeoutMs, clientInfo);
-  if (def.transport === "sse") return connectSse(def, secretsPolicy, timeoutMs, clientInfo);
+function connectServer(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
+  if (def.transport === "http") return connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider);
+  if (def.transport === "sse") return connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider);
   return connectStdio(def, secretsPolicy, timeoutMs, clientInfo);
 }
 
@@ -46041,6 +46047,24 @@ var McpToolRegistry = class {
     const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
     return { added, skipped: [] };
   }
+  /**
+   * Swap one server's entire registration — the mid-session recovery path.
+   * Every candidate the server previously contributed is dropped before the
+   * fresh tool set is added, so a changed upstream tool set is reflected
+   * exactly rather than accumulated. Exposed names are re-allocated across
+   * the whole registry, so a name this server frees may be re-assigned
+   * deterministically to another server's colliding tool — accepted drift,
+   * pinned by the spec scenario.
+   */
+  replace(serverName, upstream, tools) {
+    const kept = this.candidates.filter((candidate) => candidate.serverName !== serverName);
+    this.candidates.length = 0;
+    this.candidates.push(...kept);
+    for (const tool of tools) this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+    this.rebuild();
+    const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
+    return { added, skipped: [] };
+  }
   exposedNameFor(serverName, toolName) {
     for (const [name, entry] of this.entries) {
       if (entry.serverName === serverName && entry.toolName === toolName) return name;
@@ -46293,10 +46317,11 @@ var listSchema = external_exports.looseObject({ skills: external_exports.array(e
 var getSchema = external_exports.looseObject({ skill: external_exports.unknown() });
 
 // src/lib/gatewayBackend.ts
+function oauthAttachApplies(def) {
+  return isOAuthAuth(def.auth) && oauthOwner(def.auth) === "trellis" && !Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
+}
 async function withOAuthHeader(name, def, homeDir) {
-  if (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis") return def;
-  const hasExplicitAuth = Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
-  if (hasExplicitAuth) return def;
+  if (!oauthAttachApplies(def)) return def;
   const stored = readToken(homeDir, name);
   const resource = new URL(def.url);
   resource.hash = "";

package/docs/roadmap.md

@@ -971,7 +971,12 @@ health, honest credential status in `trellis.mcp.status`, browser callback
 page). v0.14.0 — pi native MCP delivery (pi ≥ 1.1.0 `mcp.json` writes,
 bridge retirement in the same sync; supersedes P4's default path).
 v0.14.1 — canonical `auth.client_name` for providers that gate OAuth dynamic
-client registration by client name (Figma).
+client registration by client name (Figma). v0.15.0 — workspace scope: a
+second canonical layer in the repo itself (`<repo>/.agents/`), merged
+workspace-wins-by-ID, delivered layer-preserving to all six agents.
+v0.15.1 — `--flag=value` accepted everywhere; `mcp remove --workspace`.
+v0.16.0 — doctor validates workspace `.codex/config.toml` TOML syntax.
+v0.17.0 — doctor reports diverging `trellis` entrypoints on PATH.
 
 **Cross-machine / cloud sharing — confirmed future direction, not yet
 scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-
@@ -988,6 +993,20 @@ coordination, evaluated only after the simpler pieces are proven). See
 and `daytonaio/daytona` were both evaluated and not adopted (preview-only
 API instability, and unmaintained-as-of-June-2026, respectively).
 
+**Self-evolution — direction captured 2026-10-20, not yet scoped as a
+phase.** Trellis is two decoupled subsystems: hosting (delivery and
+consistency of canonical content) and self-evolution (content that improves
+with use, running ambiently on the runtime substrate, opt-in and graded
+off → observe → propose → auto-A). Dependency runs one way, evolution →
+hosting, through a narrow port; uninstalling evolution leaves hosting
+byte-identical. Methodology ported from google-research/harness2 (no usable
+SDK exists); first step is a set of generic hosting extension points, not
+evolution code. See [`self-evolution.md`](self-evolution.md) for the full
+idea, what is verified versus assumed, and the open decisions; the
+verifiable contract is the consolidated draft at
+`openspec/changes/trellis-evolve/` (one change, two capabilities:
+`host-extension-points` and `self-evolution`; unimplemented).
+
 No dates. This is scoped by verification milestones, not calendar time.
 Execution order for P11–P16: P11 → P12 → P13 → P14 → P15 → P16 — CRUD
 (P12) lands before the larger features (P14, P15, P16) so each can be

package/docs/runtime-infra.md

@@ -0,0 +1,55 @@
+# Runtime 基建调研议程
+
+> **状态:调研议程,尚未实施。** 记录于 2026-10-23。四个方向是"我们的 runtime"离不开的
+> 基建层;逐项调研,调研结果各自沉淀后再决定实施。自我进化(第 4 项)已有完整草案,
+> 见 `docs/self-evolution.md` 与 `openspec/changes/trellis-evolve/`。
+
+## 建议顺序:1 → 2 → 3,第 4 项按既有 tasks 推进
+
+先吃透模型接入层(网关),再往网络层(代理、多机)走;进化已是实施轨道,不是调研轨道。
+
+## 1. 大模型网关(Magpie)——子仓库化 + 核心实现研究
+
+已知:
+- Magpie 已在 Air 两层实测运行(macOS 与 OrbStack worker 各自 `127.0.0.1:3425/v1`);
+  worker 层 Codex 流式/工具往返/Responses 通过。用法见 `$local-model-gateway`、
+  `$mac-air-usage`。
+
+调研问题:
+- Magpie 源码在本机的位置(**未定位,第一步**);
+- 子仓库形态:git submodule / subtree / 研究副本(先例:`~/www/morphix-research/sources/`);
+- 核心实现:provider 路由与适配、流式转发、工具调用透传、错误与重试语义。
+
+## 2. 代理——稳定访问层
+
+调研问题:
+- Magpie 到各上游 provider 的代理路由(per-provider 配置、failover 策略);
+- npm/git 等开发工具链的代理;
+- 与网关层的边界:重试/切换由代理层还是网关层负责;
+- 与 Nore 的职责区分(设备互联 vs 外网代理,别混为一谈)。
+
+已有数据点:2026-10-22 npm publish 上传连接 ECONNRESET,IPv4-first + 单 socket 解决;
+GET/ping 正常、仅上传路径异常。
+
+## 3. 多机互通——相互委派任务的网络底座
+
+已知锚点:
+- Pro↔Air 私网由 Nore 设备互联提供(`ssh morphix-air-private` → `100.127.171.120`);
+- 本机有 `~/www/nore/` 与 `~/www/nore-next/` 两个仓库,调研以 Nore 源码为主对象之一;
+- 现网痛点:SSH 中继偶发超时(Air doctor 详情两次读取均超时)。
+
+委派已有雏形(分散,未统一):Trellis `tasks_handoff`(MCP)、Air 侧 Dagu
+(`morphix-air-tasks`,当前已禁用)、agent-collab mailbox。
+
+调研问题:网络可靠性(重连/唤醒)、服务发现、委派语义与安全边界。
+
+## 4. 自我进化——已是实施轨道
+
+不在本文重复。接手入口:`docs/self-evolution.md` 的"接手指南";下一步是其
+tasks 第 1 组的三个只读前置验证(元数据信号采样、provider 读取路径、扩展加载机制),
+之后才是托管扩展点(P1)。
+
+## 对照样本(见记忆 research-subjects-backlog)
+
+Raven(harness of harnesses)、Octop(腾讯云多 Agent,coordinator 调度与 workspace
+分层)、asyar(轻量启动器,仅交互效率参照)。

package/docs/self-evolution.md

@@ -0,0 +1,209 @@
+# 自我进化:Trellis 的第二个子系统(想法沉淀)
+
+> **状态:整合草案,尚未实现。** 记录于 2026-10-20,来自一轮对 google-research/harness2 的调研与讨论;同日已整合为 `openspec/changes/trellis-evolve/`(一份草案、两个解耦的 capability)。
+> 本文是**想法与取舍**:是什么、为什么、边界在哪、已核实什么、还没定什么。可验证的行为约束在 change 的 `specs/` 里,**二者冲突时以 `specs/` 为准**。
+
+## 接手指南
+
+**一句话现状**:方向、边界、评测方法与护栏已定并写成可校验的草案;没有一行实现代码;下一步是先做三项只读前置验证,再做托管扩展点。
+
+**文档地图(各管什么,避免重复维护)**
+
+| 文件 | 管什么 | 更新时机 |
+|---|---|---|
+| `docs/self-evolution.md`(本文) | 想法、取舍、已核实/未核实、路线 | 每次核实出新事实或做出决定 |
+| `openspec/changes/trellis-evolve/proposal.md` | 为什么、改什么、影响面 | 范围变化时 |
+| `…/specs/host-extension-points/spec.md` | 托管侧通用扩展点的行为契约 | 接口决定后 |
+| `…/specs/self-evolution/spec.md` | 进化子系统的行为契约 | 行为决定后 |
+| `…/design.md` | 技术决策、已核实现状(带代码位置)、风险、开放问题 | 决策或核实后 |
+| `…/tasks.md` | 实施顺序与逐项验证方式 | 实施中勾选 |
+| `docs/roadmap.md` | 一段指针 | 阶段变化时 |
+
+**建议阅读顺序**:本文"一句话"与"核心原则" → `design.md` 的 Context(已核实表)与 Open Questions → `tasks.md` 前三组 → 需要细节再读 `specs/`。
+
+**接手后第一步(tasks 第 1 组,全部只读)**:① 真机采样元数据事件能产生什么信号;② 核实 skills/instructions provider 是实时读取还是启动时缓存;③ 定下扩展加载机制与状态目录路径。这三项会决定 `host-extension-points` 的具体接口,**不要在它们之前开始写实现**。
+
+**需要接手人特别留意的三件事**
+
+1. **解耦是硬约束**:依赖只能是进化 → 托管。`src/evolve/` 只允许 import `src/host/*`,有测试强制。任何让托管"知道"进化的改动都是方向性错误。
+2. **带外批准目前不是完全可靠的**:有 shell 能力的 agent 理论上能执行管理面命令,TTY 检测只是启发式。`auto-A` 开启之前必须再评估(见 design 的 Risks 与 Open Questions)。
+3. **覆盖范围有边界**:事件只来自经 gateway/runtime 投递的 agent,仅走原生渲染的 agent 没有工具调用事件。不要在文档或 doctor 输出里假装全覆盖。
+
+**本草案的形成过程(便于判断哪些结论可信)**:最初按"用户运行 `trellis evolve` 命令触发"建模,被用户纠正为"环境式、跑在 runtime 上、与托管解耦、可选开启"后整体重写。命令式阶段遗留的"单备份会话写入""staging 复现层分裂"等需求已下沉为托管的公开接口。
+
+## 一句话
+
+Trellis 由两个**解耦**的部分组成:**托管**(让配置被正确投递并保持一致)和**自我进化**(让被托管的内容随使用变得更好)。进化是挂在 runtime 底座上的环境式能力,跑在其上的 agent 自己持续进化,可选安装、分级开启;它**不是**一条要用户去敲的命令。
+
+## 为什么要做
+
+托管已经覆盖 skills、MCP、指令、scope、memory,但托管内容的**改进完全靠人**。信号其实一直存在,缺的是把"信号 → 提案 → 验证 → 采纳 → 教训沉淀"闭环起来的机制。2026-10 的两个真实事故说明了这一点:
+
+- workspace `.codex/config.toml` 重复键,让该项目的所有 Codex 会话静默失败约 19 小时,没有任何机制主动发现;
+- PATH 上 0.12.0 旧入口遮蔽 0.16.0,把版本分叉误诊成 `servers.yaml` 配置错误。
+
+两件事 doctor 都在事后补上了检查,但"事故 → 人发现 → 人修 → 人补检查"这条链全靠人。进化要缩短的就是这条链。
+
+## 核心原则:两个子系统,一个窄接口
+
+| | 托管 (Hosting) | 自我进化 (Evolution) |
+|---|---|---|
+| 职责 | canonical 内容被正确投递并保持一致 | 被托管的内容随使用变好 |
+| 拥有 | canonical、adapters、gateway、backup、doctor、memory 管道 | 信号、提案、验证、风险门、lesson、运行档案 |
+| 不知道 | 进化的存在 | 具体 agent 怎么渲染、怎么投递 |
+| 缺席时 | 完全正常 | (本来就可选) |
+
+- **依赖方向只有一条:进化 → 托管,绝不反向。** 卸载进化,托管行为逐字节不变。这比"功能开关"更强:它是**可选安装**。
+- **进化自己声明它需要的 `HostPort`,托管去实现**,和 harness2 的 `Substrate` 协议同构(方法只依赖协议,不 import 具体框架)。好处:进化可以用 fake host 独立测试;托管的 `scope.yaml`(怎么渲染)与进化的"可编辑表面"声明(哪些能改、有什么静默失效坑)各管各的;架构上不堵死将来对接别的宿主。
+- 早期进化放在同仓库独立目录(`src/evolve/` 只允许 import 托管的公开 `host` 子路径,用测试强制边界),接口稳定后再考虑拆独立包。
+
+```
+进化(只依赖这个接口)                  托管(实现它)
+HostPort {
+  readSurface(layer)        ───────→  loadCanonicalSource(只读,已有)
+  stage(edits)              ───────→  scratch HOME + 临时 workspace(测试夹具模式已有)
+  check(staged|live)        ───────→  doctor + sync --check + secrets audit
+  apply(edits, session)     ───────→  backup session 写入(已有,未公开)
+  rollback(session)         ───────→  trellis rollback(已有,未公开)
+  subscribe(events)         ───────→  会话事件流(新增,通用)
+  remember(lesson)          ───────→  memory 管道(已有)
+  delegate(task)            ───────→  agent-bridge(进行中)
+}
+```
+
+## 环境式运行:触发、观察、通知、生效
+
+Trellis 的 gateway 是按会话拉起的 stdio 进程,规范明确 **"without a resident daemon"**,所以进化也**不引入常驻进程**,靠事件驱动:
+
+1. **观察**:被动加主动并行。被动 = gateway 路由层记录元数据(工具/skill/记忆的调用、耗时、错误类别);主动 = agent 在用户纠正时自己调用 `trellis.evolve.note` 上报。主动信号最贵、质量最高(例如一次"配置改反方向"的纠正)。
+2. **触发**:会话结束(provider 的 `close()` 钩子)时判断信号量/严重度/冷却期,满足则 detached 拉起**一次性**后台作业,单实例锁。
+3. **提案 → 验证 → 过门**:见下节,即原五环的 Propose / Probe / Compose。
+4. **通知**:pending 提案经 provider 暴露给 agent(`pending` 工具或 resource),agent 在会话里告知用户;doctor 与 GUI 也可查看。
+5. **生效**:runtime 模式下 skills / instructions 由 provider 从 canonical 实时提供,采纳后**下个会话自然读到新版本,无需 sync**;只用原生渲染的 agent,采纳后触发 sync。
+6. **分级开启**:`off`(默认)→ `observe` → `propose` → `auto-A`(仅 Class A 自动采纳)。粒度为全局默认 + per-agent + per-workspace,沿用 `onboard --memory on` 的显式选择方式,写进 canonical,doctor 可见,不静默开启。
+
+CLI 退居**管理面**:`status | pending | approve | reject | enable | disable | rollback`,不再是触发器。
+
+## 进化循环(五环)
+
+```
+Observe → Propose → Probe → Compose → Apply+Reflect
+                                         │
+          lesson 回流为下次 Propose 的上下文 ┘
+```
+
+- **Propose**:经 agent-bridge `runDelegatedCall` 委派 editor,产出结构化 `proposal.yaml`。editor 是**不可信输出**:机械校验器复核 kind/target 白名单与证据要求,错误写成可执行散文喂回重试一次,再错丢弃。**没有 evidence 链接的提案直接丢弃。**
+- **Probe**:提案先写入 staging 候选(scratch HOME,按需加临时 workspace root),不动真配置。
+- **Compose**:风险门,见下。采纳铁律:任何验收器结果不得差于 baseline,宁可不进化。
+- **Apply+Reflect**:写入走一个备份会话,单点 `trellis rollback` 整体回滚;被采纳的编辑蒸馏成 lesson `{cue, lesson, evidence, confidence?}` 进 `memories/`,作为下次提案上下文(harness2 的 improvement harness)。
+
+## 评测:怎么对比修改前后(最关键的一环)
+
+harness2 的评分是**两段式且互相隔离**:选择(匿名对比、无 ground truth)与评分(checklist,选择承诺之后才跑)物理分离,选择器永远看不到评分材料。我们按"有无现成 oracle"分层:
+
+- **L1 配置类 — 确定性差集,零 LLM**:baseline 与 staging 候选各跑 doctor / `sync --check` / secrets audit,可采纳 ⟺ 无新 finding ∧ 目标 finding 已消除 ∧ 其余不变。配置类的检查本身就是 ground truth,比 LLM 选择器更强也更便宜。两个事故都属这一类。
+- **L2 内容类 — 沙盒执行 + 匿名 A/B**:同一道探针任务在 base 与 candidate 下各跑一次,交付物冻结后,以种子匿名 id 呈现给独立选择器(不给 verdict、不含评分字样、不标明哪臂是新)。选择器失败 / 任一臂未交付 / 选中 base ⟹ 一律不采纳。**一处刻意反转**:harness2 把 base 排除出候选池("构造上无法弃权",因为它必须进化);我们把 base **留在池里**,因为我们不能退化。
+- **L3 成绩单**:一小组带显式 checklist 的探针,定期对已采纳修改跑 `n_passed/n_criteria` 看趋势。评分失败记 `None`,不计入分母,**永不记 0 分**;结果只给人看,不给选择器看。
+- **缺口**:内容类(L2)缺**探针任务集**,这是真正的前置资产,比代码更难。来源优先级:真实事故复现题 > 用户纠正转化题 > 按 skill 领域合成题。因此路线先做 L1。
+
+执行隔离:本机用"穷人沙盒"——`mkdtemp` workspace + staging 渲染配置 + 重定向的 agent 配置 HOME + 一次性会话,**沙盒保证每次执行干净可复现,对比本身发生在冻结的产物上,不在沙盒里**。容器(本机有 OrbStack)后置,等探针要跑不可信代码或需并行 K 候选时再上。
+
+## 风险分级与护栏
+
+分级由**代码按 kind + target 计算**,不信 editor 自报的 `risk_class`:
+
+- **Class A**:可逆、零爆炸半径、证据确凿(如补一个 `${VAR}` 名、修复 doctor 已报告的 drift)——仅 `auto-A` 级别且 probe 通过时自动采纳,事后通知。
+- **Class B**:skill/指令内容编辑、MCP 路由变更——永远人批。
+- **Class C**:secrets、auth、受管 agent 集合、用户手写文件、`evolve` 自身配置——校验阶段拒绝,**连提案都不生成**。
+- 无法分类 → 按 Class B。
+
+环境式运行比命令式危险得多,必须有的护栏:
+
+1. **被进化者不能批准自己的进化**:Class B 批准**只走带外通道**(CLI/GUI),agent 只能展示和提醒。否则传入 `confirm=true` 就能自批,批准形同虚设。
+2. **层级隔离**:信号、提案、verdict、lesson 全部携带 `global | workspace(<root>)` 归属;跨层写入被拒;**单个项目的证据不自动升格为全局规则**(需另一上下文佐证或显式批准);workspace 编辑继承可提交约束(`${VAR}` 引用,绝不写凭据字面值——那个文件 git 跟踪在别人的仓里)。
+3. **隐私**:观察只存元数据,不存 payload,并过 secrets 擦除。
+4. **防自激**:evolver 自己的调用与编辑不进信号源。
+5. **成本与频率**:委派 editor 有预算上限、冷却期、每日提案上限。
+6. **会话中途漂移**:gateway 启动时 pin 住 canonical 版本摘要,采纳只在会话边界生效。
+7. **并发**:信号只追加存储,evolver 作业单实例锁。
+8. **失败收口**:probe / verdict / 选择过程的任何失败一律记为"不采纳",测量失败记 unknown,不当作通过。
+9. **不 bypass 目标 agent 的审批与沙盒**:harness2 在宿主机上用 `--dangerously-bypass-approvals-and-sandbox`,这是研究代码的取舍,**我们明确不采纳**。
+
+## 托管侧需要新增的通用扩展点
+
+目前 SDK 只导出 `loadCanonicalSource`、`ALL_AGENTS`、`resolveScope` 与类型(只读),`trellis-sdk` spec 还禁止导出 adapters / commands 内部。进化要的能力托管侧都没有公开接口,所以接缝要新建,且必须是**通用扩展点,不带进化字样**:
+
+1. **事件流**:会话开始/结束、工具调用已路由(仅元数据)。指标、审计同样可用。
+2. **公开 `host` 子路径**:写入(带备份会话)、回滚、检查。不放开 `src/commands/*` 内部实现,而是新增明确的导出面。
+3. **provider 外部注册约定**:`TrellisProvider` 已是开放接口(tools / resources / prompts / skill 条目 / `close()`),进化作为外部包注册自己的 provider,托管核心无需认识它。
+
+"单备份会话写入""probe staging 复现层分裂"这类本属托管的能力,已在整合草案里下沉为 `host` 门面(备份会话内应用/回滚、staging、结构化检查);进化只调用,不拥有。
+
+## 从 harness2 学到什么(已对照源码核实)
+
+来源:`github.com/google-research/harness2`,本机副本 `~/www/morphix-research/sources/harness2`。
+
+| 机制 | 出处 | 我们怎么用 |
+|---|---|---|
+| Propose–Probe–Compose,无 ground truth 的行为对比 | `core/proposer.py` `selection.py` | 循环骨架;L2 对比 |
+| 两段式测量(选择与评分隔离) | `core/selection.py` `judge.py` | L2 选择器看不到评分材料 |
+| 失败语义收口(judge 失败 = None;选择器失败 = 回退 base;preflight 带修复命令) | `judge.py` `selection.py` | 全局失败收口原则 |
+| 指纹 + 身份守卫的复用 | `core/runmark.py` | probe 缓存键 = 被测切片 sha1 |
+| 差异即数据(`SurfaceSpec`,frozen dataclass) | `core/tree.py` | "可编辑表面 + 静默失效模式"声明为数据 |
+| 三轴正交 + 一格子一实例 | `core/spec.py` `benchmarks/workbuddy.py` | `HostPort` 与 probe adapter 的形态 |
+| 穷人沙盒 | `substrate/codex.py:149-185` | probe workspace 边界 |
+| 校验错误即 prompt(原样喂回作重试反馈) | `validate_tree` | editor 重试 |
+
+**没有可直接用的 SDK**:无 PyPI 包、`harness2/__init__.py` 为空(无公开 API)、7 个 console script、仅 Linux、Python 3.12、绑 Vertex AI 与 Docker、与三个 benchmark 耦合。**移植方法论,不移植代码。**
+
+## 已核实 / 未核实
+
+| 已核实(读过代码或 spec;位置见 design.md Context) | 未核实 / 假设 |
+|---|---|
+| gateway 无常驻进程,client 断开即释放上游 | 观察元数据是否足以支撑有价值的信号(需真机采样,tasks 1.1) |
+| **所有工具调用(内建与上游)汇入同一咽喉点** `BuiltinRegistry.callTool`,由 `tools/call` handler 调用——事件可在此一处挂载 | skills / instructions provider 是实时读取还是启动时缓存(tasks 1.2),决定"会话快照"是否需要 |
+| `RuntimeContext` 只有 `{agentId, homeDir}`,**无会话标识**——须由事件层生成 | 扩展加载机制与状态目录路径(tasks 1.3) |
+| 关闭路径只处理 stdin `end`/`close` 与 SIGTERM/SIGINT/SIGHUP;**SIGKILL/崩溃不触发 `close()`**——因此必须有"下次启动补偿检查" | 全局记忆未启用时,lesson 回流的实际效果 |
+| `openBackupSession` 与 `collectDoctorReport` 存在,但**都未经 SDK 公开**;SDK 根入口只导出 `loadCanonicalSource`/`ALL_AGENTS`/`resolveScope`,且 spec 禁止导出 adapters/commands 内部 | 带外批准在 agent 有 shell 能力时的强度(TTY 检测只是启发式) |
+| `TrellisProvider` 含 `close()` 与 skill 条目接口 | |
+| harness2 各机制的行为(见上表) | |
+
+## 已定倾向 / 待决
+
+- **倾向(未最终确认)**:Class B 批准带外为主;后台作业由会话结束拉起而不靠外部调度器;进化先同仓库独立目录;先做 L1。
+- **待决**:用户纠正的采集形态(手工 `note` vs 从会话收割);探针任务集放 canonical 还是 per-workspace;`auto-A` 之前需要多少次有人监督的运行才算"证明不误报";运行档案的轮转策略。
+
+## 前置依赖
+
+- agent-bridge 还有 5 个未完成项(委托存储、doctor 委托 section、Claude Code blocked、多跳、文档);editor 委派依赖 `runDelegatedCall`,不可用时 L1 可降级为 rule-based 提案。
+- 全局记忆需启用(`trellis onboard --memory on`)才能让 lesson 回流有真实载体;本机目前未启用。
+- 探针任务集(L2 的前置资产)。
+
+## 分阶段路线
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| P0 | doctor oracle、backup/rollback、memory 管道、agent-bridge 委派原语 | 已就位 |
+| P1 | **托管扩展点**(事件流、`host` 子路径、provider 外部注册) | 先做;进化侧一切依赖它 |
+| P2 | 进化 Observe + Propose,仅配置类、人审批 | |
+| P3 | Probe:L1 verdict 差集;`auto-A` | |
+| P4 | 内容类:L2 匿名 A/B,依赖探针任务集;lesson 回流提质 | |
+| P5 | 递归预算(K 候选 parallel / K 步 sequential)、容器化 probe | |
+
+## 明确不做
+
+- 进化 Trellis 自身代码、secrets、auth、受管 agent 集合、用户手写文件。
+- 让托管层依赖进化(依赖方向永远是进化 → 托管)。
+- 绕过目标 agent 的审批 / 沙盒机制。
+- 在没有现成 oracle 的类别上抢跑自动采纳(内容类必须等探针任务集)。
+
+## 下一步
+
+已完成:整合为 `openspec/changes/trellis-evolve/`(一份草案、两个 capability:`host-extension-points` 与 `self-evolution`),并已 `openspec validate --strict`;gateway 咽喉点与 `close()` 覆盖范围已核实(见上表)。
+
+待做(按 `tasks.md` 顺序):
+
+1. **前置验证(第 1 组,只读)**:真机采样元数据信号质量;核实 skills/instructions provider 读取路径;定下扩展加载机制与状态目录路径。
+2. **托管扩展点(第 2 组)**:事件总线、`host` 子路径门面、外部 provider 注册、"托管不依赖消费者"构建测试。纯增量、默认零行为变化,可单独发版。
+3. **进化 `off`/`observe` → `propose` → `auto-A`**(第 3–8 组),`auto-A` 之前须再评估带外批准的强度。
+4. L2 执行、探针任务集、递归预算为后续独立变更。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",