agent-trellis 0.15.1 → 0.17.0

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";
+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
@@ -44,6 +45,13 @@ const EXIT_NONZERO_KINDS = new Set([
     // exists to catch *before* the session does (trellis-mcp-oauth-renew
     // design.md D4).
     "oauth-expired",
+    // A project-level Codex config that fails TOML parsing will fail the
+    // *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. */
@@ -62,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));
@@ -120,7 +134,53 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
             // canonical has not been initialized yet.
         }
     }
-    const workspace = canonical?.workspace ? collectWorkspaceDoctorSection(canonical) : undefined;
+    // Workspace attribution runs whenever a workspace root is in scope —
+    // even when `~/.trellis/` itself failed to load or has never been
+    // initialized. The spec's third scenario: a user managing only project
+    // skills in `.agents/skills/` without a global Trellis install still
+    // gets project-level config validation
+    // (trellis-doctor-workspace-toml-validation design.md D5). When the
+    // canonical source is absent we synthesize the minimal workspace layer
+    // with every map empty — provenance is moot without a global layer, but
+    // `collectWorkspaceDoctorSection`'s per-file inspection is what we want.
+    let workspace;
+    if (canonical?.workspace) {
+        workspace = collectWorkspaceDoctorSection(canonical);
+    }
+    else {
+        const workspaceRoot = workspaceDir != null ? findWorkspaceRoot(workspaceDir) : null;
+        if (workspaceRoot) {
+            // `managedAgents` is driven by `~/.trellis/managed.yaml`, which is
+            // absent in this branch — sweep every known agent so codex's TOML
+            // file is still inspected (otherwise an empty list would skip the
+            // file entirely and the spec's scenario-3 finding would never fire).
+            const minimal = {
+                instructionsFile: "",
+                managedAgents: ALL_AGENTS,
+                skills: [],
+                agents: [],
+                memories: [],
+                mcp: { servers: {}, knownHostInjected: [] },
+                secretsPolicy: { allowedVars: [], rejectPatterns: [] },
+                diagnostics: [],
+                workspace: { root: workspaceRoot, mcpProvenance: {}, mcpGlobalServers: {}, skillProvenance: {}, globalSkills: [], shadowed: [] },
+            };
+            workspace = collectWorkspaceDoctorSection(minimal);
+        }
+    }
+    // Workspace TOML findings become top-level findings so the exit code
+    // and `--json` consumers see them alongside cross-agent findings, not
+    // only inside the workspace section. They keep `agent: "codex"` — the
+    // file layout tells us which agent the file breaks.
+    if (workspace) {
+        for (const finding of workspace.tomlFindings) {
+            findings.push({
+                kind: "workspace-toml-invalid",
+                agent: finding.agent,
+                message: `${finding.path}${finding.line !== undefined ? `:${finding.line}${finding.column !== undefined ? `:${finding.column}` : ""}` : ""} — ${finding.reason} (not rendered by Trellis; fix by hand)`,
+            });
+        }
+    }
     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 } : {}), ...(workspace ? { workspace } : {}) };
