agent-trellis 0.12.0 → 0.13.0

package/dist/cli.js

@@ -14,6 +14,7 @@ import { parseScopeArgs } from "./lib/scopeSelection.js";
 import { runMcpImport } from "./commands/mcpImport.js";
 import { parseMcpGatewayArgs, runMcpGateway, runMcpRuntime } from "./commands/mcpGateway.js";
 import { runMcpAuth } from "./commands/mcpAuth.js";
+import { runMcpRenew } from "./commands/mcpRenew.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
 import { runSkillList, runSkillAdd, runSkillRemove, runSkillScope, runSkillUpdateBuiltin } from "./commands/skill.js";
@@ -159,6 +160,16 @@ Commands:
               refreshes silently on its own and never prompts.
               --force   re-authorize even if the stored token is valid
               --json    machine-readable output, no report text
+  mcp renew
+            Silently refresh every Trellis-owned stored OAuth token that
+              needs it —
+              never opens a browser, never performs an initial grant.
+              Reports per-server health and exits non-zero when any
+              classified server needs 'mcp auth'. Safe under a scheduler
+              (launchd): idempotent on valid tokens, refreshes serialized
+              per server, overlapping runs degrade to one refresh.
+              --dry-run  report status without any token-endpoint call
+              --json     machine-readable output, no report text
   mcp-runtime --agent <agent>
             Internal MCP edge exposing Trellis providers and selected
             upstream capabilities; existing mcp-gateway configs remain valid
@@ -470,6 +481,11 @@ async function main(argv) {
             process.exitCode = (await runMcpRemove(name, { json, dryRun })).exitCode;
             return;
         }
+        if (subcommand === "renew") {
+            const { exitCode } = await runMcpRenew({ json, dryRun });
+            process.exitCode = exitCode;
+            return;
+        }
         if (subcommand === "auth") {
             const [serverName] = mcpRest;
             if (!serverName || serverName.startsWith("--")) {
@@ -481,7 +497,7 @@ async function main(argv) {
             process.exitCode = exitCode;
             return;
         }
-        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|scope <name>|remove <name>|auth <name>\n`);
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|set <name>|scope <name>|remove <name>|auth <name>|renew\n`);
         process.exitCode = 1;
         return;
     }

package/dist/commands/doctor.d.ts

@@ -5,7 +5,7 @@
  * throughout docs/research.md's investigation, now formalized.
  */
 import { loadCanonicalSource } from "../core/canonical.js";
-import type { AgentId, AgentSnapshot } from "../core/types.js";
+import type { AgentId, AgentSnapshot, CanonicalSource } from "../core/types.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -14,7 +14,7 @@ import type { AgentId, AgentSnapshot } from "../core/types.js";
  * machine.
  */
 export declare const DEFAULT_KNOWN_HOST_INJECTED: readonly string[];
