agent-trellis 0.16.0 → 0.17.1

package/dist/cli.js

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

package/dist/commands/doctor.d.ts

@@ -6,6 +6,7 @@
  */
 import { loadCanonicalSource } from "../core/canonical.js";
 import type { AgentId, AgentSnapshot, CanonicalSource } from "../core/types.js";
+import { type VersionExecutor } from "../lib/cliEntrypoints.js";
 import { type WorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
@@ -15,7 +16,7 @@ import { type WorkspaceDoctorSection } from "../lib/workspaceDoctor.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" | "oauth-expired" | "mcp-unreachable" | "workspace-toml-invalid";
+export type FindingKind = "probe-failed" | "duplication" | "collision" | "drift" | "case-mismatch" | "parse-diagnostic" | "runtime-drift" | "oauth-expired" | "mcp-unreachable" | "workspace-toml-invalid" | "cli-version-split";
 export interface Finding {
     kind: FindingKind;
     /** Omitted for a finding that names more than one agent (drift). */
@@ -52,6 +53,10 @@ export interface RunDoctorOptions {
      * seam. CLI discovery walks up from cwd via `findWorkspaceRoot`;
      * null = no workspace layer. */
     workspaceDir?: string | null;
+    /** PATH to scan for `trellis` entrypoints; defaults to the real one.
+     * Test seam, with `execVersion`. */
+    pathEnv?: string;
+    execVersion?: VersionExecutor;
 }
 export interface OAuthHealthEntry {
     server: string;

package/dist/commands/doctor.js

@@ -17,6 +17,7 @@ import { ALL_AGENTS, isOAuthAuth, oauthOwner } from "../core/types.js";
 import { classifyStoredToken, remediationFor } from "../lib/oauth/renew.js";
 import { readToken } from "../lib/oauth/store.js";
 import { findWorkspaceRoot } from "../lib/workspace.js";
+import { detectCliVersionSplit, findCliEntrypoints } from "../lib/cliEntrypoints.js";
 import { collectWorkspaceDoctorSection } from "../lib/workspaceDoctor.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
@@ -48,6 +49,9 @@ const EXIT_NONZERO_KINDS = new Set([
     // *agent*'s own startup regardless of ownership — catch it here before
     // the next session does (trellis-doctor-workspace-toml-validation).
     "workspace-toml-invalid",
+    // A stale `trellis` that wins on PATH silently changes behavior (e.g.
+    // rejecting config keys a newer copy accepts) — trellis-doctor-cli-version-split.
+    "cli-version-split",
 ]);
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -66,6 +70,12 @@ export function resolveKnownHostInjected(opts) {
 export async function runDoctor(opts = {}) {
     const workspaceDir = opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd());
     const report = await collectDoctorReport(opts.homeDir, resolveKnownHostInjected(opts), opts.probeMcp, workspaceDir);
+    // CLI boundary only: spawning `trellis --version` belongs here, not in
+    // collectDoctorReport, so library callers and their tests never depend
+    // on the developer's real PATH.
+    const split = detectCliVersionSplit(findCliEntrypoints({ pathEnv: opts.pathEnv, execVersion: opts.execVersion }));
+    if (split)
+        report.findings.push({ kind: "cli-version-split", message: split });
     const exitCode = report.findings.some((f) => EXIT_NONZERO_KINDS.has(f.kind)) ? 1 : 0;
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));

package/dist/commands/mcpAuth.d.ts

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

package/dist/commands/mcpAuth.js

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

package/dist/lib/cliEntrypoints.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Locates every `trellis` executable on PATH and compares their versions
+ * (trellis-doctor-cli-version-split). Read-only: it never edits, removes
+ * or upgrades an entrypoint — a wrapper script may be deliberately
+ * maintained by the user, so Trellis only reports.
+ */
+export interface CliEntrypoint {
+    path: string;
+    version: string;
+}
+export type VersionExecutor = (path: string) => string | undefined;
+/** Runs `<path> --version` via argv (no shell). `undefined` on any
+ * failure or unrecognizable output, so a broken entry is skipped rather
+ * than reported as a split. */
+export declare const defaultExecVersion: VersionExecutor;
+export declare function findCliEntrypoints(opts?: {
+    pathEnv?: string;
+    execVersion?: VersionExecutor;
+    name?: string;
+}): CliEntrypoint[];
+/** A finding message when two or more entries disagree; `undefined`
+ * otherwise. The first entry is the one a bare `trellis` runs. */
+export declare function detectCliVersionSplit(entries: readonly CliEntrypoint[]): string | undefined;

package/dist/lib/cliEntrypoints.js

@@ -0,0 +1,79 @@
+/**
+ * Locates every `trellis` executable on PATH and compares their versions
+ * (trellis-doctor-cli-version-split). Read-only: it never edits, removes
+ * or upgrades an entrypoint — a wrapper script may be deliberately
+ * maintained by the user, so Trellis only reports.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+const VERSION_RE = /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/;
+/** Runs `<path> --version` via argv (no shell). `undefined` on any
+ * failure or unrecognizable output, so a broken entry is skipped rather
+ * than reported as a split. */
+export const defaultExecVersion = (path) => {
+    try {
+        const out = execFileSync(path, ["--version"], { encoding: "utf-8", timeout: 5_000, stdio: ["ignore", "pipe", "ignore"] });
+        return VERSION_RE.exec(out)?.[0];
+    }
+    catch {
+        return undefined;
+    }
+};
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findCliEntrypoints(opts = {}) {
+    const pathEnv = opts.pathEnv ?? process.env.PATH ?? "";
+    const execVersion = opts.execVersion ?? defaultExecVersion;
+    const name = opts.name ?? "trellis";
+    const seenDirs = new Set();
+    const seenReal = new Set();
+    const entries = [];
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir || seenDirs.has(dir))
+            continue;
+        seenDirs.add(dir);
+        const candidate = join(dir, name);
+        if (!isExecutableFile(candidate))
+            continue;
+        let real;
+        try {
+            real = realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (seenReal.has(real))
+            continue;
+        seenReal.add(real);
+        // Spawn the PATH-visible path, not the resolved target: a shim's
+        // behavior depends on the name it is invoked by.
+        const version = execVersion(candidate);
+        if (version)
+            entries.push({ path: candidate, version });
+    }
+    return entries;
+}
+/** A finding message when two or more entries disagree; `undefined`
+ * otherwise. The first entry is the one a bare `trellis` runs. */
+export function detectCliVersionSplit(entries) {
+    if (entries.length < 2)
+        return undefined;
+    if (new Set(entries.map((e) => e.version)).size < 2)
+        return undefined;
+    const lines = entries.map((e, i) => `  ${i === 0 ? "▶ runs" : "  also"}  ${e.path}  ${e.version}`);
+    return [
+        `${entries.length} \`trellis\` entrypoints on PATH report different versions — a bare \`trellis\` runs ${entries[0].path} (${entries[0].version}), so upgrading another copy has no effect:`,
+        ...lines,
+        "Reconcile them (upgrade or remove the stale one, or reorder PATH) — Trellis does not modify entrypoints.",
+    ].join("\n");
+}

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

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

package/dist/lib/oauth/refresh.js

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

package/dist/lib/oauth/renew.js

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

package/dist/pi-bridge/bundle.js

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

package/docs/mcp-oauth-renewal.md

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

package/docs/roadmap.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",