agent-trellis 0.11.0 → 0.13.0

package/dist/adapters/mcpPlan.d.ts

@@ -34,6 +34,7 @@ export declare const RUNTIME_COMMAND = "trellis";
  * routing it exists to carry (trellis-mcp-oauth-static-client design.md
  * D1). */
 export declare function isOAuthMcpServer(def: McpServerDef): boolean;
+export declare function isAgentOwnedOAuth(def: McpServerDef): boolean;
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,

package/dist/adapters/mcpPlan.js

@@ -18,7 +18,7 @@
  */
 import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
-import { isOAuthAuth } from "../core/types.js";
+import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
@@ -40,6 +40,9 @@ export const RUNTIME_COMMAND = "trellis";
 export function isOAuthMcpServer(def) {
     return isOAuthAuth(def.auth);
 }
+export function isAgentOwnedOAuth(def) {
+    return isOAuthMcpServer(def) && oauthOwner(def.auth) === "agent";
+}
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,
@@ -158,7 +161,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
                 conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
-        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isOAuthMcpServer);
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         // Every ordinary per-server check (enabled, scope, literal secrets,
         // unresolved env names, Codex's header shape) still runs at gateway
         // startup. OAuth servers are the deliberate exception: they are written
@@ -234,15 +237,21 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
         // Runtime mode owns the agent-facing MCP edge. It resolves the same
         // direct/gateway-compatible upstream route at startup, so native
         // per-server entries are not duplicated here.
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         return {
             desired: [{
                     name: RUNTIME_ENTRY_NAME,
                     def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
-                }],
-            conflicts: [],
+                }, ...oauth.desired],
+            conflicts: oauth.conflicts,
         };
     }
-    return planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const native = planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
+    return {
+        desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
+        conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))],
+    };
 }
 function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];

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";
@@ -133,7 +134,7 @@ Commands:
             --json       machine-readable output, no report text
   mcp set <name> --auth oauth|none
             Set or clear explicit OAuth classification; canonical only.
-            --auth oauth [--client-id <id>] [--client-secret-env <NAME>]
+            --auth oauth [--auth-owner agent|trellis] [--client-id <id>] [--client-secret-env <NAME>]
                          pre-register a client for a provider that refuses
                          dynamic registration. --client-id is the PROVIDER's
                          published identifier (public by design);
@@ -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/mcp.d.ts

@@ -56,6 +56,12 @@ export interface McpListEntry {
     /** Normalized: `oauth` in either the scalar or the object form reports as
      * the scalar here — the listing reports classification, not metadata. */
     auth?: McpAuthMode;
+    authOwner?: "agent" | "trellis";
+    agentAuthorization?: Array<{
+        agent: AgentId;
+        status: "unknown";
+        instruction: string;
+    }>;
     /** Presence of pre-registered client metadata
      * (trellis-mcp-oauth-static-client task 3.2) — `true` when the object form
      * carries a `client_id`. A presence flag, deliberately not the id itself:
@@ -84,7 +90,7 @@ export interface McpListEntry {
      * printed in full. */
     staticEnv?: Record<string, string>;
 }
-export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired";
+export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired" | "unknown";
 /**
  * Reads only the per-server token store and returns the state, never a
  * token. Classification stays explicit — the caller only asks for servers
@@ -92,7 +98,7 @@ export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "e
  * name that cannot be a token filename, or an unreadable file, simply has no
  * credential: one odd entry must not take down the whole listing.
  */
