fix(uninstall): prevent over-hashing of user files in manifest

trellis init walked managed dirs (.codex/, .claude/, .opencode/) and hashed
every file into .template-hashes.json — including pre-existing user data
(.codex/sessions/, .claude/projects/, user-owned AGENTS.md). trellis uninstall
then unlinked every manifest entry, deleting that user data. Two real reports:
GitHub Issue #221 (.codex/sessions/ wiped) and PR #271 (pre-existing AGENTS.md
wiped via skip-existing path).

Manifest is now derived from "what trellis actually wrote this run", not from
walking the disk:

- writeFile() instruments recordWrite() on actual disk writes only. byte-
  identical, skip-existing, and append paths do NOT record. initializeHashes
  consumes the recorded set instead of fs.readdirSync walks.
- Root-level AGENTS.md only enters manifest when trellis writes it.
- pruneOrphanManifestKeys() self-heals already-poisoned manifests at the top
  of both trellis update and trellis uninstall. Preserves .trellis/* (still
  walk-managed), every configured-platform collectTemplates() path, every
  path referenced by any migration manifest from/to, and AGENTS.md only when
  it still carries trellis managed-block markers.
- Homedir guard: trellis init / uninstall refuse to run when cwd is exactly
  the user's home directory (realpathSync.native + Windows lowercase). Bypass
  via TRELLIS_ALLOW_HOMEDIR=1; --force does not bypass.

.trellis/ files keep their existing walk-based hashing — trellis uninstall
rm -rf's that subtree wholesale regardless of manifest content, so over-
hashing there does not affect uninstall safety.

Internal:
- New utils/cwd-guard.ts and utils/manifest-prune.ts.
- claude configurator excludes dev-only .ts from its template walk.
- 27 new tests across recorder boundaries, prune semantics, homedir cases,
  and full init+uninstall reproductions for both reported scenarios.

Spec:
- .trellis/spec/cli/backend/migrations.md adds "Manifest ownership contract"
  with the recorder rules, prune preserve-set, homedir guard, wrong-vs-
  correct, and tests required for any future change in this area.

Author: taosu

.trellis/spec/cli/backend/migrations.md

@@ -193,6 +193,84 @@ update:
 - 初始化：`trellis init` 时自动创建
 - 更新：`trellis update` 后自动更新被覆盖文件的哈希
 
+### Manifest ownership contract (CRITICAL — data loss prevention)
+
+`.template-hashes.json` is the **single source of truth** for `trellis uninstall`. Every key listed there gets `fs.unlinkSync`'d at uninstall time. Therefore the manifest must contain **only files trellis actually wrote during init / update — never files that merely happen to exist under a managed directory**.
+
+#### Why this matters
+
+`.codex/`, `.claude/`, `.opencode/` etc. contain platform-specific user data:
+- `.codex/sessions/*.jsonl` — Codex chat history
+- `.codex/history` — Codex prompt history
+- `.claude/projects/<sanitized-cwd>/*.jsonl` — Claude Code conversation history
+- User-added `.codex/skills/<name>/`, `.claude/agents/<name>/`
+
+If `initializeHashes` walks these dirs and hashes everything, uninstall faithfully deletes user data. Real reported incidents: GitHub Issue #221 (`.codex/sessions/` wiped), PR #271 (pre-existing `AGENTS.md` wiped).
+
+#### Required contract
+
+**`initializeHashes(cwd, opts)`** must derive the manifest set from `opts.trackedPaths` (a `Set<string>` of paths trellis **actually wrote this run**), NOT from `fs.readdirSync` walks of platform dirs.
+
+The set is produced by `startRecordingWrites()` / `stopRecordingWrites()` instrumentation inside `utils/file-writer.ts`. `writeFile()` records `recordWrite(absPath)` ONLY when:
+
+- The file did not exist → wrote (recorded)
+- The file existed and content differed → overwrote (recorded)
+
+And **does NOT record** when:
+
+- The file existed and content was byte-identical (no disk write)
+- `writeMode` was `skip-existing` and the file existed (skipped)
+- The call was append-mode (`appendFile`)
+
+Every configurator that wants its writes tracked must funnel through `writeFile()` — direct `fs.writeFileSync` bypasses the recorder.
+
+#### `.trellis/` walk exemption
+
+`.trellis/` files are still hashed via recursive walk (existing `collectFiles` behavior + `EXCLUDE_FROM_HASH` filters). Rationale: `trellis uninstall` step 3 does `fs.rmSync('.trellis/', { recursive: true, force: true })` regardless of manifest content, so the walk's blast radius is contained. Over-hashing inside `.trellis/` only affects `trellis update` 3-way-merge accuracy, not uninstall safety.
+
+#### Self-heal contract: `pruneOrphanManifestKeys`
+
+Existing users may have poisoned manifests from older trellis versions. `pruneOrphanManifestKeys(cwd, configuredPlatforms, hashes, opts)` runs at the top of both `trellis update` AND `trellis uninstall` (before plan classification) and prunes orphan keys.
+
+**Preserve set** (a key is kept iff one of):
+
+1. Starts with `.trellis/` (walk-managed)
+2. Path appears in `PLATFORM_FUNCTIONS[id].collectTemplates()` output for ANY configured platform
+3. Path appears in `from` or `to` of ANY migration manifest entry (across all `migrations/manifests/*.json`, not just pending) — must preserve so rename/delete migration logic still has a hash to compare against
+4. Path is `AGENTS.md` AND the file on disk contains `TRELLIS_BLOCK_START` + `TRELLIS_BLOCK_END` markers, OR the file is missing. Files lacking markers are treated as user-owned and pruned.
+
+`options.persist: false` for dry-run paths (e.g. `uninstall --dry-run`).
+
+#### Wrong vs Correct
+
+```typescript
+// Wrong — walk-based hashing pollutes manifest with user data
+for (const dir of ALL_MANAGED_DIRS) {
+  for (const f of collectFiles(cwd, dir)) {
+    hashes[f] = sha256(read(f));   // includes .codex/sessions/foo.jsonl
+  }
+}
+
+// Correct — manifest reflects exactly what trellis wrote this run
+startRecordingWrites();
+await runConfigurators(cwd);       // each writeFile() calls recordWrite()
+const written = stopRecordingWrites();
+initializeHashes(cwd, { trackedPaths: written });
+```
+
+#### Homedir guard (R2 — defense in depth)
+
+Even with the manifest contract above, `trellis init` and `trellis uninstall` refuse to run when `process.cwd()` is exactly the user's home directory. Use `isCwdHomedir()` from `utils/cwd-guard.ts` — it compares via `fs.realpathSync.native()` on both sides, Windows-lowercases for case-insensitivity, try/catch defaults permissive on lookup failure. Override via `TRELLIS_ALLOW_HOMEDIR=1` only; `--force` does NOT bypass.
+
+#### Tests required for any change in this area
+
+- Integration: pre-populate user files under `.codex/`, `.claude/`, `.opencode/`, run init+uninstall, assert user data preserved.
+- Integration: pre-existing `AGENTS.md` (skip-existing path), uninstall preserves it.
+- Integration: poisoned manifest (manually injected key) → update OR uninstall prunes it, user file survives.
+- Unit: `recordWrite` instrumentation — new/overwrite recorded, identical/skip/append NOT recorded.
+- Unit: `pruneOrphanManifestKeys` — preserves all four classes above; rewrites manifest only when pruned.length > 0.
+- Unit: `isCwdHomedir` — symlinked home matches; subdirectory does NOT match; Windows case-insensitive.
+
 ### `workflow.md` whole-file update contract
 
 `.trellis/workflow.md` is not only documentation. It is runtime input for

packages/cli/src/commands/init.ts

@@ -23,6 +23,8 @@ import { VERSION } from "../constants/version.js";
 import { agentsMdContent } from "../templates/markdown/index.js";
 import {
   setWriteMode,
+  startRecordingWrites,
+  stopRecordingWrites,
   writeFile,
   type WriteMode,
 } from "../utils/file-writer.js";
@@ -35,6 +37,11 @@ import {
   type DetectedPackage,
 } from "../utils/project-detector.js";
 import { initializeHashes } from "../utils/template-hash.js";
+import {
+  isCwdHomedir,
+  homedirGuardMessage,
+  homedirBypassEnabled,
+} from "../utils/cwd-guard.js";
 import {
   fetchTemplateIndex,
   probeRegistryIndex,
@@ -826,26 +833,35 @@ async function handleReinit(
       }
     }
 
-    for (const tool of platformsToAdd) {
-      const platformId = resolveCliFlag(tool as CliFlag);
-      if (platformId) {
-        if (configuredPlatforms.has(platformId)) {
-          console.log(
-            chalk.gray(
-              `  ○ ${AI_TOOLS[platformId].name} already configured, skipping`,
-            ),
-          );
-        } else {
-          console.log(
-            chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`),
-          );
-          await configurePlatform(platformId, cwd);
+    const reinitWritten = startRecordingWrites(cwd);
+    try {
+      for (const tool of platformsToAdd) {
+        const platformId = resolveCliFlag(tool as CliFlag);
+        if (platformId) {
+          if (configuredPlatforms.has(platformId)) {
+            console.log(
+              chalk.gray(
+                `  ○ ${AI_TOOLS[platformId].name} already configured, skipping`,
+              ),
+            );
+          } else {
+            console.log(
+              chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`),
+            );
+            await configurePlatform(platformId, cwd);
+          }
         }
       }
+    } finally {
+      stopRecordingWrites();
     }
 
-    // Update template hashes
-    const hashedCount = initializeHashes(cwd);
+    // Update template hashes. Merge mode: preserve previously-tracked
+    // platforms' hashes, layer in the newly-added platform's writes.
+    const hashedCount = initializeHashes(cwd, {
+      trackedPaths: reinitWritten,
+      merge: true,
+    });
     if (hashedCount > 0) {
       console.log(
         chalk.gray(`📋 Tracking ${hashedCount} template files for updates`),
@@ -997,6 +1013,14 @@ interface InitAnswers {
 }
 
 export async function init(options: InitOptions): Promise<void> {
+  // Refuse to run in $HOME — running here would scoop platform runtime data
+  // (Claude/Codex/OpenCode session histories etc.) into the trellis hash
+  // manifest, and a subsequent `trellis uninstall` would wipe it.
+  if (isCwdHomedir() && !homedirBypassEnabled()) {
+    console.error(chalk.red(homedirGuardMessage("init")));
+    process.exit(1);
+  }
+
   const cwd = process.cwd();
   const isFirstInit = !fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW));
   // Captured here (before createWorkflowStructure + init_developer run) so
@@ -1727,47 +1751,59 @@ export async function init(options: InitOptions): Promise<void> {
   // Create Workflow Structure
   // ==========================================================================
 
-  // Create workflow structure with project type
-  console.log(chalk.blue("📁 Creating workflow structure..."));
-  await createWorkflowStructure(cwd, {
-    projectType,
-    skipSpecTemplates: useRemoteTemplate,
-    packages: monorepoPackages,
-    remoteSpecPackages,
-  });
+  // Record every successful write from here through createRootFiles. The
+  // captured set is the source of truth for `.template-hashes.json`'s
+  // platform/root entries — replacing the previous "walk every managed dir"
+  // approach that swept user-owned runtime files into the manifest
+  // (.codex/sessions/, .claude/projects/, pre-existing AGENTS.md).
+  const writtenPaths = startRecordingWrites(cwd);
+  try {
+    // Create workflow structure with project type
+    console.log(chalk.blue("📁 Creating workflow structure..."));
+    await createWorkflowStructure(cwd, {
+      projectType,
+      skipSpecTemplates: useRemoteTemplate,
+      packages: monorepoPackages,
+      remoteSpecPackages,
+    });
 
-  // Write monorepo packages to config.yaml (non-destructive patch)
-  if (monorepoPackages) {
-    writeMonorepoConfig(cwd, monorepoPackages);
-    console.log(chalk.blue("📦 Monorepo packages written to config.yaml"));
-  }
+    // Write monorepo packages to config.yaml (non-destructive patch)
+    if (monorepoPackages) {
+      writeMonorepoConfig(cwd, monorepoPackages);
+      console.log(chalk.blue("📦 Monorepo packages written to config.yaml"));
+    }
 
-  // Write version file for update tracking
-  const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
-  fs.writeFileSync(versionPath, VERSION);
+    // Write version file for update tracking
+    const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
+    fs.writeFileSync(versionPath, VERSION);
 
-  // Configure selected tools by copying entire directories (dogfooding)
-  for (const tool of tools) {
-    const platformId = resolveCliFlag(tool);
-    if (platformId) {
-      console.log(chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`));
-      await configurePlatform(platformId, cwd);
+    // Configure selected tools by copying entire directories (dogfooding)
+    for (const tool of tools) {
+      const platformId = resolveCliFlag(tool);
+      if (platformId) {
+        console.log(
+          chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`),
+        );
+        await configurePlatform(platformId, cwd);
+      }
     }
-  }
 
-  const pythonPlatforms = getPlatformsWithPythonHooks();
-  const hasSelectedPythonPlatform = pythonPlatforms.some((id) =>
-    tools.includes(AI_TOOLS[id].cliFlag),
-  );
-  if (hasSelectedPythonPlatform) {
-    logPythonAdaptationNotice(pythonCmd);
-  }
+    const pythonPlatforms = getPlatformsWithPythonHooks();
+    const hasSelectedPythonPlatform = pythonPlatforms.some((id) =>
+      tools.includes(AI_TOOLS[id].cliFlag),
+    );
+    if (hasSelectedPythonPlatform) {
+      logPythonAdaptationNotice(pythonCmd);
+    }
 
-  // Create root files (skip if exists)
-  await createRootFiles(cwd);
+    // Create root files (skip if exists)
+    await createRootFiles(cwd);
+  } finally {
+    stopRecordingWrites();
+  }
 
   // Initialize template hashes for modification tracking
-  const hashedCount = initializeHashes(cwd);
+  const hashedCount = initializeHashes(cwd, { trackedPaths: writtenPaths });
   if (hashedCount > 0) {
     console.log(
       chalk.gray(`📋 Tracking ${hashedCount} template files for updates`),

packages/cli/src/commands/uninstall.ts

@@ -26,7 +26,16 @@ import inquirer from "inquirer";
 import { DIR_NAMES } from "../constants/paths.js";
 import { loadHashes } from "../utils/template-hash.js";
 import { cleanupEmptyDirs } from "./update.js";
-import { ALL_MANAGED_DIRS } from "../configurators/index.js";
+import {
+  ALL_MANAGED_DIRS,
+  getConfiguredPlatforms,
+} from "../configurators/index.js";
+import { pruneOrphanManifestKeys } from "../utils/manifest-prune.js";
+import {
+  isCwdHomedir,
+  homedirGuardMessage,
+  homedirBypassEnabled,
+} from "../utils/cwd-guard.js";
 import {
   scrubHooksJson,
   scrubOpencodePackageJson,
@@ -362,6 +371,14 @@ function executePlan(
  * Entry point.
  */
 export async function uninstall(options: UninstallOptions = {}): Promise<void> {
+  // Refuse to run in $HOME — same reasoning as init. A manifest poisoned by
+  // a prior buggy init would otherwise unlink global platform runtime data
+  // (chat history, session JSONLs).
+  if (isCwdHomedir() && !homedirBypassEnabled()) {
+    console.error(chalk.red(homedirGuardMessage("uninstall")));
+    process.exit(1);
+  }
+
   const cwd = process.cwd();
   const trellisDir = path.join(cwd, DIR_NAMES.WORKFLOW);
 
@@ -388,7 +405,34 @@ export async function uninstall(options: UninstallOptions = {}): Promise<void> {
     process.exit(1);
   }
 
-  const plan = buildPlan(cwd, hashes);
+  // Self-heal poisoned manifests from buggy init versions: prune any manifest
+  // entry that no current configurator owns. Runs BEFORE buildPlan so the
+  // user-owned paths (.codex/sessions/, .claude/projects/, pre-existing
+  // AGENTS.md, etc.) never reach the deletion list. See PRD R3.
+  //
+  // Dry-run: still compute the pruned hashes (so the plan reflects post-prune
+  // reality) but pass `persist: false` so no disk write happens. The actual
+  // disk write defers to executePlan time, where we'd be rewriting the
+  // manifest only to delete the whole .trellis/ dir anyway — but the
+  // computation must remain to keep the rendered plan honest.
+  const configuredPlatforms = getConfiguredPlatforms(cwd);
+  const { pruned, hashes: prunedHashes } = pruneOrphanManifestKeys(
+    cwd,
+    [...configuredPlatforms],
+    hashes,
+    { persist: !options.dryRun },
+  );
+  if (pruned.length > 0) {
+    // Surface counts only — listing every poisoned entry would alarm users
+    // without giving them an actionable signal.
+    console.log(
+      chalk.gray(
+        `   Pruned ${pruned.length} orphan manifest entries (user-owned files trellis did not write).`,
+      ),
+    );
+  }
+
+  const plan = buildPlan(cwd, prunedHashes);
   renderPlan(cwd, plan);
 
   if (options.dryRun) {

packages/cli/src/commands/update.ts

@@ -52,6 +52,7 @@ import {
   isManagedRootDir,
 } from "../configurators/index.js";
 import { replacePythonCommandLiterals } from "../configurators/shared.js";
+import { pruneOrphanManifestKeys } from "../utils/manifest-prune.js";
 
 export interface UpdateOptions {
   dryRun?: boolean;
@@ -1754,7 +1755,7 @@ export async function update(options: UpdateOptions): Promise<void> {
   // Migration metadata is displayed at the end to prevent scrolling off screen
 
   // Load template hashes for modification detection
-  const hashes = loadHashes(cwd);
+  let hashes = loadHashes(cwd);
   const isFirstHashTracking = Object.keys(hashes).length === 0;
 
   // Handle unknown version - skip regular migrations but safe-file-delete still runs
@@ -1772,6 +1773,10 @@ export async function update(options: UpdateOptions): Promise<void> {
   }
 
   // Detect legacy Codex (has .agents/skills/ tracked by Trellis but no .codex/)
+  // NOTE: this MUST happen before pruneOrphanManifestKeys below, since the
+  // detector reads the raw manifest looking for .agents/skills/ markers that
+  // the prune step would otherwise consider orphans (codex hasn't been added
+  // to configuredPlatforms yet at this point).
   const codexUpgradeNeeded = needsCodexUpgrade(cwd);
   if (codexUpgradeNeeded) {
     console.log(
@@ -1781,6 +1786,29 @@ export async function update(options: UpdateOptions): Promise<void> {
     );
   }
 
+  // Self-heal poisoned manifests: prune entries that no current platform
+  // configurator owns. This silently removes user-owned paths that early
+  // buggy versions of `trellis init` over-hashed (e.g. .codex/sessions/*).
+  // Include codex in known-platforms when codexUpgradeNeeded so legacy Codex
+  // markers under .agents/skills/ survive into the upgrade flow.
+  {
+    const configuredPlatforms = new Set<AITool>(getConfiguredPlatforms(cwd));
+    if (codexUpgradeNeeded) configuredPlatforms.add("codex");
+    const prune = pruneOrphanManifestKeys(
+      cwd,
+      [...configuredPlatforms],
+      hashes,
+    );
+    if (prune.pruned.length > 0) {
+      console.log(
+        chalk.gray(
+          `   Pruned ${prune.pruned.length} orphan manifest entries from .template-hashes.json`,
+        ),
+      );
+      hashes = prune.hashes;
+    }
+  }
+
   // For breaking releases with recommendMigrate + --migrate, bypass update.skip
   // across the board (safe-file-delete, new file writes, template updates).
   // Why: honoring skip here leaves users forever half-migrated — old deprecated