agent-trellis 0.17.0 → 0.18.0

package/dist/cli.js

@@ -172,7 +172,8 @@ Commands:
             Authorize a remote (http/sse) MCP server that uses OAuth —
               opens a browser once, stores the result 0600 under
               ~/.trellis/mcp/oauth/. A still-valid token is a no-op; an
-              expired one is refreshed without a browser. The gateway
+              expired one is refreshed without a browser. If the refresh
+              grant is rejected, this command starts a new login. The gateway
               refreshes silently on its own and never prompts.
               --force   re-authorize even if the stored token is valid
               --json    machine-readable output, no report text

package/dist/commands/mcpAuth.d.ts

@@ -19,6 +19,8 @@ export interface RunMcpAuthOptions {
     signal?: AbortSignal;
     onProgress?: (phase: "discovering" | "registering" | "waiting" | "exchanging" | "saving") => void;
     timeoutMs?: number;
+    /** An expired grant was rejected; the explicit auth command will log in again. */
+    onReauthorization?: () => void;
     /** Used by the desktop; native grants belong to each Agent. */
     requireHosted?: boolean;
 }

package/dist/commands/mcpAuth.js

@@ -12,7 +12,8 @@ import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { discoverAuthorizationServer, parseResourceMetadataUrl } from "../lib/oauth/discovery.js";
 import { authorize, abortable } from "../lib/oauth/flow.js";
-import { ensureFreshToken } from "../lib/oauth/refresh.js";
+import { ensureFreshToken, RefreshError } from "../lib/oauth/refresh.js";
+import { classifyRefreshFailure } from "../lib/oauth/renew.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 import { isExpired, readToken, tokenPath, writeToken } from "../lib/oauth/store.js";
 import { withServerLock } from "../lib/oauth/lock.js";
