agent-trellis 0.7.0 → 0.8.2

package/dist/adapters/mcpPlan.js

@@ -17,21 +17,32 @@
  * ever returns create/repair + refuse.
  */
 import { isInScope } from "../core/adapter.js";
+import { capabilityDeliveryForAgent } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
-export const GATEWAY_ENTRY_NAME = "trellis-gateway";
+export const GATEWAY_ENTRY_NAME = "trellis";
+export const LEGACY_GATEWAY_ENTRY_NAME = "trellis-gateway";
+export const RUNTIME_ENTRY_NAME = "trellis";
+export const LEGACY_RUNTIME_ENTRY_NAME = "trellis-runtime";
 /** The command an agent spawns in gateway mode. Bare `trellis` rather than
  * an absolute path: the entry has to keep working across reinstalls and
  * version bumps, and every agent resolves it through the same PATH the
  * user installed the CLI onto. */
 export const GATEWAY_COMMAND = "trellis";
+export const RUNTIME_COMMAND = "trellis";
+export function isOAuthMcpServer(def) {
+    return def.auth === "oauth";
+}
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,
  * letting some agents stay in direct or hub mode.
  */
 export function isGatewayAgent(agentId, mcp, managedAgents) {
+    const route = mcp.routes?.[agentId];
+    if (route)
+        return route.mode === "gateway";
     const gateway = mcp.gateway;
     if (!gateway?.enabled)
         return false;
@@ -39,6 +50,16 @@ export function isGatewayAgent(agentId, mcp, managedAgents) {
         return gateway.agents.includes(agentId);
     return managedAgents.includes(agentId);
 }
+function routeForAgent(agentId, mcp, managedAgents) {
+    const explicit = mcp.routes?.[agentId];
+    if (explicit)
+        return explicit;
+    if (isGatewayAgent(agentId, mcp, managedAgents))
+        return { mode: "gateway" };
+    if (mcp.hub)
+        return { mode: "hub" };
+    return { mode: "direct" };
+}
 const CODEX_STDIO_URL_CRASH_NOTE = ' On Codex specifically, this crashes the entire process at startup ("url is not supported for stdio"), not just this one server — see docs/research.md.';
 function collisionMessage(name, agentId) {
     return `refusing to write MCP server "${name}": also appears in known_host_injected.${agentId === "codex" ? CODEX_STDIO_URL_CRASH_NOTE : ""}`;
@@ -116,45 +137,122 @@ function findUnresolvedEnvName(def, policy) {
     return names.find((name) => !resolved[name]);
 }
 export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+    const route = routeForAgent(agentId, mcp, managedAgents);
+    const runtimeEnabled = capabilityDeliveryForAgent(agentId, mcp) !== "native";
     // Checked before `hub`: only one entry can be "the" MCP entry for an
     // agent, and gateway is the newer, purpose-built path (design.md D6).
     // `hub` stays available, unchanged, for anyone pointing an agent at an
     // externally-operated endpoint — including a different agent in the
     // same canonical source.
-    if (isGatewayAgent(agentId, mcp, managedAgents)) {
-        if (mcp.knownHostInjected.includes(GATEWAY_ENTRY_NAME)) {
+    if (route.mode === "gateway") {
+        const entryName = runtimeEnabled ? RUNTIME_ENTRY_NAME : GATEWAY_ENTRY_NAME;
+        if (mcp.knownHostInjected.includes(entryName)) {
             return {
                 desired: [],
-                conflicts: [{ name: GATEWAY_ENTRY_NAME, message: collisionMessage(GATEWAY_ENTRY_NAME, agentId), remediation: collisionRemediation(GATEWAY_ENTRY_NAME) }],
+                conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isOAuthMcpServer);
+        // Every ordinary per-server check (enabled, scope, literal secrets,
+        // unresolved env names, Codex's header shape) still runs at gateway
+        // startup. OAuth servers are the deliberate exception: they are written
+        // as direct entries so the gateway never owns their client connection.
         // Every per-server check (enabled, scope, literal secrets, unresolved
         // env names, Codex's header shape) still runs — but at gateway
         // *startup*, inside the subcommand, since no adapter sees an
         // individual server in this mode (design.md D6).
         return {
-            desired: [{ name: GATEWAY_ENTRY_NAME, def: { transport: "stdio", command: GATEWAY_COMMAND, args: ["mcp-gateway", "--agent", agentId] } }],
-            conflicts: [],
+            desired: [{
+                    name: entryName,
+                    def: {
+                        transport: "stdio",
+                        command: runtimeEnabled ? RUNTIME_COMMAND : GATEWAY_COMMAND,
+                        args: [runtimeEnabled ? "mcp-runtime" : "mcp-gateway", "--agent", agentId],
+                    },
+                }, ...oauth.desired],
+            conflicts: oauth.conflicts,
         };
     }
-    if (mcp.hub) {
+    if (route.mode === "hub") {
+        if (!mcp.hub) {
+            return {
+                desired: [],
+                conflicts: [{
+                        name: HUB_ENTRY_NAME,
+                        message: `cannot resolve hub route "${agentId}": canonical mcp.hub.url is not configured`,
+                        remediation: `configure mcp.hub.url or choose direct/gateway mode for ${agentId}`,
+                    }],
+            };
+        }
         if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
             return {
                 desired: [],
                 conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId), remediation: collisionRemediation(HUB_ENTRY_NAME) }],
             };
         }
-        return { desired: [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }], conflicts: [] };
+        if (route.servers) {
+            return {
+                desired: [],
+                conflicts: [{
+                        name: HUB_ENTRY_NAME,
+                        message: `cannot restrict external hub route "${agentId}" to individual MCP servers: the hub owns its upstream set`,
+                        remediation: `remove the servers list from the ${agentId} hub route, or use direct/gateway mode for per-server selection`,
+                    }],
+            };
+        }
+        const desired = [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }];
+        if (runtimeEnabled) {
+            if (mcp.knownHostInjected.includes(RUNTIME_ENTRY_NAME)) {
+                return {
+                    desired: [],
+                    conflicts: [{ name: RUNTIME_ENTRY_NAME, message: collisionMessage(RUNTIME_ENTRY_NAME, agentId), remediation: collisionRemediation(RUNTIME_ENTRY_NAME) }],
+                };
+            }
+            // The runtime provides Trellis-owned capabilities here. The external
+            // hub remains the upstream MCP edge; the runtime does not connect to
+            // canonical upstreams a second time for this route.
+            desired.push({
+                name: RUNTIME_ENTRY_NAME,
+                def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
+            });
+        }
+        return { desired, conflicts: [] };
+    }
+    if (runtimeEnabled) {
+        if (mcp.knownHostInjected.includes(RUNTIME_ENTRY_NAME)) {
+            return {
+                desired: [],
+                conflicts: [{ name: RUNTIME_ENTRY_NAME, message: collisionMessage(RUNTIME_ENTRY_NAME, agentId), remediation: collisionRemediation(RUNTIME_ENTRY_NAME) }],
+            };
+        }
+        // Runtime mode owns the agent-facing MCP edge. It resolves the same
+        // direct/gateway-compatible upstream route at startup, so native
+        // per-server entries are not duplicated here.
+        return {
+            desired: [{
+                    name: RUNTIME_ENTRY_NAME,
+                    def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
+                }],
+            conflicts: [],
+        };
     }
