agent-trellis 0.12.0 → 0.14.0

package/dist/adapters/pi.d.ts

@@ -3,22 +3,61 @@
  * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
  * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
  * override name first, and Trellis's managed file is the baseline, not an
- * override of something else). pi has no native MCP client (docs/research.md),
- * so MCP access is delivered as a single symlinked bridge extension
- * instead of native config (trellis-pi-mcp-bridge-p4) — a different
- * mechanism from every other agent's config-generation adapter, but the
- * same symlink create/repair/remove machinery as skills/instructions.
+ * override of something else).
+ *
+ * MCP delivery is version-gated (trellis-pi-native-mcp-migration):
+ *
+ * - pi >= 1.1.0 has a native MCP client, so `trellis mcp sync` merges
+ *   Trellis-managed entries into `~/.pi/agent/mcp.json` through the shared
+ *   `planJsonMcp`/`applyJsonMcp` machinery (ownership ledger, conflict
+ *   detection, user entries preserved) with the pi-shaped renderer from
+ *   `piMcp.ts`. Gateway route → the single `trellis` runtime entry;
+ *   agent-owned OAuth servers → bare `{url}` entries the user authorizes
+ *   with `pi mcp login`.
+ * - Older pis (or an unprobeable version) keep the legacy delivery: a
+ *   single symlinked bridge extension (`dist/pi-bridge/bundle.js`,
+ *   trellis-pi-mcp-bridge-p4). The version gate never moves a machine
+ *   FROM the bridge TO native until the mcp.json write succeeds — the
+ *   bridge-removal item rides along in the same plan, ordered after the
+ *   config write, and is withheld entirely when any write conflicts
+ *   (design.md D3: the two deliveries may never be active at once, every
+ *   tool would register twice).
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
 import type { CanonicalSource } from "../core/types.js";
-import type { BackupSession } from "../lib/backup.js";
+import { type BackupSession } from "../lib/backup.js";
 export declare class PiAdapter implements TrellisAdapter {
     private readonly homeDir;
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    private readonly versionProbe;
     readonly name = "pi";
     readonly id: "pi";
-    constructor(homeDir?: string);
+    constructor(homeDir?: string, 
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    versionProbe?: () => string | undefined);
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    /**
+     * Native-delivery plan (design.md D1/D3). The write items come from the
+     * shared JSON machinery unchanged; the bridge-removal item is appended
+     * last and re-cast to kind "mcp" so it travels through `trellis mcp
+     * sync` — the same command that writes mcp.json — never through bare
+     * `trellis sync`. That is what makes the migration atomic from the
+     * user's point of view: the config lands and the bridge leaves in one
+     * apply, and a bare skills/instructions sync can neither remove the
+     * bridge early nor resurrect it afterwards.
+     */
+    private planNativeMcp;
+    /**
+     * Removal ownership for the bridge, mirroring `planSymlinks`' rule: the
+     * raw readlink target must resolve under this installation's
+     * `dist/pi-bridge/` directory, or be a byte-identical bundle at the
+     * Trellis artifact shape left by a previous install root. Anything else
+     * is the user's and stays.
+     */
+    private isOwnedBridgeSymlink;
     apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/pi.js

@@ -3,20 +3,39 @@
  * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
  * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
  * override name first, and Trellis's managed file is the baseline, not an
- * override of something else). pi has no native MCP client (docs/research.md),
- * so MCP access is delivered as a single symlinked bridge extension
- * instead of native config (trellis-pi-mcp-bridge-p4) — a different
- * mechanism from every other agent's config-generation adapter, but the
- * same symlink create/repair/remove machinery as skills/instructions.
+ * override of something else).
+ *
+ * MCP delivery is version-gated (trellis-pi-native-mcp-migration):
+ *
+ * - pi >= 1.1.0 has a native MCP client, so `trellis mcp sync` merges
+ *   Trellis-managed entries into `~/.pi/agent/mcp.json` through the shared
+ *   `planJsonMcp`/`applyJsonMcp` machinery (ownership ledger, conflict
+ *   detection, user entries preserved) with the pi-shaped renderer from
+ *   `piMcp.ts`. Gateway route → the single `trellis` runtime entry;
+ *   agent-owned OAuth servers → bare `{url}` entries the user authorizes
+ *   with `pi mcp login`.
+ * - Older pis (or an unprobeable version) keep the legacy delivery: a
+ *   single symlinked bridge extension (`dist/pi-bridge/bundle.js`,
+ *   trellis-pi-mcp-bridge-p4). The version gate never moves a machine
+ *   FROM the bridge TO native until the mcp.json write succeeds — the
+ *   bridge-removal item rides along in the same plan, ordered after the
+ *   config write, and is withheld entirely when any write conflicts
+ *   (design.md D3: the two deliveries may never be active at once, every
+ *   tool would register twice).
  */
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
-import { readFileSync } from "node:fs";
 import { isInScope } from "../core/adapter.js";
 import { usesNativeCapabilityDelivery } from "../core/types.js";
 import * as piProbe from "../probes/pi.js";
