agent-trellis 0.1.0 → 0.3.0

package/dist/commands/rollback.js

@@ -0,0 +1,201 @@
+/**
+ * `trellis rollback` — restores exactly what one recorded backup run
+ * changed (trellis-backup-rollback). Every operation is checked against
+ * its target path's *current* state before touching anything: if the
+ * path still matches what the run itself left behind, it's restored; if
+ * something else has touched it since, that's a conflict, reported and
+ * left untouched — same "verify, never guess" posture `sync`/`mcp sync`
+ * already hold themselves to for every other kind of conflict.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { readlink, rm, symlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { backupsRoot } from "../lib/backup.js";
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** Newest first — run ids are ISO-timestamp-prefixed, so lexical sort is
+ * chronological sort. */
+export function listBackups(homeDir = homedir()) {
+    const root = backupsRoot(homeDir);
+    if (!existsSync(root))
+        return [];
+    const runIds = readdirSync(root).sort().reverse();
+    const summaries = [];
+    for (const runId of runIds) {
+        const manifest = tryLoadManifest(homeDir, runId);
+        if (!manifest)
+            continue;
+        summaries.push({ runId, command: manifest.command, startedAt: manifest.startedAt, operationCount: manifest.operations.length });
+    }
+    return summaries;
+}
+function tryLoadManifest(homeDir, runId) {
+    const manifestPath = join(backupsRoot(homeDir), runId, "manifest.json");
+    if (!existsSync(manifestPath))
+        return undefined;
+    return JSON.parse(readFileSync(manifestPath, "utf-8"));
+}
+export function loadManifest(homeDir, runId) {
+    const manifest = tryLoadManifest(homeDir, runId);
+    if (!manifest) {
+        throw new Error(`No backup run "${runId}" found under ${backupsRoot(homeDir)}`);
+    }
+    return manifest;
+}
+function resolveRunId(homeDir, requested) {
+    if (requested)
+        return requested;
+    const [mostRecent] = listBackups(homeDir);
+    if (!mostRecent) {
+        throw new Error(`No backup runs found under ${backupsRoot(homeDir)} — nothing to roll back`);
+    }
+    return mostRecent.runId;
+}
+async function currentLinkTarget(path) {
+    try {
+        return await readlink(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function planOperation(homeDir, runId, op) {
+    const runDir = join(backupsRoot(homeDir), runId);
+    switch (op.kind) {
+        case "file-create":
+        case "file-overwrite": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            const currentHash = sha256(readFileSync(op.path, "utf-8"));
+            if (currentHash !== op.afterHash) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+            }
+            if (op.kind === "file-create") {
+                return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
+            }
+            return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeFile)})` };
+        }
+        case "symlink-create":
+        case "symlink-repair": {
+            const current = await currentLinkTarget(op.path);
+            if (current === undefined) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            if (current !== op.afterLinkTarget) {
+                return { action: "conflict", path: op.path, description: `${op.path} points somewhere else now — left untouched` };
+            }
+            if (op.kind === "symlink-create") {
+                return { action: "restore", path: op.path, description: `remove ${op.path} (created by this run)` };
+            }
+            return { action: "restore", path: op.path, description: `repoint ${op.path} back to ${op.beforeLinkTarget}` };
+        }
+        case "symlink-remove": {
+            if (existsSync(op.path)) {
+                return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
+            }
+            return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
+        }
+    }
+}
+export async function collectRollbackPlan(homeDirInput, runIdInput) {
+    const homeDir = homeDirInput ?? homedir();
+    const runId = resolveRunId(homeDir, runIdInput);
+    const manifest = loadManifest(homeDir, runId);
+    const items = [];
+    for (const op of manifest.operations) {
+        items.push(await planOperation(homeDir, runId, op));
+    }
+    return { runId, items };
+}
+async function restoreOperation(homeDir, runId, op) {
+    const runDir = join(backupsRoot(homeDir), runId);
+    switch (op.kind) {
+        case "file-create":
+            rmSync(op.path, { force: true });
+            return;
+        case "file-overwrite":
+            writeFileSync(op.path, readFileSync(join(runDir, op.beforeFile), "utf-8"));
+            return;
+        case "symlink-create":
+            await rm(op.path, { force: true });
+            return;
+        case "symlink-repair":
+            await rm(op.path, { force: true });
+            await symlink(op.beforeLinkTarget, op.path);
+            return;
+        case "symlink-remove":
+            await symlink(op.beforeLinkTarget, op.path);
+            return;
+    }
+}
+export async function applyRollbackPlan(homeDir, runId, manifest, items) {
+    const restorePaths = new Set(items.filter((i) => i.action === "restore").map((i) => i.path));
+    for (const op of manifest.operations) {
+        if (!restorePaths.has(op.path))
+            continue;
+        await restoreOperation(homeDir, runId, op);
+    }
+}
+export async function runRollback(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (opts.list) {
+        const runs = listBackups(homeDir);
+        if (opts.json) {
+            console.log(JSON.stringify(runs, null, 2));
+        }
+        else {
+            printList(runs);
+        }
+        return { exitCode: 0 };
+    }
+    let report;
+    try {
+        report = await collectRollbackPlan(homeDir, opts.runId);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        const manifest = loadManifest(homeDir, report.runId);
+        await applyRollbackPlan(homeDir, report.runId, manifest, report.items);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report, opts.dryRun ?? false);
+    }
+    const hasConflict = report.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+function printList(runs) {
+    if (runs.length === 0) {
+        console.log("No backup runs found under ~/.trellis/backups/.");
+        return;
+    }
+    for (const run of runs) {
+        console.log(`${run.runId} — ${run.command}, ${run.operationCount} operation(s), ${run.startedAt}`);
+    }
+}
+export function printReport(report, dryRun) {
+    if (dryRun)
+        console.log("[dry run]");
+    console.log(`rollback ${report.runId}`);
+    const restored = report.items.filter((i) => i.action === "restore");
+    const conflicts = report.items.filter((i) => i.action === "conflict");
+    const alreadyReverted = report.items.filter((i) => i.action === "already-reverted");
+    if (report.items.length === 0) {
+        console.log("  nothing recorded in this run");
+        return;
+    }
+    const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+    console.log(`${icon} ${restored.length} restored, ${conflicts.length} conflict(s), ${alreadyReverted.length} already reverted`);
+    for (const item of [...restored, ...conflicts, ...alreadyReverted]) {
+        console.log(`   - [${item.action}] ${item.description}`);
+    }
+}

package/dist/commands/secretsAudit.d.ts

@@ -17,6 +17,9 @@ export interface RunSecretsAuditOptions {
     /** Same test/sandbox-only seam as every other command — never a CLI
      * flag. See docs/architecture.md's testing philosophy. */
     homeDir?: string;
+    /** Onboard-only seam — see RunSyncOptions.managedAgents. Never a CLI
+     * flag. */
+    managedAgents?: readonly AgentId[];
 }
 export interface SecretsFinding {
     /** "environment" for `missing-env-value` — that check isn't scoped to
@@ -33,3 +36,7 @@ export declare function collectSecretsAuditReport(opts?: RunSecretsAuditOptions)
 export declare function runSecretsAudit(opts?: RunSecretsAuditOptions): Promise<{
     exitCode: number;
 }>;
+/** Exported so `onboard` prints a secrets-audit report identically to
+ * running `secrets audit` standalone, instead of a second, easily-drifting
+ * copy of this formatting. */
+export declare function printReport(report: SecretsAuditReport): void;

package/dist/commands/secretsAudit.js

@@ -20,15 +20,18 @@ import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames } from "../lib/envVarNames.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
-function auditedAgents(homeDir) {
-    return [
+/** Only agents in `managedAgents` — a present-but-unmanaged agent's config
+ * file is never even read (trellis-managed-agents), same restriction as
+ * `sync`/`mcp sync`. pi has no static, generated MCP config file to audit
+ * regardless of management — its bridge reads mcp/servers.yaml directly at
+ * its own runtime (P4). See design.md Non-Goals in trellis-secrets-audit-p3. */
+function auditedAgents(homeDir, managedAgents) {
+    const all = [
         { id: "claude-code", probe: () => new ClaudeCodeAdapter(homeDir).probe(), configPath: (h) => join(h, ".claude.json"), extractNames: extractJsonEnvVarNames },
         { id: "codex", probe: () => new CodexAdapter(homeDir).probe(), configPath: (h) => join(h, ".codex", "config.toml"), extractNames: extractTomlEnvVarNames },
         { id: "kiro", probe: () => new KiroAdapter(homeDir).probe(), configPath: (h) => join(h, ".kiro", "settings", "mcp.json"), extractNames: extractJsonEnvVarNames },
-        // pi has no static, generated MCP config file to audit — its bridge
-        // reads mcp/servers.yaml directly at its own runtime (P4). See
-        // design.md Non-Goals in trellis-secrets-audit-p3.
     ];
+    return all.filter((a) => managedAgents.includes(a.id));
 }
 /**
  * Not scoped to any agent, present or not — a name that can't resolve is
@@ -72,8 +75,9 @@ function auditFile(agent, file, content, policy, extractNames) {
 export async function collectSecretsAuditReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     const canonical = loadCanonicalSource(homeDir);
+    const managedAgents = opts.managedAgents ?? canonical.managedAgents;
     const findings = [];
-    for (const agent of auditedAgents(homeDir)) {
+    for (const agent of auditedAgents(homeDir, managedAgents)) {
         const probeResult = await agent.probe();
         if (!probeResult.present)
             continue;
@@ -103,7 +107,10 @@ export async function runSecretsAudit(opts = {}) {
     }
     return { exitCode: report.findings.length > 0 ? 1 : 0 };
 }
-function printReport(report) {
+/** Exported so `onboard` prints a secrets-audit report identically to
+ * running `secrets audit` standalone, instead of a second, easily-drifting
+ * copy of this formatting. */
+export function printReport(report) {
     if (report.findings.length === 0) {
         console.log("✅ no findings — every present agent's real config and every declared env var passed all checks");
         return;

package/dist/commands/skill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import type { AgentId } from "../core/types.js";
+export interface SkillListEntry {
+    name: string;
+    scope: readonly AgentId[];
+}
+export declare function collectSkillList(homeDir?: string): SkillListEntry[];
+export declare function runSkillList(opts?: {
+    homeDir?: string;
+    json?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillAddAction = "create" | "already-present" | "conflict" | "invalid-source";
+export interface SkillAddPlan {
+    name: string;
+    action: SkillAddAction;
+    detail: string;
+    sourceDir?: string;
+}
+export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
+export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string): void;
+export declare function runSkillAdd(name: string, fromPath: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillRemoveAction = "removed" | "not-found";
+export interface SkillRemovePlan {
+    name: string;
+    action: SkillRemoveAction;
+}
+export declare function collectSkillRemovePlan(name: string, homeDir?: string): SkillRemovePlan;
+export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string): void;
+export declare function runSkillRemove(name: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};

package/dist/commands/skill.js

@@ -0,0 +1,104 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { findSkillFile } from "../lib/skillFile.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
+export function collectSkillList(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return canonical.skills.map((skill) => ({
+        name: skill.name,
+        scope: resolveScope(skill.scope, canonical.managedAgents),
+    }));
+}
+export function runSkillList(opts = {}) {
+    const entries = collectSkillList(opts.homeDir ?? homedir());
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    else if (entries.length === 0) {
+        console.log("No skills in canonical source yet.");
+    }
+    else {
+        for (const { name, scope } of entries) {
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+        }
+    }
+    return { exitCode: 0 };
+}
+export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    const skillFile = findSkillFile(fromPath);
+    if (!skillFile) {
+        return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
+    }
+    if (!skillFile.caseCorrect) {
+        return { name, action: "invalid-source", detail: `${fromPath} has skill.md, not case-correct SKILL.md — fix the case first` };
+    }
+    const canonicalDir = join(homeDir, ".trellis", "skills", name);
+    switch (decideDirImport(fromPath, canonicalDir)) {
+        case "create":
+            return { name, action: "create", detail: `will copy from ${fromPath}`, sourceDir: fromPath };
+        case "already-present":
+            return { name, action: "already-present", detail: "canonical content is already byte-identical" };
+        case "conflict":
+            return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+    }
+}
+export function applySkillAddPlan(plan, homeDir = homedir()) {
+    if (plan.action !== "create" || !plan.sourceDir)
+        return;
+    const dest = join(homeDir, ".trellis", "skills", plan.name);
+    mkdirSync(dest, { recursive: true });
+    cpSync(plan.sourceDir, dest, { recursive: true });
+}
+export function runSkillAdd(name, fromPath, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    if (!opts.dryRun && plan.action === "create") {
+        applySkillAddPlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+    }
+    return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
+}
+export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    const dir = join(homeDir, ".trellis", "skills", name);
+    return { name, action: existsSync(dir) ? "removed" : "not-found" };
+}
+export function applySkillRemovePlan(plan, homeDir = homedir()) {
+    if (plan.action !== "removed")
+        return;
+    rmSync(join(homeDir, ".trellis", "skills", plan.name), { recursive: true, force: true });
+}
+export function runSkillRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillRemovePlan(name, homeDir);
+    if (!opts.dryRun) {
+        applySkillRemovePlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else if (plan.action === "not-found") {
+        console.error(`"${name}" is not a canonical skill — nothing to remove.`);
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}removed skill "${name}" from canonical source.`);
+    }
+    return { exitCode: plan.action === "not-found" ? 1 : 0 };
+}

