agent-trellis 0.1.0 → 0.2.0

package/README.md

@@ -45,14 +45,29 @@ trellis onboard
 ```
 
 Creates canonical source, detects which of Claude Code/Codex/Kiro/pi are on
-this machine, picks a base agent to migrate from (auto-selected if only one
-is present; prompts if more than one — pass `--agent <id>` to skip the
-prompt), then runs `migrate` and `sync`. If no agent is detected, it prints
-each supported agent's real install command/URL and stops — it never
-installs anything itself. Add `--dry-run` to preview the whole thing with
-zero writes.
+this machine, then resolves two independent choices: a **migration source**
+(read from — auto-selected if only one present agent has real content,
+prompted with a numbered choice if more than one, skippable if starting
+fresh; pass `--agent <id>` to skip the prompt) and a **managed set** (written
+to — zero or more agents, chosen explicitly; pass `--manage <ids>` or
+`--manage none` to skip the prompt). The source is **not** managed by
+default — importing from Claude Code doesn't mean Trellis starts writing to
+Claude Code too, unless you explicitly include it. Selecting an agent that
+isn't installed yet (e.g. pi) is itself the authorization to install it —
+one confirmation, then a real `npm install -g <package>`; Kiro has no CLI
+package and is refused with its download URL instead. Once resolved, it
+runs `migrate`, `sync`, `mcp sync`, and `secrets audit` against the managed
+set — the whole onboarding path in one command, no follow-up commands to
+type by hand. If no agent is detected, it prints each supported agent's
+real install command/URL and stops — it never installs anything on its own
+initiative. Add `--dry-run` to preview the whole thing with zero writes.
 
-**Or step by step** (what `onboard` is actually doing under the hood):
+```
+trellis onboard --agent claude-code --manage pi
+```
+
+**Or step by step** (what `onboard` is actually doing under the hood, if you
+want to run any one stage on its own):
 
 **Already using Claude Code, Codex, Kiro, or pi and want to migrate what you
 already have?**
@@ -65,24 +80,46 @@ already have?**
    overwrites: an already-identical skill is reported and skipped, a genuine
    conflict is reported and left for you to resolve by hand. Add `--dry-run`
    to preview first.
-3. `trellis sync` — distributes canonical skills/instructions to every agent
-   present on this machine (including the ones you didn't migrate from).
-   Add `--dry-run` to preview first.
+3. `trellis sync` — distributes canonical skills/instructions to every
+   **managed** agent (`~/.trellis/managed.yaml` — empty by default; edit it
+   by hand or let `trellis onboard` write it). An agent that's merely present
+   but not managed is never touched. Add `--dry-run` to preview first.
 4. `trellis mcp sync` — distributes `~/.trellis/mcp/servers.yaml` (see
    [`schema/servers.example.yaml`](schema/servers.example.yaml)) to every
-   agent's native MCP config (create/repair only — see Known limitations).
-5. `trellis secrets audit` — fails non-zero if any agent's real config holds
-   a literal credential or an unexpected env var name.
-6. `trellis doctor` — read-only scan of every present agent's current state;
-   run any time to check for drift.
+   managed agent's native MCP config (create/repair only — see Known
+   limitations).
+5. `trellis secrets audit` — fails non-zero if any managed agent's real
+   config holds a literal credential or an unexpected env var name.
+6. `trellis doctor` — read-only scan of every present agent's current state
+   (managed or not); run any time to check for drift.
 
 **Starting from nothing?** Skip step 2 — `trellis init`'s placeholder
 `agents.md` and empty `skills/` are a fine starting point; edit them by hand.
 
+**Every real write `sync`/`mcp sync`/`onboard` perform is backed up
+first, automatically — no flag to opt in.** Before creating, repairing,
+or removing anything, each is recorded to a structured, timestamped run
+under `~/.trellis/backups/`, with enough information to invert it exactly.
+`trellis rollback` undoes one recorded run — omit a run id for the most
+recent one:
+
+```
+$ trellis rollback
+rollback 2026-09-13T04-52-18-727Z-mcp-sync
+✅ 3 restored, 0 conflict(s), 0 already reverted
+   - [restore] restore /Users/you/.claude.json to its content before this run (...)
+```
+
+If something else touched a path since the backed-up run, that one path
+is a `conflict` — reported, left untouched, never force-restored over —
+while every other path in the same rollback still restores. `--list`
+shows available runs without touching anything; `--dry-run` previews a
+restore with zero writes.
+
 ## Status
 
-**Early, pre-1.0.** All seven CLI commands above (`onboard`, `init`,
-`migrate`, `doctor`, `sync`, `mcp sync`, `secrets audit`) are implemented,
+**Early, pre-1.0.** All eight CLI commands above (`onboard`, `init`,
+`migrate`, `doctor`, `sync`, `mcp sync`, `secrets audit`, `rollback`) are implemented,
 unit-tested, and verified end-to-end against real Docker containers (never a
 developer's own dotfiles during development — see
 [`docs/architecture.md`](docs/architecture.md)'s testing philosophy). See
@@ -107,6 +144,9 @@ result is named future work, not built yet.
 - Automatic removal of an MCP server is deliberately unsupported (create/
   repair only) until an ownership-tracking mechanism exists — see
   `docs/roadmap.md`'s P2 note.
+- `~/.trellis/backups/` has no automatic pruning yet — every `sync`/
+  `mcp sync`/`onboard` run that performs a real write adds one more run
+  directory, with no cap. Delete old ones by hand for now.
 
 ## Design principles
 

package/dist/adapters/claude-code.d.ts

@@ -10,6 +10,7 @@
  */
 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 ClaudeCodeAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Claude Code";
@@ -18,6 +19,6 @@ export declare class ClaudeCodeAdapter implements TrellisAdapter {
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
     private planMcp;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/claude-code.js

@@ -8,7 +8,7 @@
  * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
  * removal (D7).
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
@@ -30,7 +30,7 @@ export class ClaudeCodeAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".claude", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -50,10 +50,10 @@ export class ClaudeCodeAdapter {
     planMcp(canonical) {
         const configPath = join(this.homeDir, ".claude.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id });
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents });
     }
-    async apply(plan) {
-        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
         const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
         if (mcpCreates.length === 0) {
             return;
@@ -61,7 +61,7 @@ export class ClaudeCodeAdapter {
         const configPath = mcpCreates[0].target;
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
         const merged = applyJsonMcp(parsed, mcpCreates);
-        writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
     }
     async verify(canonical) {
         const snapshot = await claudeCodeProbe.probe(this.homeDir);
@@ -69,7 +69,7 @@ export class ClaudeCodeAdapter {
             return { ok: false, mismatches: ["claude-code is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => 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/codex.d.ts

@@ -14,6 +14,7 @@
  */
 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 CodexAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Codex";
@@ -22,6 +23,6 @@ export declare class CodexAdapter implements TrellisAdapter {
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
     private planMcp;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/codex.js

@@ -12,7 +12,7 @@
  * automatic removal (D7: no ownership marker exists for a bare TOML key
  * the way a symlink's realpath provides for skills).
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
@@ -36,7 +36,7 @@ export class CodexAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".agents", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -62,7 +62,7 @@ export class CodexAdapter {
     planMcp(canonical) {
         const configTomlPath = join(this.homeDir, ".codex", "config.toml");
         const content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp);
+        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);
@@ -83,8 +83,8 @@ export class CodexAdapter {
         }
         return items;
     }
-    async apply(plan) {
-        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
         const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
         if (mcpCreates.length === 0) {
             return;
@@ -94,7 +94,7 @@ export class CodexAdapter {
         for (const item of mcpCreates) {
             content = upsertSection(content, item.mcpWrite.name, item.mcpWrite.def);
         }
-        writeFileSync(configTomlPath, content);
+        backup.writeFile(configTomlPath, content);
     }
     async verify(canonical) {
         const snapshot = await codexProbe.probe(this.homeDir);
@@ -102,7 +102,7 @@ export class CodexAdapter {
             return { ok: false, mismatches: ["codex is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => 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/jsonMcp.d.ts

@@ -17,6 +17,7 @@ export declare function planJsonMcp(opts: {
     parsed: Record<string, unknown> | undefined;
     mcp: McpConfig;
     agentId: AgentId;
+    managedAgents: readonly AgentId[];
 }): AdapterPlanItem[];
 /** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
  * file didn't exist), returning the object to stringify — every sibling

package/dist/adapters/jsonMcp.js

@@ -44,8 +44,8 @@ export function renderJsonServerEntry(def) {
     return entry;
 }
 export function planJsonMcp(opts) {
-    const { configPath, parsed, mcp, agentId } = opts;
-    const { desired, conflicts } = resolveMcpPlan(agentId, mcp);
+    const { configPath, parsed, mcp, agentId, managedAgents } = opts;
+    const { desired, conflicts } = resolveMcpPlan(agentId, mcp, managedAgents);
     const existingServers = parsed?.mcpServers ?? {};
     const items = [];
     for (const { name, def } of desired) {

package/dist/adapters/kiro.d.ts

@@ -16,6 +16,7 @@
  */
 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 KiroAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "Kiro";
@@ -29,6 +30,6 @@ export declare class KiroAdapter implements TrellisAdapter {
      * known_host_injected collision, never contributes a name here either. */
     private desiredApprovedEnvVars;
     private planApprovedEnvVars;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/kiro.js

@@ -14,7 +14,7 @@
  * adapter keeps that list a superset of every env name it references,
  * additive only.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { isInScope } from "../core/adapter.js";
@@ -46,7 +46,7 @@ export class KiroAdapter {
         const canonicalRoot = dirname(canonical.instructionsFile);
         const skillsRoot = join(this.homeDir, ".kiro", "skills");
         const desiredSkills = canonical.skills
-            .filter((skill) => isInScope(this.id, skill.scope))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: skillsRoot,
@@ -67,13 +67,13 @@ export class KiroAdapter {
     planMcp(canonical) {
         const configPath = join(this.homeDir, ".kiro", "settings", "mcp.json");
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id });
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id, managedAgents: canonical.managedAgents });
     }
     /** Names come from `resolveMcpPlan`, not a raw scan of `canonical.mcp.servers`
      * (design.md D2) — a server scoped away from Kiro, or refused for a
      * known_host_injected collision, never contributes a name here either. */
     desiredApprovedEnvVars(canonical) {
-        const { desired } = resolveMcpPlan(this.id, canonical.mcp);
+        const { desired } = resolveMcpPlan(this.id, canonical.mcp, canonical.managedAgents);
         const names = new Set();
         for (const { def } of desired) {
             for (const name of declaredEnvNames(def))
@@ -115,15 +115,15 @@ export class KiroAdapter {
             },
         ];
     }
-    async apply(plan) {
-        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"));
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"), backup);
         const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
         if (mcpCreates.length > 0) {
             const configPath = mcpCreates[0].target;
             const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
             const merged = applyJsonMcp(parsed, mcpCreates);
             mkdirSync(dirname(configPath), { recursive: true });
-            writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+            backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
         }
         const approvedEnvVarsCreate = plan.find((item) => item.kind === "kiro-approved-env-vars" && item.action === "create" && item.approvedEnvVars);
         if (approvedEnvVarsCreate) {
@@ -131,7 +131,7 @@ export class KiroAdapter {
             const parsed = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf-8")) : {};
             const merged = { ...parsed, [APPROVED_ENV_VARS_KEY]: approvedEnvVarsCreate.approvedEnvVars };
             mkdirSync(dirname(settingsPath), { recursive: true });
-            writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+            backup.writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
         }
     }
     async verify(canonical) {
@@ -140,7 +140,7 @@ export class KiroAdapter {
             return { ok: false, mismatches: ["kiro is not present on this machine"] };
         }
         const mismatches = [];
-        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => 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/mcpPlan.d.ts

@@ -25,4 +25,4 @@ export interface McpPlanResult {
     desired: DesiredMcpEntry[];
     conflicts: McpConflict[];
 }
-export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig): McpPlanResult;
+export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[]): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -40,7 +40,7 @@ function findLiteralSecret(def) {
     }
     return undefined;
 }
-export function resolveMcpPlan(agentId, mcp) {
+export function resolveMcpPlan(agentId, mcp, managedAgents) {
     if (mcp.hub) {
         if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
             return { desired: [], conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId) }] };
@@ -50,7 +50,7 @@ export function resolveMcpPlan(agentId, mcp) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
-        if (!isInScope(agentId, def.agents)) {
+        if (!isInScope(agentId, def.agents, managedAgents)) {
             continue;
         }
         if (mcp.knownHostInjected.includes(name)) {

package/dist/adapters/pi.d.ts

@@ -11,6 +11,7 @@
  */
 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 PiAdapter implements TrellisAdapter {
     private readonly homeDir;
     readonly name = "pi";
@@ -18,6 +19,6 @@ export declare class PiAdapter implements TrellisAdapter {
     constructor(homeDir?: string);
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/pi.js

@@ -56,7 +56,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))
+            .filter((skill) => isInScope(this.id, skill.scope, canonical.managedAgents))
             .map((skill) => ({ name: skill.name, target: skill.dir }));
         const skillItems = planSymlinks({
             rootDir: join(agentDir, "skills"),
@@ -82,8 +82,8 @@ export class PiAdapter {
         });
         return [...skillItems, ...instructionsItems, ...extensionItems];
     }
-    async apply(plan) {
-        await applySymlinkPlan(plan);
+    async apply(plan, backup) {
+        await applySymlinkPlan(plan, backup);
     }
     async verify(canonical) {
         const snapshot = await piProbe.probe(this.homeDir);
@@ -91,7 +91,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)).map((s) => s.name));
+        const desiredNames = new Set(canonical.skills.filter((s) => 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

@@ -4,6 +4,7 @@
  * trellis-sync-p1/specs/skill-instructions-sync/spec.md) — built once,
  * reused by every adapter rather than reimplemented per agent.
  */
+import { type BackupSession } from "../lib/backup.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
 export interface DesiredSymlink {
     /** Basename this entry should have under `rootDir`. */
@@ -28,6 +29,9 @@ export declare function planSymlinks(opts: {
     canonicalRoot: string;
     kind: "skill" | "instructions" | "extension";
 }): AdapterPlanItem[];
-/** Executes a `planSymlinks` result. "conflict" is report-only — see
- * src/core/adapter.ts's `apply()` doc for why this never throws. */
-export declare function applySymlinkPlan(plan: AdapterPlanItem[]): Promise<void>;
+/** Executes a `planSymlinks` result through the run's backup session
+ * (trellis-backup-rollback) — every create/repair/remove is recorded
+ * before it happens; `backup` performs the actual filesystem write, this
+ * function never calls `fs/promises` itself. "conflict" is report-only —
+ * see src/core/adapter.ts's `apply()` doc for why this never throws. */
+export declare function applySymlinkPlan(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;

package/dist/adapters/symlinkPlan.js

@@ -5,9 +5,10 @@
  * reused by every adapter rather than reimplemented per agent.
  */
 import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
-import { mkdir, rm, symlink } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { isSymlinkTo } from "../lib/fsIdentity.js";
+import { currentLinkTarget } from "../lib/backup.js";
 function isUnderRoot(path, root) {
     const normalizedRoot = resolve(root);
     const normalizedPath = resolve(path);
@@ -37,14 +38,27 @@ export function planSymlinks(opts) {
         if (isSymlinkTo(path, target)) {
             continue; // already correct — no-op
         }
-        if (existsSync(path) && !lstatSync(path).isSymbolicLink()) {
-            items.push({
-                action: "conflict",
-                kind,
-                target: path,
-                description: `${path} exists and is not a Trellis-managed symlink — left untouched`,
-            });
-            continue;
+        if (existsSync(path)) {
+            const isSymlink = lstatSync(path).isSymbolicLink();
+            // 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
+            // silently steal that ownership. Raw readlink, not realpath: a
+            // 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);
+            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 and is not a Trellis-managed symlink — left untouched`,
+                });
+                continue;
+            }
         }
         items.push({
             action: "create",
@@ -100,21 +114,33 @@ export function planSymlinks(opts) {
     }
     return items;
 }
-/** Executes a `planSymlinks` result. "conflict" is report-only — see
- * src/core/adapter.ts's `apply()` doc for why this never throws. */
-export async function applySymlinkPlan(plan) {
+/** Executes a `planSymlinks` result through the run's backup session
+ * (trellis-backup-rollback) — every create/repair/remove is recorded
+ * before it happens; `backup` performs the actual filesystem write, this
+ * function never calls `fs/promises` itself. "conflict" is report-only —
+ * see src/core/adapter.ts's `apply()` doc for why this never throws. */
+export async function applySymlinkPlan(plan, backup) {
     for (const item of plan) {
         if (item.action === "conflict")
             continue;
         if (item.action === "remove") {
-            await rm(item.target, { force: true });
+            const oldTarget = await currentLinkTarget(item.target);
+            if (oldTarget === undefined)
+                continue; // already gone — no-op, nothing to record
+            await backup.removeSymlink(item.target, oldTarget);
             continue;
         }
-        // "create": rootDir may not exist yet (first sync ever for this agent)
+        // "create" also covers repair — rootDir may not exist yet (first
+        // sync ever for this agent).
         if (!item.linkTarget)
             continue;
         await mkdir(resolve(item.target, ".."), { recursive: true });
-        await rm(item.target, { force: true }); // clear a wrong-target symlink before repointing
-        await symlink(item.linkTarget, item.target);
+        const oldTarget = await currentLinkTarget(item.target);
+        if (oldTarget === undefined) {
+            await backup.createSymlink(item.target, item.linkTarget);
+        }
+        else {
+            await backup.repairSymlink(item.target, oldTarget, item.linkTarget);
+        }
     }
 }

package/dist/cli.js

@@ -11,8 +11,9 @@ import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
 import { runMcpSync } from "./commands/mcp.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
+import { runRollback } from "./commands/rollback.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "secrets"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "secrets", "rollback"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
@@ -20,13 +21,21 @@ Usage:
   trellis <command>
 
 Commands:
-  onboard   Guided flow: init -> detect agents -> pick a base agent ->
-            migrate -> sync, in one command
-              --agent <agent>    non-interactive base-agent choice
-                                 (required with 2+ agents present and
-                                 no terminal to prompt in, e.g. --json)
-              --dry-run          preview the whole flow, write nothing
-              --json             machine-readable output, no report text
+  onboard   Guided flow: init -> detect agents -> pick a migration source ->
+            pick which agents to manage -> migrate -> sync -> mcp sync ->
+            secrets audit, in one command. Source (read from) and managed
+            set (written to) are independent; the source is not managed
+            by default.
+              --agent <agent>       non-interactive migration-source
+                                    choice (required with 2+ candidates
+                                    and no terminal to prompt in)
+              --manage <ids|none>   non-interactive managed-set choice,
+                                    e.g. --manage pi,codex ; --manage none
+                                    means "add nothing new this run"
+                                    (required with no terminal to prompt
+                                    in, e.g. --json)
+              --dry-run             preview the whole flow, write nothing
+              --json                machine-readable output, no report text
   init      Create ~/.trellis/ with a minimal valid skeleton if missing
               (never overwrites an existing file — fills in only what's
               missing) and prints which agents are present
@@ -48,11 +57,21 @@ Commands:
               --json       machine-readable output, no report text
   mcp sync  Distribute MCP servers to each agent's native config
               (create/repair only — no automatic removal, see docs/roadmap.md)
-              --json    machine-readable output, no report text
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
   secrets audit
             Scan each present agent's real MCP config for leaked
             credentials and unexpected env var names
               --json    machine-readable output, no report text
+  rollback [<run-id>]
+            Undo one recorded sync/mcp-sync/onboard run (every real write
+              it performed is backed up first, under
+              ~/.trellis/backups/) — omit <run-id> for the most recent
+              run. Refuses per-path (a conflict, not overwritten) if the
+              path changed since that run.
+              --list       show available backup runs, don't restore
+              --dry-run    preview what would be restored, write nothing
+              --json       machine-readable output, no report text
 
 See docs/roadmap.md for what's built vs. planned.`);
 }
@@ -71,7 +90,9 @@ async function main(argv) {
     if (command === "onboard") {
         const agentIndex = rest.indexOf("--agent");
         const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;
-        const { exitCode } = await runOnboard({ agent, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
+        const manageIndex = rest.indexOf("--manage");
+        const manage = manageIndex >= 0 ? rest[manageIndex + 1] : undefined;
+        const { exitCode } = await runOnboard({ agent, manage, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
         process.exitCode = exitCode;
         return;
     }
@@ -111,7 +132,7 @@ async function main(argv) {
             process.exitCode = 1;
             return;
         }
-        const { exitCode } = await runMcpSync({ json: rest.includes("--json") });
+        const { exitCode } = await runMcpSync({ json: rest.includes("--json"), dryRun: rest.includes("--dry-run") });
         process.exitCode = exitCode;
         return;
     }
@@ -126,6 +147,15 @@ async function main(argv) {
         process.exitCode = exitCode;
         return;
     }
+    if (command === "rollback") {
+        const list = rest.includes("--list");
+        const dryRun = rest.includes("--dry-run");
+        const json = rest.includes("--json");
+        const runId = rest.find((arg) => !arg.startsWith("--"));
+        const { exitCode } = await runRollback({ runId, list, dryRun, json });
+        process.exitCode = exitCode;
+        return;
+    }
     console.error(`\`trellis ${command}\` is not implemented yet — this is a pre-alpha scaffold.\nSee docs/roadmap.md for status.`);
     process.exitCode = 1;
 }