+import { probePiVersion } from "../probes/pi.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+import { piRenderer, supportsNativeMcp } from "./piMcp.js";
+import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { currentLinkTarget } from "../lib/backup.js";
 const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
 /**
  * A source-checkout bridge can survive a switch to the packaged CLI. Adopt it
@@ -61,10 +80,15 @@ function resolveBridgeFile() {
 }
 export class PiAdapter {
     homeDir;
+    versionProbe;
     name = "pi";
     id = "pi";
-    constructor(homeDir = homedir()) {
+    constructor(homeDir = homedir(), 
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    versionProbe = probePiVersion) {
         this.homeDir = homeDir;
+        this.versionProbe = versionProbe;
     }
     async probe() {
         const snapshot = await piProbe.probe(this.homeDir);
@@ -88,6 +112,9 @@ export class PiAdapter {
             canonicalRoot,
             kind: "instructions",
         });
+        if (supportsNativeMcp(this.versionProbe())) {
+            return [...skillItems, ...instructionsItems, ...this.planNativeMcp(canonical)];
+        }
         const { file: bridgeFile, symlinkName } = resolveBridgeFile();
         const extensionItems = planSymlinks({
             rootDir: join(agentDir, "extensions"),
@@ -101,8 +128,104 @@ export class PiAdapter {
         });
         return [...skillItems, ...instructionsItems, ...extensionItems];
     }
+    /**
+     * Native-delivery plan (design.md D1/D3). The write items come from the
+     * shared JSON machinery unchanged; the bridge-removal item is appended
+     * last and re-cast to kind "mcp" so it travels through `trellis mcp
+     * sync` — the same command that writes mcp.json — never through bare
+     * `trellis sync`. That is what makes the migration atomic from the
+     * user's point of view: the config lands and the bridge leaves in one
+     * apply, and a bare skills/instructions sync can neither remove the
+     * bridge early nor resurrect it afterwards.
+     */
+    planNativeMcp(canonical) {
+        const agentDir = join(this.homeDir, ".pi", "agent");
+        const configPath = join(agentDir, "mcp.json");
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
+        const items = planJsonMcp({
+            configPath,
+            parsed,
+            mcp: canonical.mcp,
+            agentId: this.id,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership,
+            render: piRenderer,
+        }).map((item) => {
+            // pi speaks stdio and streamable HTTP only — an sse server gets an
+            // honest conflict instead of an entry pi could never connect.
+            const write = item.mcpWrite;
+            if (write?.def.transport !== "sse")
+                return item;
+            return {
+                action: "conflict",
+                kind: "mcp",
+                target: item.target,
+                description: `MCP server "${write.name}" uses the sse transport, which pi does not support (stdio and streamable HTTP only) — no entry written to ${item.target}`,
+                remediation: "switch the server to streamable HTTP or stdio, or scope it away from pi",
+            };
+        });
+        const bridgePath = join(agentDir, "extensions", BRIDGE_SYMLINK_NAME);
+        const hasConflict = items.some((item) => item.action === "conflict");
+        if (!hasConflict && this.isOwnedBridgeSymlink(bridgePath)) {
+            items.push({
+                action: "remove",
+                kind: "mcp",
+                target: bridgePath,
+                description: `remove Trellis MCP bridge extension ${bridgePath} — pi >= 1.1.0 receives MCP natively via mcp.json`,
+            });
+        }
+        return items;
+    }
+    /**
+     * Removal ownership for the bridge, mirroring `planSymlinks`' rule: the
+     * raw readlink target must resolve under this installation's
+     * `dist/pi-bridge/` directory, or be a byte-identical bundle at the
+     * Trellis artifact shape left by a previous install root. Anything else
+     * is the user's and stays.
+     */
+    isOwnedBridgeSymlink(bridgePath) {
+        const stat = lstatSync(bridgePath, { throwIfNoEntry: false });
+        if (!stat?.isSymbolicLink())
+            return false;
+        const rawTarget = readlinkSync(bridgePath);
+        const { file } = resolveBridgeFile();
+        const bridgeRoot = dirname(file);
+        const resolved = rawTarget.startsWith(sep) ? rawTarget : join(dirname(bridgePath), rawTarget);
+        if (resolved === file || resolved.startsWith(bridgeRoot.endsWith(sep) ? bridgeRoot : `${bridgeRoot}${sep}`))
+            return true;
+        return isEquivalentTrellisBridge(resolved, file);
+    }
     async apply(plan, backup) {
-        await applySymlinkPlan(plan, backup);
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
+        // Real config writes carry mcpWrite/mcpRemove; the bridge-removal
+        // item is the only kind:"mcp" entry without either, and it must run
+        // strictly after the config write (design.md D3).
+        const mcpWrites = plan.filter((item) => item.kind === "mcp" && (item.mcpWrite || item.mcpRemove));
+        const bridgeRemovals = plan.filter((item) => item.kind === "mcp" && item.action === "remove" && !item.mcpWrite && !item.mcpRemove);
+        if (mcpWrites.length > 0) {
+            const configPath = mcpWrites[0].target;
+            const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+            const merged = applyJsonMcp(parsed, mcpWrites, piRenderer);
+            backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+            let ownership = loadMcpOwnership(this.homeDir);
+            for (const item of mcpWrites) {
+                if (item.action === "create" && item.mcpWrite) {
+                    ownership = recordOwned(ownership, this.id, item.mcpWrite.name, piRenderer(item.mcpWrite.def, item.mcpWrite.name));
+                }
+                else if (item.action === "remove" && item.mcpRemove) {
+                    ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+                }
+            }
+            saveMcpOwnership(this.homeDir, ownership);
+        }
+        for (const item of bridgeRemovals) {
+            const oldTarget = await currentLinkTarget(item.target);
+            if (oldTarget === undefined)
+                continue; // already gone — nothing to record
+            await backup.removeSymlink(item.target, oldTarget);
+        }
     }
     async verify(canonical) {
         const snapshot = await piProbe.probe(this.homeDir);
@@ -122,6 +245,26 @@ export class PiAdapter {
                 mismatches.push(`skill "${name}" is present on disk but not in canonical scope for pi`);
             }
         }