@@ -21,7 +22,14 @@ export async function runMcpAuth(opts) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
     try {
-        result = await authorizeMcpServer(opts);
+        result = await authorizeMcpServer({
+            ...opts,
+            onReauthorization: () => {
+                if (!opts.json)
+                    console.error(`OAuth grant for "${opts.serverName}" can no longer be refreshed; starting a new login.`);
+                opts.onReauthorization?.();
+            },
+        });
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -72,10 +80,21 @@ export async function authorizeMcpServer(opts) {
             return { server: opts.serverName, status: "already-valid", tokenFile: file, ...(existing.expiresAt ? { expiresAt: existing.expiresAt } : {}) };
         }
         if (existing?.refreshToken && !opts.requireHosted) {
-            // Expired but renewable — no browser needed.
-            const refreshed = await ensureFreshToken(homeDir, opts.serverName);
-            if (refreshed) {
-                return { server: opts.serverName, status: "refreshed", tokenFile: file, ...(refreshed.expiresAt ? { expiresAt: refreshed.expiresAt } : {}) };
+            try {
+                // Expired but renewable — no browser needed.
+                const refreshed = await ensureFreshToken(homeDir, opts.serverName);
+                if (refreshed) {
+                    return { server: opts.serverName, status: "refreshed", tokenFile: file, ...(refreshed.expiresAt ? { expiresAt: refreshed.expiresAt } : {}) };
+                }
+            }
+            catch (err) {
+                if (!(err instanceof RefreshError) || classifyRefreshFailure(err) !== "needs-auth")
+                    throw err;
+                opts.signal?.throwIfAborted();
+                // This is an explicit authorization request, so a dead grant can
+                // continue into login. Keep the old file until the new grant is
+                // saved; cancellation must not erase the prior credential.
+                opts.onReauthorization?.();
             }
         }
     }

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. */
@@ -103,7 +104,22 @@ export declare class LocalBackend implements GatewayBackend {
     listStatus(): readonly UpstreamStatus[];
     close(): Promise<void>;
     private closeUpstream;
+    /** 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;
 }
+/**
+ * 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 +128,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,7 +18,7 @@
 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 { UpstreamResources } from "./upstreamResources.js";
@@ -65,9 +65,22 @@ 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.
+        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)}`);
@@ -141,6 +154,39 @@ 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,
+        });
+    }
 }
 function failureStatus(name, def, error) {
     const detail = errorText(error).slice(0, 300);
@@ -189,6 +235,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 +255,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 +270,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/oauth/refresh.d.ts

@@ -19,6 +19,8 @@ export interface RefreshOptions {
     lockTimeoutMs?: number;
 }
 export declare class RefreshError extends Error {
+    readonly oauthError?: string | undefined;
+    constructor(message: string, oauthError?: string | undefined);
 }
 /**
  * Returns a token that is valid now, refreshing first if it isn't.
@@ -31,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

@@ -11,6 +11,11 @@
 import { isExpired, readToken, writeToken } from "./store.js";
 import { withServerLock } from "./lock.js";
 export class RefreshError extends Error {
+    oauthError;
+    constructor(message, oauthError) {
+        super(message);
+        this.oauthError = oauthError;
+    }
 }
 /**
  * Returns a token that is valid now, refreshing first if it isn't.
@@ -48,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;
@@ -67,7 +102,17 @@ export async function performRefresh(serverName, token, opts = {}) {
         body: body.toString(),
     });
     if (!response.ok) {
-        throw new RefreshError(`refresh_token grant for "${serverName}" failed with HTTP ${response.status}: ${await safeText(response)}`);
+        const detail = await safeText(response);
+        let oauthError;
+        try {
+            const payload = JSON.parse(detail);
+            if (typeof payload?.error === "string")
+                oauthError = payload.error;
+        }
+        catch {
+            // Providers may return plain text or an empty body.
+        }
+        throw new RefreshError(`refresh_token grant for "${serverName}" failed with HTTP ${response.status}: ${detail.slice(0, 200)}`, oauthError);
     }
     const payload = (await response.json());
     if (!payload.access_token) {
@@ -87,7 +132,7 @@ export async function performRefresh(serverName, token, opts = {}) {
 }
 async function safeText(response) {
     try {
-        return (await response.text()).slice(0, 200);
+        return await response.text();
     }
     catch {
         return "<unreadable body>";

package/dist/lib/oauth/renew.js

@@ -17,6 +17,7 @@
  */
 import { existsSync } from "node:fs";
 import { isExpired, readToken, tokenPath } from "./store.js";
+import { RefreshError } from "./refresh.js";
 /** Statuses that mean "a human step is required" — the non-zero-exit set
  * (design.md D6). */
 export const FAILURE_STATUSES = new Set([
@@ -77,8 +78,13 @@ export function hasRefreshToken(token) {
  * varies by provider, so message sniffing stays deliberately narrow.
  */
 export function classifyRefreshFailure(err) {
+    // A structured OAuth error takes precedence over the HTTP fallback:
+    // invalid_request also uses 400, but another login cannot fix it.
+    if (err instanceof RefreshError && err.oauthError !== undefined) {
+        return err.oauthError === "invalid_grant" ? "needs-auth" : "refresh-failed";
+    }
     const message = err instanceof Error ? err.message : String(err);
-    if (/there is no refresh token/.test(message))
+    if (/there is no refresh token|no recorded token endpoint/.test(message))
         return "needs-auth";
     if (/invalid_grant|HTTP 400|HTTP 401/.test(message))
         return "needs-auth";

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);
 }
 
@@ -46200,6 +46206,11 @@ async function withServerLock(homeDir, serverName, fn, opts = {}) {
 
 // src/lib/oauth/refresh.ts
 var RefreshError = class extends Error {
+  constructor(message, oauthError) {
+    super(message);
+    this.oauthError = oauthError;
+  }
+  oauthError;
 };
 async function ensureFreshToken(homeDir, serverName, opts = {}) {
   const now = opts.now ?? Date.now;
@@ -46242,7 +46253,14 @@ async function performRefresh(serverName, token, opts = {}) {
     body: body.toString()
   });
   if (!response.ok) {
-    throw new RefreshError(`refresh_token grant for "${serverName}" failed with HTTP ${response.status}: ${await safeText(response)}`);
+    const detail = await safeText(response);
+    let oauthError;
+    try {
+      const payload2 = JSON.parse(detail);
+      if (typeof payload2?.error === "string") oauthError = payload2.error;
+    } catch {
+    }
+    throw new RefreshError(`refresh_token grant for "${serverName}" failed with HTTP ${response.status}: ${detail.slice(0, 200)}`, oauthError);
   }
   const payload = await response.json();
   if (!payload.access_token) {
@@ -46262,7 +46280,7 @@ async function performRefresh(serverName, token, opts = {}) {
 }
 async function safeText(response) {
   try {
-    return (await response.text()).slice(0, 200);
+    return await response.text();
   } catch {
     return "<unreadable body>";
   }
@@ -46281,10 +46299,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/mcp-oauth-renewal.md

@@ -6,6 +6,16 @@ on a schedule, it refreshes whatever is expiring and reports — with a
 non-zero exit code — anything that needs a human, before an Agent session
 discovers it as a 401.
 
+When a refresh token has expired, been revoked, or been rotated out, the
+provider can reject renewal with OAuth `invalid_grant`. Run
+`trellis mcp auth <name>`: it attempts a silent refresh first, then starts
+a new browser login if the grant is no longer usable. No `--force` is
+required. Network failures, rate limits, and temporary provider failures
+remain errors to retry; they do not trigger another login. The prior
+credential is replaced only after the new authorization succeeds, so
+cancelling login preserves the existing file. Background renewal and the
+gateway report the failure and never open a browser.
+
 ```
 trellis mcp renew              # refresh what's expiring, report health
 trellis mcp renew --dry-run    # report only; no token-endpoint call

package/docs/roadmap.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-*Current release: v0.14.1 (2026-10-11). This file tracks phase-level scope;
+*Current release: v0.17.1 (2026-10-21). This file tracks phase-level scope;
 per-release detail lives in [`releases/`](releases/).*
 
 Each phase must ship with a `trellis doctor` check that verifies its own
@@ -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/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.0",
+  "version": "0.18.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",