agent-trellis 0.14.0 → 0.15.0

package/dist/lib/workspaceFiles.js

@@ -0,0 +1,264 @@
+/**
+ * Workspace (project-level) skills & instructions delivery
+ * (trellis-workspace-scope design D4/D5). Unlike global delivery (symlinks
+ * into `~/.trellis/`), workspace skills are COPIED into the agent's
+ * project-level directory — rendered artifacts must be committable to the
+ * repo and usable on filesystems without symlink support.
+ *
+ * A copy has no symlink-realpath ownership proof, so ownership mirrors the
+ * MCP ledger instead: one `.trellis-workspace.json` per destination root
+ * maps skill name → { source, sourceDigest, destDigest }. A delivered
+ * directory is "ours" only while its current digest still equals the
+ * recorded `destDigest`; a hand-edited copy is a conflict, never touched —
+ * the same posture mcpOwnership gives bare JSON/TOML keys.
+ *
+ * Instructions are delivered as marker-headed file copies: root `AGENTS.md`
+ * (read natively by Codex, pi, and Kimi Code) and Kiro's
+ * `.kiro/steering/trellis-workspace.md`. Claude Code reads `CLAUDE.md`, not
+ * `AGENTS.md`, and a repo's `CLAUDE.md` is almost always user-authored —
+ * v1 deliberately writes no Claude instructions file (documented
+ * limitation; `migrate --workspace` is the path for absorbing one).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isInScope } from "../core/adapter.js";
+import { directoryDigest } from "./dirDigest.js";
+const COPY_LEDGER_NAME = ".trellis-workspace.json";
+/** Exported for `migrate --workspace` (trellis-workspace-scope task 4.x):
+ * absorbing a root `AGENTS.md` rewrites it marker-headed in place, which
+ * must be byte-identical to what a later sync would render. */
+export const INSTRUCTIONS_MARKER = "<!-- generated by trellis from .agents/AGENTS.md — do not edit; run `trellis sync` to refresh -->";
+/** Agents that read `.agents/skills/` natively get no copy at all — the
+ * canonical directory is itself the deliverable. zcode's Runtime-only
+ * delivery owns its skills through the Runtime provider (task 2.2). */
+const COPY_TARGETS = {
+    "claude-code": join(".claude", "skills"),
+    kiro: join(".kiro", "skills"),
+};
+function instructionsTargets(agentId) {
+    switch (agentId) {
+        case "codex":
+        case "pi":
+        case "kimi-code":
+            return [{ relPath: "AGENTS.md", forAgents: "Codex/pi/Kimi Code" }];
+        case "kiro":
+            return [{ relPath: join(".kiro", "steering", "trellis-workspace.md"), forAgents: "Kiro" }];
+        default:
+            return [];
+    }
+}
+function loadCopyLedger(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {}; // corrupt ledger — treat as "nothing recorded", never crash a sync
+    }
+}
+function planWorkspaceSkillCopies(agentId, canonical) {
+    const workspace = canonical.workspace;
+    const relRoot = COPY_TARGETS[agentId];
+    if (!workspace || !relRoot)
+        return [];
+    const destRoot = join(workspace.root, relRoot);
+    const ledgerPath = join(destRoot, COPY_LEDGER_NAME);
+    const ledger = loadCopyLedger(ledgerPath);
+    const items = [];
+    const desired = canonical.skills.filter((skill) => workspace.skillProvenance[skill.name] === "workspace" && isInScope(agentId, skill.scope, canonical.managedAgents));
+    const desiredNames = new Set(desired.map((s) => s.name));
+    for (const skill of desired) {
+        const dest = join(destRoot, skill.name);
+        if (!existsSync(dest)) {
+            items.push({
+                action: "create",
+                kind: "skill",
+                layer: "workspace",
+                target: dest,
+                copyFrom: skill.dir,
+                description: `workspace skill "${skill.name}" copied to ${dest}`,
+            });
+            continue;
+        }
+        const recorded = ledger[skill.name];
+        if (!recorded) {
+            items.push({
+                action: "conflict",
+                kind: "skill",
+                layer: "workspace",
+                target: dest,
+                description: `${dest} exists and is not a Trellis-managed workspace copy — left untouched`,
+                remediation: `run \`trellis migrate --workspace\` to absorb it into .agents/, or remove it and re-run sync`,
+            });
+            continue;
+        }
+        if (directoryDigest(dest) !== recorded.destDigest) {
+            items.push({
+                action: "conflict",
+                kind: "skill",
+                layer: "workspace",
+                target: dest,
+                description: `${dest} was hand-edited since Trellis wrote it — left untouched`,
+                remediation: `merge your edits into .agents/skills/${skill.name}/ (the canonical copy), then remove ${dest} and re-run sync — Trellis will not overwrite hand edits`,
+            });
+            continue;
+        }
+        if (directoryDigest(skill.dir) === recorded.sourceDigest) {
+            continue; // fresh — no-op
+        }
+        items.push({
+            action: "create",
+            kind: "skill",
+            layer: "workspace",
+            target: dest,
+            copyFrom: skill.dir,
+            description: `workspace skill "${skill.name}" re-copied to ${dest} (source changed)`,
+        });
+    }
+    for (const name of Object.keys(ledger)) {
+        if (desiredNames.has(name))
+            continue;
+        const dest = join(destRoot, name);
+        if (!existsSync(dest)) {
+            // Stale ledger entry only — rewrite the ledger (no dir to remove).
+            items.push({
+                action: "remove",
+                kind: "skill",
+                layer: "workspace",
+                target: dest,
+                description: `stale workspace-copy ledger entry "${name}" pruned from ${ledgerPath}`,
+            });
+            continue;
+        }
+        if (directoryDigest(dest) !== ledger[name].destDigest) {
+            continue; // hand-edited since we wrote it — no longer ours to remove
+        }
+        items.push({
+            action: "remove",
+            kind: "skill",
+            layer: "workspace",
+            target: dest,
+            description: `workspace skill "${name}" removed from ${dest} — no longer in .agents/skills/`,
+        });
+    }
+    return items;
+}
+function planWorkspaceInstructions(agentId, canonical) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return [];
+    const items = [];
+    for (const target of instructionsTargets(agentId)) {
+        const path = join(workspace.root, target.relPath);
+        const rendered = workspace.instructionsFile
+            ? `${INSTRUCTIONS_MARKER}\n\n${readFileSync(workspace.instructionsFile, "utf-8")}`
+            : undefined;
+        if (rendered === undefined) {
+            // Workspace no longer declares instructions — remove the delivered
+            // file only while it's still byte-exactly a marker-headed one.
+            if (!existsSync(path))
+                continue;
+            const current = readFileSync(path, "utf-8");
+            if (!current.startsWith(INSTRUCTIONS_MARKER))
+                continue; // user's file — never ours
+            items.push({
+                action: "remove",
+                kind: "instructions",
+                layer: "workspace",
+                target: path,
+                description: `${path} removed — .agents/AGENTS.md no longer exists`,
+            });
+            continue;
+        }
+        if (!existsSync(path)) {
+            items.push({
+                action: "create",
+                kind: "instructions",
+                layer: "workspace",
+                target: path,
+                fileContent: rendered,
+                description: `workspace instructions written to ${path} (${target.forAgents})`,
+            });
+            continue;
+        }
+        const current = readFileSync(path, "utf-8");
+        if (current === rendered)
+            continue;
+        if (!current.startsWith(INSTRUCTIONS_MARKER)) {
+            items.push({
+                action: "conflict",
+                kind: "instructions",
+                layer: "workspace",
+                target: path,
+                description: `${path} exists and is not Trellis-generated — left untouched`,
+                remediation: `merge its content into .agents/AGENTS.md (e.g. via \`trellis migrate --workspace\`) and remove the file, then re-run sync`,
+            });
+            continue;
+        }
+        items.push({
+            action: "create",
+            kind: "instructions",
+            layer: "workspace",
+            target: path,
+            fileContent: rendered,
+            description: `workspace instructions updated in ${path} (source changed)`,
+        });
+    }
+    return items;
+}
+export function planWorkspaceFiles(agentId, canonical) {
+    return [...planWorkspaceSkillCopies(agentId, canonical), ...planWorkspaceInstructions(agentId, canonical)];
+}
+/** Executes a `planWorkspaceFiles` result through the run's backup session
+ * and rewrites the copy ledger for every destination root it touched. */
+export function applyWorkspaceFiles(agentId, canonical, items, backup) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return;
+    for (const item of items) {
+        if (item.layer !== "workspace" || item.action === "conflict")
+            continue;
+        if (item.kind === "instructions") {
+            if (item.action === "create" && item.fileContent !== undefined) {
+                // Kiro's steering dir (and any future nested target) may not exist
+                // yet in a fresh project — create it before the atomic write.
+                mkdirSync(dirname(item.target), { recursive: true });
+                backup.writeFile(item.target, item.fileContent);
+            }
+            else if (item.action === "remove") {
+                // removeDir's snapshot+remove works for single files too (cpSync /
+                // rmSync both accept file paths) — rollback restores the file.
+                backup.removeDir(item.target);
+            }
+            continue;
+        }
+        if (item.kind === "skill") {
+            const destRoot = dirname(item.target);
+            const ledgerPath = join(destRoot, COPY_LEDGER_NAME);
+            let ledger = loadCopyLedger(ledgerPath);
+            const name = item.target.slice(destRoot.length + 1);
+            if (item.action === "create" && item.copyFrom) {
+                if (existsSync(item.target)) {
+                    backup.replaceDirFromSource(item.target, item.copyFrom);
+                }
+                else {
+                    backup.createDirFromSource(item.target, item.copyFrom);
+                }
+                ledger = {
+                    ...ledger,
+                    [name]: { source: item.copyFrom, sourceDigest: directoryDigest(item.copyFrom), destDigest: directoryDigest(item.target) },
+                };
+            }
+            else if (item.action === "remove") {
+                if (existsSync(item.target)) {
+                    backup.removeDir(item.target);
+                }
+                const next = { ...ledger };
+                delete next[name];
+                ledger = next;
+            }
+            backup.writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`);
+        }
+    }
+}

package/dist/lib/workspaceMcp.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace (project-level) MCP delivery (trellis-workspace-scope design
+ * D4/D6/D7): renders the workspace layer's servers into each managed
+ * agent's project-level native config, as direct entries only — never
+ * through the gateway, hub, or Runtime. Reuses each format's existing
+ * machinery (`jsonMcp.ts` for the JSON agents, `tomlSection.ts` for Codex,
+ * zcode.ts's nested `mcp.servers` shape).
+ *
+ * Ownership lives IN the workspace, not the global ledger: `.agents/
+ * .trellis-rendered.json` records exactly what Trellis rendered per agent
+ * per server. It's committable on purpose (rendered entries carry only
+ * `${VAR}` references, never values) — that's what lets a fresh clone
+ * re-attach cleanly: the committed manifest proves the committed
+ * `.mcp.json` was Trellis-rendered even though this machine's global
+ * ledger has never seen it. An entry that exists in the native file but
+ * not in the manifest is user-authored and never overwritten.
+ *
+ * Routing note: the workspace-only `McpConfig` handed to `resolveMcpPlan`
+ * carries no `hub`/`gateway`/`routes`/`runtime`, so it always takes the
+ * direct branch — where a Trellis-owned OAuth server already conflicts out
+ * with "requires gateway or runtime delivery", which is exactly the
+ * workspace rule (workspace servers are agent-owned, always).
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId, CanonicalSource, McpServerDef } from "../core/types.js";
+import type { BackupSession } from "./backup.js";
+/** `.agents/.trellis-rendered.json` — the in-repo ownership manifest. */
+export declare const WORKSPACE_RENDERED_MANIFEST = ".trellis-rendered.json";
+export interface WorkspaceRenderedManifest {
+    mcp?: Partial<Record<AgentId, Record<string, unknown>>>;
+}
+export declare function loadWorkspaceRendered(workspaceRoot: string): WorkspaceRenderedManifest;
+/** The project-level config file each agent reads. zcode's is selected by
+ * presence (existing `zcode.json` beats `.zcode/config.json`), defaulting
+ * to creating `zcode.json` at the root. */
+export declare function workspaceMcpConfigPath(agentId: AgentId, workspaceRoot: string): string;
+/** zcode is the one agent whose USER-level config wins on same-name
+ * conflicts (research, 2026-10-11), so workspace-wins silently misfires
+ * there — surface it instead of implying the override worked. */
+export declare function workspacePrecedenceWarnings(agentId: AgentId, canonical: CanonicalSource): string[];
+/**
+ * The rendered form `applyWorkspaceMcp` records in the manifest for one
+ * agent — exported so `migrate --workspace` can pre-seed ownership for an
+ * entry it is adopting out of a user-authored project file: the cascade
+ * render then owns the entry (updating it to Trellis's canonical render)
+ * instead of conflict-guarding on it as user-authored content
+ * (trellis-workspace-scope task 4.6).
+ */
+export declare function renderWorkspaceManifestEntry(agentId: AgentId, name: string, def: McpServerDef): unknown;
+/** Records one ownership entry in `.agents/.trellis-rendered.json`
+ * through the run's backup session — migrate --workspace's adopt step.
+ * Delivery itself keeps writing the manifest wholesale in
+ * `applyWorkspaceMcp`; this exists only for adoption, where no delivery
+ * write to that agent's file has happened yet. */
+export declare function recordWorkspaceRendered(workspaceRoot: string, agentId: AgentId, name: string, rendered: unknown, backup: BackupSession): void;
+export declare function planWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource): AdapterPlanItem[];
+export declare function applyWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource, items: AdapterPlanItem[], backup: BackupSession): void;

package/dist/lib/workspaceMcp.js

@@ -0,0 +1,277 @@
+/**
+ * Workspace (project-level) MCP delivery (trellis-workspace-scope design
+ * D4/D6/D7): renders the workspace layer's servers into each managed
+ * agent's project-level native config, as direct entries only — never
+ * through the gateway, hub, or Runtime. Reuses each format's existing
+ * machinery (`jsonMcp.ts` for the JSON agents, `tomlSection.ts` for Codex,
+ * zcode.ts's nested `mcp.servers` shape).
+ *
+ * Ownership lives IN the workspace, not the global ledger: `.agents/
+ * .trellis-rendered.json` records exactly what Trellis rendered per agent
+ * per server. It's committable on purpose (rendered entries carry only
+ * `${VAR}` references, never values) — that's what lets a fresh clone
+ * re-attach cleanly: the committed manifest proves the committed
+ * `.mcp.json` was Trellis-rendered even though this machine's global
+ * ledger has never seen it. An entry that exists in the native file but
+ * not in the manifest is user-authored and never overwritten.
+ *
+ * Routing note: the workspace-only `McpConfig` handed to `resolveMcpPlan`
+ * carries no `hub`/`gateway`/`routes`/`runtime`, so it always takes the
+ * direct branch — where a Trellis-owned OAuth server already conflicts out
+ * with "requires gateway or runtime delivery", which is exactly the
+ * workspace rule (workspace servers are agent-owned, always).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { applyJsonMcp, planJsonMcp, renderJsonServerEntry } from "../adapters/jsonMcp.js";
+import { resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { piRenderer } from "../adapters/piMcp.js";
+import { applyZcodeMcp, planZcodeMcp } from "../adapters/zcode.js";
+import { currentServerSectionText, removeSection, renderServerSection, upsertSection } from "./tomlSection.js";
+/** `.agents/.trellis-rendered.json` — the in-repo ownership manifest. */
+export const WORKSPACE_RENDERED_MANIFEST = ".trellis-rendered.json";
+function manifestPath(workspaceRoot) {
+    return join(workspaceRoot, ".agents", WORKSPACE_RENDERED_MANIFEST);
+}
+export function loadWorkspaceRendered(workspaceRoot) {
+    const path = manifestPath(workspaceRoot);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {}; // corrupt manifest — treat as "nothing recorded", never crash a sync
+    }
+}
+/** The project-level config file each agent reads. zcode's is selected by
+ * presence (existing `zcode.json` beats `.zcode/config.json`), defaulting
+ * to creating `zcode.json` at the root. */
+export function workspaceMcpConfigPath(agentId, workspaceRoot) {
+    switch (agentId) {
+        case "claude-code":
+            return join(workspaceRoot, ".mcp.json");
+        case "codex":
+            return join(workspaceRoot, ".codex", "config.toml");
+        case "kiro":
+            return join(workspaceRoot, ".kiro", "settings", "mcp.json");
+        case "pi":
+            return join(workspaceRoot, ".pi", "mcp.json");
+        case "kimi-code":
+            return join(workspaceRoot, ".kimi-code", "mcp.json");
+        case "zcode": {
+            const flat = join(workspaceRoot, "zcode.json");
+            if (existsSync(flat))
+                return flat;
+            const nested = join(workspaceRoot, ".zcode", "config.json");
+            if (existsSync(nested))
+                return nested;
+            return flat;
+        }
+    }
+}
+/** The workspace-only view of canonical MCP: servers whose provenance is
+ * the workspace layer, no routing config — direct delivery, always. */
+function workspaceMcpConfig(canonical) {
+    const provenance = canonical.workspace?.mcpProvenance ?? {};
+    const servers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([name]) => provenance[name] === "workspace"));
+    return { servers, knownHostInjected: canonical.mcp.knownHostInjected };
+}
+/** zcode is the one agent whose USER-level config wins on same-name
+ * conflicts (research, 2026-10-11), so workspace-wins silently misfires
+ * there — surface it instead of implying the override worked. */
+export function workspacePrecedenceWarnings(agentId, canonical) {
+    if (agentId !== "zcode" || !canonical.workspace)
+        return [];
+    return canonical.workspace.shadowed
+        .filter((entry) => entry.startsWith("mcp:"))
+        .map((entry) => entry.slice(4))
+        .filter((name) => canonical.workspace?.mcpProvenance[name] === "workspace")
+        .map((name) => `zcode: workspace server "${name}" shadows a global entry, but zcode resolves same-name conflicts user-level-first — the global entry is what zcode will actually use`);
+}
+/**
+ * The unmarked-overwrite guard every workspace planner applies: an entry
+ * that exists in the agent's file but not in the in-repo manifest is
+ * user-authored — report it, never overwrite (the workspace equivalent of
+ * symlinkPlan's foreign-content refusal).
+ */
+function guardUnmarkedOverwrite(items, existingName) {
+    return items.map((item) => {
+        if (item.action !== "create" || !item.mcpWrite)
+            return item;
+        if (!existingName(item))
+            return item;
+        return {
+            action: "conflict",
+            kind: "mcp",
+            layer: "workspace",
+            target: item.target,
+            description: `${item.target} already defines "${item.mcpWrite.name}" and Trellis has no record of writing it — left untouched`,
+            remediation: `run \`trellis migrate --workspace\` to absorb the existing entry into .agents/, or remove it from the file and re-run sync`,
+        };
+    });
+}
+/**
+ * The rendered form `applyWorkspaceMcp` records in the manifest for one
+ * agent — exported so `migrate --workspace` can pre-seed ownership for an
+ * entry it is adopting out of a user-authored project file: the cascade
+ * render then owns the entry (updating it to Trellis's canonical render)
+ * instead of conflict-guarding on it as user-authored content
+ * (trellis-workspace-scope task 4.6).
+ */
+export function renderWorkspaceManifestEntry(agentId, name, def) {
+    if (agentId === "codex")
+        return renderServerSection(name, def);
+    if (agentId === "pi")
+        return piRenderer(def, name);
+    return renderJsonServerEntry(def);
+}
+/** Records one ownership entry in `.agents/.trellis-rendered.json`
+ * through the run's backup session — migrate --workspace's adopt step.
+ * Delivery itself keeps writing the manifest wholesale in
+ * `applyWorkspaceMcp`; this exists only for adoption, where no delivery
+ * write to that agent's file has happened yet. */
+export function recordWorkspaceRendered(workspaceRoot, agentId, name, rendered, backup) {
+    const manifest = loadWorkspaceRendered(workspaceRoot);
+    const agentEntries = { ...(manifest.mcp?.[agentId] ?? {}) };
+    agentEntries[name] = rendered;
+    const next = { ...manifest, mcp: { ...(manifest.mcp ?? {}), [agentId]: agentEntries } };
+    const path = manifestPath(workspaceRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    backup.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+}
+export function planWorkspaceMcp(agentId, canonical) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return [];
+    const configPath = workspaceMcpConfigPath(agentId, workspace.root);
+    const mcp = workspaceMcpConfig(canonical);
+    const manifest = loadWorkspaceRendered(workspace.root);
+    const ownership = manifest.mcp?.[agentId] ?? {};
+    const layer = (item) => ({ ...item, layer: "workspace" });
+    if (agentId === "codex") {
+        const content = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+        const { desired, conflicts } = resolveMcpPlan(agentId, mcp, canonical.managedAgents, canonical.secretsPolicy);
+        const items = [];
+        for (const { name, def } of desired) {
+            const current = currentServerSectionText(content, name);
+            const rendered = renderServerSection(name, def);
+            if (current === rendered)
+                continue;
+            items.push({
+                action: "create",
+                kind: "mcp",
+                layer: "workspace",
+                target: configPath,
+                mcpWrite: { name, def },
+                description: `MCP server "${name}" ${current === null ? "created" : "updated"} in ${configPath} (workspace)`,
+            });
+        }
+        for (const conflict of conflicts) {
+            items.push({ action: "conflict", kind: "mcp", layer: "workspace", target: configPath, description: conflict.message, ...(conflict.remediation ? { remediation: conflict.remediation } : {}) });
+        }
+        const desiredNames = new Set(desired.map((d) => d.name));
+        for (const [name, expected] of Object.entries(ownership)) {
+            if (desiredNames.has(name))
+                continue;
+            const current = currentServerSectionText(content, name);
+            if (current === null || current !== expected)
+                continue;
+            items.push({ action: "remove", kind: "mcp", layer: "workspace", target: configPath, mcpRemove: { name }, description: `MCP server "${name}" removed from ${configPath} — no longer in workspace canonical` });
+        }
+        return guardUnmarkedOverwrite(items, (item) => currentServerSectionText(content, item.mcpWrite.name) !== null && ownership[item.mcpWrite.name] === undefined);
+    }
+    if (agentId === "zcode") {
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const items = planZcodeMcp({ configPath, parsed, mcp, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership }).map(layer);
+        const servers = (parsed?.mcp?.servers ?? {});
+        return guardUnmarkedOverwrite(items, (item) => servers[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
+    }
+    const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+    const render = agentId === "pi" ? piRenderer : undefined;
+    const planned = planJsonMcp({
+        configPath,
+        parsed,
+        mcp,
+        agentId,
+        managedAgents: canonical.managedAgents,
+        policy: canonical.secretsPolicy,
+        ownership,
+        ...(render ? { render } : {}),
+    }).map(layer);
+    const existing = (parsed?.mcpServers ?? {});
+    const guarded = guardUnmarkedOverwrite(planned, (item) => existing[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
+    if (agentId !== "pi")
+        return guarded;
+    // pi speaks stdio and streamable HTTP only — an sse server gets an
+    // honest conflict instead of an entry pi could never connect (same
+    // mapping as the global path in adapters/pi.ts).
+    return guarded.map((item) => {
+        const write = item.mcpWrite;
+        if (write?.def.transport !== "sse")
+            return item;
+        return {
+            action: "conflict",
+            kind: "mcp",
+            layer: "workspace",
+            target: item.target,
+            description: `refusing to write MCP server "${write.name}" for pi: sse is not a pi transport`,
+            remediation: `use transport "http" for streamable HTTP, or keep this server global-only where gateway mode can terminate sse`,
+        };
+    });
+}
+export function applyWorkspaceMcp(agentId, canonical, items, backup) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return;
+    const writes = items.filter((item) => item.kind === "mcp" && item.layer === "workspace" && (item.action === "create" || item.action === "remove"));
+    if (writes.length === 0)
+        return;
+    const configPath = workspaceMcpConfigPath(agentId, workspace.root);
+    let manifest = loadWorkspaceRendered(workspace.root);
+    const agentEntries = { ...(manifest.mcp?.[agentId] ?? {}) };
+    if (agentId === "codex") {
+        let content = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+        for (const item of writes) {
+            if (item.action === "create" && item.mcpWrite) {
+                content = upsertSection(content, item.mcpWrite.name, item.mcpWrite.def);
+                agentEntries[item.mcpWrite.name] = renderServerSection(item.mcpWrite.name, item.mcpWrite.def);
+            }
+            else if (item.action === "remove" && item.mcpRemove) {
+                content = removeSection(content, item.mcpRemove.name);
+                delete agentEntries[item.mcpRemove.name];
+            }
+        }
+        mkdirSync(dirname(configPath), { recursive: true });
+        backup.writeFile(configPath, content);
+    }
+    else if (agentId === "zcode") {
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const merged = applyZcodeMcp(parsed, writes);
+        mkdirSync(dirname(configPath), { recursive: true });
+        backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        for (const item of writes) {
+            if (item.action === "create" && item.mcpWrite)
+                agentEntries[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
+            if (item.action === "remove" && item.mcpRemove)
+                delete agentEntries[item.mcpRemove.name];
+        }
+    }
+    else {
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const render = agentId === "pi" ? piRenderer : (def, _name) => renderJsonServerEntry(def);
+        const merged = applyJsonMcp(parsed, writes, render);
+        mkdirSync(dirname(configPath), { recursive: true });
+        backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        for (const item of writes) {
+            if (item.action === "create" && item.mcpWrite)
+                agentEntries[item.mcpWrite.name] = render(item.mcpWrite.def, item.mcpWrite.name);
+            if (item.action === "remove" && item.mcpRemove)
+                delete agentEntries[item.mcpRemove.name];
+        }
+    }
+    manifest = { ...manifest, mcp: { ...(manifest.mcp ?? {}), [agentId]: agentEntries } };
+    const path = manifestPath(workspace.root);
+    mkdirSync(dirname(path), { recursive: true });
+    backup.writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/dist/lib/workspaceMerge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Merges a workspace `.agents/` layer over the global `CanonicalSource`
+ * (trellis-workspace-scope design D3): workspace wins by ID for MCP
+ * servers and skills, `enabled: false` tombstones disable a same-ID global
+ * entry, instructions are NOT content-merged (each layer is delivered to
+ * its own level's paths; agents layer them natively). The result carries
+ * per-entry provenance plus the shadowed/tombstoned list for doctor and
+ * status attribution.
+ */
+import type { CanonicalSource, McpConfig, SkillRef } from "../core/types.js";
+import type { WorkspaceLayer } from "./workspace.js";
+/**
+ * The global layer's view of MCP config: exactly the servers the global
+ * (`~/.trellis`) layer declares, with their global definitions. Global
+ * (user-level) delivery MUST render from this view, never from the merged
+ * `canonical.mcp` — otherwise workspace servers leak into user-level files
+ * (the bug the workspace e2e caught: repo `.agents/` servers written into
+ * `~/.codex/config.toml`, `~/.pi/agent/mcp.json`, `~/.claude.json`).
+ * Tombstoned servers stay: a tombstone only removes the server from this
+ * workspace's effective view, and the shared user-level files serve every
+ * other context. Without a workspace layer this is `source.mcp` unchanged.
+ */
+export declare function globalLayerMcp(source: CanonicalSource): McpConfig;
+/**
+ * The global layer's view of skills: exactly the skills the global
+ * (`~/.trellis`) layer declares, with their global definitions. Global
+ * (user-level) skill delivery MUST symlink from this view, never from the
+ * merged `canonical.skills` — otherwise workspace skills leak into
+ * user-level dirs as symlinks pointing into one repo's `.agents/skills/`,
+ * which breaks the moment the repo is cloned elsewhere (the clone's
+ * `sync --check` then conflicts on the stale cross-repo link — found by
+ * the closed-loop e2e). Entries the workspace shadows keep their global
+ * definitions here, mirroring `globalLayerMcp`. Without a workspace layer
+ * this is `source.skills` unchanged.
+ */
+export declare function globalLayerSkills(source: CanonicalSource): SkillRef[];
+export declare function mergeWorkspaceLayer(base: CanonicalSource, layer: WorkspaceLayer): CanonicalSource;