+        if (supportsNativeMcp(this.versionProbe())) {
+            // Native mode drift: anything the plan still wants to change is by
+            // definition drift. The plan only ever names Trellis-owned entries
+            // (the ownership ledger gates removals), so user-authored servers
+            // can never surface here.
+            for (const item of this.planNativeMcp(canonical)) {
+                if (item.action === "create" && item.mcpWrite) {
+                    mismatches.push(`mcp.json entry "${item.mcpWrite.name}" is missing or differs from canonical — run trellis mcp sync`);
+                }
+                else if (item.action === "remove" && item.mcpRemove) {
+                    mismatches.push(`mcp.json entry "${item.mcpRemove.name}" is Trellis-owned but no longer in canonical — run trellis mcp sync`);
+                }
+                else if (item.action === "remove") {
+                    mismatches.push(`the Trellis MCP bridge extension is still installed but pi >= 1.1.0 uses native mcp.json — run trellis mcp sync`);
+                }
+                else if (item.action === "conflict") {
+                    mismatches.push(item.description);
+                }
+            }
+        }
         return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
     }
 }

package/dist/adapters/piMcp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * pi's native MCP config (pi >= 1.1.0) — the entry renderer and the
+ * version gate that chooses between it and the legacy bridge extension
+ * (openspec/changes/pi-native-mcp-migration design.md D1/D2).
+ *
+ * pi's mcp.json has no `type` discriminator: an entry is stdio when it
+ * carries `command`, streamable HTTP when it carries `url`. `${VAR}`
+ * references in `env`/`headers` values are expanded by pi at spawn
+ * (verified empirically against pi 1.1.0 on 2026-10-11), so the
+ * zero-plaintext rendering every other JSON agent relies on works
+ * unchanged. sse is not a pi transport — the adapter turns sse servers
+ * into conflict items rather than writing entries pi cannot connect.
+ */
+import type { McpServerDef } from "../core/types.js";
+/** The pi release that introduced the native MCP client (`pi mcp`,
+ * `~/.pi/agent/mcp.json`). */
+export declare const PI_NATIVE_MCP_SINCE = "1.1.0";
+/**
+ * Version gate (design.md D2): native delivery only when the probed
+ * version is known to understand mcp.json. Anything unparseable —
+ * including "binary not on PATH" (undefined) — falls back to the bridge,
+ * never the other way round: writing config a pi cannot read is worse
+ * than keeping a working bridge.
+ */
+export declare function supportsNativeMcp(version: string | undefined): boolean;
+/**
+ * pi-shaped rendering of a canonical server definition — the same shape
+ * `pi mcp add` writes (observed 2026-10-11): stdio as
+ * `{command, args, env?}`, http as `{url, headers?}`, no `type` field.
+ * `env` names render as `${VAR}` references exactly like the other JSON
+ * agents; OAuth `auth` metadata is Trellis-side routing information and
+ * is never rendered (an agent-owned OAuth server becomes a bare `{url}`
+ * entry that `pi mcp login <name>` authorizes into pi's own token store).
+ */
+export declare function piRenderer(def: McpServerDef, _name: string): Record<string, unknown>;