-export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "mcp-unreachable";
+export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "oauth-expired" | "mcp-unreachable";
 export interface Finding {
     kind: FindingKind;
     /** Omitted for a finding that names more than one agent (drift). */
@@ -48,9 +48,19 @@ export interface RunDoctorOptions {
      * every other Trellis entry point uses. */
     homeDir?: string;
 }
+export interface OAuthHealthEntry {
+    server: string;
+    status: "valid" | "expired" | "absent" | "unreadable";
+    expiresAt?: number;
+}
 export interface DoctorReport {
     snapshots: AgentSnapshot[];
     findings: Finding[];
+    /** Credential health for canonical OAuth-classified servers. Absent
+     * when no canonical source exists (doctor stays standalone, P0) or no
+     * server is OAuth-classified. Read-only by construction
+     * (trellis-mcp-oauth-renew design.md D4). */
+    oauth?: OAuthHealthEntry[];
 }
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -67,6 +77,16 @@ export declare function runDoctor(opts?: RunDoctorOptions): Promise<{
  * `undefined`) is unaffected.
  */
 export declare function collectDoctorReport(homeDir?: string, knownHostInjected?: readonly string[], probeMcp?: boolean): Promise<DoctorReport>;
+/**
+ * Read-only OAuth credential health (trellis-mcp-oauth-renew design.md
+ * D4): classified from the stored token file alone — no token endpoint,
+ * no writes. Scope is canonical Trellis-owned OAuth servers only, the
+ * same rule `trellis mcp renew` iterates (design.md D5 +
+ * trellis-desktop-oauth-ownership: an agent-owned server's authorization
+ * lives in the Agent's own client, so Trellis's empty token store for it
+ * is expected, never a finding), via the same classifier (design.md D2).
+ */
+export declare function collectOAuthHealth(homeDir: string, canonical: Pick<CanonicalSource, "mcp">): OAuthHealthEntry[];
 /**
  * Within one agent, across all of its skill roots: any realpath reached by
  * more than one entry, where at least one of those entries is NOT a

package/dist/commands/doctor.js

@@ -13,7 +13,9 @@ import * as kimiCodeProbe from "../probes/kimi-code.js";
 import * as zcodeProbe from "../probes/zcode.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
-import { ALL_AGENTS } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth, oauthOwner } from "../core/types.js";
+import { classifyStoredToken, remediationFor } from "../lib/oauth/renew.js";
+import { readToken } from "../lib/oauth/store.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
  * real `known_host_injected` field (P0 has no canonical source at all —
@@ -36,6 +38,10 @@ const EXIT_NONZERO_KINDS = new Set([
     "case-mismatch",
     "parse-diagnostic",
     "runtime-drift",
+    // A stored credential that will 401 on next use is exactly what doctor
+    // exists to catch *before* the session does (trellis-mcp-oauth-renew
+    // design.md D4).
+    "oauth-expired",
 ]);
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -103,8 +109,42 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         // Doctor remains useful as a standalone cross-agent scanner when
         // canonical has not been initialized yet.
     }
-    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots));
-    return { snapshots, findings };
+    const oauth = canonical ? collectOAuthHealth(homeDir, canonical) : [];
+    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots), ...oauth.flatMap((entry) => (entry.status === "valid" ? [] : [oauthFinding(entry)])));
+    return { snapshots, findings, ...(oauth.length > 0 ? { oauth } : {}) };
+}
+/**
+ * Read-only OAuth credential health (trellis-mcp-oauth-renew design.md
+ * D4): classified from the stored token file alone — no token endpoint,
+ * no writes. Scope is canonical Trellis-owned OAuth servers only, the
+ * same rule `trellis mcp renew` iterates (design.md D5 +
+ * trellis-desktop-oauth-ownership: an agent-owned server's authorization
+ * lives in the Agent's own client, so Trellis's empty token store for it
+ * is expected, never a finding), via the same classifier (design.md D2).
+ */
+export function collectOAuthHealth(homeDir, canonical) {
+    return Object.entries(canonical.mcp.servers)
+        .filter(([, def]) => isOAuthAuth(def.auth) && oauthOwner(def.auth) === "trellis")
+        .map(([name]) => name)
+        .sort()
+        .map((name) => {
+        const status = classifyStoredToken(homeDir, name);
+        const expiresAt = readToken(homeDir, name)?.expiresAt;
+        const collapsed = status === "valid" ? "valid"
+            : status === "no-token" ? "absent"
+                : status === "unreadable" ? "unreadable"
+                    : "expired";
+        return { server: name, status: collapsed, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+    });
+}
+function oauthFinding(entry) {
+    const reason = entry.status === "absent" ? "has never been authorized"
+        : entry.status === "unreadable" ? "has an unreadable credential file"
+            : "has an expired stored token";
+    return {
+        kind: "oauth-expired",
+        message: `OAuth server "${entry.server}" ${reason} — ${remediationFor(entry.status === "expired" ? "expired-renewable" : "needs-auth", entry.server)}`,
+    };
 }
 /**
  * Within one agent, across all of its skill roots: any realpath reached by
@@ -308,6 +348,14 @@ export function printReport(report) {
             console.log(`   - ${finding.message}`);
         }
     }
+    if (report.oauth && report.oauth.length > 0) {
+        console.log("\nOAuth credentials:");
+        for (const entry of report.oauth) {
+            const expiry = entry.expiresAt !== undefined ? ` (expires ${new Date(entry.expiresAt).toISOString()})` : "";
+            const icon = entry.status === "valid" ? "✅" : "❌";
+            console.log(`${icon} ${entry.server} — ${entry.status}${expiry}`);
+        }
+    }
     if (crossAgent.length > 0) {
         console.log("\nCross-agent:");
         for (const finding of crossAgent) {

package/dist/commands/mcpGateway.d.ts

@@ -46,6 +46,7 @@ export declare function parseMcpGatewayArgs(argv: readonly string[]): {
  */
 export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pick<ReturnType<typeof loadCanonicalSource>, "mcp" | "managedAgents" | "secretsPolicy">): {
     upstreams: UpstreamSpec[];
+    oauthServers: string[];
     conflicts: string[];
 };
 export declare function runMcpGateway(opts: RunMcpGatewayOptions): Promise<{

package/dist/commands/mcpGateway.js

@@ -27,7 +27,7 @@ import { TaskProvider } from "../lib/taskProvider.js";
 import { AgentBridgeProvider } from "../lib/agentBridgeProvider.js";
 import { RuntimeMemoryProvider } from "../lib/memoryProvider.js";
 import { SkillProvider } from "../lib/skillProvider.js";
-import { ALL_AGENTS } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth } from "../core/types.js";
 const CLIENT_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
 const SERVER_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
 const RUNTIME_CLIENT_INFO = { name: "trellis-mcp-runtime", version: "0.0.0" };
@@ -60,11 +60,18 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     const route = canonical.mcp.routes?.[agentId];
     const hubActive = route ? route.mode === "hub" : Boolean(canonical.mcp.hub) && !isGatewayAgent(agentId, canonical.mcp, canonical.managedAgents);
     if (hubActive) {
-        return { upstreams: [], conflicts: [] };
+        // Hub mode writes no direct entries at all (mcpPlan's hub branch), so
+        // there are no OAuth servers for the status tool to report either.
+        return { upstreams: [], oauthServers: [], conflicts: [] };
     }
     const directRoutes = canonical.mcp.routes && route
         ? { ...canonical.mcp.routes, [agentId]: { mode: "direct", ...(route.servers ? { servers: route.servers } : {}) } }
         : canonical.mcp.routes;
+    // Trellis-owned OAuth servers stay in the plan as ordinary upstreams
+    // (auth stripped here so the direct-mode plan keeps them; the original
+    // defs are restored below so withOAuthHeader can attach their tokens at
+    // connect). Agent-owned ones are excluded entirely: sync writes those as
+    // direct native entries beside the gateway (trellis-desktop-oauth-ownership).
     const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers)
         .filter(([, def]) => !isAgentOwnedOAuth(def))
         .map(([name, def]) => { const { auth: _auth, ...ordinary } = def; return [name, ordinary]; }));
@@ -81,8 +88,20 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     // every server, and every secret resolved into it, to the one agent the
     // user just said to stop involving.
     const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    // Agent-owned OAuth servers bypass the gateway as direct entries, so no
+    // connection state exists for them here — but Trellis owns the token
+    // store, so `trellis.mcp.status` reports their credential health for
+    // exactly this set. It is resolved through a second direct-mode plan
+    // over just those servers, so scope, `enabled: false` and route
+    // restrictions match what sync writes (the identical planDirectServers
+    // checks; trellis-mcp-status-credential-health design.md D4).
+    const agentOwnedServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => isAgentOwnedOAuth(def)));
+    const oauthServers = Object.keys(agentOwnedServers).length === 0
+        ? []
+        : resolveMcpPlan(agentId, { ...direct, servers: agentOwnedServers }, canonical.managedAgents, canonical.secretsPolicy).desired.map(({ name }) => name);
     return {
         upstreams: desired.map(({ name }) => ({ name, def: canonical.mcp.servers[name] })),
+        oauthServers,
         conflicts: conflicts.map((conflict) => conflict.message),
     };
 }
@@ -109,7 +128,7 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
         console.error(`trellis-mcp-gateway: ${err instanceof Error ? err.message : String(err)}`);
         return { exitCode: 1 };
     }
