agent-trellis 0.14.1 → 0.15.0

package/dist/lib/workspaceConfig.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting a server into `.agents/config.json` (`mcp add --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;
+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,98 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting a server into `.agents/config.json` (`mcp add --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);
+}
+/** 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 };
+}

package/dist/lib/workspaceFiles.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId, CanonicalSource } from "../core/types.js";
+import type { BackupSession } from "./backup.js";
+/** Per-destination-root ledger of Trellis-owned workspace copies. */
+export type WorkspaceCopyLedger = Record<string, {
+    source: string;
+    sourceDigest: string;
+    destDigest: string;
+}>;
+/** 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 declare const INSTRUCTIONS_MARKER = "<!-- generated by trellis from .agents/AGENTS.md \u2014 do not edit; run `trellis sync` to refresh -->";
+export declare function planWorkspaceFiles(agentId: AgentId, canonical: CanonicalSource): AdapterPlanItem[];
+/** Executes a `planWorkspaceFiles` result through the run's backup session
+ * and rewrites the copy ledger for every destination root it touched. */
+export declare function applyWorkspaceFiles(agentId: AgentId, canonical: CanonicalSource, items: AdapterPlanItem[], backup: BackupSession): void;

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;