-export declare function mcpCredentialState(homeDir: string, serverName: string): {
+export declare function mcpCredentialState(homeDir: string, serverName: string, resourceUrl?: string): {
     authStatus: McpAuthStatus;
     authExpiresAt?: number;
 };
@@ -156,6 +162,7 @@ export interface McpSetAuthPlan {
  * plan collector. */
 export interface McpSetAuthRawArgs {
     auth?: string;
+    authOwner?: string;
     /** Public literal by design (design.md D2) — the one field it is fine to
      * pass on a command line. Never echoed back in output or errors. */
     clientId?: string;
@@ -188,6 +195,10 @@ export declare function runMcpSetAuth(name: string | undefined, raw: McpSetAuthR
 }): {
     exitCode: number;
 };
+export declare function applyMcpSetAuthWithSync(plan: McpSetAuthPlan, homeDir: string): Promise<{
+    plan: McpSetAuthPlan;
+    sync?: McpSyncReport;
+}>;
 export type McpScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
 export interface McpScopePlan {
     name: string;

package/dist/commands/mcp.js

@@ -16,7 +16,7 @@ import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { loadCanonicalSource, upsertServerYaml, removeServerYaml } from "../core/canonical.js";
-import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, resolveScope } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, oauthOwner, resolveScope } from "../core/types.js";
 import { isValidSecretVarName } from "../lib/secretEnv.js";
 import { isExpired, readToken } from "../lib/oauth/store.js";
 import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
@@ -123,7 +123,7 @@ function serversYamlPath(homeDir) {
  * name that cannot be a token filename, or an unreadable file, simply has no
  * credential: one odd entry must not take down the whole listing.
  */
-export function mcpCredentialState(homeDir, serverName) {
+export function mcpCredentialState(homeDir, serverName, resourceUrl) {
     let token;
     try {
         token = readToken(homeDir, serverName);
@@ -133,6 +133,12 @@ export function mcpCredentialState(homeDir, serverName) {
     }
     if (!token?.accessToken)
         return { authStatus: "not-authorized" };
+    if (resourceUrl && token.resourceUrl) {
+        const resource = new URL(resourceUrl);
+        resource.hash = "";
+        if (token.resourceUrl !== resource.toString())
+            return { authStatus: "not-authorized" };
+    }
     const expiry = token.expiresAt !== undefined ? { authExpiresAt: token.expiresAt } : {};
     if (!isExpired(token))
         return { authStatus: "authorized", ...expiry };
@@ -145,7 +151,16 @@ export function collectMcpListPlan(homeDir = homedir()) {
         transport: def.transport,
         auth: isOAuthAuth(def.auth) ? "oauth" : undefined,
         preRegisteredClient: oauthClientMetadata(def.auth).clientId !== undefined ? true : undefined,
-        ...(isOAuthAuth(def.auth) ? mcpCredentialState(homeDir, name) : {}),
+        ...(isOAuthAuth(def.auth) ? {
+            authOwner: oauthOwner(def.auth),
+            ...(oauthOwner(def.auth) === "trellis" ? mcpCredentialState(homeDir, name, def.url) : {
+                authStatus: "unknown",
+                agentAuthorization: resolveScope(def.agents, canonical.managedAgents).map((agent) => ({
+                    agent, status: "unknown",
+                    instruction: agent === "codex" ? `codex mcp login ${name}` : agent === "claude-code" ? "Open Claude Code and use /mcp to authorize this server" : "Authorize this server in the Agent's MCP settings",
+                })),
+            }),
+        } : {}),
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -211,6 +226,7 @@ export function parseMcpSetArgs(argv) {
         auth: flag("--auth"),
         clientId: flag("--client-id"),
         clientSecretEnv: flag("--client-secret-env"),
+        authOwner: flag("--auth-owner"),
     };
 }
 function parseCsv(raw) {
@@ -314,8 +330,10 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     const mode = raw.auth === "oauth" || raw.auth === "none" ? raw.auth : undefined;
     if (!name)
         return { name: "(none)", auth: (mode ?? "none"), action: "invalid-input", detail: "usage: trellis mcp set <name> --auth oauth|none [--client-id <id>] [--client-secret-env <NAME>]" };
-    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined;
-    const clientFlagsDetail = "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
+    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined || raw.authOwner !== undefined;
+    const clientFlagsDetail = raw.authOwner !== undefined
+        ? "--auth-owner requires an explicit --auth oauth in the same command"
+        : "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
     if (mode === undefined) {
         // Naming the missing --auth is the actionable error when that is what
         // the user was reaching for; otherwise report the invalid value itself.
@@ -329,6 +347,9 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     if (raw.clientId === "") {
         return { name, auth: mode, action: "invalid-input", detail: "--client-id must not be empty" };
     }
+    if (raw.authOwner !== undefined && raw.authOwner !== "agent" && raw.authOwner !== "trellis") {
+        return { name, auth: mode, action: "invalid-input", detail: "--auth-owner must be agent or trellis" };
+    }
     if (raw.clientSecretEnv !== undefined && !isValidSecretVarName(raw.clientSecretEnv)) {
         // The value is deliberately not echoed: a name-shaped field failing
         // this check is at best a typo and at worst a pasted credential
@@ -387,6 +408,7 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
             ...current,
             auth: {
                 kind: "oauth",
+                ...(raw.authOwner !== undefined ? { owner: raw.authOwner } : typeof current.auth === "object" && current.auth.owner !== undefined ? { owner: current.auth.owner } : {}),
                 ...(clientId !== undefined ? { clientId } : {}),
                 ...(clientSecretEnv !== undefined ? { clientSecretEnv } : {}),
             },
@@ -424,6 +446,21 @@ export function runMcpSetAuth(name, raw, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
+export async function applyMcpSetAuthWithSync(plan, homeDir) {
+    if (plan.action !== "updated" || !plan.def)
+        return { plan };
+    const backup = openBackupSession(homeDir, "mcp-auth-owner");
+    try {
+        const path = serversYamlPath(homeDir);
+        const result = upsertServerYaml(path, plan.name, plan.def, backup);
+        if (!result.ok)
+            throw new Error(result.error);
+        return { plan, sync: await collectMcpSyncReport({ homeDir, backupSession: backup }) };
+    }
+    finally {
+        backup.finalize();
+    }
+}
 /**
  * `mcp scope <name> --agents a,b | --all | --none`
  * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as

package/dist/commands/mcpAuth.d.ts

@@ -16,6 +16,11 @@ export interface RunMcpAuthOptions {
     homeDir?: string;
     /** Test seam — the real one launches the platform browser. */
     openBrowser?: (url: string) => void | Promise<void>;
+    signal?: AbortSignal;
+    onProgress?: (phase: "discovering" | "registering" | "waiting" | "exchanging" | "saving") => void;
+    timeoutMs?: number;
+    /** Used by the desktop; native grants belong to each Agent. */
+    requireHosted?: boolean;
 }
 export interface McpAuthResult {
     server: string;
@@ -26,3 +31,4 @@ export interface McpAuthResult {
 export declare function runMcpAuth(opts: RunMcpAuthOptions): Promise<{
     exitCode: number;
 }>;
+export declare function authorizeMcpServer(opts: RunMcpAuthOptions): Promise<McpAuthResult>;

package/dist/commands/mcpAuth.js

@@ -11,16 +11,17 @@
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { discoverAuthorizationServer, parseResourceMetadataUrl } from "../lib/oauth/discovery.js";
-import { authorize } from "../lib/oauth/flow.js";
+import { authorize, abortable } from "../lib/oauth/flow.js";
 import { ensureFreshToken } from "../lib/oauth/refresh.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 import { isExpired, readToken, tokenPath, writeToken } from "../lib/oauth/store.js";
-import { oauthClientMetadata } from "../core/types.js";
+import { withServerLock } from "../lib/oauth/lock.js";
+import { isOAuthAuth, oauthOwner, oauthClientMetadata } from "../core/types.js";
 export async function runMcpAuth(opts) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
     try {
-        result = await authorizeServer(opts, homeDir);
+        result = await authorizeMcpServer(opts);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -41,7 +42,9 @@ export async function runMcpAuth(opts) {
     }
     return { exitCode: 0 };
 }
-async function authorizeServer(opts, homeDir) {
+export async function authorizeMcpServer(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    opts.signal?.throwIfAborted();
     const canonical = loadCanonicalSource(homeDir);
     const def = canonical.mcp.servers[opts.serverName];
     if (!def) {
@@ -54,15 +57,21 @@ async function authorizeServer(opts, homeDir) {
         // flow that does not exist.
         throw new Error(`MCP server "${opts.serverName}" is a stdio server — OAuth applies to http/sse servers. Its credentials come from \`env\`/\`env_aliases\` and secrets.policy.yaml.`);
     }
+    if (opts.requireHosted && (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis" || def.enabled === false)) {
+        throw new Error("This connection is authorized by its Agent; choose explicit Trellis ownership before starting hosted authorization");
+    }
     const file = tokenPath(homeDir, opts.serverName);
+    const resourceUrl = new URL(def.url);
+    resourceUrl.hash = "";
     if (!opts.force) {
-        const existing = readToken(homeDir, opts.serverName);
+        const stored = readToken(homeDir, opts.serverName);
+        const existing = stored?.resourceUrl && stored.resourceUrl !== resourceUrl.toString() ? undefined : stored;
         if (existing && !isExpired(existing)) {
             // Re-running is a no-op rather than a fresh grant: rotating a
             // perfectly good credential is a way to break a working setup.
             return { server: opts.serverName, status: "already-valid", tokenFile: file, ...(existing.expiresAt ? { expiresAt: existing.expiresAt } : {}) };
         }
-        if (existing?.refreshToken) {
+        if (existing?.refreshToken && !opts.requireHosted) {
             // Expired but renewable — no browser needed.
             const refreshed = await ensureFreshToken(homeDir, opts.serverName);
             if (refreshed) {
@@ -70,7 +79,10 @@ async function authorizeServer(opts, homeDir) {
             }
         }
     }
-    const metadata = await discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def) });
+    opts.onProgress?.("discovering");
+    const fetchImpl = (url, init) => fetch(url, { ...init, signal: opts.signal });
+    const metadata = await abortable(discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def, opts.signal), fetchImpl }), opts.signal);
+    opts.signal?.throwIfAborted();
     if (!metadata) {
         throw new Error(`could not discover OAuth metadata for "${opts.serverName}" (${def.url}) — it may not use OAuth, or may not publish RFC 8414/9728 metadata`);
     }
@@ -90,12 +102,28 @@ async function authorizeServer(opts, homeDir) {
         clientSecret = value;
     }
     const token = await authorize(opts.serverName, metadata, {
+        signal: opts.signal,
+        resourceUrl: resourceUrl.toString(),
+        onProgress: opts.onProgress,
+        timeoutMs: opts.timeoutMs,
         ...(opts.openBrowser ? { openBrowser: opts.openBrowser } : {}),
         ...(metadata.scopesSupported?.length ? { scope: metadata.scopesSupported.join(" ") } : {}),
         ...(client.clientId !== undefined ? { clientId: client.clientId } : {}),
         ...(clientSecret !== undefined ? { clientSecret } : {}),
     });
-    writeToken(homeDir, opts.serverName, token);
+    opts.signal?.throwIfAborted();
+    // Serialize the final write with silent refreshes, without holding a lock
+    // while the user is in the browser. An older refresh cannot overwrite a new
+    // grant after it is committed.
+    opts.onProgress?.("saving");
+    await withServerLock(homeDir, opts.serverName, async () => {
+        opts.signal?.throwIfAborted();
+        const current = loadCanonicalSource(homeDir).mcp.servers[opts.serverName];
+        if (!current || current.url !== def.url || JSON.stringify(current.auth) !== JSON.stringify(def.auth) || current.enabled === false) {
+            throw new Error("The server's endpoint or authorization configuration changed; start authorization again");
+        }
+        writeToken(homeDir, opts.serverName, token);
+    });
     return { server: opts.serverName, status: "authorized", tokenFile: file, ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}) };
 }
 /**
@@ -113,9 +141,9 @@ function secretSourceLabel(policy) {
  * server directly, which beats probing well-known paths. Failure is not
  * an error: discovery falls back to probing.
  */
-async function probeWwwAuthenticate(def) {
+async function probeWwwAuthenticate(def, signal) {
     try {
-        const response = await fetch(def.url, { method: "GET" });
+        const response = await fetch(def.url, { method: "GET", signal });
         if (response.status !== 401)
             return null;
         const header = response.headers.get("www-authenticate");

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

@@ -14,10 +14,10 @@
  * an in-process backend without this file, or any agent's config,
  * changing.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
-import { isGatewayAgent, isOAuthMcpServer, resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { isGatewayAgent, isAgentOwnedOAuth, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { LocalBackend } from "../lib/gatewayBackend.js";
 import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { BuiltinRegistry, createRuntimeServer, UpstreamProvider } from "../lib/mcpRuntime.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,12 +60,21 @@ 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;
-    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => !isOAuthMcpServer(def)));
+    // 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]; }));
     const direct = { ...canonical.mcp, servers: ordinaryServers, gateway: undefined, hub: undefined, routes: directRoutes, runtime: undefined };
     // The managed set is passed through unchanged, so an unmanaged agent
     // reaches nothing. Being spawned is NOT treated as consent here, which
@@ -79,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, def }) => ({ name, def })),
+        upstreams: desired.map(({ name }) => ({ name, def: canonical.mcp.servers[name] })),
+        oauthServers,
         conflicts: conflicts.map((conflict) => conflict.message),
     };
 }
@@ -107,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}`);
     }
@@ -122,10 +143,17 @@ 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)]);
-    const server = createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    // 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 };
 }