@0dai-dev/cli 4.1.0 → 4.3.4

package/lib/commands/init.js

@@ -1,16 +1,147 @@
 "use strict";
+const crypto = require("crypto");
 const shared = require("../shared");
 const {
-  T, R, D, log,
+  T, R, D, W, log,
   fs, path,
   VERSION, SUPPORTED_CLIS,
-  apiCall, makeEnsureAuthenticated, ensureLicenseActivation,
+  CONFIG_DIR, PROJECTS_FILE,
+  apiCall, makeEnsureAuthenticated, ensureLicenseActivation, loadAuthState,
   collectMetadata, buildProjectIdentity, registerProject,
-  writeFiles, writeManagedFiles, sendProjectHeartbeat, recordExperienceEvent,
+  writeFiles, sendProjectHeartbeat, recordExperienceEvent,
+  logFirstRunSuccess,
 } = shared;
-const { cmdAuthLogin } = require("./auth");
+const { cmdAuthLogin, ensureAccountForActivation, parseActivationArgs } = require("./auth");
+const { ensureGithubFlowPolicy, warnHooksPathDrift } = require("./gh");
+const { renderFileMapDiff, confirmOrExit, shouldAutoYes } = require("../utils/diff-preview");
+const { bootstrapMcp } = require("../utils/mcp-auth");
 
 const ensureAuthenticated = makeEnsureAuthenticated(cmdAuthLogin);
