agent-trellis 0.14.1 → 0.15.0

package/dist/commands/mcp.js

@@ -27,6 +27,10 @@ import { PiAdapter } from "../adapters/pi.js";
 import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { applyWorkspaceMcp, planWorkspaceMcp, workspacePrecedenceWarnings } from "../lib/workspaceMcp.js";
+import { readWorkspaceConfigJson, upsertWorkspaceServer } from "../lib/workspaceConfig.js";
+import { toServerDefYaml } from "../core/mcpServerDef.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
@@ -42,14 +46,16 @@ function buildAdapters(homeDir, managedAgents) {
 }
 export async function collectMcpSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const loaded = loadCanonicalSource(homeDir);
+    const workspaceDir = opts.globalOnly ? null : (opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd()));
+    const loaded = loadCanonicalSource({ homeDir, workspaceDir });
     const canonical = {
         ...loaded,
         ...(opts.managedAgents ? { managedAgents: opts.managedAgents } : {}),
         ...(opts.mcp ? { mcp: opts.mcp } : {}),
     };
     const reports = [];
-    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
+    const writeMode = !opts.dryRun && !opts.check;
+    const ownSession = writeMode && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
     for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
@@ -57,14 +63,17 @@ export async function collectMcpSyncReport(opts = {}) {
             reports.push({ agent: adapter.id, present: false, items: [] });
             continue;
         }