package/dist/adapters/piMcp.js

@@ -0,0 +1,58 @@
+/**
+ * pi's native MCP config (pi >= 1.1.0) — the entry renderer and the
+ * version gate that chooses between it and the legacy bridge extension
+ * (openspec/changes/pi-native-mcp-migration design.md D1/D2).
+ *
+ * pi's mcp.json has no `type` discriminator: an entry is stdio when it
+ * carries `command`, streamable HTTP when it carries `url`. `${VAR}`
+ * references in `env`/`headers` values are expanded by pi at spawn
+ * (verified empirically against pi 1.1.0 on 2026-10-11), so the
+ * zero-plaintext rendering every other JSON agent relies on works
+ * unchanged. sse is not a pi transport — the adapter turns sse servers
+ * into conflict items rather than writing entries pi cannot connect.
+ */
+import { resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+/** The pi release that introduced the native MCP client (`pi mcp`,
+ * `~/.pi/agent/mcp.json`). */
+export const PI_NATIVE_MCP_SINCE = "1.1.0";
+/**
+ * Version gate (design.md D2): native delivery only when the probed
+ * version is known to understand mcp.json. Anything unparseable —
+ * including "binary not on PATH" (undefined) — falls back to the bridge,
+ * never the other way round: writing config a pi cannot read is worse
+ * than keeping a working bridge.
+ */
+export function supportsNativeMcp(version) {
+    if (version === undefined)
+        return false;
+    const match = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(version.trim());
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return major > 1 || (major === 1 && minor >= 1);
+}
+/**
+ * pi-shaped rendering of a canonical server definition — the same shape
+ * `pi mcp add` writes (observed 2026-10-11): stdio as
+ * `{command, args, env?}`, http as `{url, headers?}`, no `type` field.
+ * `env` names render as `${VAR}` references exactly like the other JSON
+ * agents; OAuth `auth` metadata is Trellis-side routing information and
+ * is never rendered (an agent-owned OAuth server becomes a bare `{url}`
+ * entry that `pi mcp login <name>` authorizes into pi's own token store).
+ */
+export function piRenderer(def, _name) {
+    if (def.transport === "http" || def.transport === "sse") {
+        const entry = { url: def.url };
+        if (def.headers && Object.keys(def.headers).length > 0) {
+            entry.headers = def.headers;
+        }
+        return entry;
+    }
+    const entry = { command: def.command, args: def.args ?? [] };
+    const env = resolvedEnvTextMap(def);
+    if (Object.keys(env).length > 0) {
+        entry.env = env;
+    }
+    return entry;
+}

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/mcp.js

@@ -111,6 +111,12 @@ export function printReport(report, dryRun) {
         for (const item of [...created, ...removed, ...conflicts]) {
             console.log(`   - [${item.action}] ${item.description}`);
         }
+        // pi does not watch mcp.json (verified 2026-10-11): without this hint
+        // a changed config silently only takes effect on the next pi launch
+        // (trellis-pi-native-mcp-migration design.md D5).
+        if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
+            console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+        }
     }
 }
 function serversYamlPath(homeDir) {

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 };