agent-trellis 0.14.1 → 0.15.0

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;

package/dist/lib/workspaceMerge.js

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function globalLayerMcp(source) {
+    const info = source.workspace;
+    if (!info)
+        return source.mcp;
+    return { ...source.mcp, servers: info.mcpGlobalServers };
+}
+/**
+ * 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 function globalLayerSkills(source) {
+    return source.workspace?.globalSkills ?? source.skills;
+}
+export function mergeWorkspaceLayer(base, layer) {
+    const shadowed = [];
+    // Captured before any mutation: the global delivery path renders from
+    // this map (see globalLayerMcp), so workspace entries never reach
+    // user-level config files.
+    const mcpGlobalServers = { ...base.mcp.servers };
+    const servers = { ...base.mcp.servers };
+    const mcpProvenance = Object.fromEntries(Object.keys(base.mcp.servers).map((name) => [name, "global"]));
+    for (const name of layer.tombstones) {
+        if (servers[name] !== undefined) {
+            delete servers[name];
+            delete mcpProvenance[name];
+            shadowed.push(`mcp:${name}`);
+        }
+        else {
+            layer.diagnostics.push(`.agents/config.json: tombstone "${name}" matches no global server — no-op`);
+        }
+    }
+    for (const [name, def] of Object.entries(layer.servers)) {
+        if (servers[name] !== undefined)
+            shadowed.push(`mcp:${name}`);
+        servers[name] = def;
+        mcpProvenance[name] = "workspace";
+    }
+    const skills = [...base.skills];
+    // Captured before any mutation: the global delivery path symlinks from
+    // this list (see globalLayerSkills), so workspace skills never reach
+    // user-level skill dirs.
+    const globalSkills = [...base.skills];
+    const skillProvenance = Object.fromEntries(base.skills.map((s) => [s.name, "global"]));
+    for (const wsSkill of layer.skills) {
+        const idx = skills.findIndex((s) => s.name === wsSkill.name);
+        if (idx >= 0) {
+            shadowed.push(`skill:${wsSkill.name}`);
+            skills[idx] = wsSkill;
+        }
+        else {
+            skills.push(wsSkill);
+        }
+        skillProvenance[wsSkill.name] = "workspace";
+    }
+    return {
+        ...base,
+        skills,
+        mcp: { ...base.mcp, servers },
+        diagnostics: [...base.diagnostics, ...layer.diagnostics],
+        workspace: {
+            root: layer.root,
+            ...(layer.instructionsFile !== undefined ? { instructionsFile: layer.instructionsFile } : {}),
+            mcpProvenance,
+            mcpGlobalServers,
+            skillProvenance,
+            globalSkills,
+            shadowed,
+        },
+    };
+}

package/dist/lib/workspaceMigrate.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `trellis migrate --workspace`'s scanner + planner (trellis-workspace-
+ * scope tasks 4.1–4.5): inventories every managed agent's project-level
+ * MCP config plus the root `AGENTS.md`, classifies each finding, and
+ * produces a pure plan — no writes anywhere, so `--dry-run` prints the
+ * byte-identical plan a real run would execute.
+ *
+ * Classification (one `action` per item):
+ * - `already-managed`     — the in-repo manifest (`.agents/.trellis-
+ *                           rendered.json`) records Trellis having rendered
+ *                           this entry, or `.agents/` already holds it
+ * - `skip-local`          — a `*.local.*` sibling of a scanned config path;
+ *                           listed, never read (task 4.5)
+ * - `skip-unsupported`    — malformed entry (e.g. stdio without command)
+ * - `extract-secret`      — a reject-pattern literal in `staticEnv`: value
+ *                           goes to the global secret store, the committed
+ *                           `.agents/config.json` only ever gets `${VAR}`
+ * - `identical-to-global` — deep-equal to the global canonical entry;
+ *                           default drop, `--dedup override` imports it as
+ *                           an intentional shadow (task 4.4)
+ * - `conflict`            — same name with differing defs across agents
+ *                           (task 4.3, resolved only by `--choose
+ *                           name=agentId`), or a reject-pattern literal in
+ *                           a field other than `staticEnv` (unlike the
+ *                           global migrate, `.agents/config.json` is
+ *                           COMMITTED — a plaintext literal must never be
+ *                           written into it)
+ * - `create`              — will import into `.agents/`
+ *
+ * Secret handling invariant (task 4.2): no literal secret value ever rides
+ * on a plan item — extraction re-reads the source file at apply time,
+ * exactly like the global migrate's design.md D9.
+ */
+import type { AgentId, McpServerDef, SecretsPolicy } from "../core/types.js";
+import type { McpMigrateReadResult } from "./mcpMigrateRead.js";
+export type WorkspaceMigrateAction = "create" | "already-managed" | "skip-local" | "skip-unsupported" | "extract-secret" | "identical-to-global" | "conflict";
+export interface WorkspaceMigrateItem {
+    kind: "mcp" | "instructions";
+    name: string;
+    action: WorkspaceMigrateAction;
+    detail: string;
+    /** Only set (and only meaningful) on `conflict`: the concrete next
+     * action, matching the global migrate's convention. */
+    remediation?: string;
+    /** Agents whose project config this name was found in. */
+    sources: AgentId[];
+    /** Set from `--choose name=agentId` — which agent's def won a cross-
+     * agent conflict. */
+    chosenSource?: AgentId;
+    /** Side-by-side defs for a cross-agent conflict, keyed by agent. */
+    defs?: Partial<Record<AgentId, McpServerDef>>;
+    /** The def to import. On `extract-secret` this is already the SAFE
+     * form — the flagged staticEnv value replaced by a name-only `env`
+     * reference; the literal never appears on this object. */
+    mcpDef?: McpServerDef;
+    /** Instructions body to import (root AGENTS.md content). */
+    sourceContent?: string;
+    /** `extract-secret` only — see the global migrate's D9/D11: the
+     * synthesized variable name, the resolved secret-store path, the
+     * original staticEnv dict key, and which agent's file to re-read the
+     * real value from at apply time. Never the value itself. */
+    extractVarName?: string;
+    extractTargetPath?: string;
+    extractSourceKey?: string;
+    extractSourceAgent?: AgentId;
+    /** Task 4.2: the source file holding the literal is git-tracked, so the
+     * value must be considered compromised — rotate it. */
+    rotationAdvisory?: string;
+    /** Task 4.4: how an `identical-to-global` item was (or would be)
+     * handled — `drop` (default) or `override` (`--dedup override`). */
+    dedupChoice?: "drop" | "override";
+}
+export interface WorkspaceMigratePlan {
+    workspaceRoot: string;
+    items: WorkspaceMigrateItem[];
+}
+export interface WorkspaceMigrateScanEntry {
+    agent: AgentId;
+    name: string;
+    def: McpServerDef;
+    sourcePath: string;
+}
+export interface WorkspaceMigrateScan {
+    entries: WorkspaceMigrateScanEntry[];
+    unsupported: {
+        agent: AgentId;
+        name: string;
+        reason: string;
+        sourcePath: string;
+    }[];
+    /** `*.local.*` siblings found next to scanned config paths — paths
+     * only, contents never read. */
+    localFiles: string[];
+}
+/**
+ * Apply-time re-read of one agent's project MCP defs (task 4.2, mirroring
+ * the global migrate's D9): an extraction's real value is recovered from
+ * the source file HERE, at apply time — it never rides on the plan object
+ * a `--json`/`--dry-run` caller might log or serialize.
+ */
+export declare function readWorkspaceAgentMcpDefsForApply(workspaceRoot: string, agentId: AgentId): McpMigrateReadResult;
+/**
+ * Inventories all six agents' project-level MCP config paths (the same
+ * paths workspace delivery writes, so migration and delivery can never
+ * disagree about where an agent reads) plus their `*.local.*` siblings.
+ * Pure: reads files, writes nothing.
+ */
+export declare function scanWorkspaceMcp(workspaceRoot: string): WorkspaceMigrateScan;
+export interface CollectWorkspaceMigrateOptions {
+    workspaceRoot: string;
+    homeDir: string;
+    secretsPolicy: SecretsPolicy;
+    /** `--choose name=agentId` resolutions for cross-agent conflicts. */
+    choose?: Record<string, AgentId>;
+    /** `--dedup` handling for `identical-to-global` items; default `drop`. */
+    dedup?: "drop" | "override";
+}
+export declare function collectWorkspaceMigratePlan(opts: CollectWorkspaceMigrateOptions): WorkspaceMigratePlan;