-        const items = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
-        if (!opts.dryRun) {
-            await adapter.apply(items, backup);
+        const globalItems = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
+        const wsItems = planWorkspaceMcp(adapter.id, canonical);
+        if (writeMode) {
+            await adapter.apply(globalItems, backup);
+            applyWorkspaceMcp(adapter.id, canonical, wsItems, backup);
         }
-        reports.push({ agent: adapter.id, present: true, items });
+        const warnings = workspacePrecedenceWarnings(adapter.id, canonical);
+        reports.push({ agent: adapter.id, present: true, items: [...globalItems, ...wsItems], ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports };
+    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runMcpSync(opts = {}) {
     let report;
@@ -79,22 +88,31 @@ export async function runMcpSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report, opts.dryRun ?? false);
+        printReport(report, opts.dryRun ?? false, opts.check ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    if (opts.check) {
+        const hasPending = report.reports.some((r) => r.items.some((i) => i.action !== "conflict"));
+        return { exitCode: hasPending || hasConflict ? 1 : 0 };
+    }
     return { exitCode: hasConflict ? 1 : 0 };
 }
 /** Exported so `onboard` prints an mcp-sync report identically to running
  * `mcp sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export function printReport(report, dryRun) {
+export function printReport(report, dryRun, check = false) {
     if (dryRun)
         console.log("[dry run]");
+    if (check)
+        console.log("[check]");
+    if (report.workspaceRoot) {
+        console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
+    }
     if (report.reports.length === 0) {
         console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
         return;
     }
-    for (const { agent, present, items } of report.reports) {
+    for (const { agent, present, items, warnings } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
@@ -104,18 +122,27 @@ export function printReport(report, dryRun) {
         const conflicts = items.filter((i) => i.action === "conflict");
         if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
             console.log(`✅ ${agent} — already in sync`);
-            continue;
         }
-        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
-        console.log(`${icon} ${agent} — ${created.length} created/updated, ${removed.length} removed, ${conflicts.length} conflict(s)`);
-        for (const item of [...created, ...removed, ...conflicts]) {
-            console.log(`   - [${item.action}] ${item.description}`);
+        else {
+            const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+            console.log(`${icon} ${agent} — ${created.length} created/updated, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+            for (const item of [...created, ...removed, ...conflicts]) {
+                console.log(`   - [${item.action}]${item.layer === "workspace" ? " (workspace)" : ""} ${item.description}`);
+                // Conflicts carry the actionable fix (e.g. the unmarked-overwrite
+                // guard's "run migrate --workspace or remove the entry") — printing
+                // only the description would leave the user stuck at "left untouched".
+                if (item.remediation)
+                    console.log(`     → ${item.remediation}`);
+            }
+            // pi does not watch mcp.json (verified 2026-10-11): without this hint
+            // a changed config silently only takes effect on the next pi launch
+            // (trellis-pi-native-mcp-migration design.md D5).
+            if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
+                console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+            }
         }
-        // pi does not watch mcp.json (verified 2026-10-11): without this hint
-        // a changed config silently only takes effect on the next pi launch
-        // (trellis-pi-native-mcp-migration design.md D5).
-        if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
-            console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+        for (const warning of warnings ?? []) {
+            console.log(`   ⚠ ${warning}`);
         }
     }
 }
@@ -260,37 +287,43 @@ const TRANSPORTS = ["stdio", "http", "sse"];
  * write failure — design.md's open question, resolved in favor of
  * refusing early with a specific reason. No `--force`: an existing name
  * always refuses, ever (design.md D4).
+ *
+ * Split into two steps so `mcp add --workspace` reuses the identical
+ * flag validation/def construction and only swaps which file's existing
+ * entries it conflicts against (trellis-workspace-scope task 3.4):
+ * `buildMcpAddDef` is the pure part, `collectMcpAddPlan` adds the
+ * global-canonical existence check.
  */
-export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
+export function buildMcpAddDef(name, raw) {
     if (!name) {
-        return { name: "(none)", action: "invalid-input", detail: "a name is required: trellis mcp add <name> --transport ..." };
+        return { ok: false, plan: { name: "(none)", action: "invalid-input", detail: "a name is required: trellis mcp add <name> --transport ..." } };
     }
     if (!raw.transport || !TRANSPORTS.includes(raw.transport)) {
-        return { name, action: "invalid-input", detail: `--transport must be one of: ${TRANSPORTS.join(", ")}` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--transport must be one of: ${TRANSPORTS.join(", ")}` } };
     }
     const transport = raw.transport;
     if (transport === "stdio" && !raw.command) {
-        return { name, action: "invalid-input", detail: "--transport stdio requires --command" };
+        return { ok: false, plan: { name, action: "invalid-input", detail: "--transport stdio requires --command" } };
     }
     if ((transport === "http" || transport === "sse") && !raw.url) {
-        return { name, action: "invalid-input", detail: `--transport ${transport} requires --url` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--transport ${transport} requires --url` } };
     }
     if (raw.auth !== undefined && raw.auth !== "oauth") {
-        return { name, action: "invalid-input", detail: `--auth must be "oauth" when provided (got ${raw.auth})` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--auth must be "oauth" when provided (got ${raw.auth})` } };
     }
     if (raw.auth === "oauth" && transport === "stdio") {
-        return { name, action: "invalid-input", detail: "--auth oauth requires an http or sse MCP server" };
+        return { ok: false, plan: { name, action: "invalid-input", detail: "--auth oauth requires an http or sse MCP server" } };
     }
     const agentsList = parseCsv(raw.agents);
     if (agentsList) {
         for (const id of agentsList) {
             if (!ALL_AGENTS.includes(id)) {
-                return { name, action: "invalid-input", detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` };
+                return { ok: false, plan: { name, action: "invalid-input", detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` } };
             }
         }
     }
     if (raw.enabled !== undefined && raw.enabled !== "true" && raw.enabled !== "false") {
-        return { name, action: "invalid-input", detail: `--enabled must be "true" or "false" (got ${raw.enabled})` };
+        return { ok: false, plan: { name, action: "invalid-input", detail: `--enabled must be "true" or "false" (got ${raw.enabled})` } };
     }
     const def = {
         transport,
@@ -304,15 +337,46 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
         ...(raw.enabled !== undefined ? { enabled: raw.enabled === "true" } : {}),
         ...(agentsList ? { agents: agentsList } : {}),
     };
+    return { ok: true, name, def };
+}
+export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
+    const built = buildMcpAddDef(name, raw);
+    if (!built.ok)
+        return built.plan;
+    const def = built.def;
     const canonical = loadCanonicalSource(homeDir);
-    const existing = canonical.mcp.servers[name];
+    const existing = canonical.mcp.servers[built.name];
     if (existing) {
         if (JSON.stringify(existing) === JSON.stringify(def)) {
-            return { name, action: "already-present", detail: "canonical entry is already identical" };
+            return { name: built.name, action: "already-present", detail: "canonical entry is already identical" };
         }
-        return { name, action: "conflict", detail: `servers.yaml already has "${name}" with different settings — resolve by hand (no --force, design.md D4)` };
+        return { name: built.name, action: "conflict", detail: `servers.yaml already has "${built.name}" with different settings — resolve by hand (no --force, design.md D4)` };
     }
-    return { name, action: "create", detail: "will add to servers.yaml", def };
+    return { name: built.name, action: "create", detail: "will add to servers.yaml", def };
+}
+/** The workspace twin of `collectMcpAddPlan` (trellis-workspace-scope
+ * task 3.4): identical validation, but the existence check runs against
+ * `.agents/config.json` — compared through the same snake_case
+ * serialization the file stores, so a re-add of the same definition is
+ * a clean "already-present" no-op. A global same-name entry is NOT a
+ * conflict here (workspace shadowing a global entry is a legal,
+ * documented merge outcome), just noted in the detail. */
+export function collectMcpAddWorkspacePlan(name, raw, workspaceRoot, homeDir = homedir()) {
+    const built = buildMcpAddDef(name, raw);
+    if (!built.ok)
+        return built.plan;
+    const def = built.def;
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const existing = config.mcp?.servers?.[built.name];
+    if (existing) {
+        if (JSON.stringify(existing) === JSON.stringify(toServerDefYaml(def))) {
+            return { name: built.name, action: "already-present", detail: ".agents/config.json entry is already identical" };
+        }
+        return { name: built.name, action: "conflict", detail: `.agents/config.json already has "${built.name}" with different settings — resolve by hand (no --force)` };
+    }
+    const global = loadCanonicalSource(homeDir).mcp.servers[built.name];
+    const shadowNote = global ? ` (shadows the global "${built.name}" for this project)` : "";
+    return { name: built.name, action: "create", detail: `will add to .agents/config.json${shadowNote}`, def };
 }
 /**
  * Sets or clears the OAuth classification, and optionally the
@@ -587,8 +651,56 @@ export async function applyMcpAddWithSync(plan, opts = {}) {
     }
     return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
 }
+/** Workspace twin of `applyMcpAddWithSync` (trellis-workspace-scope task
+ * 3.4): writes `.agents/config.json` instead of `servers.yaml`, then
+ * cascades the same mcp sync — which, run inside the workspace, renders
+ * only the project-level targets for the workspace layer (plus the usual
+ * global-layer targets; the agent does its own layering). */
+export async function applyMcpAddWorkspaceWithSync(plan, workspaceRoot, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "mcp-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    if (!opts.dryRun && plan.action === "create" && plan.def) {
+        upsertWorkspaceServer(workspaceRoot, plan.name, plan.def, session);
+    }
+    ownSession?.finalize();
+    const planFailed = plan.action === "conflict" || plan.action === "invalid-input";
+    let syncReport;
+    if (!planFailed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
 export async function runMcpAdd(name, raw, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    if (opts.workspace) {
+        const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
+        if (!workspaceRoot) {
+            console.error("no .agents/ found here or above — run `trellis init --workspace` first (or pass --workspace from inside the repo)");
+            return { exitCode: 1 };
+        }
+        let plan;
+        try {
+            plan = collectMcpAddWorkspacePlan(name, raw, workspaceRoot, homeDir);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return { exitCode: 1 };
+        }
+        const { sync: syncReport } = await applyMcpAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
+        const planFailed = plan.action === "conflict" || plan.action === "invalid-input";
+        if (opts.json) {
+            console.log(JSON.stringify(syncReport ? { ...plan, workspace: workspaceRoot, sync: syncReport } : { ...plan, workspace: workspaceRoot }, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}mcp add ${plan.name} --workspace`);
+            console.log(`  [${plan.action}] ${plan.detail}`);
+            if (syncReport)
+                printReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: planFailed || syncConflict ? 1 : 0 };
+    }
     let plan;
     try {
         plan = collectMcpAddPlan(name, raw, homeDir);

package/dist/commands/migrate.d.ts

@@ -7,6 +7,18 @@
 import type { AgentId, McpServerDef } from "../core/types.js";
 import type { BackupSession } from "../lib/backup.js";
 import { type NativeMemoryCandidate, type NativeMemoryDiscovery } from "../lib/nativeMemory.js";
+/** Where a `staticEnv` literal secret's real value goes when
+ * `secrets.policy.yaml` doesn't already have its own `env_file`
+ * (trellis-migrate-extract-static-env-secrets design.md D3) — a sibling
+ * of `servers.yaml`, so "the mcp stuff" stays one directory rather than
+ * a second, disconnected location. `~`-form for what gets written into
+ * `secrets.policy.yaml` itself (portable across machines); resolved form
+ * for real file I/O. */
+export declare const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+/** Exported for `migrate --workspace` (trellis-workspace-scope task 4.2) —
+ * its staticEnv extraction lands in the same default store under the same
+ * naming scheme, never a second location. */
+export declare function defaultLocalSecretsEnvFilePath(homeDir: string): string;
 export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict" | "extract-secret";
 /** Internal kind naming, unchanged since before `--only` existed
  * (trellis-migrate-category-selection design.md D2) — the CLI-facing

package/dist/commands/migrate.js

@@ -29,8 +29,11 @@ import { discoverNativeMemory, MAX_NATIVE_MEMORY_BYTES, renderNativeMemory } fro
  * a second, disconnected location. `~`-form for what gets written into
  * `secrets.policy.yaml` itself (portable across machines); resolved form
  * for real file I/O. */
-const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
-function defaultLocalSecretsEnvFilePath(homeDir) {
+export const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+/** Exported for `migrate --workspace` (trellis-workspace-scope task 4.2) —
+ * its staticEnv extraction lands in the same default store under the same
+ * naming scheme, never a second location. */
+export function defaultLocalSecretsEnvFilePath(homeDir) {
     return join(homeDir, ".trellis", "mcp", "servers.local.env");
 }
 /** Picks the rc file `ensureShellEnvSource` writes its one pointer block
@@ -54,8 +57,9 @@ const PROBES = {
     "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
     zcode: (homeDir) => zcodeProbe.probe(homeDir),
 };
-/** pi has no static MCP config to read at all (roadmap.md P14/
- * trellis-migrate-mcp-servers) — deliberately absent, not an oversight;
+/** pi's mcp.json migrate-in is not implemented (roadmap.md P14/
+ * trellis-migrate-mcp-servers predates pi 1.1.0's native MCP config) —
+ * deliberately absent, not an oversight;
  * `collectMigratePlan` skips the `mcp` category entirely for pi. */
 const MCP_READERS = {
     "claude-code": readClaudeCodeMcpDefs,

package/dist/commands/migrateWorkspace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `trellis migrate --workspace` — absorbs a repo's existing project-level
+ * agent config (all six agents' MCP files + root AGENTS.md) into
+ * `.agents/`, then re-renders (trellis-workspace-scope group 4).
+ *
+ * Flow: plan (pure, `src/lib/workspaceMigrate.ts`) → refuse on unresolved
+ * conflicts → one backup session named `workspace-<repo-hash>` covering
+ * every write (task 4.6 — `.agents/` writes, the secret-store extraction,
+ * the marker-headed AGENTS.md rewrite, and the cascade render, so a
+ * single `trellis rollback` restores originals and removes generated
+ * `.agents/` content) → post-migration equivalence report (task 4.7).
+ */
+import type { AgentId } from "../core/types.js";
+import type { WorkspaceMigratePlan } from "../lib/workspaceMigrate.js";
+export interface RunMigrateWorkspaceOptions {
+    /** Test/sandbox seam — CLI resolves via findWorkspaceRoot(cwd), falling
+     * back to cwd itself so a legacy project without `.agents/` yet can
+     * still be scanned (apply then creates `.agents/` through backup). */
+    workspaceDir?: string;
+    /** Raw `name=agentId` strings from repeated `--choose`. */
+    choose?: string[];
+    /** Raw `--dedup` value: `drop` (default) or `override`. */
+    dedup?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    homeDir?: string;
+}
+export interface WorkspaceMigrateEquivalence {
+    /** Per agent: server names found in its project config before the
+     * migration vs. what the post-migration render now delivers. */
+    agents: {
+        agent: AgentId;
+        before: string[];
+        after: string[];
+    }[];
+}
+export declare function runMigrateWorkspace(opts?: RunMigrateWorkspaceOptions): Promise<{
+    exitCode: number;
+}>;
+export declare function printWorkspaceMigratePlan(plan: WorkspaceMigratePlan, dryRun: boolean): void;

package/dist/commands/migrateWorkspace.js

@@ -0,0 +1,197 @@
+/**
+ * `trellis migrate --workspace` — absorbs a repo's existing project-level
+ * agent config (all six agents' MCP files + root AGENTS.md) into
+ * `.agents/`, then re-renders (trellis-workspace-scope group 4).
+ *
+ * Flow: plan (pure, `src/lib/workspaceMigrate.ts`) → refuse on unresolved
+ * conflicts → one backup session named `workspace-<repo-hash>` covering
+ * every write (task 4.6 — `.agents/` writes, the secret-store extraction,
+ * the marker-headed AGENTS.md rewrite, and the cascade render, so a
+ * single `trellis rollback` restores originals and removes generated
+ * `.agents/` content) → post-migration equivalence report (task 4.7).
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ALL_AGENTS } from "../core/types.js";
+import { ensureGitignoreEntry, loadCanonicalSource, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { openBackupSession } from "../lib/backup.js";
+import { writeLocalSecretValue } from "../lib/secretEnv.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { upsertWorkspaceServer } from "../lib/workspaceConfig.js";
+import { INSTRUCTIONS_MARKER } from "../lib/workspaceFiles.js";
+import { recordWorkspaceRendered, renderWorkspaceManifestEntry } from "../lib/workspaceMcp.js";
+import { collectWorkspaceMigratePlan, readWorkspaceAgentMcpDefsForApply } from "../lib/workspaceMigrate.js";
+import { collectMcpSyncReport } from "./mcp.js";
+import { collectSyncReport } from "./sync.js";
+import { defaultLocalSecretsEnvFilePath, DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE } from "./migrate.js";
+/** Task 4.6's `<repo-hash>`: stable per checkout path, short enough to
+ * stay readable in a backups listing. */
+function repoHash(workspaceRoot) {
+    return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 12);
+}
+/**
+ * Applies one plan item. MCP items go through `upsertWorkspaceServer`
+ * (which serializes the snake_case shape and fills `version`); the
+ * extract-secret companion write mirrors the global migrate's
+ * `applyStaticEnvExtraction` — real value re-read from the SOURCE file at
+ * apply time, never carried on the plan (D9). Instructions import writes
+ * `.agents/AGENTS.md` and rewrites the root file marker-headed in place
+ * (a `file-overwrite` op — rollback restores the original unmarked file).
+ */
+function applyWorkspaceMigrateItem(item, plan, homeDir, backup) {
+    if (item.kind === "mcp" && (item.action === "create" || item.action === "extract-secret") && item.mcpDef) {
+        upsertWorkspaceServer(plan.workspaceRoot, item.name, item.mcpDef, backup);
+        // Adopt the source entries: every agent file this name came from gets
+        // a manifest ownership record, so the cascade render owns the entry
+        // (bringing it to Trellis's canonical render) instead of conflict-
+        // guarding on it as user-authored content. Without this the migration
+        // would import into .agents/ and then immediately conflict on the
+        // very files it absorbed.
+        for (const agent of item.sources) {
+            recordWorkspaceRendered(plan.workspaceRoot, agent, item.name, renderWorkspaceManifestEntry(agent, item.name, item.mcpDef), backup);
+        }
+        if (item.action === "extract-secret" && item.extractVarName && item.extractTargetPath && item.extractSourceKey && item.extractSourceAgent) {
+            const realValue = readWorkspaceAgentMcpDefsForApply(plan.workspaceRoot, item.extractSourceAgent)
+                .entries.find((e) => e.name === item.name)?.def.staticEnv?.[item.extractSourceKey];
+            if (realValue !== undefined) {
+                if (item.extractTargetPath === defaultLocalSecretsEnvFilePath(homeDir)) {
+                    ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env", backup);
+                }
+                writeLocalSecretValue(item.extractTargetPath, item.extractVarName, realValue, backup);
+                const policyResult = writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName: item.extractVarName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE }, backup);
+                // A failed policy write leaves the extracted var unresolvable —
+                // the cascade render then refuses with a confusing conflict. Say
+                // why, plainly, while the run is still honest about it.
+                if (!policyResult.ok) {
+                    console.error(`warning: extracted ${item.extractVarName} but could not record it in secrets.policy.yaml: ${policyResult.error}`);
+                }
+            }
+            // undefined = the source changed between plan and apply; the safe
+            // def (name-only reference) is still imported, matching the global
+            // migrate's "nothing left to extract" behavior.
+        }
+        return;
+    }
+    if (item.kind === "instructions" && item.action === "create" && item.sourceContent !== undefined) {
+        const target = join(plan.workspaceRoot, ".agents", "AGENTS.md");
+        mkdirSync(dirname(target), { recursive: true });
+        backup.writeFile(target, item.sourceContent);
+        // Rewrite the root file marker-headed NOW so the cascade instructions
+        // sync sees current === rendered (no-op) instead of conflicting on an
+        // unmarked file. Byte-identical to planWorkspaceInstructions' render.
+        backup.writeFile(join(plan.workspaceRoot, "AGENTS.md"), `${INSTRUCTIONS_MARKER}\n\n${item.sourceContent}`);
+    }
+}
+export async function runMigrateWorkspace(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    // --- flag validation (raw strings arrive from cli.ts) ---
+    const choose = {};
+    for (const raw of opts.choose ?? []) {
+        const eq = raw.indexOf("=");
+        const agent = eq === -1 ? "" : raw.slice(eq + 1);
+        if (eq === -1 || !ALL_AGENTS.includes(agent)) {
+            console.error(`--choose must be name=agentId with agentId one of: ${ALL_AGENTS.join(", ")} (got "${raw}")`);
+            return { exitCode: 1 };
+        }
+        choose[raw.slice(0, eq)] = agent;
+    }
+    if (opts.dedup !== undefined && opts.dedup !== "drop" && opts.dedup !== "override") {
+        console.error(`--dedup must be drop or override (got ${opts.dedup})`);
+        return { exitCode: 1 };
+    }
+    const secretsPolicy = loadCanonicalSource({ homeDir, workspaceDir: null }).secretsPolicy;
+    const plan = collectWorkspaceMigratePlan({ workspaceRoot, homeDir, secretsPolicy, choose, dedup: opts.dedup });
+    // Task 4.3/4.2: a real run with ANY unresolved conflict writes nothing —
+    // the user resolves (via --choose, or by fixing the source) and re-runs.
+    const conflicts = plan.items.filter((i) => i.action === "conflict");
+    if (conflicts.length > 0 && !opts.dryRun) {
+        printWorkspaceMigratePlan(plan, false);
+        console.error(`\n${conflicts.length} unresolved conflict(s) — nothing was written. Resolve each and re-run.`);
+        return { exitCode: 1 };
+    }
+    // Task 4.7's "before" half: what each agent's project config held.
+    const beforeByAgent = new Map();
+    for (const item of plan.items) {
+        if (item.kind !== "mcp" || item.action === "skip-local")
+            continue;
+        for (const agent of item.sources) {
+            beforeByAgent.set(agent, [...new Set([...(beforeByAgent.get(agent) ?? []), item.name])]);
+        }
+    }
+    let equivalence;
+    if (!opts.dryRun) {
+        const actionable = plan.items.filter((i) => i.action === "create" || i.action === "extract-secret");
+        const backup = openBackupSession(homeDir, `workspace-${repoHash(workspaceRoot)}`);
+        for (const item of actionable) {
+            applyWorkspaceMigrateItem(item, plan, homeDir, backup);
+        }
+        // Cascade render through the SAME session (task 4.6): MCP artifacts
+        // for every managed agent, so one `trellis rollback` undoes the whole
+        // migration. Instructions only cascade when an instructions item was
+        // actually applied — scoping the side effects to what migration
+        // touched, same discipline as `mcp add --workspace`'s MCP-only
+        // cascade.
+        await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, backupSession: backup });
+        if (actionable.some((i) => i.kind === "instructions")) {
+            await collectSyncReport({ target: "instructions", homeDir, workspaceDir: workspaceRoot, backupSession: backup });
+        }
+        backup.finalize();
+        // Task 4.7's "after" half: a fresh dry-run render against the
+        // migrated `.agents/` proves the absorbed config now delivers.
+        const after = await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, dryRun: true });
+        equivalence = {
+            agents: after.reports
+                .filter((r) => r.present)
+                .map((r) => ({
+                agent: r.agent,
+                before: (beforeByAgent.get(r.agent) ?? []).sort(),
+                after: r.items.filter((i) => i.kind === "mcp" && i.layer === "workspace" && i.mcpWrite).map((i) => i.mcpWrite.name).sort(),
+            }))
+                .filter((a) => a.before.length > 0 || a.after.length > 0),
+        };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ...plan, ...(equivalence ? { equivalence } : {}) }, null, 2));
+    }
+    else {
+        printWorkspaceMigratePlan(plan, opts.dryRun ?? false);
+        if (equivalence)
+            printEquivalence(equivalence);
+    }
+    return { exitCode: conflicts.length > 0 ? 1 : 0 };
+}
+export function printWorkspaceMigratePlan(plan, dryRun) {
+    console.log(`${dryRun ? "[dry run] " : ""}migrate --workspace ${plan.workspaceRoot}`);
+    if (plan.items.length === 0) {
+        console.log("  nothing to migrate");
+        return;
+    }
+    for (const item of plan.items) {
+        const label = item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions (AGENTS.md)";
+        console.log(`  [${item.action}] ${label} — ${item.detail}`);
+        if (item.defs) {
+            for (const [agent, def] of Object.entries(item.defs)) {
+                console.log(`      ${agent}: ${JSON.stringify(def)}`);
+            }
+        }
+        if (item.rotationAdvisory) {
+            console.log(`      ⚠ ${item.rotationAdvisory}`);
+        }
+        if (item.remediation) {
+            console.log(`      → ${item.remediation}`);
+        }
+    }
+}
+function printEquivalence(equivalence) {
+    console.log("equivalence (before → rendered after):");
+    if (equivalence.agents.length === 0) {
+        console.log("  no managed agent renders workspace servers on this machine");
+        return;
+    }
+    for (const { agent, before, after } of equivalence.agents) {
+        console.log(`  ${agent}: [${before.join(", ") || "—"}] → [${after.join(", ") || "—"}]`);
+    }
+}