-    const { upstreams, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
+    const { upstreams, oauthServers, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
     for (const message of conflicts) {
         console.error(`trellis-mcp-gateway: ${message}`);
     }
@@ -124,7 +143,16 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
             // process has no terminal to run one in (design.md D9).
             homeDir,
         });
-    const registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend), new TaskProvider(), new AgentBridgeProvider(), new UpstreamProvider(backend)]);
+    // The status tool's oauth section covers both ownership kinds
+    // (trellis-desktop-oauth-ownership): trellis-owned servers arrive as
+    // upstreams (auth intact) — their Trellis-store credential health is
+    // what the gateway itself will rely on at connect; agent-owned servers
+    // bypass the gateway as direct entries and are marked agent-managed.
+    const oauthReport = [
+        ...upstreams.filter((u) => isOAuthAuth(u.def.auth)).map((u) => ({ name: u.name, owner: "trellis" })),
+        ...oauthServers.map((name) => ({ name, owner: "agent" })),
+    ];
+    const registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend, { homeDir, oauthServers: oauthReport }), new TaskProvider(), new AgentBridgeProvider(), new UpstreamProvider(backend)]);
     const server = serveStdio(() => createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry));
     await waitForShutdown(registry, server);
     return { exitCode: 0 };

package/dist/commands/mcpRenew.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `trellis mcp renew` — scheduled, non-interactive renewal of stored OAuth
+ * tokens (trellis-mcp-oauth-renew).
+ *
+ * Deliberately an orchestrator and nothing more: the refresh itself is
+ * `ensureFreshToken`, the same function the gateway calls before every
+ * upstream request, with the same lock, skew, and rotation semantics
+ * (design.md D1). This command's entire job is to run that path *before*
+ * an Agent session discovers a dead credential as a 401, and to say
+ * plainly which servers need a human.
+ *
+ * Never opens a browser, never performs an initial grant — that remains
+ * `trellis mcp auth` (mcp-gateway-hosting design.md D9). Scope is
+ * canonical Trellis-owned OAuth servers only: classification is explicit,
+ * never inferred from token files or URLs (design.md D5), and since
+ * trellis-desktop-oauth-ownership an explicit `owner: trellis` is what
+ * makes a credential Trellis's responsibility at all — agent-owned
+ * servers are authorized by the Agent's own client, which neither reads
+ * Trellis's token store nor can be renewed from here, so reporting them
+ * as `no-token` would cry wolf on every run.
+ */
+import { type OAuthRenewStatus } from "../lib/oauth/renew.js";
+import type { FetchLike } from "../lib/oauth/discovery.js";
+export interface RunMcpRenewOptions {
+    json?: boolean;
+    dryRun?: boolean;
+    /** Defaults to the real `~`; overridable for tests — the seam every
+     * other Trellis entry point exposes. */
+    homeDir?: string;
+    /** Test seam for the token-endpoint call — an interval-scheduled run
+     * must use the real fetch, so this is not a supported user flag. */
+    fetchImpl?: FetchLike;
+}
+export interface McpRenewEntry {
+    server: string;
+    status: OAuthRenewStatus;
+    expiresAt?: number;
+    remediation?: string;
+}
+export interface McpRenewResult {
+    entries: McpRenewEntry[];
+    /** True when every classified server is healthy without a human step
+     * (design.md D6). The vacuous case — zero OAuth servers — is ok. */
+    ok: boolean;
+}
+/** Exported so tests and `doctor` reuse the exact iteration/scope rule
+ * without capturing stdout or re-deriving it (design.md D2's one-rule
+ * property). Read-only when `dryRun`: no network, no writes. */
+export declare function collectRenewEntries(opts: RunMcpRenewOptions): Promise<McpRenewResult>;
+export declare function runMcpRenew(opts: RunMcpRenewOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/mcpRenew.js

@@ -0,0 +1,104 @@
+/**
+ * `trellis mcp renew` — scheduled, non-interactive renewal of stored OAuth
+ * tokens (trellis-mcp-oauth-renew).
+ *
+ * Deliberately an orchestrator and nothing more: the refresh itself is
+ * `ensureFreshToken`, the same function the gateway calls before every
+ * upstream request, with the same lock, skew, and rotation semantics
+ * (design.md D1). This command's entire job is to run that path *before*
+ * an Agent session discovers a dead credential as a 401, and to say
+ * plainly which servers need a human.
+ *
+ * Never opens a browser, never performs an initial grant — that remains
+ * `trellis mcp auth` (mcp-gateway-hosting design.md D9). Scope is
+ * canonical Trellis-owned OAuth servers only: classification is explicit,
+ * never inferred from token files or URLs (design.md D5), and since
+ * trellis-desktop-oauth-ownership an explicit `owner: trellis` is what
+ * makes a credential Trellis's responsibility at all — agent-owned
+ * servers are authorized by the Agent's own client, which neither reads
+ * Trellis's token store nor can be renewed from here, so reporting them
+ * as `no-token` would cry wolf on every run.
+ */
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { isOAuthAuth, oauthOwner } from "../core/types.js";
+import { ensureFreshToken } from "../lib/oauth/refresh.js";
+import { classifyRefreshFailure, classifyStoredToken, FAILURE_STATUSES, remediationFor, } from "../lib/oauth/renew.js";
+import { readToken } from "../lib/oauth/store.js";
+/** Exported so tests and `doctor` reuse the exact iteration/scope rule
+ * without capturing stdout or re-deriving it (design.md D2's one-rule
+ * property). Read-only when `dryRun`: no network, no writes. */
+export async function collectRenewEntries(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    const canonical = loadCanonicalSource(homeDir);
+    const names = Object.entries(canonical.mcp.servers)
+        .filter(([, def]) => isOAuthAuth(def.auth) && oauthOwner(def.auth) === "trellis")
+        .map(([name]) => name)
+        .sort();
+    const entries = [];
+    for (const name of names) {
+        entries.push(await renewOne(homeDir, name, opts));
+    }
+    return { entries, ok: entries.every((entry) => !FAILURE_STATUSES.has(entry.status)) };
+}
+async function renewOne(homeDir, name, opts) {
+    // The pre-refresh classification decides what `ensureFreshToken`'s
+    // return means: it only contacts the endpoint when the stored token was
+    // absent-but-not-required (returns undefined) or expiring (refreshes),
+    // so "expired-renewable before, token after" ⇒ a refresh just happened.
+    const before = classifyStoredToken(homeDir, name);
+    if (opts.dryRun)
+        return withDetails(homeDir, name, before);
+    try {
+        const token = await ensureFreshToken(homeDir, name, { ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}) });
+        if (!token)
+            return withDetails(homeDir, name, "no-token");
+        return withDetails(homeDir, name, before === "expired-renewable" ? "refreshed" : "valid");
+    }
+    catch (err) {
+        return withDetails(homeDir, name, classifyRefreshFailure(err));
+    }
+}
+function withDetails(homeDir, name, status) {
+    const expiresAt = readToken(homeDir, name)?.expiresAt;
+    return {
+        server: name,
+        status,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+        ...(FAILURE_STATUSES.has(status) || status === "expired-renewable" ? { remediation: remediationFor(status, name) } : {}),
+    };
+}
+const STATUS_ICON = {
+    valid: "✅",
+    refreshed: "🔄",
+    "expired-renewable": "⏳",
+    "no-token": "❌",
+    "refresh-failed": "❌",
+    "needs-auth": "❌",
+    unreadable: "⚠️",
+};
+export async function runMcpRenew(opts) {
+    let result;
+    try {
+        result = await collectRenewEntries(opts);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (result.entries.length === 0) {
+        console.log("No OAuth-classified MCP servers in canonical config — nothing to renew.");
+    }
+    else {
+        for (const entry of result.entries) {
+            const expiry = entry.expiresAt !== undefined ? ` (expires ${new Date(entry.expiresAt).toISOString()})` : "";
+            console.log(`${STATUS_ICON[entry.status]} ${entry.server} — ${entry.status}${expiry}`);
+            if (entry.remediation)
+                console.log(`   → ${entry.remediation}`);
+        }
+    }
+    return { exitCode: result.ok ? 0 : 1 };
+}

package/dist/lib/gatewayBackend.d.ts

@@ -45,6 +45,11 @@ export interface UpstreamStatus {
     name: string;
     transport: "stdio" | "http" | "sse";
     status: UpstreamStatusKind;
+    /** How many tools this upstream contributed at connect time — the
+     * structured form of the count `detail` already carries in prose, so
+     * Agents reasoning about capability never parse a sentence
+     * (trellis-mcp-status-credential-health design.md D5). */
+    toolCount?: number;
     detail?: string;
     remediation?: string;
     remediationKind?: "oauth" | "environment" | "install" | "endpoint" | "router";

package/dist/lib/gatewayBackend.js

@@ -98,6 +98,7 @@ export class LocalBackend {
                 name,
                 transport,
                 status: "degraded",
+                toolCount: 0,
                 detail: "router connected but exposed no downstream tools",
                 remediationKind: "router",
                 requiresHuman: true,
@@ -106,7 +107,7 @@ export class LocalBackend {
             });
         }
         else {
-            this.statuses.set(name, { name, transport, status: "ready", detail: `connected; ${tools.length} tool(s) available` });
+            this.statuses.set(name, { name, transport, status: "ready", toolCount: tools.length, detail: `connected; ${tools.length} tool(s) available` });
         }
     }
     async listTools() {

package/dist/lib/mcpStatusProvider.d.ts

@@ -1,10 +1,44 @@
 import type { CallToolResult, Tool } from "@modelcontextprotocol/server";
 import type { GatewayBackend } from "./gatewayBackend.js";
 import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+import { type OAuthRenewStatus } from "./oauth/renew.js";
+export interface McpStatusProviderOptions {
+    /** Where the OAuth token store lives. Omitted, the `oauth` section of
+     * the report is empty — the provider stays usable by callers with no
+     * home directory, the same contract `LocalBackend` exposes. */
+    homeDir?: string;
+    /** OAuth-classified servers in scope for this agent, with their
+     * ownership (trellis-desktop-oauth-ownership). Trellis-owned servers
+     * connect through the gateway with a Trellis-store token, so their
+     * stored-credential health is meaningful and reported. Agent-owned
+     * servers are direct native entries authorized by the Agent's own
+     * client — reported as `agent-managed` precisely because inferring
+     * their state from Trellis's store would be a lie (that change's
+     * "unknown native authorization is displayed as unknown"). */
+    oauthServers?: readonly OAuthServerRef[];
+}
+export interface OAuthServerRef {
+    name: string;
+    owner: "agent" | "trellis";
+}
+/** One OAuth-classified server's credential health. `credential` — not
+ * `status` — because the gateway cannot observe a direct-routed server's
+ * connection state; claiming "ready" would be a lie
+ * (trellis-mcp-status-credential-health design.md D1). */
+export interface OAuthCredentialReport {
+    name: string;
+    owner: "agent" | "trellis";
+    credential: OAuthRenewStatus | "agent-managed";
+    /** ISO 8601, when the stored token carries an expiry at all. */
+    expiresAt?: string;
+    /** Present only when there is an action for Trellis to take. */
+    remediation?: string;
+}
 export declare class McpStatusProvider implements TrellisProvider {
     private readonly backend;
+    private readonly options;
     readonly id = "mcp";
-    constructor(backend: GatewayBackend);
+    constructor(backend: GatewayBackend, options?: McpStatusProviderOptions);
     listTools(): Tool[];
     callTool(name: string, _args: unknown, _context: RuntimeContext): Promise<CallToolResult>;
 }

package/dist/lib/mcpStatusProvider.js

@@ -1,14 +1,17 @@
+import { describeStoredToken, remediationFor } from "./oauth/renew.js";
 const STATUS_TOOL = {
     name: "trellis.mcp.status",
-    description: "Show MCP upstream availability and the safe next action for authentication or configuration failures.",
+    description: "Show MCP upstream availability, credential health for OAuth-classified direct-routed servers, and the safe next action for authentication or configuration failures.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
 };
 export class McpStatusProvider {
     backend;
+    options;
     id = "mcp";
-    constructor(backend) {
+    constructor(backend, options = {}) {
         this.backend = backend;
+        this.options = options;
     }
     listTools() {
         return [STATUS_TOOL];
@@ -17,9 +20,29 @@ export class McpStatusProvider {
         if (name !== STATUS_TOOL.name)
             return { content: [{ type: "text", text: `unknown MCP status tool "${name}"` }], isError: true };
         const statuses = this.backend.listStatus?.() ?? [];
+        // Strictly read-only (design.md D3): classification reads the token
+        // files and nothing else — no token endpoint, no refresh, no writes.
+        // The readOnlyHint annotation on the tool depends on that staying true.
+        const oauth = this.options.homeDir
+            ? (this.options.oauthServers ?? []).map(({ name: serverName, owner }) => {
+                if (owner === "agent") {
+                    return { name: serverName, owner, credential: "agent-managed" };
+                }
+                const { status, expiresAt } = describeStoredToken(this.options.homeDir, serverName);
+                const remediation = remediationFor(status, serverName);
+                return {
+                    name: serverName,
+                    owner,
+                    credential: status,
+                    ...(expiresAt !== undefined ? { expiresAt } : {}),
+                    ...(remediation !== "" ? { remediation } : {}),
+                };
+            })
+            : [];
+        const report = { servers: statuses, oauth };
         return {
-            content: [{ type: "text", text: JSON.stringify({ servers: statuses }, null, 2) }],
-            structuredContent: { servers: statuses },
+            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+            structuredContent: report,
         };
     }
 }

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

@@ -0,0 +1,11 @@
+export interface CallbackPageOptions {
+    serverName: string;
+    hasCode: boolean;
+    error?: string;
+    acceptLanguage?: string;
+}
+/** Browser receipt only: the caller still validates and persists the grant. */
+export declare function renderCallbackPage(options: CallbackPageOptions): {
+    html: string;
+    contentSecurityPolicy: string;
+};

package/dist/lib/oauth/callbackPage.js

@@ -0,0 +1,89 @@
+import { randomBytes } from "node:crypto";
+const COPY = {
+    en: {
+        received: "Authorization response received",
+        receivedBody: "Return to Trellis or your terminal to check the final connection result.",
+        cancelled: "Authorization cancelled",
+        cancelledBody: "Return to Trellis and start again when you are ready.",
+        failed: "Authorization could not continue",
+        failedBody: "Return to Trellis or your terminal for details, then try again.",
+        incomplete: "Authorization response incomplete",
+        incompleteBody: "No authorization code was received. Start again from Trellis.",
+        close: "Close this tab",
+        manual: "If this tab stays open, close it manually and return to Trellis or your terminal.",
+        noScript: "You can close this tab manually and return to Trellis or your terminal.",
+    },
+    zh: {
+        received: "授权响应已接收",
+        receivedBody: "请返回 Trellis 或终端查看最终连接结果。",
+        cancelled: "授权已取消",
+        cancelledBody: "准备好后，请返回 Trellis 重新发起授权。",
+        failed: "授权暂未完成",
+        failedBody: "请返回 Trellis 或终端查看原因，然后重试。",
+        incomplete: "授权响应不完整",
+        incompleteBody: "未收到授权码，请从 Trellis 重新发起授权。",
+        close: "关闭此标签页",
+        manual: "如果页面没有关闭，请手动关闭此标签页，返回 Trellis 或终端。",
+        noScript: "你可以手动关闭此标签页，返回 Trellis 或终端。",
+    },
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+}
+// Inline the existing docs/assets/brand-v3/trellis-mark-v3-a.svg geometry so
+// callback pages work offline and inside the packaged Sidecar.
+const MARK = `<svg viewBox="0 0 96 96" aria-hidden="true" focusable="false"><g fill="none" stroke="currentColor" stroke-linecap="round"><rect x="16" y="18" width="64" height="18" rx="9" stroke-width="5.5"/><g stroke-width="2.6" clip-path="url(#a-beam)"><path d="M-64.5 32 L-55.5 23"/><path d="M-64.5 23 L-55.5 32"/><path d="M-46.5 32 L-37.5 23"/><path d="M-46.5 23 L-37.5 32"/><path d="M-28.5 32 L-19.5 23"/><path d="M-28.5 23 L-19.5 32"/><path d="M-10.5 32 L-1.5 23"/><path d="M-10.5 23 L-1.5 32"/><path d="M7.5 32 L16.5 23"/><path d="M7.5 23 L16.5 32"/><path d="M25.5 32 L34.5 23"/><path d="M25.5 23 L34.5 32"/><path d="M43.5 32 L52.5 23"/><path d="M43.5 23 L52.5 32"/><path d="M61.5 32 L70.5 23"/><path d="M61.5 23 L70.5 32"/><path d="M79.5 32 L88.5 23"/><path d="M79.5 23 L88.5 32"/><path d="M97.5 32 L106.5 23"/><path d="M97.5 23 L106.5 32"/><path d="M115.5 32 L124.5 23"/><path d="M115.5 23 L124.5 32"/></g><path d="M48 36 V78" stroke-width="8"/></g><defs><clipPath id="a-beam"><rect x="21" y="23" width="54" height="9" rx="4.5"/></clipPath></defs></svg>`;
+/** Browser receipt only: the caller still validates and persists the grant. */
+export function renderCallbackPage(options) {
+    const chinese = options.acceptLanguage?.split(",")[0]?.trim().toLowerCase().startsWith("zh") ?? false;
+    const copy = chinese ? COPY.zh : COPY.en;
+    const state = options.error === "access_denied" ? "cancelled" : options.error ? "failed" : options.hasCode ? "received" : "incomplete";
+    const title = copy[state];
+    const description = copy[`${state}Body`];
+    const nonce = randomBytes(16).toString("base64");
+    const contentSecurityPolicy = `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;
+    const html = `<!doctype html>
+<html lang="${chinese ? "zh-CN" : "en"}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light">
+<title>${escapeHtml(title)} · Trellis</title>
+<style nonce="${nonce}">
+:root{color-scheme:light;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans",Arial,sans-serif;color:#182230;background:#fff;font-synthesis:none;-webkit-font-smoothing:antialiased}
+*{box-sizing:border-box}body{margin:0;min-height:100vh;min-height:100dvh;display:grid;place-items:center;padding:32px 24px}
+main{width:100%;max-width:440px;text-align:center}.brand{display:flex;align-items:center;justify-content:center;flex-wrap:wrap;gap:8px;margin-bottom:24px;font-size:14px;color:#667085}.brand svg{width:28px;height:28px;flex:none}.brand-name{font-weight:600;color:#344054}.separator{color:#98a2b3}.server{max-width:100%;overflow-wrap:anywhere}
+h1{font-size:25px;font-weight:600;line-height:1.35;letter-spacing:-.5px;margin:0 0 12px;overflow-wrap:anywhere}.description{font-size:14px;line-height:1.7;color:#667085;margin:0 0 24px}
+button{appearance:none;border:1px solid #2563eb;border-radius:8px;background:#2563eb;color:#fff;font:inherit;font-size:14px;font-weight:500;line-height:1.5;padding:10px 18px;min-height:44px;max-width:100%;cursor:pointer}button:hover{background:#1d4ed8;border-color:#1d4ed8}button:focus-visible{outline:3px solid #93b4ff;outline-offset:3px}.help{font-size:12px;line-height:1.65;color:#667085;margin:16px 0 0;overflow-wrap:anywhere}.help:focus{outline:none}
+[hidden]{display:none!important}@media(max-width:480px){body{padding:24px}h1{font-size:23px}}
+</style>
+</head>
+<body>
+<main>
+  <div class="brand">${MARK}<span class="brand-name">Trellis</span><span class="separator" aria-hidden="true">·</span><span class="server">${escapeHtml(options.serverName)}</span></div>
+  <section aria-labelledby="page-title" data-state="${state}">
+    <h1 id="page-title">${title}</h1>
+    <p class="description">${description}</p>
+    <button id="close-tab" type="button" hidden>${copy.close}</button>
+    <p id="close-help" class="help" role="status" tabindex="-1" hidden>${copy.manual}</p>
+    <p id="manual-close" class="help">${copy.noScript}</p>
+  </section>
+</main>
+<script nonce="${nonce}">
+try { history.replaceState(null, '', location.pathname); } catch (_) {}
+const button = document.getElementById('close-tab');
+button.hidden = false;
+document.getElementById('manual-close').hidden = true;
+button.addEventListener('click', function () {
+  try { window.close(); } catch (_) {}
+  setTimeout(function () {
+    const help = document.getElementById('close-help');
+    help.hidden = false;
+    help.focus({ preventScroll: true });
+  }, 150);
+});
+</script>
+</body>
+</html>`;
+    return { html, contentSecurityPolicy };
+}

package/dist/lib/oauth/flow.js

@@ -17,6 +17,7 @@ import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createPkcePair } from "./pkce.js";
+import { renderCallbackPage } from "./callbackPage.js";
 export class AuthorizationError extends Error {
 }
 /**
@@ -82,7 +83,7 @@ const STATIC_CLIENT_REMEDIATION = "register a client with the provider and set a
 /** A one-shot loopback listener for the redirect. Bound to 127.0.0.1
  * explicitly, never 0.0.0.0: the authorization code arrives in this URL,
  * and a listener on all interfaces would accept it from the network. */
-function listenForCallback(port) {
+function listenForCallback(port, serverName) {
     return new Promise((resolve, reject) => {
         let settle;
         const received = new Promise((r) => {
@@ -112,10 +113,15 @@ function listenForCallback(port) {
                 if (description)
                     result.errorDescription = description;
             }
-            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-            res.end(result.error
-                ? `<html><body><h1>Authorization failed</h1><p>${escapeHtml(result.errorDescription ?? result.error)}</p></body></html>`
-                : "<html><body><h1>Authorization response received</h1><p>You can close this tab and return to Trellis.</p></body></html>");
+            const page = renderCallbackPage({ serverName, hasCode: Boolean(result.code), error: result.error, acceptLanguage: req.headers["accept-language"] });
+            res.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "referrer-policy": "no-referrer",
+                "x-content-type-options": "nosniff",
+                "content-security-policy": page.contentSecurityPolicy,
+            });
+            res.end(page.html);
             settle(result);
         });
         server.on("error", reject);
@@ -124,9 +130,6 @@ function listenForCallback(port) {
         });
     });
 }
-function escapeHtml(value) {
-    return value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
-}
 /**
  * Runs the full authorization-code-plus-PKCE exchange and returns a
  * token ready to persist. Does not write anything — storage is the
@@ -137,7 +140,7 @@ export async function authorize(serverName, metadata, opts = {}) {
     const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, { ...init, signal: opts.signal }));
     const now = opts.now ?? Date.now;
     const timeoutMs = opts.timeoutMs ?? 300_000;
-    const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0);
+    const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0, serverName);
     const redirectUri = `http://127.0.0.1:${port}/callback`;
     try {
         let clientId = opts.clientId;

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

@@ -0,0 +1,75 @@
+/**
+ * Per-server OAuth credential health classification, shared by
+ * `trellis mcp renew`, `trellis doctor`, and the `trellis.mcp.status`
+ * Runtime tool (trellis-mcp-oauth-renew design.md D2,
+ * trellis-mcp-status-credential-health design.md D2).
+ *
+ * One function, two consumers, on purpose: a gateway call, a renew run,
+ * and a doctor report all read the same token files, so the statuses they
+ * derive must come from a single computation — two classifiers could
+ * drift into disagreeing about whether a credential is healthy, which is
+ * exactly the kind of "reported ready but 401s in session" mismatch this
+ * change exists to eliminate.
+ *
+ * Everything here is derived from the stored token at call time. Nothing
+ * is persisted: the next caller recomputes from the same source of truth
+ * the gateway reads.
+ */
+import { type StoredToken } from "./store.js";
+export type OAuthRenewStatus = 
+/** Nothing stored; renewal can do nothing. */
+"no-token"
+/** Stored and not expired (within the same skew `ensureFreshToken` uses). */
+ | "valid"
+/** Was expired, refresh succeeded. Only the refresh path produces this. */
+ | "refreshed"
+/** Expired but a refresh token is present — a real renew run would
+ * attempt a refresh. Only the read-only path produces this. */
+ | "expired-renewable"
+/** Refresh was attempted and failed (network error, or the grant was
+ * rejected — a possibly revoked credential). */
+ | "refresh-failed"
+/** Expired with no refresh token: only a fresh authorization helps. */
+ | "needs-auth"
+/** A file exists on disk but cannot be interpreted. */
+ | "unreadable";
+/** Statuses that mean "a human step is required" — the non-zero-exit set
+ * (design.md D6). */
+export declare const FAILURE_STATUSES: ReadonlySet<OAuthRenewStatus>;
+export declare function remediationFor(status: OAuthRenewStatus, serverName: string): string;
+/** Test seam for expiry checks, mirroring the `now` seams the rest of the
+ * oauth package already exposes. */
+export interface ClassifyOptions {
+    now?: number;
+}
+/**
+ * The stored token's health plus its expiry (ISO 8601, when the token
+ * carries one — store.ts's contract makes `expiresAt` optional). The
+ * status tool needs the timestamp to answer "how long is this credential
+ * good for"; renew and doctor need only the status
+ * (trellis-mcp-status-credential-health design.md D2).
+ */
+export interface OAuthTokenDescription {
+    status: OAuthRenewStatus;
+    expiresAt?: string;
+}
+/**
+ * Read-only classification: no network, no writes — doctor's and the
+ * status tool's path (design.md D4). A token with no `expiresAt` never
+ * expires (store.ts's own contract), so it classifies `valid`.
+ */
+export declare function describeStoredToken(homeDir: string, serverName: string, opts?: ClassifyOptions): OAuthTokenDescription;
+export declare function classifyStoredToken(homeDir: string, serverName: string, opts?: ClassifyOptions): OAuthRenewStatus;
+/** Exported for tests that build statuses straight from token fixtures. */
+export declare function hasRefreshToken(token: StoredToken | undefined): boolean;
+/**
+ * Maps a refresh failure to a status. The RFC 6749 §5.2 errors that mean
+ * "this grant is dead" — `invalid_grant`, and Figma-style servers that
+ * answer a rejected refresh with a bare 400/401 and no parseable body —
+ * get `needs-auth`, because re-authorization is the only remaining step
+ * and the user should not be told to "try refreshing again". Everything
+ * else (timeouts, 5xx, DNS) is `refresh-failed`: transient, worth another
+ * scheduled attempt before bothering a human. Rejected-grant phrasing
+ * varies by provider, so message sniffing stays deliberately narrow.
+ */
+export declare function classifyRefreshFailure(err: unknown): OAuthRenewStatus;

package/dist/lib/oauth/renew.js

@@ -0,0 +1,86 @@
+/**
+ * Per-server OAuth credential health classification, shared by
+ * `trellis mcp renew`, `trellis doctor`, and the `trellis.mcp.status`
+ * Runtime tool (trellis-mcp-oauth-renew design.md D2,
+ * trellis-mcp-status-credential-health design.md D2).
+ *
+ * One function, two consumers, on purpose: a gateway call, a renew run,
+ * and a doctor report all read the same token files, so the statuses they
+ * derive must come from a single computation — two classifiers could
+ * drift into disagreeing about whether a credential is healthy, which is
+ * exactly the kind of "reported ready but 401s in session" mismatch this
+ * change exists to eliminate.
+ *
+ * Everything here is derived from the stored token at call time. Nothing
+ * is persisted: the next caller recomputes from the same source of truth
+ * the gateway reads.
+ */
+import { existsSync } from "node:fs";
+import { isExpired, readToken, tokenPath } from "./store.js";
+/** Statuses that mean "a human step is required" — the non-zero-exit set
+ * (design.md D6). */
+export const FAILURE_STATUSES = new Set([
+    "no-token",
+    "refresh-failed",
+    "needs-auth",
+    "unreadable",
+]);
+export function remediationFor(status, serverName) {
+    switch (status) {
+        case "no-token":
+        case "needs-auth":
+        case "unreadable":
+            return `run \`trellis mcp auth ${serverName}\``;
+        case "expired-renewable":
+            return `run \`trellis mcp renew\` to attempt a silent refresh now, or \`trellis mcp auth ${serverName}\` if that fails`;
+        case "refresh-failed":
+            return `run \`trellis mcp auth ${serverName}\` — the stored grant was rejected or unreachable (possibly revoked)`;
+        default:
+            return "";
+    }
+}
+/**
+ * Read-only classification: no network, no writes — doctor's and the
+ * status tool's path (design.md D4). A token with no `expiresAt` never
+ * expires (store.ts's own contract), so it classifies `valid`.
+ */
+export function describeStoredToken(homeDir, serverName, opts = {}) {
+    if (!existsSync(tokenPath(homeDir, serverName)))
+        return { status: "no-token" };
+    const token = readToken(homeDir, serverName);
+    if (!token)
+        return { status: "unreadable" };
+    const description = {
+        status: "valid",
+        ...(token.expiresAt !== undefined ? { expiresAt: new Date(token.expiresAt).toISOString() } : {}),
+    };
+    if (!isExpired(token, undefined, opts.now))
+        return description;
+    description.status = token.refreshToken ? "expired-renewable" : "needs-auth";
+    return description;
+}
+export function classifyStoredToken(homeDir, serverName, opts = {}) {
+    return describeStoredToken(homeDir, serverName, opts).status;
+}
+/** Exported for tests that build statuses straight from token fixtures. */
+export function hasRefreshToken(token) {
+    return token?.refreshToken !== undefined;
+}
+/**
+ * Maps a refresh failure to a status. The RFC 6749 §5.2 errors that mean
+ * "this grant is dead" — `invalid_grant`, and Figma-style servers that
+ * answer a rejected refresh with a bare 400/401 and no parseable body —
+ * get `needs-auth`, because re-authorization is the only remaining step
+ * and the user should not be told to "try refreshing again". Everything
+ * else (timeouts, 5xx, DNS) is `refresh-failed`: transient, worth another
+ * scheduled attempt before bothering a human. Rejected-grant phrasing
+ * varies by provider, so message sniffing stays deliberately narrow.
+ */
+export function classifyRefreshFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/there is no refresh token/.test(message))
+        return "needs-auth";
+    if (/invalid_grant|HTTP 400|HTTP 401/.test(message))
+        return "needs-auth";
+    return "refresh-failed";
+}

package/docs/getting-started.md

@@ -907,6 +907,15 @@ An Agent can call the read-only `trellis.mcp.status` Runtime tool to explain
 this partial state to the user. It reports unavailable or authorization-
 required servers and gives the next safe action, such as `trellis mcp auth
 figma`, without exposing tokens or opening a browser from the Agent process.
+Each connected upstream also carries a structured `toolCount`, and an `oauth`
+section reports credential health with explicit ownership: Trellis-owned
+OAuth servers (which connect through the gateway on a Trellis-store token)
+report `valid` / `no-token` / `expired-renewable` / `needs-auth` /
+`unreadable` with `expiresAt` when known; agent-owned servers report
+`agent-managed`, since their authorization lives in the Agent's own client
+and is never inferred from Trellis's store. The classification is read-only
+and shared with `trellis mcp renew` and `trellis doctor`, so the three can
+never disagree.
 
 This command only applies to `http`/`sse` servers. stdio servers get
 their credentials from `env`/`env_aliases` as described above; running

package/docs/mcp-authorization-ownership.md

@@ -49,11 +49,30 @@ so a cancelled grant cannot overwrite a concurrent refresh.
 The gateway can silently refresh its own hosted credentials; it never opens a
 browser. Agents with native connections continue using their own flows.
 
+## Browser callback feedback
+
+The local callback page shows a compact Trellis/service label, one status message,
+one short instruction and a close action, with Chinese or English copy based on
+the browser's preferred language. Receiving an
+authorization response is an intermediate step: validation, token exchange and
+credential storage still determine the final result shown in Trellis or the
+terminal. Cancellation, provider errors and incomplete responses have separate
+messages and guidance for starting again.
+
+The page uses no external assets and does not display authorization parameters
+or raw provider descriptions. Responses disable caching and referrer disclosure;
+when JavaScript is available, the page also removes the query and fragment from
+the current browser history entry. The close action offers manual-close guidance
+when a browser blocks it, and manual guidance remains visible without JavaScript.
+
 ## Verification
 
 Run core tests and typecheck, GUI sidecar tests/typecheck and GUI smoke tests.
 `npm run test:oauth-browser --workspace @trellis/gui` additionally uses installed
-Google Chrome headlessly with a local authorization-server fixture. It exercises
-real browser CORS, PKCE callback, progress, cancellation, retry and owner
-confirmation without contacting a real provider or using personal credentials.
+Google Chrome headlessly with a local authorization-server fixture. Set
+`TRELLIS_OAUTH_BROWSER_EXECUTABLE` to use a compatible Chromium executable instead.
+It exercises real browser CORS, PKCE callback, progress, cancellation, retry,
+owner confirmation and callback feedback without contacting a real provider or
+using personal credentials. Set `TRELLIS_OAUTH_SCREENSHOTS` to an output directory
+to save callback desktop/mobile previews during that run.
 Desktop packaging and installed-app acceptance happen after these checks.

package/docs/mcp-oauth-renewal.md

@@ -0,0 +1,88 @@
+# Scheduled OAuth renewal — `trellis mcp renew`
+
+The gateway and the pi bridge already refresh OAuth tokens silently before
+every upstream call. `trellis mcp renew` moves that renewal *earlier*: run
+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.
+
+```
+trellis mcp renew              # refresh what's expiring, report health
+trellis mcp renew --dry-run    # report only; no token-endpoint call
+trellis mcp renew --json       # machine-readable (no credential material)
+```
+
+Scope is canonical OAuth servers with an explicit `owner: trellis` —
+classification is explicit (mcp-auth-routing-policy), and ownership decides
+whose problem the credential is (trellis-desktop-oauth-ownership): an
+agent-owned server (the default, e.g. scalar `auth: oauth`) is authorized by
+the Agent's own client, never reads Trellis's token store, and is neither
+renewed nor reported here. The command never opens a browser and never
+performs an initial grant; that remains `trellis mcp auth <name>`
+(mcp-gateway-hosting design.md D9). Exit code: `0` when every Trellis-owned
+server is valid or refreshed, `1` when any needs `trellis mcp auth`, has
+never been authorized, or has an unreadable credential file.
+
+`trellis doctor` reports the same per-server health read-only (no network,
+no writes) and surfaces an `oauth-expired` finding — contributing to a
+non-zero doctor exit — for credentials that are expired or absent.
+
+## launchd setup (macOS)
+
+Trellis has no daemon; periodic renewal belongs to the platform
+scheduler. Save this as `~/Library/LaunchAgents/com.trellis.mcp-renew.plist`,
+adjusting the `trellis` path (`which trellis`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.trellis.mcp-renew</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/trellis</string>
+    <string>mcp</string>
+    <string>renew</string>
+    <string>--json</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>21600</integer>
+  <key>ThrottleInterval</key>
+  <integer>600</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/trellis-mcp-renew.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/trellis-mcp-renew.log</string>
+</dict>
+</plist>
+```
+
+Then:
+
+```
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.trellis.mcp-renew.plist
+launchctl kickstart gui/$(id -u)/com.trellis.mcp-renew   # run once now
+launchctl bootout gui/$(id -u)/com.trellis.mcp-renew     # uninstall
+```
+
+Why these knobs:
+
+- **`ThrottleInterval`** (design.md D3) caps how close together runs may
+  be. A machine waking from sleep with a launchd backlog runs once, not N
+  times — refresh-endpoint hammering is the failure mode that gets refresh
+  tokens revoked by rate-limiting providers, which is worse than the
+  disease this job exists to prevent.
+- **`StartInterval` of 6h** is comfortably inside typical refresh-token
+  lifetimes (days to months) while keeping token-endpoint traffic near
+  zero: a valid token is a no-op *read*, so most runs make no network
+  calls at all.
+- **Overlapping runs are safe**: refresh is serialized by the per-server
+  lock (`src/lib/oauth/lock.ts`). A second concurrent run waits, then
+  reads the token the first one just wrote.
+- **`--json` to a log** gives you a parseable trail. A `1` exit means
+  "something needs `trellis mcp auth <name>`" — the JSON names which.
+
+Check on demand: `trellis doctor` shows the same per-server credential
+health.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.12.0",
+  "version": "0.13.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",