package/dist/commands/sync.d.ts

@@ -7,6 +7,7 @@
  */
 import type { AdapterPlanItem } from "../core/adapter.js";
 import type { AgentId } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
 export interface RunSyncOptions {
     /** Omit to sync both. */
     target?: "skills" | "instructions";
@@ -21,6 +22,18 @@ export interface RunSyncOptions {
     homeDir?: string;
     /** Compute and report the plan without calling adapter.apply(). */
     dryRun?: boolean;
+    /** Onboard-only seam: preview/act against a managed-agent set that
+     * hasn't been written to `~/.trellis/managed.yaml` yet (its own
+     * `--dry-run` still needs a real plan against the set the user is
+     * about to select, not the one already on disk). Never a CLI flag —
+     * standalone `trellis sync` always reads canonical's own. */
+    managedAgents?: readonly AgentId[];
+    /** Onboard-only seam (trellis-backup-rollback): a session already open
+     * for the whole onboard run, so one `trellis rollback` undoes every
+     * stage together instead of one per stage. When given, this function
+     * does NOT finalize it — only whoever opened it does. Never a CLI
+     * flag — standalone `trellis sync` always opens and finalizes its own. */
+    backupSession?: BackupSession;
 }
 export interface AgentSyncReport {
     agent: AgentId;

package/dist/commands/sync.js

@@ -11,14 +11,35 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
-function buildAdapters(homeDir) {
-    return [new ClaudeCodeAdapter(homeDir), new CodexAdapter(homeDir), new KiroAdapter(homeDir), new PiAdapter(homeDir)];
+import { openBackupSession } from "../lib/backup.js";
+const ADAPTER_FACTORY = {
+    "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
+    codex: (homeDir) => new CodexAdapter(homeDir),
+    kiro: (homeDir) => new KiroAdapter(homeDir),
+    pi: (homeDir) => new PiAdapter(homeDir),
+};
+/** Only agents in `canonical.managedAgents` — an agent present on this
+ * machine but not managed gets no adapter at all, not a zero-item plan
+ * (trellis-managed-agents). */
+function buildAdapters(homeDir, managedAgents) {
+    return managedAgents.map((id) => ADAPTER_FACTORY[id](homeDir));
 }
 export async function collectSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const canonical = loadCanonicalSource(homeDir);
+    const loaded = loadCanonicalSource(homeDir);
+    // A single override point, not two: every downstream read of "who's
+    // managed" — the adapter list built here AND each adapter's own
+    // in-scope filtering via `canonical.managedAgents` — must agree, or a
+    // dry-run preview computed against a not-yet-written managed set would
+    // silently diverge from what onboard's own outer adapter list acted on.
+    const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
-    for (const adapter of buildAdapters(homeDir)) {
+    // Own session only when the caller didn't share one (trellis-backup-
+    // rollback D2) — dry-run never opens or writes one, there's nothing to
+    // record.
+    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
+    const backup = opts.backupSession ?? ownSession;
+    for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
         if (!probeResult.present) {
             reports.push({ agent: adapter.id, present: false, items: [] });
@@ -40,10 +61,11 @@ export async function collectSyncReport(opts = {}) {
             items = items.filter((item) => item.kind === kind);
         }
         if (!opts.dryRun) {
-            await adapter.apply(items);
+            await adapter.apply(items, backup);
         }
         reports.push({ agent: adapter.id, present: true, items });
     }
+    ownSession?.finalize();
     return { reports };
 }
 export async function runSync(opts = {}) {
@@ -70,6 +92,10 @@ export async function runSync(opts = {}) {
 export function printReport(report, dryRun) {
     if (dryRun)
         console.log("[dry run]");
+    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) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);

package/dist/core/adapter.d.ts

@@ -10,6 +10,7 @@
  */
 import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
 import { resolveScope } from "./types.js";
+import type { BackupSession } from "../lib/backup.js";
 export interface AdapterProbeResult {
     present: boolean;
     version?: string;
@@ -19,14 +20,18 @@ export interface AdapterPlanItem {
     /**
      * "create" also covers repair (wrong symlink target, or an MCP server
      * definition that differs from canonical); "remove" is the delete half
-     * for skills/instructions — a Trellis-managed symlink whose canonical
-     * entry is gone or was just scoped away from this agent. MCP server
-     * items never use "remove" (see `kind: "mcp"` below — no ownership
-     * marker exists yet to make that provably safe, trellis-mcp-sync-p2
-     * design.md D7). "conflict" is either a real, non-symlink path
-     * occupying a spot Trellis would otherwise touch, or an MCP server
-     * refused for a collision/secrets-guard reason — reported, never acted
-     * on. See `plan()`'s doc below.
+     * for skills/instructions (a Trellis-managed symlink whose canonical
+     * entry is gone or was just scoped away from this agent) and, since
+     * trellis-mcp-lifecycle-parity, for MCP servers too — but only when
+     * `src/lib/mcpOwnership.ts`'s ledger proves the agent's current native
+     * entry is still exactly what Trellis itself last wrote there
+     * (mcpPlan.ts's own D7 reasoning: a bare TOML/JSON key has no ownership
+     * marker on its own, so this ledger is what makes removal provably
+     * safe instead of guessing). A name whose native content has since
+     * been hand-edited is left alone, never removed. "conflict" is either
+     * a real, non-symlink path occupying a spot Trellis would otherwise
+     * touch, or an MCP server refused for a collision/secrets-guard
+     * reason — reported, never acted on. See `plan()`'s doc below.
      */
     action: "create" | "remove" | "conflict";
     /** Lets `trellis sync skills` / `trellis sync instructions` /
@@ -63,6 +68,12 @@ export interface AdapterPlanItem {
         name: string;
         def: McpServerDef;
     };
+    /** Only set (and only meaningful) when `kind === "mcp"` and
+     * `action === "remove"`: the server name to delete from `target` via
+     * that agent's own mechanism. */
+    mcpRemove?: {
+        name: string;
+    };
     /** Only set (and only meaningful) when `kind === "kiro-approved-env-vars"`
      * and `action === "create"`: the full, already-deduplicated array to
      * write as `kiroAgent.mcpApprovedEnvVars` — a union of whatever was
@@ -91,7 +102,7 @@ export interface TrellisAdapter {
      * entries, MCP servers) through its `scope` field before planning any
      * change for it — an item scoped away from `this.id` must produce no
      * plan item at all, not a plan item that's later skipped. Use
-     * `resolveScope(item.scope).includes(this.id)`. See docs/architecture.md
+     * `isInScope(this.id, item.scope, canonical.managedAgents)`. See docs/architecture.md
      * "Private / agent-specific capabilities" — the default (`scope`
      * omitted) is "all agents," so this filter is a no-op for the common
      * case and only actually excludes anything when a capability was
@@ -123,11 +134,17 @@ export interface TrellisAdapter {
      * item in the same plan from being applied. The caller (e.g. `trellis
      * sync`) is responsible for surfacing conflicts and failing the overall
      * command (non-zero exit), not `apply()` per item.
+     *
+     * MUST perform every real write through `backup` (`writeFile`/
+     * `createSymlink`/`repairSymlink`/`removeSymlink`), never directly —
+     * `backup` is the only thing that may call `fs`/`fs/promises` to
+     * mutate a path this method touches (trellis-backup-rollback design.md
+     * D3/D5). Mandatory, not optional: the caller always has one open.
      */
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     /** Re-read the agent's own state and confirm it matches canonical. */
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }
 /** Convenience used by every adapter's `plan()` — see the scope-filtering
  * obligation documented above. */
-export declare function isInScope(id: AgentId, scope: Parameters<typeof resolveScope>[0]): boolean;
+export declare function isInScope(id: AgentId, scope: Parameters<typeof resolveScope>[0], managedAgents: readonly AgentId[]): boolean;

package/dist/core/adapter.js

@@ -11,6 +11,6 @@
 import { resolveScope } from "./types.js";
 /** Convenience used by every adapter's `plan()` — see the scope-filtering
  * obligation documented above. */
-export function isInScope(id, scope) {
-    return resolveScope(scope).includes(id);
+export function isInScope(id, scope, managedAgents) {
+    return resolveScope(scope, managedAgents).includes(id);
 }

package/dist/core/canonical.d.ts

@@ -4,7 +4,31 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { CanonicalSource } from "./types.js";
+import type { CanonicalSource, McpServerDef } from "./types.js";
+/**
+ * The on-disk shape for one server entry — `static_env` (snake_case, like
+ * every other multi-word key across `.trellis/*.yaml`) is translated to
+ * `McpServerDef.staticEnv` (camelCase) below; every other field happens
+ * to already be a single word, so no server-def field needed this
+ * treatment before (trellis-mcp-static-env-and-disabled-servers).
+ */
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv"> & {
+    static_env?: Record<string, string>;
+};
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written YAML never gets a literal `null`
+ * for an omitted optional. */
+export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;
+export type ServersYamlWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use
@@ -14,3 +38,4 @@ import type { CanonicalSource } from "./types.js";
  * parameter does not weaken.
  */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
+export {};