agent-trellis 0.12.0 → 0.14.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/dist/probes/pi.d.ts

@@ -5,10 +5,13 @@
  * and `dist/core/resource-loader.js` (`loadContextFileFromDir(resolvedAgentDir)`),
  * not by assumption. See design.md D5 (openspec/changes/trellis-doctor-p0).
  *
- * pi has no native MCP client (docs/research.md) — nothing to read or
- * probe, so `mcpServers` is always empty here. That's real information
- * (this is why P4 has to write a runtime bridge extension instead of
- * generating config), not an omission.
+ * pi >= 1.1.0 has a native MCP client (`~/.pi/agent/mcp.json`), which the
+ * adapter manages (trellis-pi-native-mcp-migration); the probe still
+ * reports `mcpServers: []` because server health is the runtime's job,
+ * not the probe's. `probePiVersion` is split out so the adapter's
+ * native-vs-bridge version gate shares exactly this exec and tests can
+ * inject a seam.
  */
 import type { AgentSnapshot } from "../core/types.js";
+export declare function probePiVersion(): string | undefined;
 export declare function probe(homeDir?: string): Promise<AgentSnapshot>;