agent-trellis 0.14.1 → 0.15.1

package/dist/lib/mcpMigrateRead.js

@@ -73,7 +73,11 @@ function splitJsonEnvMap(env) {
         result.staticEnv = literal;
     return result;
 }
-function fromRichJsonServerDef(raw) {
+/** Also exported for the workspace-migration scanner's zcode reader
+ * (trellis-workspace-scope task 4.1): zcode's project config nests the
+ * same rich-JSON server shape under `mcp.servers`, so the walker there
+ * reuses this per-entry mapping unchanged. */
+export function fromRichJsonServerDef(raw) {
     if (raw.url) {
         const transport = raw.type === "sse" ? "sse" : "http";
         const def = { transport, url: raw.url };
@@ -89,7 +93,10 @@ function fromRichJsonServerDef(raw) {
     Object.assign(def, splitJsonEnvMap(raw.env));
     return def;
 }
-function readRichJsonMcpDefs(configPath) {
+/** Also the workspace-migration scanner's JSON reader (trellis-workspace-
+ * scope task 4.1): project-level `.mcp.json`-shape files parse through
+ * the exact same rules as their global counterparts. */
+export function readRichJsonMcpDefs(configPath) {
     const parsed = readJsonFile(configPath);
     const entries = [];
     const unsupported = [];

package/dist/lib/scopeSelection.d.ts

@@ -27,7 +27,7 @@ export type ScopeSelection = {
     detail: string;
 };
 export declare const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
-/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+/** Shared reader — accepts `--agents <ids>` and `--agents=<ids>`. */
 export declare function parseScopeArgs(argv: readonly string[]): ScopeSelectorRaw;
 export declare function resolveScopeSelection(raw: ScopeSelectorRaw, managed: readonly AgentId[]): ScopeSelection;
 /** Order-insensitive equality between the scope on disk and the one about to

package/dist/lib/scopeSelection.js

@@ -6,12 +6,13 @@
  * disagree about what a given selection means.
  */
 import { ALL_AGENTS } from "../core/types.js";
+import { flagValue } from "./cliArgs.js";
 export const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
-/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+/** Shared reader — accepts `--agents <ids>` and `--agents=<ids>`. */
 export function parseScopeArgs(argv) {
-    const i = argv.indexOf("--agents");
+    const agents = flagValue(argv, "--agents");
     return {
-        ...(i >= 0 ? { agents: argv[i + 1] ?? "" } : {}),
+        ...(agents !== undefined ? { agents } : {}),
         all: argv.includes("--all"),
         none: argv.includes("--none"),
     };

package/dist/lib/skillProvider.js

@@ -4,10 +4,23 @@ import { resolve, relative, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { isInScope } from "../core/adapter.js";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { findWorkspaceRoot } from "./workspace.js";
 import { resolveScope } from "../core/types.js";
 import { buildSkillEntry, parseSkillUri, readSkillFileBytes, toResourceContent } from "./skillManifest.js";
 const MAX_FILE_BYTES = 256 * 1024;
 const SKILL_RESOURCE_PREFIX = "trellis://skills/";
+/**
+ * The Runtime process is spawned by the agent with the agent's own cwd —
+ * inside a repo carrying `.agents/`, skills served over the Runtime
+ * (zcode's delivery path) include the workspace layer, exactly like the
+ * file-delivered agents get their project copies (trellis-workspace-scope
+ * task 2.2). MCP upstream connections are deliberately NOT layered this
+ * way (design D6: workspace servers are direct, agent-owned) — this
+ * helper is used only here, never in the gateway's upstream resolution.
+ */
+function loadSkillCanonical(homeDir) {
+    return loadCanonicalSource({ homeDir, workspaceDir: findWorkspaceRoot(process.cwd()) });
+}
 const SEARCH_TOOL = {
     name: "trellis.skills.search",
     description: "Search in-scope Trellis skills by name or description, then read one selected skill on demand.",
@@ -131,7 +144,7 @@ export class SkillProvider {
     }
     /** `skills/list` — one entry per servable, in-scope skill. */
     listSkillEntries(context) {
-        return this.catalog(loadCanonicalSource(context.homeDir), context.agentId).map(({ entry }) => entry);
+        return this.catalog(loadSkillCanonical(context.homeDir), context.agentId).map(({ entry }) => entry);
     }
     /** `skills/get` — lookup by URI, independent of listing. Out-of-scope and
      * unknown URIs are indistinguishable by design. */
@@ -145,7 +158,7 @@ export class SkillProvider {
         return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
     }
     async callTool(name, args, context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const input = (args ?? {});
         if (name === SEARCH_TOOL.name)
             return this.search(canonical, context.agentId, input);
@@ -156,7 +169,7 @@ export class SkillProvider {
         return errorResult(`unknown skill provider tool "${name}"`);
     }
     listResources(context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const legacy = canonical.skills
             .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
             .map((skill) => ({
@@ -181,7 +194,7 @@ export class SkillProvider {
         if (segments.length !== 2 || segments[1] !== "SKILL.md") {
             throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
         }
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = skillFor(canonical, context.agentId, segments[0]);
         if (!skill)
             throw new Error(`skill "${segments[0]}" is not available to ${context.agentId}`);
@@ -192,7 +205,7 @@ export class SkillProvider {
      * computed its digests — the two cannot disagree. */
     readConventionalResource(uri, context) {
         const parsed = parseSkillUri(uri);
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = parsed ? skillFor(canonical, context.agentId, parsed.name) : undefined;
         const served = skill && parsed ? this.catalog(canonical, context.agentId).find(({ entry }) => entry.uri === `skill://${parsed.name}/SKILL.md`) : undefined;
         if (!parsed || !skill || !served || !served.entry.resources.some((file) => file.uri === uri)) {

package/dist/lib/workspace.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import type { McpServerDef, SecretsPolicy, SkillRef } from "../core/types.js";
+export declare const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export declare const WORKSPACE_CONFIG_VERSION = 1;
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export declare function findWorkspaceRoot(startDir: string): string | null;
+export interface WorkspaceLayer {
+    /** Absolute workspace root (the directory containing `.agents/`). */
+    root: string;
+    /** Validated MCP servers from `config.json`, minus tombstones. */
+    servers: Record<string, McpServerDef>;
+    /** Server names declared with `enabled: false` — they disable a same-ID
+     * global entry and render nothing themselves. */
+    tombstones: string[];
+    /** Skills from `.agents/skills/<name>/`. */
+    skills: SkillRef[];
+    /** `.agents/AGENTS.md`, when present. */
+    instructionsFile?: string;
+    diagnostics: string[];
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export declare function loadWorkspaceLayer(workspaceDir: string, policy: SecretsPolicy): WorkspaceLayer;

package/dist/lib/workspace.js

@@ -0,0 +1,158 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { oauthClientMetadata } from "../core/types.js";
+import { fromServerDefYaml } from "../core/mcpServerDef.js";
+export const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export const WORKSPACE_CONFIG_VERSION = 1;
+const CONFIG_SOURCE_LABEL = ".agents/config.json";
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export function findWorkspaceRoot(startDir) {
+    const home = resolve(homedir());
+    let dir = resolve(startDir);
+    while (true) {
+        if (dir === home)
+            return null;
+        const candidate = join(dir, WORKSPACE_DIR_NAME);
+        try {
+            if (statSync(candidate).isDirectory())
+                return dir;
+        }
+        catch {
+            // not present or unreadable — keep walking
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function isTombstone(def) {
+    return def.enabled === false && def.transport === undefined;
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export function loadWorkspaceLayer(workspaceDir, policy) {
+    const layerRoot = join(workspaceDir, WORKSPACE_DIR_NAME);
+    const diagnostics = [];
+    const layer = { root: workspaceDir, servers: {}, tombstones: [], skills: [], diagnostics };
+    const configPath = join(layerRoot, "config.json");
+    if (existsSync(configPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch (err) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: invalid JSON — ${err.message}`);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: top level must be an object { "version", "mcp" }`);
+        }
+        const { version, mcp, ...extra } = parsed;
+        const configVersion = version === undefined ? WORKSPACE_CONFIG_VERSION : version;
+        if (typeof configVersion !== "number" || !Number.isInteger(configVersion) || configVersion < 1) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: "version" must be a positive integer, got ${JSON.stringify(version)}`);
+        }
+        if (configVersion > WORKSPACE_CONFIG_VERSION) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: schema version ${configVersion} is newer than this Trellis understands (${WORKSPACE_CONFIG_VERSION}) — upgrade Trellis`);
+        }
+        for (const key of Object.keys(extra)) {
+            diagnostics.push(`${CONFIG_SOURCE_LABEL}: unrecognized top-level key "${key}" — ignored`);
+        }
+        if (mcp !== undefined) {
+            if (typeof mcp !== "object" || mcp === null || typeof mcp.servers !== "object" || mcp.servers === null || Array.isArray(mcp.servers)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "mcp.servers" must be an object mapping server names to definitions`);
+            }
+            for (const [name, rawDef] of Object.entries(mcp.servers)) {
+                if (typeof rawDef !== "object" || rawDef === null) {
+                    throw new Error(`${CONFIG_SOURCE_LABEL}: "${name}" must be a server definition object or { "enabled": false }`);
+                }
+                if (isTombstone(rawDef)) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                // enabled:false WITH a transport is tombstone semantics too — it
+                // disables the same-ID global entry and renders nothing.
+                if (rawDef.enabled === false) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                layer.servers[name] = fromServerDefYaml(name, rawDef, CONFIG_SOURCE_LABEL);
+            }
+        }
+    }
+    const instructionsPath = join(layerRoot, "AGENTS.md");
+    if (existsSync(instructionsPath)) {
+        layer.instructionsFile = instructionsPath;
+    }
+    const skillsRoot = join(layerRoot, "skills");
+    let skillEntries = [];
+    try {
+        skillEntries = readdirSync(skillsRoot);
+    }
+    catch {
+        // no skills/ — optional, same as every other layer file
+    }
+    for (const name of skillEntries) {
+        const dir = join(skillsRoot, name);
+        try {
+            if (statSync(dir).isDirectory())
+                layer.skills.push({ name, dir });
+        }
+        catch {
+            // unreadable/broken entry — skip, not a load failure
+        }
+    }
+    assertWorkspaceSecretsClean(layer.servers, policy);
+    return layer;
+}
+/** An exact `${NAME}` value is a reference to the global secret store, not
+ * a literal — the only credential-shaped content allowed in a committable
+ * project layer (same classification as mcpMigrateRead.ts). */
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * Load-time secrets boundary for the project layer (workspace-scope spec
+ * "Secrets stay global-only"): scans the fields a pasted secret could
+ * reach — `env` entries, `staticEnv` values, `headers` values, and OAuth
+ * client metadata — and refuses the load, naming the server and field but
+ * never echoing the value.
+ */
+function assertWorkspaceSecretsClean(servers, policy) {
+    const check = (server, field, value) => {
+        if (value === undefined || VAR_REF_RE.test(value))
+            return;
+        for (const pattern of policy.rejectPatterns) {
+            if (pattern.test(value)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "${server}" ${field} matches a secrets.policy.yaml reject pattern — the project layer is committable and must carry only \${VAR} references; move the value to the global secret store (the offending value is intentionally not printed)`);
+            }
+        }
+    };
+    for (const [name, def] of Object.entries(servers)) {
+        for (const entry of def.env ?? [])
+            check(name, "env", entry);
+        for (const [key, value] of Object.entries(def.staticEnv ?? {}))
+            check(name, `static_env.${key}`, value);
+        for (const [key, value] of Object.entries(def.headers ?? {}))
+            check(name, `headers.${key}`, value);
+        const meta = oauthClientMetadata(def.auth);
+        check(name, "auth.client_id", meta.clientId);
+        check(name, "auth.client_secret_env", meta.clientSecretEnv);
+    }
+}

package/dist/lib/workspaceConfig.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting/removing a server in `.agents/config.json`
+ * (`mcp add --workspace` / `mcp remove --workspace`).
+ *
+ * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
+ * same file, same schema, one validator (via `toServerDefYaml`, so a
+ * `McpServerDef` serializes to the exact snake_case shape the loader
+ * validates back). Everything written here is committable by design:
+ * only `${VAR}` references ever land in `config.json`, never values
+ * (the loader refuses literals at read time; these helpers never
+ * resolve anything in the first place).
+ */
+import type { McpServerDef } from "../core/types.js";
+import { type McpServerDefYaml } from "../core/mcpServerDef.js";
+import type { BackupSession } from "./backup.js";
+export interface WorkspaceConfigJson {
+    version?: number;
+    mcp?: {
+        servers?: Record<string, McpServerDefYaml>;
+    };
+    [key: string]: unknown;
+}
+export declare function workspaceConfigPath(workspaceRoot: string): string;
+/** `{}` when the file doesn't exist yet (a workspace may carry only
+ * skills/AGENTS.md); a clear error naming the file when it exists but
+ * doesn't parse — never a raw JSON stack. */
+export declare function readWorkspaceConfigJson(workspaceRoot: string): WorkspaceConfigJson;
+export declare function writeWorkspaceConfigJson(workspaceRoot: string, config: WorkspaceConfigJson, backup?: BackupSession): void;
+/** Insert or replace `mcp.servers.<name>` with the def serialized through
+ * the shared YAML/JSON translator. `version` is filled in when absent —
+ * an existing file's version (and any unknown keys) is preserved. */
+export declare function upsertWorkspaceServer(workspaceRoot: string, name: string, def: McpServerDef, backup?: BackupSession): void;
+/** Delete `mcp.servers.<name>`, preserving every other key (unknown keys
+ * included, same posture as the upsert). Returns false — and writes
+ * nothing — when the entry isn't there. The follow-up `mcp sync` is what
+ * propagates the deletion to the rendered project-level files. */
+export declare function removeWorkspaceServer(workspaceRoot: string, name: string, backup?: BackupSession): boolean;
+export interface WorkspaceScaffoldFile {
+    path: string;
+    action: "create" | "already-present";
+}
+/** Exported for `migrate --workspace`: a `.agents/AGENTS.md` holding
+ * exactly this template is treated as still-empty scaffolding that an
+ * instructions import may replace, not as user content to conflict on. */
+export declare const WORKSPACE_AGENTS_MD_TEMPLATE = "# Project instructions\n\nShared instructions for every agent working in this repository. Trellis\ndelivers this file to agents that don't read `.agents/AGENTS.md`\nnatively (Codex/pi/Kimi do; Kiro gets a steering copy; Claude Code keeps\nits own CLAUDE.md).\n";
+/** Fill-missing-only scaffold of `.agents/`: never overwrites anything
+ * that already exists, so re-running is a no-op (idempotent by
+ * construction, same posture as global `trellis init`). */
+export declare function scaffoldWorkspace(workspaceRoot: string, write?: boolean): WorkspaceScaffoldFile[];

package/dist/lib/workspaceConfig.js

@@ -0,0 +1,117 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting/removing a server in `.agents/config.json`
+ * (`mcp add --workspace` / `mcp remove --workspace`).
+ *
+ * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
+ * same file, same schema, one validator (via `toServerDefYaml`, so a
+ * `McpServerDef` serializes to the exact snake_case shape the loader
+ * validates back). Everything written here is committable by design:
+ * only `${VAR}` references ever land in `config.json`, never values
+ * (the loader refuses literals at read time; these helpers never
+ * resolve anything in the first place).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { toServerDefYaml } from "../core/mcpServerDef.js";
+import { WORKSPACE_CONFIG_VERSION, WORKSPACE_DIR_NAME } from "./workspace.js";
+export function workspaceConfigPath(workspaceRoot) {
+    return join(workspaceRoot, WORKSPACE_DIR_NAME, "config.json");
+}
+/** `{}` when the file doesn't exist yet (a workspace may carry only
+ * skills/AGENTS.md); a clear error naming the file when it exists but
+ * doesn't parse — never a raw JSON stack. */
+export function readWorkspaceConfigJson(workspaceRoot) {
+    const path = workspaceConfigPath(workspaceRoot);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("top level must be an object");
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function writeWorkspaceConfigJson(workspaceRoot, config, backup) {
+    const path = workspaceConfigPath(workspaceRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const content = `${JSON.stringify(config, null, 2)}\n`;
+    if (backup) {
+        backup.writeFile(path, content);
+        return;
+    }
+    writeFileSync(path, content);
+}
+/** Insert or replace `mcp.servers.<name>` with the def serialized through
+ * the shared YAML/JSON translator. `version` is filled in when absent —
+ * an existing file's version (and any unknown keys) is preserved. */
+export function upsertWorkspaceServer(workspaceRoot, name, def, backup) {
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const servers = { ...(config.mcp?.servers ?? {}), [name]: toServerDefYaml(def) };
+    const next = {
+        ...config,
+        version: config.version ?? WORKSPACE_CONFIG_VERSION,
+        mcp: { ...(config.mcp ?? {}), servers },
+    };
+    writeWorkspaceConfigJson(workspaceRoot, next, backup);
+}
+/** Delete `mcp.servers.<name>`, preserving every other key (unknown keys
+ * included, same posture as the upsert). Returns false — and writes
+ * nothing — when the entry isn't there. The follow-up `mcp sync` is what
+ * propagates the deletion to the rendered project-level files. */
+export function removeWorkspaceServer(workspaceRoot, name, backup) {
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const servers = config.mcp?.servers;
+    if (!servers || !(name in servers))
+        return false;
+    const nextServers = { ...servers };
+    delete nextServers[name];
+    const next = {
+        ...config,
+        mcp: { ...(config.mcp ?? {}), servers: nextServers },
+    };
+    writeWorkspaceConfigJson(workspaceRoot, next, backup);
+    return true;
+}
+/** Exported for `migrate --workspace`: a `.agents/AGENTS.md` holding
+ * exactly this template is treated as still-empty scaffolding that an
+ * instructions import may replace, not as user content to conflict on. */
+export const WORKSPACE_AGENTS_MD_TEMPLATE = `# Project instructions
+
+Shared instructions for every agent working in this repository. Trellis
+delivers this file to agents that don't read \`.agents/AGENTS.md\`
+natively (Codex/pi/Kimi do; Kiro gets a steering copy; Claude Code keeps
+its own CLAUDE.md).
+`;
+/** Fill-missing-only scaffold of `.agents/`: never overwrites anything
+ * that already exists, so re-running is a no-op (idempotent by
+ * construction, same posture as global `trellis init`). */
+export function scaffoldWorkspace(workspaceRoot, write = true) {
+    const agentsDir = join(workspaceRoot, WORKSPACE_DIR_NAME);
+    const configPath = workspaceConfigPath(workspaceRoot);
+    const skillsDir = join(agentsDir, "skills");
+    const agentsMdPath = join(agentsDir, "AGENTS.md");
+    if (write) {
+        mkdirSync(agentsDir, { recursive: true });
+        mkdirSync(skillsDir, { recursive: true });
+    }
+    const files = [];
+    files.push(existsSync(configPath)
+        ? { path: configPath, action: "already-present" }
+        : { path: configPath, action: "create" });
+    if (!existsSync(configPath) && write) {
+        writeFileSync(configPath, `${JSON.stringify({ version: WORKSPACE_CONFIG_VERSION, mcp: { servers: {} } }, null, 2)}\n`);
+    }
+    files.push(existsSync(agentsMdPath)
+        ? { path: agentsMdPath, action: "already-present" }
+        : { path: agentsMdPath, action: "create" });
+    if (!existsSync(agentsMdPath) && write) {
+        writeFileSync(agentsMdPath, WORKSPACE_AGENTS_MD_TEMPLATE);
+    }
+    return files;
+}

package/dist/lib/workspaceDoctor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Workspace attribution for `trellis doctor` (trellis-workspace-scope
+ * task 3.5): given the workspace-merged canonical source, reports which
+ * layer each MCP server / skill comes from, what the workspace shadowed
+ * or tombstoned, which `${VAR}` references in workspace server defs
+ * don't resolve under the current secrets policy, which project-level
+ * native config files hold entries Trellis never rendered (the
+ * `migrate --workspace` hint), and zcode's reverse-precedence deviation
+ * (task 2.5's doctor half). Read-only by construction — it computes
+ * from the already-loaded canonical source and file reads only.
+ */
+import type { AgentId, CanonicalSource, LayerProvenance } from "../core/types.js";
+export interface WorkspaceLayerEntry {
+    name: string;
+    layer: LayerProvenance;
+}
+export interface WorkspaceUnmigratedHint {
+    agent: AgentId;
+    path: string;
+    /** Entry names present in the file with no Trellis manifest record. */
+    entries: string[];
+}
+export interface WorkspaceDoctorSection {
+    root: string;
+    mcp: WorkspaceLayerEntry[];
+    skills: WorkspaceLayerEntry[];
+    /** `mcp:name` / `skill:name` entries the workspace layer overrode. */
+    shadowed: string[];
+    /** `mcp:name` entries the workspace layer tombstoned (global entry
+     * disabled for this project). Subset of `shadowed`. */
+    tombstoned: string[];
+    /** `${VAR}` references in workspace server defs that resolve to
+     * nothing under the current secrets policy. Names only — never
+     * values. */
+    unresolvedVars: {
+        server: string;
+        field: string;
+        name: string;
+    }[];
+    unmigrated: WorkspaceUnmigratedHint[];
+    /** zcode's user-level-first deviation notices (empty otherwise). */
+    precedenceWarnings: string[];
+}
+export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): WorkspaceDoctorSection | undefined;

package/dist/lib/workspaceDoctor.js

@@ -0,0 +1,94 @@
+/**
+ * Workspace attribution for `trellis doctor` (trellis-workspace-scope
+ * task 3.5): given the workspace-merged canonical source, reports which
+ * layer each MCP server / skill comes from, what the workspace shadowed
+ * or tombstoned, which `${VAR}` references in workspace server defs
+ * don't resolve under the current secrets policy, which project-level
+ * native config files hold entries Trellis never rendered (the
+ * `migrate --workspace` hint), and zcode's reverse-precedence deviation
+ * (task 2.5's doctor half). Read-only by construction — it computes
+ * from the already-loaded canonical source and file reads only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolveSecretEnv } from "./secretEnv.js";
+import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+function collectVarRefs(canonical) {
+    const provenance = canonical.workspace?.mcpProvenance ?? {};
+    const refs = [];
+    for (const [name, def] of Object.entries(canonical.mcp.servers)) {
+        if (provenance[name] !== "workspace")
+            continue;
+        for (const envName of def.env ?? []) {
+            refs.push({ server: name, field: "env", name: envName });
+        }
+        for (const [key, value] of Object.entries(def.staticEnv ?? {})) {
+            const match = VAR_REF_RE.exec(value);
+            if (match)
+                refs.push({ server: name, field: `static_env.${key}`, name: match[1] });
+        }
+        for (const [key, value] of Object.entries(def.headers ?? {})) {
+            const match = VAR_REF_RE.exec(value);
+            if (match)
+                refs.push({ server: name, field: `headers.${key}`, name: match[1] });
+        }
+    }
+    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. */
+function unmarkedEntries(agentId, configPath, recorded) {
+    if (!existsSync(configPath))
+        return [];
+    let names = [];
+    if (agentId === "codex") {
+        const content = readFileSync(configPath, "utf-8");
+        const re = /^\[mcp_servers\.([^\]]+)\]\s*$/gm;
+        let match;
+        while ((match = re.exec(content)) !== null)
+            names.push(match[1]);
+    }
+    else {
+        try {
+            const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+            const servers = agentId === "zcode"
+                ? (parsed.mcp?.servers ?? {})
+                : (parsed.mcpServers ?? {});
+            names = Object.keys(servers);
+        }
+        catch {
+            return []; // unparsable file is the sync guard's finding, not doctor's
+        }
+    }
+    return names.filter((name) => recorded[name] === undefined);
+}
+export function collectWorkspaceDoctorSection(canonical) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return undefined;
+    const mcp = Object.keys(canonical.mcp.servers)
+        .map((name) => ({ name, layer: workspace.mcpProvenance[name] ?? "global" }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const skills = canonical.skills
+        .map((s) => ({ name: s.name, layer: workspace.skillProvenance[s.name] ?? "global" }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    // A shadowed mcp entry that no longer exists in the merged source was
+    // tombstoned; one still present (with workspace provenance) was
+    // overridden.
+    const tombstoned = workspace.shadowed.filter((entry) => entry.startsWith("mcp:") && canonical.mcp.servers[entry.slice(4)] === undefined);
+    const refs = collectVarRefs(canonical);
+    const resolved = resolveSecretEnv([...new Set(refs.map((r) => r.name))], canonical.secretsPolicy);
+    const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
+    const manifest = loadWorkspaceRendered(workspace.root);
+    const unmigrated = [];
+    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 precedenceWarnings = canonical.managedAgents.flatMap((id) => workspacePrecedenceWarnings(id, canonical));
+    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, precedenceWarnings };
+}