+    return planDirectServers(agentId, mcp, managedAgents, policy, route);
+}
+function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
         if (def.enabled === false) {
             continue;
         }
+        if (filter && !filter(def))
+            continue;
         if (!isInScope(agentId, def.agents, managedAgents)) {
             continue;
         }
+        if (route.servers && !route.servers.includes(name)) {
+            continue;
+        }
         if (mcp.knownHostInjected.includes(name)) {
             conflicts.push({ name, message: collisionMessage(name, agentId), remediation: collisionRemediation(name) });
             continue;

package/dist/adapters/pi.js

@@ -9,13 +9,31 @@
  * mechanism from every other agent's config-generation adapter, but the
  * same symlink create/repair/remove machinery as skills/instructions.
  */
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { isInScope } from "../core/adapter.js";
+import { usesNativeCapabilityDelivery } from "../core/types.js";
 import * as piProbe from "../probes/pi.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
 const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
+/**
+ * A source-checkout bridge can survive a switch to the packaged CLI. Adopt it
+ * only when it has the Trellis bridge artifact shape and is byte-identical
+ * to the bundle this installation would write. This is intentionally not a
+ * general symlink ownership rule.
+ */
+function isEquivalentTrellisBridge(existingTarget, desiredTarget) {
+    if (!existingTarget.endsWith(`${sep}${join("dist", "pi-bridge", "bundle.js")}`))
+        return false;
+    try {
+        return readFileSync(existingTarget).equals(readFileSync(desiredTarget));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The bundled bridge file's location — always `<repo-root>/dist/pi-bridge/
  * bundle.js`, never `~/.trellis/` (it's Trellis's own packaged code, not a
@@ -56,7 +74,7 @@ export class PiAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const agentDir = join(this.homeDir, ".pi", "agent");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
+            .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: join(agentDir, "skills"),
@@ -79,6 +97,7 @@ export class PiAdapter {
             // (design.md D2), same role `canonicalRoot` plays for skills.
             canonicalRoot: dirname(bridgeFile),
             kind: "extension",
+            adoptExistingSymlink: isEquivalentTrellisBridge,
         });
         return [...skillItems, ...instructionsItems, ...extensionItems];
     }
@@ -91,7 +110,7 @@ export class PiAdapter {
             return { ok: false, mismatches: ["pi is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, s.scope, canonical.managedAgents)).map((s) => s.name));
         const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
         for (const name of desiredNames) {
             if (!actualSkills.has(name)) {

package/dist/adapters/symlinkPlan.d.ts

@@ -12,6 +12,12 @@ export interface DesiredSymlink {
     /** Absolute path the symlink should point at (inside `canonicalRoot`). */
     target: string;
 }
+/**
+ * A narrowly-scoped escape hatch for artifacts that Trellis can identify
+ * across installation roots. The default ownership rule remains path-based;
+ * callers must opt in explicitly for a particular artifact kind.
+ */
+export type ExistingSymlinkAdoption = (existingTarget: string, desiredTarget: string) => boolean;
 /**
  * `rootDir` is the directory entries are named directly under (e.g.
  * `~/.claude/skills`, or the instructions file's own parent directory when
@@ -28,6 +34,7 @@ export declare function planSymlinks(opts: {
     desired: DesiredSymlink[];
     canonicalRoot: string;
     kind: "skill" | "instructions" | "extension";
+    adoptExistingSymlink?: ExistingSymlinkAdoption;
 }): AdapterPlanItem[];
 /** Executes a `planSymlinks` result through the run's backup session
  * (trellis-backup-rollback) — every create/repair/remove is recorded

package/dist/adapters/symlinkPlan.js

@@ -4,9 +4,9 @@
  * trellis-sync-p1/specs/skill-instructions-sync/spec.md) — built once,
  * reused by every adapter rather than reimplemented per agent.
  */
-import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { lstatSync, readdirSync, readlinkSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { isSymlinkTo } from "../lib/fsIdentity.js";
 import { currentLinkTarget } from "../lib/backup.js";
 function isUnderRoot(path, root) {
@@ -29,7 +29,7 @@ function isUnderRoot(path, root) {
  * case this removal path exists to catch.
  */
 export function planSymlinks(opts) {
-    const { rootDir, desired, kind } = opts;
+    const { rootDir, desired, kind, adoptExistingSymlink } = opts;
     const items = [];
     const desiredNames = new Set(desired.map((d) => d.name));
     const canonicalRootResolved = resolve(opts.canonicalRoot);
@@ -38,8 +38,15 @@ export function planSymlinks(opts) {
         if (isSymlinkTo(path, target)) {
             continue; // already correct — no-op
         }
-        if (existsSync(path)) {
-            const isSymlink = lstatSync(path).isSymbolicLink();
+        // lstat sees dangling links too; existsSync would treat them as absent
+        // and bypass the foreign-link protection below.
+        const existing = lstatSync(path, { throwIfNoEntry: false });
+        if (existing) {
+            const isSymlink = existing.isSymbolicLink();
+            const rawExistingTarget = isSymlink ? readlinkSync(path) : undefined;
+            const resolvedExistingTarget = rawExistingTarget === undefined
+                ? undefined
+                : resolve(dirname(path), rawExistingTarget);
             // A symlink whose stored target resolves outside canonicalRoot is
             // owned by something else (e.g. a user's own dotfile-management
             // setup) — repairing it as if it were a stale Trellis entry would
@@ -47,14 +54,16 @@ export function planSymlinks(opts) {
             // symlink Trellis itself left pointing at a since-removed canonical
             // entry is broken by construction and must still be treated as
             // ours to repair, not thrown out to a conflict by a realpath error.
-            const isForeign = isSymlink && !isUnderRoot(readlinkSync(path), canonicalRootResolved);
+            const isForeign = resolvedExistingTarget !== undefined
+                && !isUnderRoot(resolvedExistingTarget, canonicalRootResolved)
+                && adoptExistingSymlink?.(resolvedExistingTarget, target) !== true;
             if (!isSymlink || isForeign) {
                 items.push({
                     action: "conflict",
                     kind,
                     target: path,
                     description: isForeign
-                        ? `${path} exists as a symlink to ${readlinkSync(path)}, not owned by Trellis — left untouched`
+                        ? `${path} exists as a symlink to ${rawExistingTarget}, not owned by Trellis — left untouched`
                         : `${path} exists and is not a Trellis-managed symlink — left untouched`,
                     remediation: isForeign
                         ? `remove the existing symlink at ${path} if you want Trellis to manage it, then re-run sync — otherwise leave it, Trellis will not touch it`

package/dist/adapters/zcode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime-first ZCode adapter.
+ *
+ * ZCode's native `~/.agents/skills` scan prevents scope-safe native delivery,
+ * so Runtime-only delivery uses one MCP Runtime edge and turns off the two
+ * native Skill switches through a ledger-backed, reversible config change.
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+import type { BackupSession } from "../lib/backup.js";
+export declare class ZcodeAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    private readonly env;
+    readonly name = "ZCode";
+    readonly id: "zcode";
+    constructor(homeDir?: string, env?: NodeJS.ProcessEnv);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}

package/dist/adapters/zcode.js

@@ -0,0 +1,234 @@
+/**
+ * Runtime-first ZCode adapter.
+ *
+ * ZCode's native `~/.agents/skills` scan prevents scope-safe native delivery,
+ * so Runtime-only delivery uses one MCP Runtime edge and turns off the two
+ * native Skill switches through a ledger-backed, reversible config change.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isInScope } from "../core/adapter.js";
+import { capabilityDeliveryForAgent, usesNativeCapabilityDelivery } from "../core/types.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { renderJsonServerEntry } from "./jsonMcp.js";
+import { LEGACY_GATEWAY_ENTRY_NAME, LEGACY_RUNTIME_ENTRY_NAME, resolveMcpPlan } from "./mcpPlan.js";
+import { deepEqual } from "../lib/deepEqual.js";
+import { forgetOwned, loadMcpOwnership, ownedByAgent, recordOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { forgetZcodeSettingsOwnership, loadZcodeSettingsOwnership, saveZcodeSettingsOwnership } from "../lib/zcodeOwnership.js";
+import * as zcodeProbe from "../probes/zcode.js";
+function readConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function zcodeServers(parsed) {
+    return record(record(parsed?.mcp).servers);
+}
+function planZcodeMcp(opts) {
+    const { desired, conflicts } = resolveMcpPlan("zcode", opts.mcp, opts.managedAgents, opts.policy);
+    const existing = zcodeServers(opts.parsed);
+    const items = [];
+    for (const { name, def } of desired) {
+        const rendered = renderJsonServerEntry(def);
+        if (deepEqual(existing[name], rendered))
+            continue;
+        items.push({
+            action: "create",
+            kind: "mcp",
+            target: opts.configPath,
+            mcpWrite: { name, def },
+            description: `MCP server "${name}" ${existing[name] === undefined ? "created" : "updated"} in ${opts.configPath}`,
+        });
+    }
+    for (const conflict of conflicts) {
+        items.push({ action: "conflict", kind: "mcp", target: opts.configPath, description: conflict.message, ...(conflict.remediation ? { remediation: conflict.remediation } : {}) });
+    }
+    const desiredNames = new Set(desired.map((entry) => entry.name));
+    for (const [name, expected] of Object.entries(opts.ownership)) {
+        if (desiredNames.has(name))
+            continue;
+        if ((name === LEGACY_GATEWAY_ENTRY_NAME || name === LEGACY_RUNTIME_ENTRY_NAME) && desiredNames.has("trellis"))
+            continue;
+        if (existing[name] === undefined || !deepEqual(existing[name], expected))
+            continue;
+        items.push({
+            action: "remove",
+            kind: "mcp",
+            target: opts.configPath,
+            mcpRemove: { name },
+            description: `MCP server "${name}" removed from ${opts.configPath} — no longer in canonical`,
+        });
+    }
+    return items;
+}
+function applyZcodeMcp(parsed, items) {
+    const base = parsed ?? {};
+    const mcp = record(base.mcp);
+    const servers = { ...record(mcp.servers) };
+    for (const item of items) {
+        if (item.kind !== "mcp")
+            continue;
+        if (item.action === "create" && item.mcpWrite)
+            servers[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
+        if (item.action === "remove" && item.mcpRemove)
+            delete servers[item.mcpRemove.name];
+    }
+    return { ...base, mcp: { ...mcp, servers } };
+}
+function currentSkillControls(parsed) {
+    const features = record(parsed?.features);
+    const skills = record(parsed?.skills);
+    return {
+        featuresSkill: typeof features.skill === "boolean" ? features.skill : null,
+        skillsEnabled: typeof skills.enabled === "boolean" ? skills.enabled : null,
+    };
+}
+function applySkillControls(parsed, controls) {
+    const features = { ...record(parsed.features) };
+    const skills = { ...record(parsed.skills) };
+    if (controls.featuresSkill === null)
+        delete features.skill;
+    else
+        features.skill = controls.featuresSkill;
+    if (controls.skillsEnabled === null)
+        delete skills.enabled;
+    else
+        skills.enabled = controls.skillsEnabled;
+    return { ...parsed, features, skills };
+}
+export class ZcodeAdapter {
+    homeDir;
+    env;
+    name = "ZCode";
+    id = "zcode";
+    constructor(homeDir = homedir(), env = process.env) {
+        this.homeDir = homeDir;
+        this.env = env;
+    }
+    async probe() {
+        const snapshot = await zcodeProbe.probe(this.homeDir, { env: this.env });
+        return { present: snapshot.present, version: snapshot.version, ...(snapshot.diagnostics.length ? { detail: snapshot.diagnostics.join("; ") } : {}) };
+    }
+    async plan(canonical) {
+        const profile = zcodeProbe.resolveZcodeProfile(this.homeDir, this.env);
+        if (!profile)
+            return [];
+        const parsed = readConfig(profile.configPath);
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const runtimeOnly = capabilityDeliveryForAgent(this.id, canonical.mcp) === "mcp";
+        const items = [];
+        items.push(...planSymlinks({
+            rootDir: join(this.homeDir, ".zcode", "skills"),
+            desired: usesNativeCapabilityDelivery(this.id, canonical.mcp)
+                ? canonical.skills.filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents)).map((skill) => ({ name: skill.name, target: skill.dir }))
+                : [],
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        }));
+        items.push(...planSymlinks({
+            rootDir: join(this.homeDir, ".zcode"),
+            desired: [{ name: "AGENTS.md", target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        }));
+        items.push(...planZcodeMcp({
+            configPath: profile.configPath,
+            parsed,
+            mcp: canonical.mcp,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
+        }));
+        const current = currentSkillControls(parsed);
+        const ownership = loadZcodeSettingsOwnership(this.homeDir);
+        if (runtimeOnly && (current.featuresSkill !== false || current.skillsEnabled !== false)) {
+            items.push({
+                action: "create",
+                kind: "zcode-skill-control",
+                target: profile.configPath,
+                zcodeSkillControls: { featuresSkill: false, skillsEnabled: false, previous: current },
+                description: `native ZCode Skill discovery disabled in ${profile.configPath} for Runtime-only delivery`,
+            });
+        }
+        else if (!runtimeOnly && ownership?.configPath === profile.configPath && current.featuresSkill === false && current.skillsEnabled === false) {
+            items.push({
+                action: "remove",
+                kind: "zcode-skill-control",
+                target: profile.configPath,
+                zcodeSkillControls: { ...ownership.previous },
+                description: `previous native ZCode Skill settings restored in ${profile.configPath}`,
+            });
+        }
+        return items;
+    }
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"), backup);
+        const configItems = plan.filter((item) => (item.kind === "mcp" || item.kind === "zcode-skill-control") && (item.action === "create" || item.action === "remove"));
+        if (configItems.length === 0)
+            return;
+        const configPath = configItems[0].target;
+        let merged = applyZcodeMcp(readConfig(configPath), configItems);
+        const control = configItems.find((item) => item.kind === "zcode-skill-control")?.zcodeSkillControls;
+        if (control)
+            merged = applySkillControls(merged, control);
+        backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        let ownership = loadMcpOwnership(this.homeDir);
+        for (const item of configItems) {
+            if (item.kind !== "mcp")
+                continue;
+            if (item.action === "create" && item.mcpWrite)
+                ownership = recordOwned(ownership, this.id, item.mcpWrite.name, renderJsonServerEntry(item.mcpWrite.def));
+            if (item.action === "remove" && item.mcpRemove)
+                ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+        }
+        saveMcpOwnership(this.homeDir, ownership);
+        const controlItem = configItems.find((item) => item.kind === "zcode-skill-control");
+        if (controlItem?.action === "create" && controlItem.zcodeSkillControls?.previous) {
+            saveZcodeSettingsOwnership(this.homeDir, {
+                configPath,
+                managed: { featuresSkill: false, skillsEnabled: false },
+                previous: controlItem.zcodeSkillControls.previous,
+            });
+        }
+        else if (controlItem?.action === "remove") {
+            forgetZcodeSettingsOwnership(this.homeDir);
+        }
+    }
+    async verify(canonical) {
+        const snapshot = await zcodeProbe.probe(this.homeDir, { env: this.env });
+        if (!snapshot.present)
+            return { ok: false, mismatches: ["zcode is not present on this machine"] };
+        const profile = zcodeProbe.resolveZcodeProfile(this.homeDir, this.env);
+        if (!profile)
+            return { ok: false, mismatches: ["zcode profile cannot be selected"] };
+        const mismatches = [];
+        const desiredNativeSkills = canonical.skills
+            .filter((skill) => usesNativeCapabilityDelivery(this.id, canonical.mcp) && isInScope(this.id, skill.scope, canonical.managedAgents))
+            .map((skill) => skill.name);
+        const actualNativeSkills = new Set(snapshot.skillRoots.filter((root) => root.path === join(this.homeDir, ".zcode", "skills")).flatMap((root) => root.skills.map((skill) => skill.name)));
+        for (const name of desiredNativeSkills)
+            if (!actualNativeSkills.has(name))
+                mismatches.push(`skill "${name}" is missing on ZCode`);
+        const expectedMcp = planZcodeMcp({
+            configPath: profile.configPath,
+            parsed: readConfig(profile.configPath),
+            mcp: canonical.mcp,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership: ownedByAgent(loadMcpOwnership(this.homeDir), this.id),
+        }).filter((item) => item.action === "create" || item.action === "conflict");
+        mismatches.push(...expectedMcp.map((item) => item.description));
+        if (!snapshot.instructionsFile?.isSymlink || snapshot.instructionsFile.target !== canonical.instructionsFile)
+            mismatches.push("shared instructions are not linked into ~/.zcode/AGENTS.md");
+        if (capabilityDeliveryForAgent(this.id, canonical.mcp) === "mcp") {
+            const controls = currentSkillControls(readConfig(profile.configPath));
+            if (controls.featuresSkill !== false || controls.skillsEnabled !== false)
+                mismatches.push("native ZCode Skill discovery is still enabled during Runtime-only delivery");
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}