@0dai-dev/cli 4.2.0 → 4.3.5

package/lib/commands/init.js

@@ -1,17 +1,148 @@
 "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,
+  CONFIG_DIR, PROJECTS_FILE,
   apiCall, makeEnsureAuthenticated, ensureLicenseActivation, loadAuthState,
   collectMetadata, buildProjectIdentity, registerProject,
   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 { recordActivationInit } = require("../utils/activation_telemetry");
 
 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) {
@@ -32,14 +163,138 @@ 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;
   }
 
@@ -58,12 +313,13 @@ async function cmdInit(target, args = []) {
   }
 
   // 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);
@@ -71,9 +327,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;
@@ -83,7 +355,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);
@@ -123,6 +395,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");
@@ -136,8 +413,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}`);
@@ -180,6 +464,8 @@ async function cmdInit(target, args = []) {
   // 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.
+  recordActivationInit(target, boundProject.project_id || identity.project_id);
+
   const firstRun = logFirstRunSuccess(target, {
     license: true,
     project_bound: true,
@@ -196,6 +482,136 @@ async function cmdInit(target, args = []) {
     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 };
+}
+
+// runDocLinkCheck — SPEC-028 Phase 2 (#2689). After the managed layer has been
+// written, run scripts/doc_link_check.py to surface broken/closed cross-refs
+// in ai/ and docs/. Warn-only by default so a flaky reference never blocks an
+// otherwise successful sync; --strict-links promotes failures to a non-zero
+// exit, and --skip-link-check bypasses the hook entirely.
+//
+// The hook intentionally stays silent when the script is missing (Phase 1 may
+// not have shipped to a downstream project) and when python3 is unavailable.
+// Output is streamed inline via stdio: "inherit" so authors see exact paths.
+function runDocLinkCheck(target, args = [], options = {}) {
+  if (args.includes("--skip-link-check")) {
+    return { skipped: true, reason: "flag" };
+  }
+  const script = path.join(target, "scripts", "doc_link_check.py");
+  if (!fs.existsSync(script)) {
+    return { skipped: true, reason: "missing-script" };
+  }
+  const quiet = !!options.quiet;
+  const strict = args.includes("--strict-links");
+  const { spawnSync } = require("child_process");
+  if (!quiet) log("doc-link-check: scanning ai/**/*.md docs/**/*.md");
+  const result = spawnSync(
+    "python3",
+    [
+      script,
+      "--repo-root",
+      target,
+      "--paths",
+      "ai/**/*.md",
+      "docs/**/*.md",
+      "--format",
+      "md",
+      "--fail-on",
+      "broken,closed",
+    ],
+    { stdio: "inherit", cwd: target },
+  );
+  if (result.error && result.error.code === "ENOENT") {
+    if (!quiet) console.log(`  ${D}doc-link-check skipped: python3 not found${R}`);
+    return { skipped: true, reason: "no-python" };
+  }
+  const status = typeof result.status === "number" ? result.status : 0;
+  if (status !== 0) {
+    if (strict) {
+      log(`${W}doc-link-check failed (exit ${status}); --strict-links is set${R}`);
+      process.exit(status);
+    }
+    if (!quiet) log(`${W}doc-link-check found issues (exit ${status}); warn-only (pass --strict-links to fail sync)${R}`);
+    return { ran: true, status, strict, broken: true };
+  }
+  if (!quiet) log("doc-link-check: clean");
+  return { ran: true, status: 0, strict, broken: false };
 }
 
 async function cmdSync(target, args = []) {
@@ -240,24 +656,9 @@ async function cmdSync(target, args = []) {
   const license = await ensureLicenseActivation();
   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 {}
-        }
-      }
-    };
-    walk(aiDir);
-  }
+  // 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}`);
@@ -284,7 +685,14 @@ 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}`);
     }
@@ -292,6 +700,23 @@ async function cmdSync(target, args = []) {
   }
   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}`);
@@ -302,6 +727,37 @@ async function cmdSync(target, args = []) {
     log("already up to date");
   }
 
+  // SPEC-028 Phase 2 (#2689) — scan managed docs for broken cross-refs after
+  // the layer is on disk. Warn-only unless --strict-links; --skip-link-check
+  // bypasses. Runs even when no files changed so stale local refs surface on
+  // every sync.
+  runDocLinkCheck(target, args, { quiet });
+  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"];
@@ -332,6 +788,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
@@ -343,8 +800,10 @@ async function cmdSync(target, args = []) {
     }
   } catch {}
 
-  // Update portfolio registry
-  registerProject(target, path.basename(target), stack);
+  // 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(() => {});
@@ -412,4 +871,21 @@ function buildLocalSyncPreview(target, { version, stack, cliVersion }) {
   };
 }
 
-module.exports = { cmdInit, cmdSync, buildLocalSyncPreview };
+module.exports = {
+  cmdInit,
+  cmdSync,
+  cmdProjectBind,
+  buildLocalSyncPreview,
+  runMcpBootstrap,
+  bindProjectForCloud,
+  cloudInitCheckpointPath,
+  writeCloudInitCheckpoint,
+  clearCloudInitCheckpoint,
+  buildCloudInitResumeCommand,
+  collectCurrentAiFiles,
+  hashFile,
+  detectRegistryDrift,
+  guardRegistryDrift,
+  runDocLinkCheck,
+  SYNC_FULL_CONTENT_LIMIT,
+};