@@ -395,6 +455,10 @@ export function printReport(report) {
         for (const hint of ws.unmigrated) {
             console.log(`   ⚠ ${hint.path} holds ${hint.entries.length} entr${hint.entries.length === 1 ? "y" : "ies"} Trellis didn't render (${hint.entries.join(", ")}) — run \`trellis migrate --workspace\``);
         }
+        for (const finding of ws.tomlFindings) {
+            const location = finding.line !== undefined ? `:${finding.line}${finding.column !== undefined ? `:${finding.column}` : ""}` : "";
+            console.log(`   ⚠ ${finding.path}${location} — ${finding.reason} (not rendered by Trellis — fix by hand and re-run \`trellis doctor\`)`);
+        }
         for (const warning of ws.precedenceWarnings) {
             console.log(`   ⚠ ${warning}`);
         }

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/workspaceDoctor.d.ts

@@ -20,6 +20,19 @@ export interface WorkspaceUnmigratedHint {
     /** Entry names present in the file with no Trellis manifest record. */
     entries: string[];
 }
+/** One parse-level failure when inspecting an agent's project MCP file.
+ * Distinct from `parse-diagnostic` (agent-global probes). Even when Trellis
+ * has never rendered into this file, a project file that breaks the agent's
+ * own startup is exactly what doctor exists to surface
+ * (trellis-doctor-workspace-toml-validation). */
+export interface WorkspaceTomlFinding {
+    agent: AgentId;
+    path: string;
+    /** Parser's 1-based line and column of the failure, when known. */
+    line?: number;
+    column?: number;
+    reason: string;
+}
 export interface WorkspaceDoctorSection {
     root: string;
     mcp: WorkspaceLayerEntry[];
@@ -38,6 +51,8 @@ export interface WorkspaceDoctorSection {
         name: string;
     }[];
     unmigrated: WorkspaceUnmigratedHint[];
+    /** Parse-level failures on workspace agent MCP files (usually empty). */
+    tomlFindings: WorkspaceTomlFinding[];
     /** zcode's user-level-first deviation notices (empty otherwise). */
     precedenceWarnings: string[];
 }

package/dist/lib/workspaceDoctor.js

@@ -10,6 +10,7 @@
  * from the already-loaded canonical source and file reads only.
  */
 import { existsSync, readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
 import { resolveSecretEnv } from "./secretEnv.js";
 import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
 const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
@@ -36,15 +37,36 @@ function collectVarRefs(canonical) {
     return refs;
 }
 /** Entry names a JSON `mcpServers` file / Codex TOML / zcode nested
- * config holds beyond what the in-repo manifest records Trellis
- * rendering. Regex-parses Codex TOML section headers — doctor only
- * needs names for a hint, not a full TOML AST. */
+ * config holds beyond what the in-repo manifest records Trellis rendering.
+ *
+ * The Codex branch TOML-parses the file first — syntactically invalid TOML
+ * is indistinguishable from valid TOML to the section-header regex, but is
+ * fatal to Codex's own startup, so it is surfaced as `invalid` and never
+ * turned into an unmigrated hint. The parsed AST is discarded on success:
+ * header extraction keeps using the existing regex to avoid changing edge
+ * semantics (dotted quoted keys, single-quoted keys) that the regex was
+ * already validated against — smol-toml is used parse-only, never
+ * round-tripped, respecting lib/tomlSection.ts's write-path constraint. */
 function unmarkedEntries(agentId, configPath, recorded) {
     if (!existsSync(configPath))
-        return [];
+        return { kind: "ok", names: [] };
     let names = [];
     if (agentId === "codex") {
         const content = readFileSync(configPath, "utf-8");
+        try {
+            parseToml(content);
+        }
+        catch (err) {
+            const tomLError = err;
+            const reason = tomLError.message?.split("\n")[0] ?? String(err);
+            return {
+                kind: "invalid",
+                path: configPath,
+                ...(typeof tomLError.line === "number" ? { line: tomLError.line } : {}),
+                ...(typeof tomLError.column === "number" ? { column: tomLError.column + 1 } : {}),
+                reason,
+            };
+        }
         const re = /^\[mcp_servers\.([^\]]+)\]\s*$/gm;
         let match;
         while ((match = re.exec(content)) !== null)
@@ -59,10 +81,10 @@ function unmarkedEntries(agentId, configPath, recorded) {
             names = Object.keys(servers);
         }
         catch {
-            return []; // unparsable file is the sync guard's finding, not doctor's
+            return { kind: "ok", names: [] }; // unparsable file is the sync guard's finding, not doctor's
         }
     }
-    return names.filter((name) => recorded[name] === undefined);
+    return { kind: "ok", names: names.filter((name) => recorded[name] === undefined) };
 }
 export function collectWorkspaceDoctorSection(canonical) {
     const workspace = canonical.workspace;
@@ -83,12 +105,17 @@ export function collectWorkspaceDoctorSection(canonical) {
     const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
     const manifest = loadWorkspaceRendered(workspace.root);
     const unmigrated = [];
+    const tomlFindings = [];
     for (const agentId of canonical.managedAgents) {
         const configPath = workspaceMcpConfigPath(agentId, workspace.root);
-        const entries = unmarkedEntries(agentId, configPath, manifest.mcp?.[agentId] ?? {});
-        if (entries.length > 0)
-            unmigrated.push({ agent: agentId, path: configPath, entries });
+        const result = unmarkedEntries(agentId, configPath, manifest.mcp?.[agentId] ?? {});
+        if (result.kind === "invalid") {
+            tomlFindings.push({ agent: agentId, path: result.path, ...(result.line !== undefined ? { line: result.line } : {}), ...(result.column !== undefined ? { column: result.column } : {}), reason: result.reason });
+            continue; // never report an unparseable file's entries as unmigrated — spec req 2
+        }
+        if (result.names.length > 0)
+            unmigrated.push({ agent: agentId, path: configPath, entries: result.names });
     }
     const precedenceWarnings = canonical.managedAgents.flatMap((id) => workspacePrecedenceWarnings(id, canonical));
-    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, precedenceWarnings };
+    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, tomlFindings, precedenceWarnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -64,6 +64,7 @@
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@modelcontextprotocol/server": "^2.3.1",
+    "smol-toml": "^1.9.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   }