@brainervirus/workit-core 1.2.1 → 1.3.0

package/src/core/cutover.ts

@@ -1,13 +1,17 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
+  closeSync,
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
+  opendirSync,
+  openSync,
   readFileSync,
+  readSync,
   readdirSync,
-  rmSync,
-  statSync,
-  writeFileSync,
+  unlinkSync,
+  constants as fsConstants,
 } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -27,6 +31,8 @@ import {
   mergeOpenCodeConfig,
 } from "./registration";
 import { WORKIT_METHOD_SKILLS, WORKIT_SKILL_ALIASES } from "./skill-manifests";
+import { writeFileAtomic, writeFileExclusive } from "./safe-write";
+import { LEGACY_CURSOR_ASSET_DIGESTS } from "./legacy-ownership";
 
 export type CutoverHost = "opencode" | "cursor" | "codex" | "pi";
 
@@ -36,9 +42,37 @@ export type SessionObservation = {
   state: "stopped" | "active" | "unknown";
 };
 
+export type CutoverInventoryEntry = {
+  path: string;
+  kind: "file" | "directory" | "symlink" | "other";
+  category:
+    | "configuration"
+    | "recovery"
+    | "project-state"
+    | "project-history"
+    | "host-configuration"
+    | "integration";
+  disposition: "preserve" | "convert" | "unknown";
+  bytes: number;
+  digest: Digest | null;
+  ownershipEvidence: string | null;
+};
+
+export type CutoverInventory = {
+  complete: boolean;
+  entries: CutoverInventoryEntry[];
+  files: number;
+  bytes: number;
+  bytesByCategory: Partial<Record<CutoverInventoryEntry["category"], number>>;
+  issues: string[];
+  revision: Digest;
+};
+
 export type CutoverPlan = {
   id: Id;
+  archiveDir: string | null;
   managedFiles: { path: string; beforeDigest: Digest | null; afterDigest: Digest }[];
+  inventory: CutoverInventory;
   sessions: SessionObservation[];
   unresolved: { key: string; reason: string }[];
   conversion: ConversionPreview;
@@ -48,6 +82,7 @@ export type CutoverPlan = {
 
 export type CutoverReceipt = {
   backupId: Id;
+  archiveDir: string;
   planId: Id;
   generation: "legacy" | "v1";
   hosts: CutoverHost[];
@@ -56,6 +91,23 @@ export type CutoverReceipt = {
   notes: string[];
 };
 
+type CutoverJournal = {
+  schemaVersion: 1;
+  backupId: Id;
+  archiveDir: string;
+  planId: Id;
+  hosts: CutoverHost[];
+  resolutions: Record<string, string>;
+  conversionNeeded: boolean;
+  phase: "applying" | "interrupted" | "partial" | "complete";
+  completedSteps: string[];
+  appliedHosts: CutoverHost[];
+  currentStep: string | null;
+  error: string | null;
+  startedAt: string;
+  notes: string[];
+};
+
 export type CutoverDecision = {
   approve: true;
   hosts: CutoverHost[];
@@ -64,21 +116,30 @@ export type CutoverDecision = {
 
 export type RollbackPreview = {
   backupId: Id;
-  restorable: { path: string; currentDigest: Digest; installedDigest: Digest }[];
-  conflicts: { path: string; currentDigest: Digest; installedDigest: Digest }[];
+  restorable: {
+    path: string;
+    currentDigest: Digest;
+    installedDigest: Digest;
+    restore: "backup" | "remove";
+  }[];
+  conflicts: { path: string; currentDigest: Digest | null; installedDigest: Digest }[];
   preserved: string[];
+  issues: string[];
 };
 
 export type CutoverPaths = {
   home?: string;
   configDir?: string;
   stateDir?: string;
+  archiveDir?: string;
   dev?: string | null;
   workspace?: string;
   opencodeConfig?: string;
   cursorSettings?: string;
   cursorMcp?: string;
   cursorPluginDir?: string;
+  piConfig?: string;
+  piSettings?: string;
   sessions?: SessionObservation[];
   env?: NodeJS.ProcessEnv;
 };
@@ -89,6 +150,8 @@ export type GenerationState = {
 };
 
 const GENERATION_FILE = "generation.json";
+const CUTOVER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const validCutoverId = (value: string): boolean => CUTOVER_ID.test(value);
 
 const resolvePaths = (options: CutoverPaths = {}) => {
   const home = options.home ?? options.env?.HOME ?? os.homedir();
@@ -100,6 +163,7 @@ const resolvePaths = (options: CutoverPaths = {}) => {
     options.stateDir ??
     options.env?.WORKFLOW_TOOLKIT_STATE ??
     path.join(home, ".local", "state", "workit");
+  const piAgentDir = options.env?.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent");
   return {
     home,
     configDir,
@@ -112,13 +176,79 @@ const resolvePaths = (options: CutoverPaths = {}) => {
     cursorMcp: options.cursorMcp ?? path.join(home, ".cursor", "mcp.json"),
     cursorPluginDir:
       options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
+    piConfig: options.piConfig ?? path.join(home, ".pi", "config.json"),
+    piSettings: options.piSettings ?? path.join(piAgentDir, "settings.json"),
     sessions: options.sessions ?? [],
   };
 };
 
+const MAX_CUTOVER_INVENTORY_ENTRIES = 50_000;
+const MAX_CUTOVER_INVENTORY_DEPTH = 64;
+
+const isMissing = (error: unknown): boolean =>
+  typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+
+const lstatOrNull = (file: string) => {
+  try {
+    return lstatSync(file);
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+};
+
+const noSymlinkAncestor = (file: string): boolean => {
+  let current = path.resolve(file);
+  for (;;) {
+    const stat = lstatOrNull(current);
+    if (stat?.isSymbolicLink()) return false;
+    const parent = path.dirname(current);
+    if (parent === current) return true;
+    current = parent;
+  }
+};
+
+const readDirNamesBounded = (
+  dir: string,
+  limit: number,
+): { names: string[]; truncated: boolean } => {
+  const handle = opendirSync(dir);
+  const names: string[] = [];
+  try {
+    for (;;) {
+      const entry = handle.readSync();
+      if (!entry) return { names: names.sort(), truncated: false };
+      if (names.length === limit) return { names: names.sort(), truncated: true };
+      names.push(entry.name);
+    }
+  } finally {
+    handle.closeSync();
+  }
+};
+
 export const digestFile = (file: string): Digest | null => {
-  if (!existsSync(file)) return null;
-  return createHash("sha256").update(readFileSync(file)).digest("hex");
+  if (!noSymlinkAncestor(path.dirname(file))) return null;
+  const stat = lstatOrNull(file);
+  if (!stat?.isFile() || stat.isSymbolicLink()) return null;
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let offset = 0;
+    for (;;) {
+      const read = readSync(fd, chunk, 0, chunk.length, offset);
+      if (read === 0) break;
+      hash.update(chunk.subarray(0, read));
+      offset += read;
+    }
+    return hash.digest("hex");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
 };
 
 export const readGenerationState = (configDir: string): GenerationState => {
@@ -134,8 +264,7 @@ export const readGenerationState = (configDir: string): GenerationState => {
 };
 
 export const writeGenerationState = (configDir: string, state: GenerationState): void => {
-  mkdirSync(configDir, { recursive: true });
-  writeFileSync(path.join(configDir, GENERATION_FILE), JSON.stringify(state, null, 2) + "\n");
+  writeFileAtomic(path.join(configDir, GENERATION_FILE), JSON.stringify(state, null, 2) + "\n");
 };
 
 const listSkillNames = (root: string): string[] => {
@@ -168,22 +297,13 @@ export const classifyHostGeneration = (
     try {
       const cfg = JSON.parse(readFileSync(paths.opencodeConfig, "utf8"));
       const plugins = Array.isArray(cfg.plugin) ? cfg.plugin : cfg.plugin ? [cfg.plugin] : [];
-      const hasLegacyPin = plugins.some(
-        (p: unknown) =>
-          String(p).includes("workflow-toolkit") || String(p).includes("/assets/commands/wk-"),
-      );
-      const hasWorkit = plugins.some((p: unknown) => isWorkitPlugin(p));
-      const devAssets =
-        paths.dev &&
-        existsSync(path.join(paths.dev, "packages/workit-opencode/assets/commands/wk-init.md"));
-      const legacy = hasLegacyPin || Boolean(devAssets);
-      const v1 =
-        hasWorkit &&
-        paths.dev &&
-        existsSync(path.join(paths.dev, "packages/workit-opencode/dist/plugin.js"));
+      const workitPins = plugins.filter((p: unknown) => isWorkitPlugin(p));
+      const canonicalV1Pin = `file://${paths.dev}/packages/workit-opencode/dist/plugin.js`;
+      const v1 = workitPins.some((p: unknown) => String(p) === canonicalV1Pin);
+      const legacy = workitPins.some((p: unknown) => String(p) !== canonicalV1Pin);
       if (legacy && v1) return "mixed";
       if (v1) return "v1";
-      if (legacy || hasWorkit) return "legacy";
+      if (legacy) return "legacy";
       return "none";
     } catch {
       return "none";
@@ -196,14 +316,29 @@ export const classifyHostGeneration = (
     return existsSync(path.join(plugin, ".codex-plugin")) ? "v1" : "legacy";
   }
   if (host === "pi") {
-    const piConfig = path.join(paths.home, ".pi", "config.json");
-    if (!existsSync(piConfig)) return "none";
+    const extension = paths.dev && path.resolve(paths.dev, "packages/workit-pi/dist/workit.js");
+    const packageDir = paths.dev && path.resolve(paths.dev, "packages/workit-pi");
+    if (!existsSync(paths.piConfig) && !existsSync(paths.piSettings)) return "none";
     try {
-      const cfg = JSON.parse(readFileSync(piConfig, "utf8"));
-      const exts = cfg?.extensions ?? cfg?.pi?.extensions ?? [];
-      const has = (Array.isArray(exts) ? exts : []).some((e: unknown) =>
-        String(e).includes("workit"),
-      );
+      const config = existsSync(paths.piConfig)
+        ? JSON.parse(readFileSync(paths.piConfig, "utf8"))
+        : {};
+      const settings = existsSync(paths.piSettings)
+        ? JSON.parse(readFileSync(paths.piSettings, "utf8"))
+        : {};
+      const ext = config?.extensions ?? config?.pi?.extensions ?? [];
+      const packages = settings?.packages ?? [];
+      const has =
+        (typeof extension === "string" &&
+          Array.isArray(ext) &&
+          ext.some(
+            (entry: unknown) => typeof entry === "string" && path.resolve(entry) === extension,
+          )) ||
+        (typeof packageDir === "string" &&
+          Array.isArray(packages) &&
+          packages.some(
+            (entry: unknown) => typeof entry === "string" && path.resolve(entry) === packageDir,
+          ));
       return has ? "v1" : "none";
     } catch {
       return "none";
@@ -264,45 +399,431 @@ const managedCutoverFiles = (paths: ReturnType<typeof resolvePaths>): string[] =
   paths.opencodeConfig,
   paths.cursorSettings,
   paths.cursorMcp,
+  paths.piConfig,
+  paths.piSettings,
   path.join(paths.cursorPluginDir, "hooks", "hooks-cursor.json"),
 ];
 
+type CutoverScope = {
+  path: string;
+  category: CutoverInventoryEntry["category"];
+  disposition: CutoverInventoryEntry["disposition"];
+};
+
+const exactRegistrationEvidence = (
+  file: string,
+  paths: ReturnType<typeof resolvePaths>,
+): string | null => {
+  try {
+    if (!noSymlinkAncestor(path.dirname(file))) return null;
+    const fileStat = lstatOrNull(file);
+    if (!fileStat?.isFile() || fileStat.isSymbolicLink()) return null;
+    if (file === paths.opencodeConfig) {
+      const cfg = JSON.parse(readFileSync(file, "utf8"));
+      const plugins = Array.isArray(cfg.plugin) ? cfg.plugin : cfg.plugin ? [cfg.plugin] : [];
+      const workit = plugins.filter((plugin: unknown) => isWorkitPlugin(plugin));
+      return workit.length > 0 ? "exact Workit plugin entry in OpenCode config" : null;
+    }
+    if (file === paths.cursorSettings) {
+      const cfg = JSON.parse(readFileSync(file, "utf8"));
+      const enabled = cfg?.enabled_plugins;
+      const pluginEnabled =
+        enabled &&
+        typeof enabled === "object" &&
+        Object.entries(enabled).some(([name, value]) => isWorkitPlugin(name) && value === true);
+      const dirs = Array.isArray(cfg?.plugin_dirs) ? cfg.plugin_dirs : [];
+      const dirRegistered = dirs.some(
+        (dir: unknown) => typeof dir === "string" && path.resolve(dir) === paths.cursorPluginDir,
+      );
+      return pluginEnabled || dirRegistered
+        ? "exact Workit plugin key or directory in Cursor settings"
+        : null;
+    }
+    if (file === paths.cursorMcp) {
+      const cfg = JSON.parse(readFileSync(file, "utf8"));
+      const servers = cfg?.mcpServers;
+      const workit =
+        servers &&
+        typeof servers === "object" &&
+        Object.entries(servers).some(([name, value]) => {
+          if (isWorkitPlugin(name)) return true;
+          const server = value as { command?: unknown; args?: unknown } | null;
+          return (
+            server?.command === "npx" &&
+            Array.isArray(server.args) &&
+            server.args.includes(`--package=${CURSOR_RUNTIME_PACKAGE}`)
+          );
+        });
+      return workit ? "exact Workit MCP server entry in Cursor config" : null;
+    }
+    if (file === paths.piConfig) {
+      const cfg = JSON.parse(readFileSync(file, "utf8"));
+      const ext = paths.dev && path.join(paths.dev, "packages/workit-pi/dist/workit.js");
+      const skills = paths.dev && path.join(paths.dev, "packages/workit-pi/skills");
+      const matches = (value: unknown, target: string | null): boolean =>
+        target !== null &&
+        typeof value === "string" &&
+        path.resolve(value) === path.resolve(target);
+      const extensions = cfg?.extensions ?? cfg?.pi?.extensions;
+      const skillPaths = cfg?.skills ?? cfg?.pi?.skills;
+      if (
+        (Array.isArray(extensions) && extensions.some((entry: unknown) => matches(entry, ext))) ||
+        (Array.isArray(skillPaths) && skillPaths.some((entry: unknown) => matches(entry, skills)))
+      ) {
+        return "exact Workit extension or skills path in Pi config";
+      }
+    }
+    if (file === paths.piSettings) {
+      const cfg = JSON.parse(readFileSync(file, "utf8"));
+      const packageDir = paths.dev && path.join(paths.dev, "packages/workit-pi");
+      const matches = (entry: unknown): boolean =>
+        typeof packageDir === "string" &&
+        typeof entry === "string" &&
+        path.resolve(entry) === path.resolve(packageDir);
+      if (Array.isArray(cfg?.packages) && cfg.packages.some(matches)) {
+        return "exact Workit package path in Pi settings";
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+};
+
+const appendExactPath = (value: unknown, target: string): unknown[] => {
+  const entries = Array.isArray(value) ? value : value === undefined ? [] : [value];
+  return [
+    ...entries.filter(
+      (entry) => typeof entry !== "string" || path.resolve(entry) !== path.resolve(target),
+    ),
+    target,
+  ];
+};
+
+const mergePiConfig = (current: Record<string, unknown>, dev: string): Record<string, unknown> => {
+  const nestedPi =
+    current.pi && typeof current.pi === "object" && !Array.isArray(current.pi)
+      ? (current.pi as Record<string, unknown>)
+      : null;
+  const target = nestedPi ?? current;
+  const extension = path.join(dev, "packages/workit-pi/dist/workit.js");
+  const skills = path.join(dev, "packages/workit-pi/skills");
+  return nestedPi
+    ? {
+        ...current,
+        pi: {
+          ...nestedPi,
+          extensions: appendExactPath(nestedPi.extensions, extension),
+          skills: appendExactPath(nestedPi.skills, skills),
+        },
+      }
+    : {
+        ...target,
+        extensions: appendExactPath(target.extensions, extension),
+        skills: appendExactPath(target.skills, skills),
+      };
+};
+
+const mergePiSettings = (
+  current: Record<string, unknown>,
+  dev: string,
+): Record<string, unknown> => ({
+  ...current,
+  packages: appendExactPath(current.packages, path.join(dev, "packages/workit-pi")),
+});
+
+const legacyFlowInventoryTargets = (workspace: string, issues: Set<string>): string[] => {
+  const docs = path.join(workspace, "docs");
+  let docsStat: ReturnType<typeof lstatSync> | null;
+  try {
+    if (!noSymlinkAncestor(path.dirname(docs))) {
+      issues.add(`symlinked parent is outside the inventoried scope: ${path.dirname(docs)}`);
+      return [];
+    }
+    docsStat = lstatOrNull(docs);
+  } catch (error) {
+    issues.add(`cannot inspect project history at ${docs}: ${String(error)}`);
+    return [];
+  }
+  if (!docsStat) return [];
+  if (docsStat.isSymbolicLink()) return [docs];
+  if (!docsStat.isDirectory()) return [];
+
+  const targets: string[] = [];
+  try {
+    const { names: slugs, truncated } = readDirNamesBounded(docs, MAX_CUTOVER_INVENTORY_ENTRIES);
+    if (truncated) {
+      issues.add(`project history inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} entries`);
+    }
+    for (const slug of slugs) {
+      const slugPath = path.join(docs, slug);
+      const slugStat = lstatOrNull(slugPath);
+      if (!slugStat) continue;
+      if (slugStat.isSymbolicLink()) {
+        targets.push(slugPath);
+        continue;
+      }
+      if (!slugStat.isDirectory()) continue;
+      const sddPath = path.join(slugPath, "sdd");
+      const sddStat = lstatOrNull(sddPath);
+      if (!sddStat) continue;
+      if (sddStat.isSymbolicLink()) {
+        targets.push(sddPath);
+        continue;
+      }
+      if (!sddStat.isDirectory()) continue;
+      const flow = path.join(sddPath, "flow.json");
+      if (lstatOrNull(flow)) targets.push(flow);
+      if (targets.length >= MAX_CUTOVER_INVENTORY_ENTRIES) {
+        issues.add(`project history inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} entries`);
+        break;
+      }
+    }
+  } catch (error) {
+    issues.add(`cannot enumerate project history at ${docs}: ${String(error)}`);
+  }
+  return targets;
+};
+
+const cutoverInventoryScopes = (
+  paths: ReturnType<typeof resolvePaths>,
+  issues: Set<string>,
+): CutoverScope[] => [
+  { path: paths.configDir, category: "configuration", disposition: "preserve" },
+  { path: paths.stateDir, category: "recovery", disposition: "preserve" },
+  {
+    path: path.join(paths.workspace, ".workit"),
+    category: "project-state",
+    disposition: "preserve",
+  },
+  ...legacyFlowInventoryTargets(paths.workspace, issues).map((path) => ({
+    path,
+    category: "project-history" as const,
+    disposition: "preserve" as const,
+  })),
+  { path: paths.opencodeConfig, category: "host-configuration", disposition: "unknown" },
+  { path: paths.cursorSettings, category: "host-configuration", disposition: "unknown" },
+  { path: paths.cursorMcp, category: "host-configuration", disposition: "unknown" },
+  {
+    path: paths.cursorPluginDir,
+    category: "integration",
+    disposition: "unknown",
+  },
+  {
+    path: path.join(paths.home, ".codex", "plugins", "workit"),
+    category: "integration",
+    disposition: "unknown",
+  },
+  {
+    path: paths.piConfig,
+    category: "host-configuration",
+    disposition: "unknown",
+  },
+  {
+    path: paths.piSettings,
+    category: "host-configuration",
+    disposition: "unknown",
+  },
+];
+
+const buildCutoverInventory = (paths: ReturnType<typeof resolvePaths>): CutoverInventory => {
+  const entries: CutoverInventoryEntry[] = [];
+  const issues = new Set<string>();
+  const seen = new Set<string>();
+  const cursorPluginRegistered = exactRegistrationEvidence(paths.cursorSettings, paths) !== null;
+  const add = (scope: CutoverScope, file: string, depth: number): void => {
+    if (entries.length >= MAX_CUTOVER_INVENTORY_ENTRIES) {
+      issues.add(`cutover inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} entries`);
+      return;
+    }
+    if (seen.has(file)) return;
+    seen.add(file);
+
+    if (depth === 0) {
+      try {
+        if (!noSymlinkAncestor(path.dirname(file))) {
+          issues.add(`symlinked parent is outside the inventoried scope: ${path.dirname(file)}`);
+          return;
+        }
+      } catch (error) {
+        issues.add(`cannot inspect parent for ${file}: ${String(error)}`);
+        return;
+      }
+    }
+    let stat: ReturnType<typeof lstatSync> | null;
+    try {
+      stat = lstatOrNull(file);
+    } catch (error) {
+      issues.add(`cannot inspect ${file}: ${String(error)}`);
+      return;
+    }
+    if (!stat) return;
+
+    const kind: CutoverInventoryEntry["kind"] = stat.isSymbolicLink()
+      ? "symlink"
+      : stat.isDirectory()
+        ? "directory"
+        : stat.isFile()
+          ? "file"
+          : "other";
+    let digest: Digest | null = null;
+    if (kind === "file") {
+      try {
+        digest = digestFile(file);
+        if (digest === null) issues.add(`file changed during inventory: ${file}`);
+      } catch (error) {
+        issues.add(`cannot read ${file}: ${String(error)}`);
+      }
+    } else if (kind === "symlink") {
+      issues.add(`symlink not followed during inventory: ${file}`);
+    } else if (kind === "other") {
+      issues.add(`unsupported filesystem entry during inventory: ${file}`);
+    }
+
+    const inCursorPlugin =
+      file === paths.cursorPluginDir || file.startsWith(`${paths.cursorPluginDir}${path.sep}`);
+    const cursorAssetPath = inCursorPlugin
+      ? path.relative(paths.cursorPluginDir, file).split(path.sep).join("/")
+      : "";
+    const expectedCursorDigest = LEGACY_CURSOR_ASSET_DIGESTS[cursorAssetPath];
+    const verifiedCursorAsset =
+      kind === "file" && digest !== null && expectedCursorDigest === digest;
+    const ownershipEvidence = verifiedCursorAsset
+      ? `SHA-256 matches generated Cursor asset from Workit 1.2.1: ${cursorAssetPath}`
+      : kind === "file"
+        ? exactRegistrationEvidence(file, paths)
+        : inCursorPlugin && cursorPluginRegistered
+          ? "Cursor settings registers this plugin directory; individual files remain unverified"
+          : null;
+    const disposition =
+      file === path.join(paths.configDir, "config.json")
+        ? "convert"
+        : verifiedCursorAsset || (ownershipEvidence && scope.category === "host-configuration")
+          ? "convert"
+          : scope.disposition;
+    entries.push({
+      path: file,
+      kind,
+      category: scope.category,
+      disposition,
+      bytes: kind === "file" ? stat.size : 0,
+      digest,
+      ownershipEvidence,
+    });
+
+    if (kind !== "directory") return;
+    if (depth >= MAX_CUTOVER_INVENTORY_DEPTH) {
+      issues.add(`inventory depth exceeds ${MAX_CUTOVER_INVENTORY_DEPTH}: ${file}`);
+      return;
+    }
+    try {
+      const { names, truncated } = readDirNamesBounded(
+        file,
+        Math.max(0, MAX_CUTOVER_INVENTORY_ENTRIES - entries.length),
+      );
+      if (truncated)
+        issues.add(`cutover inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} entries`);
+      for (const name of names) add(scope, path.join(file, name), depth + 1);
+    } catch (error) {
+      issues.add(`cannot enumerate ${file}: ${String(error)}`);
+    }
+  };
+
+  for (const scope of cutoverInventoryScopes(paths, issues)) add(scope, scope.path, 0);
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  const bytesByCategory: CutoverInventory["bytesByCategory"] = {};
+  let files = 0;
+  let bytes = 0;
+  const hash = createHash("sha256");
+  for (const entry of entries) {
+    if (entry.kind === "file") {
+      files += 1;
+      bytes += entry.bytes;
+      bytesByCategory[entry.category] = (bytesByCategory[entry.category] ?? 0) + entry.bytes;
+    }
+    hash.update(`${entry.path}\0${entry.kind}\0${entry.bytes}\0${entry.digest ?? ""}\n`);
+  }
+  const issueList = [...issues].sort();
+  for (const issue of issueList) hash.update(`!${issue}\n`);
+  return {
+    complete: issueList.length === 0,
+    entries,
+    files,
+    bytes,
+    bytesByCategory,
+    issues: issueList,
+    revision: hash.digest("hex"),
+  };
+};
+
 const hostMutationTargets = (
   paths: ReturnType<typeof resolvePaths>,
   hosts: CutoverHost[],
 ): string[] => {
   const targets: string[] = [];
   for (const host of hosts) {
-    if (host === "cursor") {
-      targets.push(path.join(paths.cursorPluginDir, "skills"));
-      const vendor = path.join(paths.cursorPluginDir, "vendor");
-      if (existsSync(vendor)) targets.push(vendor);
-    }
+    if (host === "cursor")
+      targets.push(
+        path.join(paths.cursorPluginDir, "skills"),
+        path.join(paths.cursorPluginDir, "commands"),
+        path.join(paths.cursorPluginDir, "rules", "workit-contract.mdc"),
+      );
     if (host === "codex") targets.push(path.join(paths.home, ".codex", "plugins", "workit"));
-    if (host === "pi") targets.push(path.join(paths.home, ".pi", "config.json"));
+    if (host === "pi") targets.push(paths.piConfig, paths.piSettings);
   }
   return targets;
 };
 
-const expandBackupTargets = (targets: string[]): string[] => {
+const expandBackupTargets = (targets: string[]): { files: string[]; issues: string[] } => {
   const files: string[] = [];
+  const issues = new Set<string>();
   for (const target of targets) {
-    if (!existsSync(target)) continue;
-    const st = statSync(target);
-    if (st.isDirectory()) {
-      const walk = (dir: string) => {
-        for (const name of readdirSync(dir)) {
-          const p = path.join(dir, name);
-          if (statSync(p).isDirectory()) walk(p);
-          else files.push(p);
+    const walk = (file: string, depth: number): void => {
+      if (files.length >= MAX_CUTOVER_INVENTORY_ENTRIES) {
+        issues.add(`backup inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} files`);
+        return;
+      }
+      if (depth === 0 && !noSymlinkAncestor(path.dirname(file))) {
+        issues.add(`symlinked parent is outside the backup scope: ${path.dirname(file)}`);
+        return;
+      }
+      let stat: ReturnType<typeof lstatSync> | null;
+      try {
+        stat = lstatOrNull(file);
+      } catch (error) {
+        issues.add(`cannot inspect backup target ${file}: ${String(error)}`);
+        return;
+      }
+      if (!stat) return;
+      if (stat.isSymbolicLink()) {
+        issues.add(`symlink not followed in backup target: ${file}`);
+        return;
+      }
+      if (stat.isDirectory()) {
+        if (depth >= MAX_CUTOVER_INVENTORY_DEPTH) {
+          issues.add(`backup inventory depth exceeds ${MAX_CUTOVER_INVENTORY_DEPTH}: ${file}`);
+          return;
         }
-      };
-      walk(target);
-    } else {
-      files.push(target);
-    }
+        try {
+          const { names, truncated } = readDirNamesBounded(
+            file,
+            Math.max(0, MAX_CUTOVER_INVENTORY_ENTRIES - files.length),
+          );
+          if (truncated)
+            issues.add(`backup inventory exceeds ${MAX_CUTOVER_INVENTORY_ENTRIES} files`);
+          for (const name of names) walk(path.join(file, name), depth + 1);
+        } catch (error) {
+          issues.add(`cannot enumerate backup target ${file}: ${String(error)}`);
+        }
+      } else if (stat.isFile()) {
+        files.push(file);
+      } else {
+        issues.add(`unsupported backup entry: ${file}`);
+      }
+    };
+    walk(target, 0);
   }
-  return files;
+  return { files, issues: [...issues] };
 };
 
 const cutoverBackupTargets = (
@@ -310,8 +831,29 @@ const cutoverBackupTargets = (
   hosts: CutoverHost[],
 ): string[] => [...new Set([...managedCutoverFiles(paths), ...hostMutationTargets(paths, hosts)])];
 
-const backupRoot = (stateDir: string, backupId: Id) =>
-  path.join(stateDir, "cutover", "backups", backupId);
+const backupRoot = (archiveDir: string, backupId: Id) => path.join(archiveDir, backupId);
+
+const archiveDestinationError = (
+  archiveDir: string,
+  paths: ReturnType<typeof resolvePaths>,
+): string | null => {
+  const resolved = path.resolve(archiveDir);
+  const scopes = [paths.configDir, paths.stateDir, paths.workspace].map((p) => path.resolve(p));
+  if (
+    scopes.some(
+      (scope) =>
+        resolved === scope ||
+        resolved.startsWith(scope + path.sep) ||
+        scope.startsWith(resolved + path.sep),
+    )
+  ) {
+    return "archive destination must be separate from config, state, and workspace";
+  }
+  if (!noSymlinkAncestor(resolved)) return "archive destination has a symlinked ancestor";
+  const existing = lstatOrNull(resolved);
+  if (existing && !existing.isDirectory()) return "archive destination is not a directory";
+  return null;
+};
 
 const backupRelPath = (file: string, paths: ReturnType<typeof resolvePaths>): string => {
   if (file.startsWith(paths.configDir + path.sep) || file === paths.configDir) {
@@ -320,24 +862,117 @@ const backupRelPath = (file: string, paths: ReturnType<typeof resolvePaths>): st
   return path.join("home", path.relative(paths.home, file));
 };
 
+type VerifiedBackupFile = { digest: Digest; storagePath: string };
+
+const readBackupFiles = (
+  backupId: Id,
+  archiveDir: string,
+  paths: ReturnType<typeof resolvePaths>,
+): { files: Map<string, VerifiedBackupFile>; issues: string[] } => {
+  const root = backupRoot(archiveDir, backupId);
+  const manifestPath = path.join(root, "manifest.json");
+  const files = new Map<string, VerifiedBackupFile>();
+  const issues: string[] = [];
+  if (digestFile(manifestPath) === null) {
+    return { files, issues: ["backup manifest is missing or unsafe"] };
+  }
+
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return { files, issues: ["backup manifest is unreadable"] };
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { files, issues: ["backup manifest is malformed"] };
+  }
+
+  const data = manifest as Record<string, unknown>;
+  const hashed = data.schemaVersion === 1 && data.storage === "sha256-path-v1";
+  const legacy = data.schemaVersion === undefined && data.storage === undefined;
+  if (data.backupId !== backupId || (!hashed && !legacy) || !Array.isArray(data.files)) {
+    return { files, issues: ["backup manifest identity or format is invalid"] };
+  }
+
+  for (const item of data.files) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      issues.push("backup manifest contains an invalid file entry");
+      continue;
+    }
+    const entry = item as Record<string, unknown>;
+    if (
+      typeof entry.path !== "string" ||
+      !path.isAbsolute(entry.path) ||
+      path.resolve(entry.path) !== entry.path
+    ) {
+      issues.push("backup manifest contains an invalid file path");
+      continue;
+    }
+    const digest = hashed ? entry.digest : entry.installedDigest;
+    if (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)) {
+      issues.push(`backup digest is invalid: ${entry.path}`);
+      continue;
+    }
+    if (files.has(entry.path)) {
+      issues.push(`backup path is duplicated: ${entry.path}`);
+      continue;
+    }
+
+    const relative = hashed
+      ? path.join("files", createHash("sha256").update(entry.path).digest("hex"))
+      : backupRelPath(entry.path, paths);
+    const storagePath = path.resolve(root, relative);
+    const fromRoot = path.relative(path.resolve(root), storagePath);
+    if (
+      fromRoot === "" ||
+      fromRoot === ".." ||
+      fromRoot.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(fromRoot)
+    ) {
+      issues.push(`backup path escapes its directory: ${entry.path}`);
+      continue;
+    }
+    if (digestFile(storagePath) !== digest) {
+      issues.push(`backup content failed verification: ${entry.path}`);
+      continue;
+    }
+    files.set(entry.path, { digest: digest as Digest, storagePath });
+  }
+  return { files, issues };
+};
+
 const writeBackup = (
   backupId: Id,
+  archiveDir: string,
   paths: ReturnType<typeof resolvePaths>,
   files: string[],
 ): void => {
-  const root = backupRoot(paths.stateDir, backupId);
+  const root = backupRoot(archiveDir, backupId);
   mkdirSync(root, { recursive: true });
-  const manifest: CutoverReceipt["managedFiles"] = [];
+  const manifest: { path: string; digest: Digest }[] = [];
   for (const file of files) {
     if (!existsSync(file)) continue;
-    const dest = path.join(root, backupRelPath(file, paths));
+    const before = digestFile(file);
+    if (before === null) throw new Error(`backup source is not a regular file: ${file}`);
+    const dest = path.join(
+      root,
+      "files",
+      createHash("sha256").update(path.resolve(file)).digest("hex"),
+    );
     mkdirSync(path.dirname(dest), { recursive: true });
-    cpSync(file, dest);
-    manifest.push({ path: file, installedDigest: digestFile(file)! });
+    cpSync(file, dest, { dereference: false, errorOnExist: true });
+    if (digestFile(file) !== before || digestFile(dest) !== before) {
+      throw new Error(`backup verification failed: ${file}`);
+    }
+    manifest.push({ path: path.resolve(file), digest: before });
   }
-  writeFileSync(
+  writeFileAtomic(
     path.join(root, "manifest.json"),
-    JSON.stringify({ backupId, files: manifest }, null, 2) + "\n",
+    JSON.stringify(
+      { schemaVersion: 1, storage: "sha256-path-v1", backupId, files: manifest },
+      null,
+      2,
+    ) + "\n",
   );
 };
 
@@ -345,11 +980,72 @@ const receiptPath = (stateDir: string, backupId: Id) =>
   path.join(stateDir, "cutover", "receipts", `${backupId}.json`);
 
 const writeReceipt = (receipt: CutoverReceipt, stateDir: string): void => {
-  mkdirSync(path.dirname(receiptPath(stateDir, receipt.backupId)), { recursive: true });
-  writeFileSync(receiptPath(stateDir, receipt.backupId), JSON.stringify(receipt, null, 2) + "\n");
+  writeFileAtomic(receiptPath(stateDir, receipt.backupId), JSON.stringify(receipt, null, 2) + "\n");
+};
+
+const cutoverJournalPath = (stateDir: string, backupId: Id): string =>
+  path.join(stateDir, "cutover", "journals", `${backupId}.json`);
+
+const writeCutoverJournal = (journal: CutoverJournal, stateDir: string): void => {
+  writeFileAtomic(
+    cutoverJournalPath(stateDir, journal.backupId),
+    JSON.stringify(journal, null, 2) + "\n",
+  );
+};
+
+const isCutoverHost = (value: unknown): value is CutoverHost =>
+  value === "opencode" || value === "cursor" || value === "codex" || value === "pi";
+
+const readCutoverJournal = (backupId: Id, stateDir: string): CutoverJournal | null => {
+  if (!validCutoverId(backupId)) return null;
+  const file = cutoverJournalPath(stateDir, backupId);
+  if (digestFile(file) === null) return null;
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8")) as Partial<CutoverJournal>;
+    const stepNames = new Set([
+      "configuration",
+      "generation",
+      "verification",
+      "receipt",
+      ...(value.hosts ?? []).map((h) => `host:${h}`),
+    ]);
+    if (
+      value.schemaVersion !== 1 ||
+      value.backupId !== backupId ||
+      typeof value.archiveDir !== "string" ||
+      !path.isAbsolute(value.archiveDir) ||
+      path.resolve(value.archiveDir) !== value.archiveDir ||
+      typeof value.planId !== "string" ||
+      !Array.isArray(value.hosts) ||
+      !value.hosts.every(isCutoverHost) ||
+      !value.hosts.length ||
+      !value.resolutions ||
+      typeof value.resolutions !== "object" ||
+      Object.values(value.resolutions).some((entry) => typeof entry !== "string") ||
+      typeof value.conversionNeeded !== "boolean" ||
+      !["applying", "interrupted", "partial", "complete"].includes(value.phase ?? "") ||
+      !Array.isArray(value.completedSteps) ||
+      value.completedSteps.some((step) => typeof step !== "string" || !stepNames.has(step)) ||
+      !Array.isArray(value.appliedHosts) ||
+      value.appliedHosts.some((host) => !isCutoverHost(host) || !value.hosts?.includes(host)) ||
+      !(
+        value.currentStep === null ||
+        (typeof value.currentStep === "string" && stepNames.has(value.currentStep))
+      ) ||
+      !(value.error === null || typeof value.error === "string") ||
+      typeof value.startedAt !== "string" ||
+      !Array.isArray(value.notes) ||
+      value.notes.some((note) => typeof note !== "string")
+    )
+      return null;
+    return value as CutoverJournal;
+  } catch {
+    return null;
+  }
 };
 
 export const readCutoverReceipt = (backupId: Id, stateDir: string): CutoverReceipt | null => {
+  if (!validCutoverId(backupId)) return null;
   const file = receiptPath(stateDir, backupId);
   if (!existsSync(file)) return null;
   try {
@@ -387,6 +1083,16 @@ const plannedAfterDigest = (
     );
     return createHash("sha256").update(JSON.stringify(merged.config)).digest("hex");
   }
+  if (file === paths.piConfig && paths.dev) {
+    const current = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    const next = mergePiConfig(current, paths.dev);
+    return createHash("sha256").update(JSON.stringify(next)).digest("hex");
+  }
+  if (file === paths.piSettings && paths.dev) {
+    const current = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    const next = mergePiSettings(current, paths.dev);
+    return createHash("sha256").update(JSON.stringify(next)).digest("hex");
+  }
   if (file.endsWith("hooks-cursor.json")) {
     const entry = cursorHooksEntry(paths.cursorPluginDir);
     const base = existsSync(file)
@@ -406,13 +1112,28 @@ export function previewCutover(
   hosts: CutoverHost[] = ["opencode", "cursor"],
 ): CutoverPlan {
   const paths = resolvePaths(options);
-  const conversion = previewConversion({ configDir: paths.configDir });
   const blocked: string[] = [];
+  const archiveDir = options.archiveDir ? path.resolve(options.archiveDir) : null;
+  if (archiveDir) {
+    const archiveError = archiveDestinationError(archiveDir, paths);
+    if (archiveError) blocked.push(archiveError);
+  }
+  const inventory = buildCutoverInventory(paths);
+  let conversion: ConversionPreview = { mappings: [], preserved: [], unresolved: [] };
+  if (inventory.complete) {
+    try {
+      conversion = previewConversion({ configDir: paths.configDir });
+    } catch (error) {
+      blocked.push(`cannot preview configuration conversion: ${String(error)}`);
+    }
+  }
   const unresolved = [...conversion.unresolved];
 
-  for (const host of hosts) {
-    const gen = classifyHostGeneration(host, paths);
-    if (gen === "mixed") blocked.push(`${host}: mixed legacy and v1 components`);
+  if (inventory.complete) {
+    for (const host of hosts) {
+      const gen = classifyHostGeneration(host, paths);
+      if (gen === "mixed") blocked.push(`${host}: mixed legacy and v1 components`);
+    }
   }
 
   for (const session of paths.sessions) {
@@ -421,17 +1142,51 @@ export function previewCutover(
     }
   }
 
-  const managedFiles = managedCutoverFiles(paths).map((filePath) => ({
-    path: filePath,
-    beforeDigest: digestFile(filePath),
-    afterDigest: existsSync(filePath)
-      ? plannedAfterDigest(filePath, hosts[0] ?? "cursor", paths)
-      : createHash("sha256").update("").digest("hex"),
-  }));
+  for (const issue of inventory.issues) blocked.push(`inventory: ${issue}`);
+
+  const managedFiles = managedCutoverFiles(paths).map((filePath) => {
+    if (!noSymlinkAncestor(path.dirname(filePath))) {
+      blocked.push(`symlinked parent is outside the inventoried scope: ${path.dirname(filePath)}`);
+      return {
+        path: filePath,
+        beforeDigest: null,
+        afterDigest: createHash("sha256").update("").digest("hex"),
+      };
+    }
+    const stat = lstatOrNull(filePath);
+    if (stat && !stat.isFile()) {
+      blocked.push(`managed path is not a regular file: ${filePath}`);
+      return {
+        path: filePath,
+        beforeDigest: null,
+        afterDigest: createHash("sha256").update("").digest("hex"),
+      };
+    }
+    const beforeDigest = digestFile(filePath);
+    try {
+      return {
+        path: filePath,
+        beforeDigest,
+        afterDigest:
+          beforeDigest === null
+            ? createHash("sha256").update("").digest("hex")
+            : plannedAfterDigest(filePath, hosts[0] ?? "cursor", paths),
+      };
+    } catch (error) {
+      blocked.push(`cannot plan managed file ${filePath}: ${String(error)}`);
+      return {
+        path: filePath,
+        beforeDigest,
+        afterDigest: beforeDigest ?? createHash("sha256").update("").digest("hex"),
+      };
+    }
+  });
 
   return {
     id: randomUUID(),
+    archiveDir,
     managedFiles,
+    inventory,
     sessions: paths.sessions,
     unresolved,
     conversion,
@@ -440,32 +1195,56 @@ export function previewCutover(
   };
 }
 
-const syncV1CursorSkills = (pluginDir: string, dev: string | null) => {
+const syncV1CursorSkills = (pluginDir: string, dev: string | null, notes: string[]) => {
+  const syncGeneratedFile = (relative: string, file: string, content: string): void => {
+    if (!noSymlinkAncestor(path.dirname(file))) throw new Error(`symlinked parent: ${file}`);
+    const stat = lstatOrNull(file);
+    if (stat?.isSymbolicLink()) throw new Error(`refusing to write through symlink: ${file}`);
+    if (stat && !stat.isFile()) throw new Error(`refusing to replace non-file: ${file}`);
+    const desiredDigest = createHash("sha256").update(content).digest("hex");
+    if (!stat) {
+      writeFileExclusive(file, content);
+      return;
+    }
+    const currentDigest = digestFile(file);
+    if (currentDigest === desiredDigest) return;
+    if (currentDigest === LEGACY_CURSOR_ASSET_DIGESTS[relative]) {
+      writeFileAtomic(file, content);
+      notes.push(`cursor: refreshed verified generated asset ${relative}`);
+    } else {
+      notes.push(`cursor: preserved modified or unknown asset ${relative}`);
+    }
+  };
   mkdirSync(path.join(pluginDir, "skills"), { recursive: true });
   for (const skill of WORKIT_METHOD_SKILLS) {
     const src = dev ? path.join(dev, "packages/workit-cursor/skills", skill, "SKILL.md") : null;
     const destDir = path.join(pluginDir, "skills", skill);
     mkdirSync(destDir, { recursive: true });
-    writeFileSync(
+    syncGeneratedFile(
+      `skills/${skill}/SKILL.md`,
       path.join(destDir, "SKILL.md"),
       src && existsSync(src) ? readFileSync(src, "utf8") : "# v1\n",
     );
   }
-  for (const name of readdirSync(path.join(pluginDir, "skills"))) {
-    if (name.startsWith("wk-"))
-      rmSync(path.join(pluginDir, "skills", name), { recursive: true, force: true });
-  }
   // Bare slash aliases ship next to skills so installs match the repo.
   mkdirSync(path.join(pluginDir, "commands"), { recursive: true });
   for (const alias of Object.keys(WORKIT_SKILL_ALIASES)) {
     const src = dev ? path.join(dev, "packages/workit-cursor/commands", `${alias}.md`) : null;
-    writeFileSync(
+    syncGeneratedFile(
+      `commands/${alias}.md`,
       path.join(pluginDir, "commands", `${alias}.md`),
       src && existsSync(src) ? readFileSync(src, "utf8") : `# /${alias}\n`,
     );
   }
-  const vendor = path.join(pluginDir, "vendor");
-  if (existsSync(vendor)) rmSync(vendor, { recursive: true, force: true });
+  const ruleSource = dev && path.join(dev, "packages/workit-cursor/rules/workit-contract.mdc");
+  if (ruleSource && existsSync(ruleSource)) {
+    mkdirSync(path.join(pluginDir, "rules"), { recursive: true });
+    syncGeneratedFile(
+      "rules/workit-contract.mdc",
+      path.join(pluginDir, "rules", "workit-contract.mdc"),
+      readFileSync(ruleSource, "utf8"),
+    );
+  }
 };
 
 const applyHostCutover = (
@@ -474,18 +1253,18 @@ const applyHostCutover = (
   notes: string[],
 ): boolean => {
   if (host === "cursor") {
-    syncV1CursorSkills(paths.cursorPluginDir, paths.dev);
+    syncV1CursorSkills(paths.cursorPluginDir, paths.dev, notes);
     const settings = existsSync(paths.cursorSettings)
       ? JSON.parse(readFileSync(paths.cursorSettings, "utf8"))
       : {};
-    writeFileSync(
+    writeFileAtomic(
       paths.cursorSettings,
       JSON.stringify(mergeCursorSettings(settings, paths.cursorPluginDir).config, null, 2) + "\n",
     );
     const mcp = existsSync(paths.cursorMcp)
       ? JSON.parse(readFileSync(paths.cursorMcp, "utf8"))
       : { mcpServers: {} };
-    writeFileSync(
+    writeFileAtomic(
       paths.cursorMcp,
       JSON.stringify(
         mergeCursorMcp(mcp, "workit", cursorMcpServerEntry(paths.cursorPluginDir)).config,
@@ -498,10 +1277,36 @@ const applyHostCutover = (
       ? JSON.parse(readFileSync(hooksPath, "utf8"))
       : { version: 1, hooks: {} };
     const entry = cursorHooksEntry(paths.cursorPluginDir);
-    writeFileSync(
+    const hookConfig = hooks && typeof hooks === "object" ? hooks : { version: 1, hooks: {} };
+    const hookMap =
+      hookConfig.hooks && typeof hookConfig.hooks === "object" ? hookConfig.hooks : {};
+    const sessionStart = Array.isArray(hookMap.sessionStart) ? hookMap.sessionStart : [];
+    const isWorkitSessionStart = (value: unknown): boolean => {
+      const command =
+        typeof value === "string"
+          ? value
+          : value && typeof value === "object" && "command" in value
+            ? String(value.command)
+            : "";
+      return (
+        command === entry.command ||
+        command ===
+          `npx -y --prefer-online --min-release-age=0 --package=${CURSOR_RUNTIME_PACKAGE} workit-cursor-session-start`
+      );
+    };
+    writeFileAtomic(
       hooksPath,
       JSON.stringify(
-        { ...hooks, hooks: { ...hooks.hooks, sessionStart: [{ command: entry.command }] } },
+        {
+          ...hookConfig,
+          hooks: {
+            ...hookMap,
+            sessionStart: [
+              ...sessionStart.filter((item: unknown) => !isWorkitSessionStart(item)),
+              entry,
+            ],
+          },
+        },
         null,
         2,
       ) + "\n",
@@ -516,11 +1321,11 @@ const applyHostCutover = (
     const distDir = path.join(paths.dev, "packages/workit-opencode/dist");
     mkdirSync(distDir, { recursive: true });
     const dist = path.join(distDir, "plugin.js");
-    if (!existsSync(dist)) writeFileSync(dist, "export default {};\n");
+    if (!existsSync(dist)) writeFileExclusive(dist, "export default {};\n");
     const current = existsSync(paths.opencodeConfig)
       ? JSON.parse(readFileSync(paths.opencodeConfig, "utf8"))
       : {};
-    writeFileSync(
+    writeFileAtomic(
       paths.opencodeConfig,
       JSON.stringify(mergeOpenCodeConfig(current, pin).config, null, 2) + "\n",
     );
@@ -535,22 +1340,33 @@ const applyHostCutover = (
       path.join(pluginDir, ".codex-plugin"),
       {
         recursive: true,
+        force: false,
+        errorOnExist: false,
+        dereference: false,
       },
     );
     notes.push("codex: installed v1 plugin scaffold");
     return true;
   }
   if (host === "pi" && paths.dev) {
-    const piConfig = path.join(paths.home, ".pi", "config.json");
-    mkdirSync(path.dirname(piConfig), { recursive: true });
-    const current = existsSync(piConfig) ? JSON.parse(readFileSync(piConfig, "utf8")) : {};
-    const next = {
-      ...current,
-      extensions: [`${path.join(paths.dev, "packages/workit-pi/dist/workit.js")}`],
-      skills: [`${path.join(paths.dev, "packages/workit-pi/skills")}`],
+    mkdirSync(path.dirname(paths.piConfig), { recursive: true });
+    mkdirSync(path.dirname(paths.piSettings), { recursive: true });
+    const readConfig = (file: string): Record<string, unknown> => {
+      if (!existsSync(file)) return {};
+      const value = JSON.parse(readFileSync(file, "utf8"));
+      return value && typeof value === "object" && !Array.isArray(value) ? value : {};
     };
-    writeFileSync(piConfig, JSON.stringify(next, null, 2) + "\n");
-    notes.push("pi: registered v1 extension and skills");
+    writeFileAtomic(
+      paths.piConfig,
+      JSON.stringify(mergePiConfig(readConfig(paths.piConfig), paths.dev), null, 2) + "\n",
+    );
+    writeFileAtomic(
+      paths.piSettings,
+      JSON.stringify(mergePiSettings(readConfig(paths.piSettings), paths.dev), null, 2) + "\n",
+    );
+    notes.push(
+      "pi: registered v1 package, extension, and skills while preserving unrelated entries",
+    );
     return true;
   }
   return false;
@@ -574,6 +1390,25 @@ export function applyCutover(
   }
 
   const paths = resolvePaths(options);
+  if (!options.archiveDir || !plan.archiveDir)
+    return failure("needs_input", "archive destination is required (--archive-dir)");
+  const archiveDir = path.resolve(options.archiveDir);
+  if (archiveDir !== plan.archiveDir)
+    return failure("revision_conflict", "archive destination changed since preview");
+  const archiveError = archiveDestinationError(archiveDir, paths);
+  if (archiveError) return failure("requirements_unsatisfied", archiveError);
+  if (!plan.inventory?.complete) {
+    return failure("requirements_unsatisfied", "cutover inventory is incomplete");
+  }
+  const currentInventory = buildCutoverInventory(paths);
+  if (!currentInventory.complete) {
+    return failure("requirements_unsatisfied", "cutover inventory is incomplete", {
+      fields: currentInventory.issues.map((issue) => ({ path: issue, reason: "inventory" })),
+    });
+  }
+  if (currentInventory.revision !== plan.inventory.revision) {
+    return failure("revision_conflict", "cutover sources changed since preview");
+  }
   for (const entry of plan.managedFiles) {
     const current = digestFile(entry.path);
     if (entry.beforeDigest !== null && current !== entry.beforeDigest) {
@@ -598,74 +1433,267 @@ export function applyCutover(
 
   const backupId = randomUUID();
   const backupTargets = cutoverBackupTargets(paths, decision.hosts);
-  const backupFiles = expandBackupTargets(backupTargets);
-  writeBackup(backupId, paths, backupFiles);
-
-  const conversionNotes: string[] = [];
-  if (plan.unresolved.length > 0 || plan.conversion.mappings.length > 0) {
-    const applied = applyConversionConfig(
-      paths.configDir,
-      plan.conversion,
-      decision.resolutions ?? {},
-    );
-    conversionNotes.push(
-      `config: wrote ${applied.configPath} and recorded choices at ${applied.choicesPath}`,
+  const backupInventory = expandBackupTargets(backupTargets);
+  if (backupInventory.issues.length > 0) {
+    return failure("requirements_unsatisfied", "cutover backup inventory is incomplete", {
+      fields: backupInventory.issues.map((issue) => ({ path: issue, reason: "inventory" })),
+    });
+  }
+  try {
+    mkdirSync(archiveDir, { recursive: true });
+    writeBackup(backupId, archiveDir, paths, backupInventory.files);
+    const journal: CutoverJournal = {
+      schemaVersion: 1,
+      backupId,
+      archiveDir,
+      planId: plan.id,
+      hosts: [...decision.hosts],
+      resolutions: { ...decision.resolutions },
+      conversionNeeded: plan.unresolved.length > 0 || plan.conversion.mappings.length > 0,
+      phase: "applying",
+      completedSteps: [],
+      appliedHosts: [],
+      currentStep: null,
+      error: null,
+      startedAt: new Date().toISOString(),
+      notes: [],
+    };
+    writeCutoverJournal(journal, paths.stateDir);
+    return runCutoverJournal(journal, paths, plan.conversion);
+  } catch (error) {
+    return failure("requirements_unsatisfied", `could not stage cutover backup: ${String(error)}`);
+  }
+}
+
+const runCutoverJournal = (
+  journal: CutoverJournal,
+  paths: ReturnType<typeof resolvePaths>,
+  conversion?: ConversionPreview,
+): Result<CutoverReceipt> => {
+  const completed = (step: string): boolean => journal.completedSteps.includes(step);
+  const fail = (step: string, error: unknown): Result<CutoverReceipt> => {
+    journal.phase = "interrupted";
+    journal.currentStep = step;
+    journal.error = String(error);
+    try {
+      writeCutoverJournal(journal, paths.stateDir);
+    } catch (journalError) {
+      return failure(
+        "requirements_unsatisfied",
+        `cutover interrupted at ${step}; journal write failed: ${String(journalError)}`,
+        { path: journal.backupId, operation: step },
+      );
+    }
+    return failure(
+      "requirements_unsatisfied",
+      `cutover interrupted at ${step}; resume backup ${journal.backupId}`,
+      {
+        path: journal.backupId,
+        operation: step,
+        guidance: journal.error,
+      },
     );
+  };
+  const begin = (step: string): void => {
+    journal.phase = "applying";
+    journal.currentStep = step;
+    journal.error = null;
+    writeCutoverJournal(journal, paths.stateDir);
+  };
+  const finish = (step: string): void => {
+    if (!completed(step)) journal.completedSteps.push(step);
+    journal.currentStep = null;
+    journal.error = null;
+    writeCutoverJournal(journal, paths.stateDir);
+  };
+
+  if (journal.conversionNeeded && !completed("configuration")) {
+    try {
+      begin("configuration");
+      const applied = applyConversionConfig(
+        paths.configDir,
+        conversion ?? previewConversion({ configDir: paths.configDir }),
+        journal.resolutions,
+      );
+      const note = `config: wrote ${applied.configPath} and recorded choices at ${applied.choicesPath}`;
+      if (!journal.notes.includes(note)) journal.notes.push(note);
+      finish("configuration");
+    } catch (error) {
+      return fail("configuration", error);
+    }
   }
 
-  const notes: string[] = [...conversionNotes];
-  let partial = false;
-  const applied: CutoverHost[] = [];
-  for (const host of decision.hosts) {
-    const ok = applyHostCutover(host, paths, notes);
-    if (ok) applied.push(host);
-    else partial = true;
+  for (const host of journal.hosts) {
+    const step = `host:${host}`;
+    if (completed(step)) continue;
+    try {
+      begin(step);
+      const before = new Set(journal.notes);
+      if (!applyHostCutover(host, paths, journal.notes)) {
+        journal.phase = "partial";
+        journal.currentStep = null;
+        journal.error = `${host} requires a local dev installation before activation`;
+        writeCutoverJournal(journal, paths.stateDir);
+        continue;
+      }
+      journal.appliedHosts.push(host);
+      journal.notes = [...before, ...journal.notes.filter((note) => !before.has(note))];
+      finish(step);
+    } catch (error) {
+      return fail(step, error);
+    }
   }
 
-  if (!partial) {
-    writeGenerationState(paths.configDir, {
-      target: "v1",
-      cutover: { backupId, planId: plan.id, at: new Date().toISOString() },
-    });
+  const partial = journal.appliedHosts.length !== journal.hosts.length;
+  if (!partial && !completed("generation")) {
+    try {
+      begin("generation");
+      writeGenerationState(paths.configDir, {
+        target: "v1",
+        cutover: { backupId: journal.backupId, planId: journal.planId, at: journal.startedAt },
+      });
+      finish("generation");
+    } catch (error) {
+      return fail("generation", error);
+    }
   }
 
-  const managedFiles = expandBackupTargets(backupTargets)
-    .filter((f) => existsSync(f))
-    .map((f) => ({ path: f, installedDigest: digestFile(f)! }));
+  const backupTargets = cutoverBackupTargets(paths, journal.hosts);
+  const postCutoverInventory = expandBackupTargets(backupTargets);
+  if (postCutoverInventory.issues.length > 0) {
+    return fail("verification", postCutoverInventory.issues.join("; "));
+  }
+  const managedFiles: CutoverReceipt["managedFiles"] = [];
+  for (const file of postCutoverInventory.files) {
+    const installedDigest = digestFile(file);
+    if (installedDigest === null) return fail("verification", `cannot verify ${file}`);
+    managedFiles.push({ path: file, installedDigest });
+  }
 
   const receipt: CutoverReceipt = {
-    backupId,
-    planId: plan.id,
+    backupId: journal.backupId,
+    archiveDir: journal.archiveDir,
+    planId: journal.planId,
     generation: partial ? "legacy" : "v1",
-    hosts: applied,
+    hosts: [...journal.appliedHosts],
     managedFiles,
     partial,
-    notes,
+    notes: [...journal.notes],
   };
-  writeReceipt(receipt, paths.stateDir);
+  try {
+    begin("receipt");
+    writeReceipt(receipt, paths.stateDir);
+    journal.phase = partial ? "partial" : "complete";
+    journal.currentStep = null;
+    journal.error = partial ? journal.error : null;
+    finish("receipt");
+    return success(null, null, receipt);
+  } catch (error) {
+    return fail("receipt", error);
+  }
+};
 
-  return success(null, null, receipt);
+export function resumeCutover(backupId: Id, options: CutoverPaths = {}): Result<CutoverReceipt> {
+  if (!validCutoverId(backupId))
+    return failure("not_found", `cutover journal not found: ${backupId}`);
+  const paths = resolvePaths(options);
+  const journal = readCutoverJournal(backupId, paths.stateDir);
+  if (!journal) return failure("not_found", `cutover journal not found: ${backupId}`);
+  if (journal.phase === "complete") {
+    const receipt = readCutoverReceipt(backupId, paths.stateDir);
+    return receipt
+      ? success(null, null, receipt)
+      : failure("requirements_unsatisfied", `cutover receipt is missing: ${backupId}`);
+  }
+  return runCutoverJournal(journal, paths);
 }
 
 export function previewRollback(backupId: Id, options: CutoverPaths = {}): RollbackPreview {
   const paths = resolvePaths(options);
-  const root = backupRoot(paths.stateDir, backupId);
+  if (!validCutoverId(backupId)) {
+    return {
+      backupId,
+      restorable: [],
+      conflicts: [],
+      preserved: [],
+      issues: ["invalid cutover backup id"],
+    };
+  }
   const receipt = readCutoverReceipt(backupId, paths.stateDir);
   const restorable: RollbackPreview["restorable"] = [];
   const conflicts: RollbackPreview["conflicts"] = [];
   const preserved: string[] = [];
+  const issues: string[] = [];
 
-  if (!existsSync(root) || !receipt) return { backupId, restorable, conflicts, preserved };
+  if (
+    !receipt ||
+    receipt.backupId !== backupId ||
+    typeof receipt.archiveDir !== "string" ||
+    !path.isAbsolute(receipt.archiveDir) ||
+    path.resolve(receipt.archiveDir) !== receipt.archiveDir
+  ) {
+    return {
+      backupId,
+      restorable,
+      conflicts,
+      preserved,
+      issues: ["cutover receipt or archive destination is missing"],
+    };
+  }
+  const archiveError = archiveDestinationError(receipt.archiveDir, paths);
+  if (archiveError) {
+    return { backupId, restorable, conflicts, preserved, issues: [archiveError] };
+  }
+  const root = backupRoot(receipt.archiveDir, backupId);
 
+  if (!existsSync(root)) {
+    return { backupId, restorable, conflicts, preserved, issues: ["backup directory is missing"] };
+  }
+  if (!receipt) {
+    return {
+      backupId,
+      restorable,
+      conflicts,
+      preserved,
+      issues: ["cutover receipt is missing or unreadable"],
+    };
+  }
+  const backup = readBackupFiles(backupId, receipt.archiveDir, paths);
+  issues.push(...backup.issues);
+
+  const seen = new Set<string>();
   for (const entry of receipt.managedFiles) {
+    if (
+      !path.isAbsolute(entry.path) ||
+      path.resolve(entry.path) !== entry.path ||
+      seen.has(entry.path)
+    ) {
+      issues.push(`receipt contains an invalid or duplicate path: ${entry.path}`);
+      continue;
+    }
+    seen.add(entry.path);
     const current = digestFile(entry.path);
-    if (current === null) continue;
+    const original = backup.files.get(entry.path);
+    if (current === null) {
+      if (original || lstatOrNull(entry.path)) {
+        conflicts.push({
+          path: entry.path,
+          currentDigest: null,
+          installedDigest: entry.installedDigest,
+        });
+      }
+      continue;
+    }
     if (current === entry.installedDigest) {
       restorable.push({
         path: entry.path,
         currentDigest: current,
         installedDigest: entry.installedDigest,
+        restore: original ? "backup" : "remove",
       });
+    } else if (original && current === original.digest) {
+      // A previous rollback attempt already restored this file.
+      continue;
     } else {
       conflicts.push({
         path: entry.path,
@@ -678,15 +1706,22 @@ export function previewRollback(backupId: Id, options: CutoverPaths = {}): Rollb
   const v1Task = path.join(paths.workspace, ".workit");
   if (existsSync(v1Task)) preserved.push(v1Task);
 
-  return { backupId, restorable, conflicts, preserved };
+  return { backupId, restorable, conflicts, preserved, issues };
 }
 
 export function applyRollback(
   backupId: Id,
   options: CutoverPaths = {},
 ): Result<{ restored: string[] }> {
+  if (!validCutoverId(backupId)) return failure("not_found", `backup not found: ${backupId}`);
   const paths = resolvePaths(options);
   const preview = previewRollback(backupId, options);
+  if (preview.issues.length > 0) {
+    return failure("recovery_required", "rollback backup failed integrity checks", {
+      path: paths.stateDir,
+      guidance: preview.issues.join("; "),
+    });
+  }
   if (preview.conflicts.length > 0) {
     return failure(
       "revision_conflict",
@@ -697,15 +1732,47 @@ export function applyRollback(
     );
   }
 
-  const root = backupRoot(paths.stateDir, backupId);
+  const receipt = readCutoverReceipt(backupId, paths.stateDir);
+  if (!receipt) return failure("not_found", `backup not found: ${backupId}`);
+  const root = backupRoot(receipt.archiveDir, backupId);
   if (!existsSync(root)) return failure("not_found", `backup not found: ${backupId}`);
+  const backup = readBackupFiles(backupId, receipt.archiveDir, paths);
+  if (backup.issues.length > 0) {
+    return failure("recovery_required", "rollback backup failed integrity checks", {
+      path: root,
+      guidance: backup.issues.join("; "),
+    });
+  }
 
   const restored: string[] = [];
   for (const entry of preview.restorable) {
-    const src = path.join(root, backupRelPath(entry.path, paths));
-    if (!existsSync(src)) continue;
-    mkdirSync(path.dirname(entry.path), { recursive: true });
-    cpSync(src, entry.path);
+    if (digestFile(entry.path) !== entry.currentDigest) {
+      return failure("revision_conflict", "managed file changed during rollback", {
+        path: entry.path,
+      });
+    }
+    if (entry.restore === "remove") {
+      unlinkSync(entry.path);
+      restored.push(entry.path);
+      continue;
+    }
+    const original = backup.files.get(entry.path);
+    if (!original) {
+      return failure("recovery_required", "verified rollback content is missing", {
+        path: entry.path,
+      });
+    }
+    const content = readFileSync(original.storagePath);
+    const digest = createHash("sha256").update(content).digest("hex");
+    if (digest !== original.digest) {
+      return failure("recovery_required", "rollback content changed during apply", {
+        path: original.storagePath,
+      });
+    }
+    writeFileAtomic(entry.path, content.toString("utf8"));
+    if (digestFile(entry.path) !== original.digest) {
+      return failure("storage_error", "restored file failed verification", { path: entry.path });
+    }
     restored.push(entry.path);
   }