+const SYNC_FULL_CONTENT_LIMIT = 10000;
+const CLOUD_INIT_CHECKPOINT_REL = path.join(".0dai", "cloud-init-checkpoint.json");
+
+function hashFile(filePath) {
+  const hash = crypto.createHash("sha256");
+  const fd = fs.openSync(filePath, "r");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  try {
+    let bytesRead = 0;
+    do {
+      bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (bytesRead > 0) hash.update(buffer.subarray(0, bytesRead));
+    } while (bytesRead > 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return hash.digest("hex");
+}
+
+function describeCurrentFile(filePath, stat) {
+  if (stat.size < SYNC_FULL_CONTENT_LIMIT) return fs.readFileSync(filePath, "utf8");
+  return {
+    size: stat.size,
+    sha256: hashFile(filePath),
+    compare: "hash-only",
+  };
+}
+
+// detectRegistryDrift — Phase 1.5 of #2237 registry self-heal.
+// Returns { drifted: bool, existingPath?: string, currentPath: string } when an
+// entry with the same `name` is already in ~/.0dai/projects.json but points at
+// a different directory than the one we're about to register. Caller decides
+// what to do (warn, prompt, or auto-overwrite based on flags).
+function detectRegistryDrift(target, name) {
+  const currentPath = path.resolve(target);
+  try {
+    if (!fs.existsSync(PROJECTS_FILE)) return { drifted: false, currentPath };
+    const raw = fs.readFileSync(PROJECTS_FILE, "utf8");
+    const data = JSON.parse(raw);
+    const projects = Array.isArray(data && data.projects) ? data.projects : [];
+    for (const entry of projects) {
+      if (!entry || typeof entry !== "object") continue;
+      if (entry.name !== name) continue;
+      if (!entry.path || typeof entry.path !== "string") continue;
+      if (entry.path === currentPath) continue;
+      return { drifted: true, existingPath: entry.path, currentPath, archived: entry.archived === true };
+    }
+  } catch {}
+  return { drifted: false, currentPath };
+}
+
+// guardRegistryDrift — returns true when caller may proceed with registration,
+// false if the operator declined the overwrite. Async to support interactive
+// prompt; honours --non-interactive (and --yes / common CI flags) by
+// auto-overwriting silently. ODAI_REGISTRY_DRIFT_OVERWRITE=1 also bypasses
+// the prompt for scripted runs.
+async function guardRegistryDrift(target, name, args) {
+  const drift = detectRegistryDrift(target, name);
+  if (!drift.drifted) return true;
+  // Archived entries are not a real conflict — registry_audit.py archives
+  // missing paths; let init silently overwrite them.
+  if (drift.archived) return true;
+
+  const nonInteractive =
+    args.includes("--non-interactive") ||
+    args.includes("--yes") ||
+    args.includes("-y") ||
+    !process.stdout.isTTY ||
+    process.env.ODAI_REGISTRY_DRIFT_OVERWRITE === "1";
+
+  log(`${W}registry drift: project '${name}' is registered at ${drift.existingPath}${R}`);
+  console.log(`  current cwd: ${drift.currentPath}`);
+  if (nonInteractive) {
+    console.log(`  ${D}auto-overwriting registry entry (non-interactive mode)${R}`);
+    return true;
+  }
+
+  try {
+    const readline = require("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question(`  Overwrite registry entry to point at ${drift.currentPath}? [y/N] `, (a) => {
+        rl.close();
+        resolve(String(a || "").trim().toLowerCase());
+      });
+    });
+    if (answer === "y" || answer === "yes") return true;
+  } catch {
+    // readline failed (e.g. no TTY) — fall through to skip
+  }
+  console.log(
+    `  ${D}skipping registry update. Set ODAI_REGISTRY_DRIFT_OVERWRITE=1 or pass --non-interactive to overwrite.${R}`,
+  );
+  return false;
+}
+
+function registerProjectOrExit(target, name, stack) {
+  try {
+    return registerProject(target, name, stack, CONFIG_DIR, PROJECTS_FILE);
+  } catch (err) {
+    log(`error: failed to update project registry: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function collectCurrentAiFiles(target) {
+  const currentFiles = {};
+  const aiDir = path.join(target, "ai");
+  if (fs.existsSync(aiDir)) {
+    const walk = (dir) => {
+      for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, f.name);
+        if (f.isDirectory()) walk(p);
+        else {
+          try {
+            const stat = fs.statSync(p);
+            if (stat.isFile()) currentFiles[path.relative(target, p)] = describeCurrentFile(p, stat);
+          } catch {}
+        }
+      }
+    };
+    walk(aiDir);
+  }
+  return currentFiles;
+}
 
 // bindProjectForCloud — binds project to cloud via /v1/projects/bind
 async function bindProjectForCloud(target, metadata, identity) {
@@ -31,24 +162,163 @@ async function bindProjectForCloud(target, metadata, identity) {
   };
 }
 
+function cloudInitCheckpointPath(target) {
+  return path.join(target, CLOUD_INIT_CHECKPOINT_REL);
+}
+
+function _hasAuthToken() {
+  const auth = loadAuthState();
+  return !!(auth && (auth.api_key || auth.access_token || auth.token));
+}
+
+function _quoteCommandArg(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\"'\"'")}'`;
+}
+
+function _initCommandName(args = []) {
+  const first = String((Array.isArray(args) ? args : [])[0] || "");
+  return first === "init-existing" ? "init-existing" : "init";
+}
+
+function _resumeArgs(args = []) {
+  const raw = Array.isArray(args) ? args : [];
+  const withoutCommand = raw[0] === "init" || raw[0] === "init-existing" ? raw.slice(1) : raw.slice();
+  const skipWithValue = new Set(["--auth-code", "--oauth-code", "--exchange-code", "--code", "--activation-code", "--redeem-code", "--plan-code"]);
+  const filtered = [];
+  for (let i = 0; i < withoutCommand.length; i++) {
+    const arg = String(withoutCommand[i] || "");
+    if (!arg || arg === "--resume") continue;
+    if (skipWithValue.has(arg)) { i++; continue; }
+    if ([...skipWithValue].some((name) => arg.startsWith(`${name}=`))) continue;
+    filtered.push(arg);
+  }
+  return filtered;
+}
+
+function buildCloudInitResumeCommand(target, args = []) {
+  const parts = ["0dai", _initCommandName(args), "--target", _quoteCommandArg(path.resolve(target)), "--resume"];
+  for (const arg of _resumeArgs(args)) parts.push(_quoteCommandArg(arg));
+  return parts.join(" ");
+}
+
+function writeCloudInitCheckpoint(target, details = {}) {
+  const checkpointPath = cloudInitCheckpointPath(target);
+  const checkpoint = {
+    version: 1,
+    command: _initCommandName(details.args || []),
+    stage: details.stage || "auth_required",
+    reason: details.reason || "missing_auth",
+    target: path.resolve(target),
+    created_at: new Date().toISOString(),
+    next_command: "0dai auth login --device --no-browser",
+    resume_command: buildCloudInitResumeCommand(target, details.args || []),
+  };
+  fs.mkdirSync(path.dirname(checkpointPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2) + "\n", { mode: 0o600 });
+  return checkpoint;
+}
+
+function clearCloudInitCheckpoint(target) {
+  try { fs.unlinkSync(cloudInitCheckpointPath(target)); } catch {}
+}
+
+function maybePauseCloudInitForAuth(target, args = [], options = {}) {
+  if (options.dryRun || options.localMode) return false;
+  if (_hasAuthToken()) return false;
+  const parsed = parseActivationArgs(args, { genericCode: "activation" });
+  if (parsed.authCode) return false;
+  if (process.stdout.isTTY && process.stdin.isTTY) return false;
+
+  const checkpoint = writeCloudInitCheckpoint(target, {
+    args,
+    stage: "auth_required",
+    reason: "missing_auth",
+  });
+  log("authentication required for init");
+  console.log(`  ${D}Checkpoint: ${CLOUD_INIT_CHECKPOINT_REL}${R}`);
+  console.log(`  ${D}Run: ${checkpoint.next_command}${R}`);
+  console.log(`  ${D}Then: ${checkpoint.resume_command}${R}`);
+  process.exit(1);
+}
+
+async function cmdProjectBind(target, args = []) {
+  const json = args.includes("--json");
+  const authStatus = await ensureAuthenticated("project bind");
+  const license = await ensureLicenseActivation();
+  const metadata = collectMetadata(target);
+  const identity = buildProjectIdentity(target, metadata);
+  const boundProject = await bindProjectForCloud(target, metadata, identity);
+  const stack = boundProject.stack || identity.stack || "unknown";
+  if (await guardRegistryDrift(target, path.basename(target), args)) {
+    registerProjectOrExit(target, path.basename(target), stack);
+  }
+  const heartbeat = await sendProjectHeartbeat(target, identity, { stack }, {
+    project_id: boundProject.project_id || identity.project_id,
+  }).catch((err) => ({ error: err.message || String(err) }));
+  const payload = {
+    ok: true,
+    account: {
+      email: authStatus.email || null,
+      plan: authStatus.plan || license.plan || "free",
+      activation: license.status || "active",
+    },
+    project: {
+      project_id: boundProject.project_id || identity.project_id,
+      name: boundProject.name || identity.project_name,
+      stack,
+      binding_status: boundProject.binding_status || "bound",
+    },
+    heartbeat: !(heartbeat && heartbeat.error),
+  };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    log("project bound");
+    console.log(`  account: ${payload.account.email || "unknown"} · plan: ${payload.account.plan} · activation: ${payload.account.activation}`);
+    console.log(`  project: ${payload.project.project_id}`);
+    if (!payload.heartbeat) console.log(`  ${D}heartbeat deferred; run 0dai status to inspect local state${R}`);
+  }
+  return payload;
+}
+
 async function cmdInit(target, args = []) {
   const dryRun = args.includes("--dry-run");
   const minimal = args.includes("--minimal");
   const noWizard = args.includes("--no-wizard");
+  const localMode = args.includes("--local");
 
   if (fs.existsSync(path.join(target, "ai", "VERSION"))) {
     const v = fs.readFileSync(path.join(target, "ai", "VERSION"), "utf8").trim();
     log(`ai/ layer already exists (v${v}). Run '0dai sync' to update.`);
+    if (args.includes("--resume")) clearCloudInitCheckpoint(target);
+    if (!dryRun) await runMcpBootstrap(target, args);
     return;
   }
 
+  // Pre-check: verify init quota before starting wizard (avoid 10 min wizard → "limit reached")
+  if (!dryRun) {
+    try {
+      const precheck = await apiCall("/v1/projects/precheck", {
+        device_id: shared.deviceFingerprint(),
+      });
+      if (precheck.error && precheck.error.includes("limit")) {
+        log(`${precheck.error}`);
+        if (precheck.hint) console.log(`  ${D}${precheck.hint}${R}`);
+        return;
+      }
+    } catch {}
+  }
+
   // First-run wizard (unless --no-wizard or non-interactive)
-  if (!noWizard && !dryRun && !minimal) {
+  if (!noWizard && !dryRun && !minimal && !localMode) {
     try {
       const { runWizard, isInteractive } = require("../wizard");
       if (isInteractive()) {
         const result = await runWizard(target);
         if (result.completed) {
+          await runMcpBootstrap(target, args);
           try {
             const ob = require("../onboarding");
             ob.trackFirstInit(target);
@@ -56,9 +326,25 @@ async function cmdInit(target, args = []) {
           } catch {}
           return;
         }
+        if (result.cancelled) return;
       }
     } catch {}
   }
+  if (localMode) {
+    const { runWizard } = require("../wizard");
+    const result = await runWizard(target, { forceLocal: true });
+    if (result.completed) {
+      await runMcpBootstrap(target, args);
+      try {
+        const ob = require("../onboarding");
+        ob.trackFirstInit(target);
+        ob.showWhatsNext("local", false);
+      } catch {}
+      return;
+    }
+  }
+
+  maybePauseCloudInitForAuth(target, args, { dryRun, localMode });
 
   const isTTY = process.stdout.isTTY;
   let spinner = null;
@@ -68,7 +354,7 @@ async function cmdInit(target, args = []) {
 
   const metadata = collectMetadata(target);
   const { projectFiles, manifestContents, clis } = metadata;
-  const authStatus = await ensureAuthenticated("init");
+  const authStatus = await ensureAccountForActivation("init", args);
   const license = await ensureLicenseActivation();
   const identity = buildProjectIdentity(target, metadata);
   const boundProject = await bindProjectForCloud(target, metadata, identity);
@@ -108,6 +394,11 @@ async function cmdInit(target, args = []) {
     return;
   }
   writeFiles(target, result.files || {});
+  const envManifest = normalizeEnvironmentManifest(target);
+  if (envManifest.changed) {
+    log("environment manifest target normalized: ai/manifest/environment.yaml");
+  }
+  await runMcpBootstrap(target, args);
 
   // Ensure ai/VERSION matches CLI version
   const versionFile = path.join(target, "ai", "VERSION");
@@ -121,8 +412,15 @@ async function cmdInit(target, args = []) {
     if (!text.includes(".0dai")) fs.appendFileSync(gi, "\n.0dai/\n");
   } catch {}
 
-  // Register in global portfolio
-  registerProject(target, path.basename(target), result.stack);
+  const gitPolicy = ensureGithubFlowPolicy(target);
+  if (gitPolicy && gitPolicy.protection && gitPolicy.protection.skipped) {
+    console.log(`  ${D}branch protection: ${gitPolicy.protection.reason}${R}`);
+  }
+
+  // Register in global portfolio (Phase 1.5 #2237: drift guard)
+  if (await guardRegistryDrift(target, path.basename(target), args)) {
+    registerProjectOrExit(target, path.basename(target), result.stack);
+  }
 
   log(`initialized (${result.file_count || "?"} files)`);
   console.log(`  account: ${authStatus.email} · plan: ${authStatus.plan || license.plan || "free"} · activation: ${license.status}`);
@@ -150,9 +448,9 @@ async function cmdInit(target, args = []) {
   }
   console.log(`  ${D}3.${R} Open dashboard: ${D}https://0dai.dev/dashboard${R}`);
 
-  await sendProjectHeartbeat(identity, result, {
+  const heartbeat = await sendProjectHeartbeat(target, identity, result, {
     project_id: boundProject.project_id || identity.project_id,
-  }).catch(() => {});
+  }).catch(() => null);
   recordExperienceEvent(target, {
     event_type: "config_generated",
     agent: "cli",
@@ -162,18 +460,107 @@ async function cmdInit(target, args = []) {
     context: { stack: result.stack || identity.stack || "unknown", files_touched: Number(result.file_count || 0), tests_passed: true },
   });
 
+  // First-run proof gate (issue #342). All 4 gates pass once we reach here:
+  // license active (line above), project bound, ai/ layer written, heartbeat sent.
+  // Idempotent — only fires once per project. See docs/first-run.md.
+  const firstRun = logFirstRunSuccess(target, {
+    license: true,
+    project_bound: true,
+    layer_written: true,
+    heartbeat: !!heartbeat && !heartbeat.error,
+  });
+  if (firstRun.fired) {
+    const suffix = typeof firstRun.elapsedS === "number" ? ` (${firstRun.elapsedS}s)` : "";
+    console.log(`  ${D}first-run gate: success${suffix}${R}`);
+  }
+
   // Send anonymous usage ping
   apiCall("/v1/feedback", { report: {
     stack_detected: result.stack || "?", _auto: true, _plan: result.plan || "trial",
     _cli_version: VERSION, _files_generated: result.file_count || 0,
   }}).catch(() => {});
+  clearCloudInitCheckpoint(target);
+}
+
+async function runMcpBootstrap(target, args = []) {
+  const result = await bootstrapMcp(target, args, (message) => log(message));
+  if (!result.ok) {
+    log(`warn: MCP bootstrap skipped: ${result.warnings.join("; ")}`);
+    return result;
+  }
+  if (result.config) {
+    const verbs = [];
+    if (result.config.added && result.config.added.length) verbs.push(`${result.config.added.length} server(s) added`);
+    if (result.config.updated && result.config.updated.length) verbs.push(`${result.config.updated.length} server(s) reset`);
+    if (result.config.changed) {
+      log(`MCP config ready (${verbs.join(", ") || "updated"}): .mcp.json`);
+    }
+  }
+  if (result.settings && result.settings.changed) {
+    log("Claude project MCP auto-load enabled: .claude/settings.json");
+  }
+  if (result.auth) {
+    if (result.auth.status === "preserved") {
+      log("MCP auth token preserved");
+    } else if (result.auth.status === "written") {
+      log(`MCP auth token stored: ${result.auth.tokenPath}`);
+    } else if (result.auth.status === "disabled") {
+      log("MCP cloud auth skipped (--no-mcp-auth)");
+    } else if (result.auth.status === "skipped") {
+      console.log(`  ${D}MCP cloud auth skipped. In Claude Code, run /mcp Authenticate for claude.ai 0dai${R}`);
+    }
+  }
+  for (const warning of result.warnings || []) log(`warn: ${warning}`);
+  return result;
+}
+
+function normalizeEnvironmentManifest(target) {
+  const filePath = path.join(target, "ai", "manifest", "environment.yaml");
+  if (!fs.existsSync(filePath)) return { path: filePath, changed: false };
+  const original = fs.readFileSync(filePath, "utf8");
+  const lines = original.split(/\n/);
+  let inWorkspace = false;
+  let sawTarget = false;
+  let sawCwd = false;
+  const next = [];
+  for (const line of lines) {
+    if (/^\S/.test(line) && !line.startsWith("workspace:")) inWorkspace = false;
+    if (line.trim() === "workspace:") {
+      inWorkspace = true;
+      next.push(line);
+      continue;
+    }
+    if (inWorkspace && /^  target:\s*/.test(line)) {
+      next.push("  target: .");
+      sawTarget = true;
+      continue;
+    }
+    if (inWorkspace && /^  cwd:\s*/.test(line)) {
+      next.push("  cwd: .");
+      sawCwd = true;
+      continue;
+    }
+    if (inWorkspace && /^available_clis:\s*$/.test(line)) {
+      if (!sawTarget) next.push("  target: .");
+      if (!sawCwd) next.push("  cwd: .");
+      inWorkspace = false;
+    }
+    next.push(line);
+  }
+  if (inWorkspace) {
+    if (!sawTarget) next.push("  target: .");
+    if (!sawCwd) next.push("  cwd: .");
+  }
+  const rendered = next.join("\n");
+  if (rendered === original) return { path: filePath, changed: false };
+  fs.writeFileSync(filePath, rendered, "utf8");
+  return { path: filePath, changed: true };
 }
 
 async function cmdSync(target, args = []) {
   const dryRun = args.includes("--dry-run");
   const quiet = args.includes("--quiet") || args.includes("-q");
   const force = args.includes("--force");
-  const updateTemplates = args.includes("--update-templates");
 
   // Quick local check: skip API if already at current version (unless dry-run or force)
   let version = "unknown";
@@ -181,8 +568,6 @@ async function cmdSync(target, args = []) {
 
   const metadata = collectMetadata(target);
   const { manifestContents, clis } = metadata;
-  const authStatus = await ensureAuthenticated("sync");
-  const license = await ensureLicenseActivation();
   let stack = "generic", agents = [];
   try {
     const d = JSON.parse(fs.readFileSync(path.join(target, "ai", "manifest", "discovery.json"), "utf8"));
@@ -190,35 +575,41 @@ async function cmdSync(target, args = []) {
     agents = d.selected_agents || [];
   } catch {}
   const identity = buildProjectIdentity(target, metadata, stack);
-  const boundProject = await bindProjectForCloud(target, metadata, identity);
 
-  // Collect current ai/ files
-  const currentFiles = {};
-  const aiDir = path.join(target, "ai");
-  if (fs.existsSync(aiDir)) {
-    const walk = (dir) => {
-      for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
-        const p = path.join(dir, f.name);
-        if (f.isDirectory()) walk(p);
-        else {
-          try {
-            const stat = fs.statSync(p);
-            if (stat.size < 10000) currentFiles[path.relative(target, p)] = fs.readFileSync(p, "utf8");
-          } catch {}
-        }
+  if (dryRun) {
+    const auth = loadAuthState();
+    const hasAuth = !!(auth && (auth.api_key || auth.access_token || auth.token));
+    if (!hasAuth) {
+      const preview = buildLocalSyncPreview(target, { version, stack, cliVersion: VERSION });
+      log(`${D}dry-run: local preview without auth (exact cloud plan unavailable)${R}`);
+      console.log(`  stack: ${preview.stack}`);
+      console.log(`  ai version: ${preview.current_version} ${preview.version_matches ? `${D}(matches CLI ${preview.cli_version})${R}` : `${D}(CLI ${preview.cli_version})${R}`}`);
+      if (preview.changes.length) {
+        console.log("  likely changes:");
+        for (const change of preview.changes) console.log(`    ~ ${change}`);
+      } else {
+        console.log(`  ${D}no obvious local drift found${R}`);
       }
-    };
-    walk(aiDir);
+      console.log(`  ${D}Run: 0dai auth login for exact managed diff and write-mode sync${R}`);
+      return;
+    }
   }
 
+  const authStatus = await ensureAuthenticated("sync");
+  const license = await ensureLicenseActivation();
+  const boundProject = await bindProjectForCloud(target, metadata, identity);
+
+  // Collect current ai/ files. Small files send content; larger files send
+  // hash descriptors so the server can compare without a full upload.
+  const currentFiles = collectCurrentAiFiles(target);
+
   if (dryRun) log(`${D}dry-run: checking what sync would change...${R}`);
   if (force && !dryRun) log(`${T}force mode: will overwrite native configs from ai/ source${R}`);
-  if (updateTemplates && !dryRun) log(`${T}template update mode: will refresh managed native configs from latest templates${R}`);
 
   const result = await apiCall("/v1/sync", {
     ai_version: version, stack, agents: agents.length ? agents : clis,
     current_files: currentFiles, manifest_contents: manifestContents,
-    dry_run: dryRun, quiet, force, update_templates: updateTemplates,
+    dry_run: dryRun, quiet, force,
     project_name: identity.project_name,
     project_id: boundProject.project_id || identity.project_id,
     remote_origin: identity.remote_origin,
@@ -237,17 +628,38 @@ async function cmdSync(target, args = []) {
     const files = Object.keys(updated);
     if (files.length) {
       log(`${D}dry-run: would update ${files.length} file(s):${R}`);
-      for (const f of files) console.log(`  ${D}~ ${f}${R}`);
+      const { diff, summary } = renderFileMapDiff(updated, currentFiles);
+      for (const f of summary.added) console.log(`  ${D}+ ${f}${R}`);
+      for (const f of summary.modified) console.log(`  ${D}~ ${f}${R}`);
+      for (const f of summary.removed) console.log(`  ${D}- ${f}${R}`);
+      if (diff && !args.includes("--no-diff")) {
+        console.log("");
+        console.log(diff);
+      }
     } else {
       log(`${D}dry-run: nothing to update${R}`);
     }
-    if (result.template_update_available) {
-      console.log(`  ${D}template update available: run 0dai sync --update-templates${R}`);
-    }
     return;
   }
   const changedCount = Object.keys(updated).length;
   if (changedCount) {
+    if (!quiet && !shouldAutoYes(args)) {
+      const { diff, summary } = renderFileMapDiff(updated, currentFiles);
+      log(`sync would change ${changedCount} file(s):`);
+      for (const f of summary.added) console.log(`  ${D}+ ${f}${R}`);
+      for (const f of summary.modified) console.log(`  ${D}~ ${f}${R}`);
+      for (const f of summary.removed) console.log(`  ${D}- ${f}${R}`);
+      if (diff && !args.includes("--no-diff")) {
+        console.log("");
+        console.log(diff);
+        console.log("");
+      }
+      const ok = await confirmOrExit({ args, quiet, message: "Apply sync?", defaultYes: false });
+      if (!ok) {
+        log("aborted by user (no files changed). Re-run with --yes to skip this prompt.");
+        return;
+      }
+    }
     writeFiles(target, updated);
     if (!quiet) {
       for (const f of Object.keys(updated)) console.log(`  ~ ${f}`);
@@ -257,19 +669,39 @@ async function cmdSync(target, args = []) {
   } else {
     log("already up to date");
   }
-
-  if (result.template_update_available && !updateTemplates && !quiet) {
-    console.log(`  ${D}Template update available: run 0dai sync --update-templates to refresh managed native configs${R}`);
+  const envManifest = normalizeEnvironmentManifest(target);
+  if (!quiet && envManifest.changed) {
+    log("environment manifest target normalized: ai/manifest/environment.yaml");
+  }
+  await runMcpBootstrap(target, [...args, "--no-mcp-auth"]);
+
+  // Round-trip imported personas back to native agent dirs (Phase 2 of #2197).
+  // Currently supports claude-code only. Persona files marked
+  // `imported_from: "claude-code"` are mirrored into `.claude/agents/<name>.md`
+  // so users can edit either side without losing parity.
+  // Phase 2.5 (deferred): full export — generate agents for personas that
+  // were authored in 0dai but not imported. Tracked in #2197.
+  try {
+    const { syncImportedClaudeCodeAgents } = require("./import_claude_code_agents");
+    const rt = syncImportedClaudeCodeAgents(target, { dryRun });
+    if (!quiet && rt.written.length) {
+      log(`round-trip: wrote ${rt.written.length} claude-code agent file(s) from imported personas`);
+      for (const w of rt.written) {
+        const rel = path.relative(target, w.outPath).replace(/\\/g, "/");
+        console.log(`  -> ${rel}`);
+      }
+    }
+  } catch (err) {
+    if (!quiet) console.log(`  ${D}round-trip skipped: ${err.message}${R}`);
   }
 
   // --force: also overwrite native configs (CLAUDE.md, AGENTS.md, etc.) from ai/ source
   if (force && result.native_configs) {
+    const NATIVE_CONFIGS = ["CLAUDE.md", "AGENTS.md", "GEMINI.md", "opencode.json", ".cursorrules", ".windsurfrules", ".aider.conf.yml"];
     let overwritten = 0;
-    for (const [name, content] of Object.entries(result.native_configs)) {
-      const targetPath = path.join(target, name);
-      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-      if (content) {
-        fs.writeFileSync(targetPath, content, "utf8");
+    for (const name of NATIVE_CONFIGS) {
+      if (result.native_configs[name]) {
+        fs.writeFileSync(path.join(target, name), result.native_configs[name], "utf8");
         overwritten++;
         if (!quiet) console.log(`  [force] ${name} overwritten from ai/ source`);
       }
@@ -277,11 +709,6 @@ async function cmdSync(target, args = []) {
     if (overwritten && !quiet) {
       log(`force: ${overwritten} native config file(s) overwritten`);
     }
-  } else if (updateTemplates && result.native_configs) {
-    writeManagedFiles(target, result.native_configs);
-    if (!quiet) {
-      log("template update: managed native configs refreshed");
-    }
   }
 
   // --force: update drift baseline hashes so drift clears after regeneration
@@ -298,6 +725,7 @@ async function cmdSync(target, args = []) {
   if (!quiet) {
     console.log(`  account: ${authStatus.email} · plan: ${authStatus.plan || license.plan || "free"} · activation: ${license.status}`);
     console.log(`  project: ${boundProject.project_id || identity.project_id}`);
+    warnHooksPathDrift(target);
   }
 
   // Ensure ai/VERSION matches CLI version after successful sync
@@ -309,9 +737,11 @@ async function cmdSync(target, args = []) {
     }
   } catch {}
 
-  // Update portfolio registry
-  registerProject(target, path.basename(target), stack);
-  await sendProjectHeartbeat(identity, result, {
+  // Update portfolio registry (Phase 1.5 #2237: drift guard)
+  if (await guardRegistryDrift(target, path.basename(target), args)) {
+    registerProjectOrExit(target, path.basename(target), stack);
+  }
+  await sendProjectHeartbeat(target, identity, result, {
     project_id: boundProject.project_id || identity.project_id,
   }).catch(() => {});
   recordExperienceEvent(target, {
@@ -324,4 +754,74 @@ async function cmdSync(target, args = []) {
   });
 }
 
-module.exports = { cmdInit, cmdSync };
+function buildLocalSyncPreview(target, { version, stack, cliVersion }) {
+  const changes = [];
+  const expectedAiFiles = [
+    "ai/VERSION",
+    "ai/manifest/project.yaml",
+    "ai/manifest/commands.yaml",
+    "ai/manifest/discovery.json",
+  ];
+  for (const rel of expectedAiFiles) {
+    if (!fs.existsSync(path.join(target, rel))) changes.push(`${rel} (missing)`);
+  }
+
+  if (version !== "unknown" && version !== cliVersion) {
+    changes.push(`ai/VERSION (${version} -> ${cliVersion})`);
+  }
+
+  const driftTracked = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    "opencode.json",
+    ".cursorrules",
+    ".windsurfrules",
+    ".aider.conf.yml",
+  ];
+  const hashesPath = path.join(target, "ai", "manifest", "config_hashes.json");
+  try {
+    const hashes = JSON.parse(fs.readFileSync(hashesPath, "utf8"));
+    const crypto = require("crypto");
+    for (const rel of driftTracked) {
+      const filePath = path.join(target, rel);
+      const recorded = hashes[rel];
+      const exists = fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+      if (recorded && !exists) changes.push(`${rel} (missing from workspace)`);
+      if (recorded && exists) {
+        const currentHash = crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+        if (currentHash !== String(recorded.hash || "")) changes.push(`${rel} (local edits)`);
+      }
+    }
+  } catch {}
+
+  if (!fs.existsSync(path.join(target, "ai"))) {
+    changes.push("ai/ layer missing — run 0dai init after auth");
+  }
+
+  return {
+    stack,
+    current_version: version,
+    cli_version: cliVersion,
+    version_matches: version === cliVersion,
+    changes,
+  };
+}
+
+module.exports = {
+  cmdInit,
+  cmdSync,
+  cmdProjectBind,
+  buildLocalSyncPreview,
+  runMcpBootstrap,
+  bindProjectForCloud,
+  cloudInitCheckpointPath,
+  writeCloudInitCheckpoint,
+  clearCloudInitCheckpoint,
+  buildCloudInitResumeCommand,
+  collectCurrentAiFiles,
+  hashFile,
+  detectRegistryDrift,
+  guardRegistryDrift,
+  SYNC_FULL_CONTENT_LIMIT,
+};