agent-trellis 0.4.0 → 0.6.0

package/dist/commands/mcpGateway.js

@@ -0,0 +1,148 @@
+/**
+ * `trellis mcp-gateway --agent <id>` — the stdio MCP server an agent
+ * spawns in gateway mode (trellis-mcp-gateway-hosting).
+ *
+ * Not a user-facing command in the usual sense: nobody types this. An
+ * agent's own MCP client spawns it exactly the way it spawns any other
+ * stdio server, talks to it for the session, and closes the pipe on exit
+ * (design.md D2). There is no daemon, no lifecycle command, and nothing
+ * for the user to notice.
+ *
+ * This file depends on `GatewayBackend` and nothing below it — no
+ * connection, no transport, no server definition (design.md D11). That is
+ * what lets v2 point the same stdio edge at one shared service instead of
+ * an in-process backend without this file, or any agent's config,
+ * changing.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { LocalBackend } from "../lib/gatewayBackend.js";
+import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { ALL_AGENTS } from "../core/types.js";
+const CLIENT_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+const SERVER_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+export function parseMcpGatewayArgs(argv) {
+    const index = argv.indexOf("--agent");
+    if (index === -1 || index === argv.length - 1) {
+        return { error: `mcp-gateway requires --agent <${ALL_AGENTS.join("|")}>` };
+    }
+    const value = argv[index + 1];
+    if (!ALL_AGENTS.includes(value)) {
+        return { error: `unknown agent "${value}" — expected one of ${ALL_AGENTS.join(", ")}` };
+    }
+    return { agentId: value };
+}
+/**
+ * The in-scope upstream set for this agent, resolved through the very same
+ * `resolveMcpPlan` that direct mode uses — per-server `agents:` scope,
+ * `enabled: false`, host-injected collisions, literal-secret refusals and
+ * unresolved `env` names all apply here identically, because it is
+ * literally the same function (design.md D6).
+ *
+ * The one thing that must be stripped is gateway mode itself: asking
+ * `resolveMcpPlan` for this agent's plan while gateway mode is on would
+ * answer "one entry, pointing at the gateway" — the gateway being told to
+ * connect to itself. Resolving against a gateway-less view of the same
+ * canonical gives the set gateway mode replaced.
+ */
+export function resolveGatewayUpstreams(agentId, canonical) {
+    const direct = { ...canonical.mcp, gateway: undefined };
+    // The managed set is passed through unchanged, so an unmanaged agent
+    // reaches nothing. Being spawned is NOT treated as consent here, which
+    // is a deliberate divergence from `src/pi-bridge/index.ts` (which passes
+    // ALL_AGENTS on the grounds that pi loading the extension is itself the
+    // signal). The triggers differ: pi's bridge only exists on disk because
+    // Trellis symlinked it into pi's own directory while pi was managed, so
+    // its presence IS the marker. A gateway entry, by contrast, outlives
+    // un-managing — it sits in the agent's config until a later sync's
+    // ownership-gated removal clears it. Serving that stale entry would hand
+    // every server, and every secret resolved into it, to the one agent the
+    // user just said to stop involving.
+    const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    return {
+        upstreams: desired.map(({ name, def }) => ({ name, def })),
+        conflicts: conflicts.map((conflict) => conflict.message),
+    };
+}
+export async function runMcpGateway(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (err) {
+        // stderr, never stdout: stdout IS the MCP protocol stream here, and a
+        // stray line on it corrupts the agent's parser rather than informing
+        // anyone.
+        console.error(`trellis-mcp-gateway: ${err instanceof Error ? err.message : String(err)}`);
+        return { exitCode: 1 };
+    }
+    const { upstreams, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
+    for (const message of conflicts) {
+        console.error(`trellis-mcp-gateway: ${message}`);
+    }
+    const backend = opts.backendFactory
+        ? await opts.backendFactory(upstreams, homeDir)
+        : await LocalBackend.connect(upstreams, {
+            secretsPolicy: canonical.secretsPolicy,
+            clientInfo: CLIENT_INFO,
+            connectTimeoutMs,
+            // Enables silent OAuth refresh-before-connect. Never an
+            // interactive grant: that is `trellis mcp auth`'s job, and this
+            // process has no terminal to run one in (design.md D9).
+            homeDir,
+        });
+    const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await backend.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await backend.callTool(request.params.name, request.params.arguments);
+        return result;
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await waitForShutdown(backend, server);
+    return { exitCode: 0 };
+}
+/**
+ * Teardown on client disconnect — the piece neither layer below provides.
+ *
+ * `StdioServerTransport.start()` registers listeners for `'data'` and
+ * `'error'` only, so stdin reaching EOF never reaches `onclose`; and POSIX
+ * re-parents an orphan to launchd rather than killing it, while this
+ * process's own event loop is held open by every upstream it connected.
+ * Without this, each agent session would permanently leak a gateway plus
+ * its entire upstream process set (design.md D13).
+ */
+function waitForShutdown(backend, server) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const shutdown = async () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                await backend.close();
+            }
+            catch (err) {
+                console.error(`trellis-mcp-gateway: failed to close backend: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                await server.close();
+            }
+            catch {
+                // best-effort; the process is going away regardless
+            }
+            resolve();
+        };
+        process.stdin.on("end", shutdown);
+        process.stdin.on("close", shutdown);
+        for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+            process.once(signal, shutdown);
+        }
+    });
+}

package/dist/commands/memory.d.ts

@@ -1,13 +1,18 @@
 /**
- * `trellis memory sync` — ingests canonical `memories/*.md` into the
- * on-disk knowledge-graph file `@modelcontextprotocol/server-memory`
- * itself reads at startup, closing P6's explicitly-left-open "auto-
- * ingesting memories/*.md content into the running memory server's
- * store" gap (trellis-memory-sync). Never spawns or talks to a running
- * server process — this is a plain file write, same posture as every
- * other Trellis write.
+ * `trellis memory sync`/`trellis memory extract` — the two one-directional
+ * halves of Trellis's shared-memory story: sync ingests canonical
+ * `memories/*.md` into the on-disk knowledge-graph file
+ * `@modelcontextprotocol/server-memory` itself reads at startup, closing
+ * P6's explicitly-left-open "auto-ingesting memories/*.md content into
+ * the running memory server's store" gap (trellis-memory-sync); extract
+ * reads the graph's own real, non-Trellis entities back into new
+ * canonical files, closing P15's own explicitly-named "per-agent
+ * extraction into canonical remains a separate, open gap"
+ * (trellis-memory-extraction). Neither spawns or talks to a running
+ * server process — both are plain file operations, same posture as
+ * every other Trellis write.
  */
-import { type MemorySyncPlan } from "../lib/memoryGraph.js";
+import { type MemoryExtractionPlan, type MemorySyncPlan } from "../lib/memoryGraph.js";
 export interface RunMemorySyncOptions {
     homeDir?: string;
     json?: boolean;
@@ -21,17 +26,6 @@ export type MemorySyncResult = {
     configured: false;
     reason: string;
 };
-/**
- * Looks up `mcp.servers["memory"]` specifically (matching `schema/
- * servers.example.yaml`'s own naming convention for the default shared-
- * memory backend) — not a heuristic scan for any server whose command
- * happens to mention `@modelcontextprotocol/server-memory`, since a
- * user could reasonably name or configure it differently and this
- * would then silently miss it. `static_env.MEMORY_FILE_PATH` must be
- * set explicitly: the server's own unset-env default resolves relative
- * to wherever `npx` cached the package, a location Trellis has no
- * reliable way to predict.
- */
 export declare function collectMemorySyncResult(homeDir?: string): MemorySyncResult;
 export declare function applyMemorySync(result: MemorySyncResult): void;
 /**
@@ -45,3 +39,32 @@ export declare function printMemorySyncResult(result: MemorySyncResult, dryRun:
 export declare function runMemorySync(opts?: RunMemorySyncOptions): {
     exitCode: number;
 };
+export interface RunMemoryExtractionOptions {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+export type MemoryExtractionResult = {
+    configured: true;
+    graphPath: string;
+    plan: MemoryExtractionPlan;
+} | {
+    configured: false;
+    reason: string;
+};
+/**
+ * The reverse direction of `collectMemorySyncResult`: reads the same
+ * graph file, but plans which of its real, non-`trellis-memory` entities
+ * (`planMemoryExtraction`) should become new canonical files — never the
+ * other way around, and never touching an entity `memory sync` itself
+ * owns (trellis-memory-extraction).
+ */
+export declare function collectMemoryExtractionResult(homeDir?: string): MemoryExtractionResult;
+export declare function applyMemoryExtraction(result: MemoryExtractionResult, homeDir?: string): void;
+/** Mirrors `printMemorySyncResult`'s own export-pair convention — reused
+ * verbatim if `onboard` ever chains this stage too, not a second,
+ * drifting copy. */
+export declare function printMemoryExtractionResult(result: MemoryExtractionResult, dryRun: boolean): void;
+export declare function runMemoryExtraction(opts?: RunMemoryExtractionOptions): {
+    exitCode: number;
+};

package/dist/commands/memory.js

@@ -1,17 +1,22 @@
 /**
- * `trellis memory sync` — ingests canonical `memories/*.md` into the
- * on-disk knowledge-graph file `@modelcontextprotocol/server-memory`
- * itself reads at startup, closing P6's explicitly-left-open "auto-
- * ingesting memories/*.md content into the running memory server's
- * store" gap (trellis-memory-sync). Never spawns or talks to a running
- * server process — this is a plain file write, same posture as every
- * other Trellis write.
+ * `trellis memory sync`/`trellis memory extract` — the two one-directional
+ * halves of Trellis's shared-memory story: sync ingests canonical
+ * `memories/*.md` into the on-disk knowledge-graph file
+ * `@modelcontextprotocol/server-memory` itself reads at startup, closing
+ * P6's explicitly-left-open "auto-ingesting memories/*.md content into
+ * the running memory server's store" gap (trellis-memory-sync); extract
+ * reads the graph's own real, non-Trellis entities back into new
+ * canonical files, closing P15's own explicitly-named "per-agent
+ * extraction into canonical remains a separate, open gap"
+ * (trellis-memory-extraction). Neither spawns or talks to a running
+ * server process — both are plain file operations, same posture as
+ * every other Trellis write.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { loadCanonicalSource } from "../core/canonical.js";
-import { planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
+import { parseMemoryGraph, planMemoryExtraction, planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
 const MEMORY_SERVER_NAME = "memory";
 /**
  * Looks up `mcp.servers["memory"]` specifically (matching `schema/
@@ -22,9 +27,12 @@ const MEMORY_SERVER_NAME = "memory";
  * would then silently miss it. `static_env.MEMORY_FILE_PATH` must be
  * set explicitly: the server's own unset-env default resolves relative
  * to wherever `npx` cached the package, a location Trellis has no
- * reliable way to predict.
+ * reliable way to predict. Shared by `collectMemorySyncResult` and
+ * `collectMemoryExtractionResult` — both directions must never disagree
+ * about which graph file they're reading/writing
+ * (trellis-memory-extraction).
  */
-export function collectMemorySyncResult(homeDir = homedir()) {
+function resolveMemoryServerGraphPath(homeDir) {
     const canonical = loadCanonicalSource(homeDir);
     const server = canonical.mcp.servers[MEMORY_SERVER_NAME];
     const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
@@ -34,10 +42,16 @@ export function collectMemorySyncResult(homeDir = homedir()) {
             reason: `no "${MEMORY_SERVER_NAME}" MCP server with static_env.MEMORY_FILE_PATH configured in servers.yaml — see schema/servers.example.yaml`,
         };
     }
-    const graphPath = rawPath.replace(/^~(?=$|\/)/, homeDir);
-    const currentContent = existsSync(graphPath) ? readFileSync(graphPath, "utf-8") : undefined;
+    return { configured: true, graphPath: rawPath.replace(/^~(?=$|\/)/, homeDir) };
+}
+export function collectMemorySyncResult(homeDir = homedir()) {
+    const lookup = resolveMemoryServerGraphPath(homeDir);
+    if (!lookup.configured)
+        return lookup;
+    const canonical = loadCanonicalSource(homeDir);
+    const currentContent = existsSync(lookup.graphPath) ? readFileSync(lookup.graphPath, "utf-8") : undefined;
     const plan = planMemorySync(canonical, currentContent);
-    return { configured: true, graphPath, plan };
+    return { configured: true, graphPath: lookup.graphPath, plan };
 }
 export function applyMemorySync(result) {
     if (!result.configured || !result.plan.nextGraph)
@@ -87,3 +101,74 @@ export function runMemorySync(opts = {}) {
     const hasConflict = result.configured && result.plan.items.some((i) => i.action === "conflict");
     return { exitCode: hasConflict ? 1 : 0 };
 }
+function canonicalMemoryFilePath(homeDir, slug) {
+    return join(homeDir, ".trellis", "memories", `${slug}.md`);
+}
+/**
+ * The reverse direction of `collectMemorySyncResult`: reads the same
+ * graph file, but plans which of its real, non-`trellis-memory` entities
+ * (`planMemoryExtraction`) should become new canonical files — never the
+ * other way around, and never touching an entity `memory sync` itself
+ * owns (trellis-memory-extraction).
+ */
+export function collectMemoryExtractionResult(homeDir = homedir()) {
+    const lookup = resolveMemoryServerGraphPath(homeDir);
+    if (!lookup.configured)
+        return lookup;
+    const graphContent = existsSync(lookup.graphPath) ? readFileSync(lookup.graphPath, "utf-8") : undefined;
+    const graphLines = graphContent !== undefined ? parseMemoryGraph(graphContent) : [];
+    const plan = planMemoryExtraction(graphLines, (slug) => {
+        const file = canonicalMemoryFilePath(homeDir, slug);
+        return existsSync(file) ? readFileSync(file, "utf-8") : undefined;
+    });
+    return { configured: true, graphPath: lookup.graphPath, plan };
+}
+export function applyMemoryExtraction(result, homeDir = homedir()) {
+    if (!result.configured)
+        return;
+    for (const item of result.plan.items) {
+        if (item.action !== "create" || item.content === undefined)
+            continue;
+        const file = canonicalMemoryFilePath(homeDir, item.slug);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, item.content);
+    }
+}
+/** Mirrors `printMemorySyncResult`'s own export-pair convention — reused
+ * verbatim if `onboard` ever chains this stage too, not a second,
+ * drifting copy. */
+export function printMemoryExtractionResult(result, dryRun) {
+    if (!result.configured) {
+        console.log(result.reason);
+        return;
+    }
+    console.log(`${dryRun ? "[dry run] " : ""}memory extract — ${result.graphPath}`);
+    if (result.plan.items.length === 0) {
+        console.log("  nothing to extract — no non-trellis-memory entities with observations in the graph");
+    }
+    for (const item of result.plan.items) {
+        console.log(`  [${item.action}] "${item.name}" (${item.slug}.md) — ${item.detail}`);
+    }
+}
+export function runMemoryExtraction(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectMemoryExtractionResult(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        applyMemoryExtraction(result, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printMemoryExtractionResult(result, opts.dryRun ?? false);
+    }
+    const hasConflict = result.configured && result.plan.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}

package/dist/commands/migrate.d.ts

@@ -5,7 +5,7 @@
  * plan-then-apply split every adapter already uses.
  */
 import type { AgentId, McpServerDef } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "conflict";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict";
 /** Internal kind naming, unchanged since before `--only` existed
  * (trellis-migrate-category-selection design.md D2) — the CLI-facing
  * flag value is the plural `"skills"`, mapped to this singular `"skill"`
@@ -17,6 +17,10 @@ export interface MigratePlanItem {
     name: string;
     action: MigrateAction;
     detail: string;
+    /** Only set (and only meaningful) when `action === "conflict"`: the
+     * concrete next action, distinct from `detail`'s restatement of why
+     * (trellis-onboard-closed-loop design.md D7). */
+    remediation?: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;
@@ -28,6 +32,19 @@ export interface MigratePlan {
     present: boolean;
     items: MigratePlanItem[];
 }
+/**
+ * True when `existing` and `def` differ ONLY in which of `env`/
+ * `envAliases`/`staticEnv` an env value is filed under, while every
+ * other field and every value's resolved literal/reference text stays
+ * identical — the exact shape a migrate-read classification fix (like
+ * `trellis-migrate-env-var-alias`) leaves behind on already-migrated
+ * canonical data. Not a real conflict: the underlying value never
+ * changed, only Trellis's own bucketing of it got more precise
+ * (trellis-migrate-reclassify-repair). Anything this doesn't cover — a
+ * real value change, a different command, an added/removed field —
+ * still conflicts, unchanged.
+ */
+export declare function isSafeReclassification(existing: McpServerDef, def: McpServerDef): boolean;
 /**
  * `only` restricts which kind(s) are even considered — not a post-hoc
  * filter on a fully-computed plan (trellis-migrate-category-selection

package/dist/commands/migrate.js

@@ -14,7 +14,7 @@ import * as piProbe from "../probes/pi.js";
 import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
-import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs } from "../lib/mcpMigrateRead.js";
+import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
@@ -44,7 +44,13 @@ function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
         case "already-present":
             return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
         case "conflict":
-            return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+            return {
+                kind: "skill",
+                name,
+                action: "conflict",
+                detail: `canonical skills/${name}/ already exists with different content — resolve by hand`,
+                remediation: `compare \`~/.trellis/skills/${name}/\` against the source agent's copy and either update canonical by hand or delete the source's copy if canonical's is the one to keep`,
+            };
     }
 }
 function planInstructions(snapshot, canonicalAgentsMd) {
@@ -58,7 +64,13 @@ function planInstructions(snapshot, canonicalAgentsMd) {
         sourceContent = readFileSync(snapshot.instructionsFile.path, "utf-8");
     }
     catch (err) {
-        return { kind: "instructions", name: "agents.md", action: "conflict", detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}` };
+        return {
+            kind: "instructions",
+            name: "agents.md",
+            action: "conflict",
+            detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: `check that ${snapshot.instructionsFile.path} exists and is readable, then re-run migrate`,
+        };
     }
     if (!existsSync(canonicalAgentsMd)) {
         return { kind: "instructions", name: "agents.md", action: "create", detail: "canonical agents.md does not exist yet", sourceContent };
@@ -70,7 +82,32 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     if (current === sourceContent) {
         return { kind: "instructions", name: "agents.md", action: "already-migrated", detail: "canonical content is byte-identical" };
     }
-    return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
+    return {
+        kind: "instructions",
+        name: "agents.md",
+        action: "conflict",
+        detail: "canonical agents.md already has different real content — resolve by hand",
+        remediation: `compare \`~/.trellis/agents.md\` against ${snapshot.instructionsFile.path} and either merge by hand or delete whichever copy you don't want to keep`,
+    };
+}
+/**
+ * True when `existing` and `def` differ ONLY in which of `env`/
+ * `envAliases`/`staticEnv` an env value is filed under, while every
+ * other field and every value's resolved literal/reference text stays
+ * identical — the exact shape a migrate-read classification fix (like
+ * `trellis-migrate-env-var-alias`) leaves behind on already-migrated
+ * canonical data. Not a real conflict: the underlying value never
+ * changed, only Trellis's own bucketing of it got more precise
+ * (trellis-migrate-reclassify-repair). Anything this doesn't cover — a
+ * real value change, a different command, an added/removed field —
+ * still conflicts, unchanged.
+ */
+export function isSafeReclassification(existing, def) {
+    const { env: _e1, envAliases: _ea1, staticEnv: _se1, ...restExisting } = existing;
+    const { env: _e2, envAliases: _ea2, staticEnv: _se2, ...restDef } = def;
+    if (!deepEqual(restExisting, restDef))
+        return false;
+    return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
 }
 function planMcpServer(name, def, existing) {
     if (existing === undefined) {
@@ -79,7 +116,16 @@ function planMcpServer(name, def, existing) {
     if (deepEqual(existing, def)) {
         return { kind: "mcp", name, action: "already-migrated", detail: "canonical definition is already identical" };
     }
-    return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
+    if (isSafeReclassification(existing, def)) {
+        return { kind: "mcp", name, action: "reclassify", detail: "same value, only its internal classification changed — safe to update", mcpDef: def };
+    }
+    return {
+        kind: "mcp",
+        name,
+        action: "conflict",
+        detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand`,
+        remediation: `compare the source agent's own definition for "${name}" against \`~/.trellis/mcp/servers.yaml\` and update canonical by hand if the source's is the one to keep`,
+    };
 }
 /**
  * `only` restricts which kind(s) are even considered — not a post-hoc
@@ -127,7 +173,7 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
 export function applyMigratePlan(plan, homeDir = homedir()) {
     const canonicalRoot = join(homeDir, ".trellis");
     for (const item of plan.items) {
-        if (item.action !== "create")
+        if (item.action !== "create" && item.action !== "reclassify")
             continue;
         if (item.kind === "skill" && item.sourceDir) {
             const dest = join(canonicalRoot, "skills", item.name);

package/dist/commands/onboard.d.ts

@@ -18,7 +18,9 @@ import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
 import type { MemorySyncResult } from "./memory.js";
+import type { DoctorReport } from "./doctor.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
+import type { VerdictItem } from "./onboardVerdict.js";
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -64,6 +66,10 @@ export interface RunOnboardOptions {
      * answer — "skip migrate for this run" (design.md D6) — distinct from
      * `source` being unresolved at all. */
     promptForMigrateCategories?: (source: OnboardAgentSummary) => Promise<MigrateKind[]>;
+    /** Test-only: replaces the real end-of-`--dry-run` "apply now?" picker
+     * (design.md D9). `true` means "apply for real", matching what
+     * accepting the real picker's "Yes, apply now" option means. */
+    promptToApply?: () => Promise<boolean>;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -90,13 +96,41 @@ export interface OnboardResult {
     migrateSkipped?: string;
     syncReport?: SyncReport;
     mcpSyncReport?: McpSyncReport;
+    /**
+     * The self-verification re-plan (design.md D2b): a dry-run re-plan of
+     * `sync`/`mcp sync`, run immediately after their real apply, against
+     * the state that apply just wrote. Absent on `--dry-run` (nothing was
+     * written, so nothing to verify) and on every early-refusal path.
+     * Present, and empty, on a real run whose write actually held.
+     */
+    syncVerification?: SyncReport;
+    mcpSyncVerification?: McpSyncReport;
     memorySyncResult?: MemorySyncResult;
     secretsAuditReport?: SecretsAuditReport;
+    /**
+     * A broader, whole-machine health scan — the same detectors
+     * `trellis doctor` itself runs, against every agent (not scoped to
+     * `managedAgents`, design.md D3), never with MCP handshake probing
+     * (design.md D4). Complementary to, and distinct from, the
+     * write-verification above: this cannot itself prove a write took
+     * effect (it never reads canonical), only that something looks
+     * inconsistent across agents independent of this run.
+     */
+    doctorReport?: DoctorReport;
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and
      * text output both surface, so a machine caller doesn't have to
      * hardcode them a second time. */
     installHints?: Record<AgentId, string>;
+    /**
+     * Every stage's conflicts and findings, normalized to one shape
+     * (trellis-onboard-closed-loop design.md D5) — the single source
+     * `runOnboard`'s exit code and the terminal verdict block both derive
+     * from, so the two can never disagree. Always present, empty on a
+     * fully clean run (including refusal paths, where it reflects
+     * whatever partial data was collected before the refusal).
+     */
+    verdict: VerdictItem[];
 }
 export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
 export declare function runOnboard(opts?: RunOnboardOptions): Promise<{