@vibecompass/vibecompass 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 0.12.0 - 2026-07-10
+
+- New `vibecompass bootstrap --bundle <file>` materializes a complete local
+  root from a hosted bootstrap-export bundle (fail-closed hash validation,
+  verbatim writes, sync-cursor seeding for local-primary bundles).
+- New `vibecompass sync-adopt [--accept-divergence]` re-baselines a root's
+  sync cursor onto the hosted head after a divergence preview (D-215) — the
+  recovery path for fresh clones and second devices.
+- New `vibecompass promote-hosted [--resume|--abort]` and
+  `vibecompass demote-hosted [--accept-divergence]` run the D-288 two-phase
+  hosting-mode cutover: fresh verified baseline, server-side transition
+  intent with a completeness report, local flip + promoted-root marker, and
+  confirm — resumable after any crash and fully reversible.
+- Promoted roots hard-refuse canonical write commands (override with
+  VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1); `vibecompass status` now checks
+  the hosted mode and warns on local/hosted mode mismatches.
+- `apply-export` pre-validates every operation before writing and treats
+  already-applied operations as converged, so retries after partial failure
+  succeed. `docs-review --apply-decision-artifact` is idempotent and
+  crash-safe (provenance Source line, marker repair, post-write verification,
+  code-enforced append-only) and warns on hosted-only roots.
+
+- The missing-sync-token error now explains how to recover: re-export the bound
+  env var, persist it in a shell profile, or rotate the token from the hosted
+  dashboard (previously a bare "requires VIBECOMPASS_SYNC_TOKEN" with no
+  guidance). README documents the persistence recipe.
+- AGENTS.md gains a release checklist, including verifying that
+  `vibecompass-mcp`'s dependency range still spans the new version so core
+  releases stop stranding the MCP package (its `^0.1.0` pin had drifted 27
+  releases behind).
+
 ## 0.11.2 - 2026-07-06
 
 - Complete the remaining Phase 8 start-session overlap warnings: lanes can now

package/README.md

@@ -250,6 +250,17 @@ changed canonical project-memory files and the hosted dashboard should catch
 up. Hosted-only projects do not use a local authoritative push; update or
 refresh them through the hosted dashboard/proposal flow.
 
+The sync token is read from the environment variable you bind (for example
+`VIBECOMPASS_SYNC_TOKEN`). One-off `export`s do not survive new terminals —
+persist the token in your shell profile (`~/.zshenv` or `~/.bashrc`):
+
+```bash
+echo 'export VIBECOMPASS_SYNC_TOKEN="<your sync token>"' >> ~/.zshenv
+```
+
+If the token is lost, rotate it on the hosted dashboard under Setup -> Hosted
+sync and export the new value.
+
 ### Multiple environments
 
 One project can have named sync targets (for example a local dev server and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -17,8 +17,11 @@ import { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 import { refreshWorkflow } from './refresh-workflow.js';
 import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
 import { PACKAGE_VERSION } from './version.js';
+import { demoteHosted, promoteHosted } from './mode-transition.js';
 import {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,
@@ -437,6 +440,71 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'promote-hosted' || parsed.command === 'demote-hosted') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const run = parsed.command === 'promote-hosted' ? promoteHosted : demoteHosted;
+    const result = await run(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Mode transition: ${result.status}\n`);
+    if (result.completeness) {
+      io.stdout.write(`Carries over: ${result.completeness.carries_over}\n`);
+      for (const [kind, total] of Object.entries(result.completeness.documents_by_kind ?? {})) {
+        io.stdout.write(`  ${kind}: ${total}\n`);
+      }
+      io.stdout.write('Does not carry over:\n');
+      for (const item of result.completeness.does_not_carry_over ?? []) {
+        io.stdout.write(`  - ${item}\n`);
+      }
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Note: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'sync-adopt') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await adoptRemoteHead(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Sync adopt: ${result.status}\n`);
+    io.stdout.write(`Adopted head: ${result.remoteRevisionId}\n`);
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'bootstrap') {
+    const result = await bootstrapFromBundle(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Bootstrap: ${result.status}\n`);
+    io.stdout.write(`Root: ${result.rootDir}\n`);
+    io.stdout.write(`Documents: ${result.documentCount}\n`);
+    if (result.mode) {
+      io.stdout.write(`Mode: ${result.mode}\n`);
+    }
+    if (result.manifestPath) {
+      io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
   if (parsed.command === 'pull-preview') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pullPreviewProjectMemory(parsed.options, {
@@ -708,6 +776,18 @@ export function parseCliArgs(argv) {
       return parsePushArgs(rest);
     }
 
+    if (command === 'promote-hosted' || command === 'demote-hosted') {
+      return parseModeTransitionArgs(command, rest);
+    }
+
+    if (command === 'sync-adopt') {
+      return parseSyncAdoptArgs(rest);
+    }
+
+    if (command === 'bootstrap') {
+      return parseBootstrapArgs(rest);
+    }
+
     if (command === 'pull-preview') {
       return parsePullPreviewArgs(rest);
     }
@@ -1776,6 +1856,122 @@ function parseDocsReviewArgs(argv) {
   };
 }
 
+function parseModeTransitionArgs(command, argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--resume') {
+      parsed.resume = true;
+      continue;
+    }
+    if (token === '--abort') {
+      parsed.abort = true;
+      continue;
+    }
+    if (token === '--accept-divergence') {
+      parsed.acceptDivergence = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${command}.`);
+    }
+  }
+
+  return { command, options: parsed };
+}
+
+function parseSyncAdoptArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--accept-divergence') {
+      parsed.acceptDivergence = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-adopt.`);
+    }
+  }
+
+  return {
+    command: 'sync-adopt',
+    options: parsed,
+  };
+}
+
+function parseBootstrapArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--bundle':
+        parsed.bundlePath = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for bootstrap.`);
+    }
+  }
+
+  return {
+    command: 'bootstrap',
+    options: parsed,
+  };
+}
+
 function parsePushArgs(argv) {
   return {
     command: 'push',
@@ -2183,6 +2379,10 @@ function usageText() {
     '  vibecompass next-decision-id [options]',
     '  vibecompass sync-agents [options]',
     '  vibecompass push [options]',
+    '  vibecompass bootstrap --bundle <file> [--root <dir>]',
+    '  vibecompass sync-adopt [--accept-divergence] [options]',
+    '  vibecompass promote-hosted [--resume|--abort] [options]',
+    '  vibecompass demote-hosted [--accept-divergence] [options]',
     '  vibecompass pull-preview [options]',
     '  vibecompass pull-export [options]',
     '  vibecompass apply-export [options]',

package/src/docs-review.js

@@ -434,6 +434,15 @@ async function applyDecisionArtifactLocked(options) {
     throw new Error(`Decision artifact ${artifactId} must include a non-empty rationale before it can be appended locally.`);
   }
 
+  // Idempotency guard: never append the same artifact twice. The marker is
+  // the fast path; the file-content check covers a crash between the file
+  // write and the marker update.
+  if (artifact.local_status === 'applied') {
+    throw new Error(
+      `Decision artifact ${artifactId} is already applied locally as ${artifact.local_decision_id ? `decision ${artifact.local_decision_id}` : 'a decision entry'}. Re-applying would append a duplicate entry.`,
+    );
+  }
+
   const nextDecisionId = await readNextDecisionId(options.rootDir);
   const targetFilePath = path.join(options.rootDir, targetPath);
   await mkdir(path.dirname(targetFilePath), { recursive: true });
@@ -446,27 +455,99 @@ async function applyDecisionArtifactLocked(options) {
     existingContent = `# ${path.basename(targetPath, '.md')} decisions\n`;
   }
 
-  const entry = renderDecisionEntry({
-    decisionId: nextDecisionId,
-    title,
-    decision,
-    rationale,
-    context,
-    artifactId,
-  });
-  await writeFile(targetFilePath, `${existingContent.trimEnd()}\n\n${entry}`, 'utf8');
-  const indexResult = options.refreshIndex
-    ? await refreshDecisionIndex(options.rootDir)
-    : {
+  const applyWarnings = [];
+  const alreadyInFile = existingContent.includes(
+    `hosted docs-review artifact ${artifactId}`,
+  );
+  let appliedDecisionIdForMarker = nextDecisionId;
+
+  if (alreadyInFile) {
+    // A previous apply wrote the file but crashed before recording the
+    // marker. Repair the marker instead of appending a duplicate.
+    applyWarnings.push(
+      `Artifact ${artifactId} was already present in ${targetPath}; repaired the marker without appending a duplicate entry.`,
+    );
+    const existingIdMatch = existingContent.match(
+      new RegExp(
+        `### (D-\\d+)[^\\n]*(?:\\n(?!### ).*)*hosted docs-review artifact ${artifactId.replaceAll(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}`,
+      ),
+    );
+    appliedDecisionIdForMarker = existingIdMatch
+      ? Number.parseInt(existingIdMatch[1].slice(2), 10)
+      : nextDecisionId;
+  } else {
+    const entry = renderDecisionEntry({
+      decisionId: nextDecisionId,
+      title,
+      decision,
+      rationale,
+      context,
+      artifactId,
+    });
+    const nextContent = `${existingContent.trimEnd()}\n\n${entry}`;
+    // Append-only enforced in code, not just convention: the previous file
+    // content must survive verbatim as a prefix of what we write.
+    if (!nextContent.startsWith(existingContent.trimEnd())) {
+      throw new Error(
+        `Refusing to apply artifact ${artifactId}: the write would not preserve the existing content of ${targetPath} (decisions are append-only).`,
+      );
+    }
+    await writeFile(targetFilePath, nextContent, 'utf8');
+
+    // Post-write verification: the canonical write must be durable and
+    // intact before the marker records the artifact as applied.
+    const verification = await readFile(targetFilePath, 'utf8');
+    if (verification !== nextContent) {
+      throw new Error(
+        `Post-write verification failed for ${targetPath}: the file on disk does not match the appended content. The marker was NOT updated; inspect the file and retry.`,
+      );
+    }
+  }
+
+  // Hosted-only roots can apply locally but can never push the result back
+  // until the project is demoted to local-primary — say so instead of letting
+  // the user discover it at push time.
+  try {
+    const projectConfig = parseSimpleYaml(
+      await readFile(path.join(options.rootDir, 'project.yaml'), 'utf8'),
+      { sourceName: 'project.yaml' },
+    );
+    if (projectConfig?.mode === 'hosted-only') {
+      applyWarnings.push(
+        'This is a hosted-only project: the locally applied decision cannot be pushed back to the hosted canonical store. The hosted copy was already recorded when the artifact was accepted; treat this local root as a working copy.',
+      );
+    }
+  } catch {
+    // Unreadable project.yaml is surfaced by other commands; not fatal here.
+  }
+
+  let indexResult;
+  if (options.refreshIndex) {
+    try {
+      indexResult = await refreshDecisionIndex(options.rootDir);
+    } catch (error) {
+      // An index-refresh failure after a verified canonical write must not
+      // strand the marker (a retry would duplicate the entry): degrade to a
+      // warning and keep going.
+      indexResult = {
+        refreshed: false,
+        warnings: [
+          `decisions/INDEX.md refresh failed after the entry was appended: ${error.message}. Run vibecompass refresh-decision-index manually.`,
+        ],
+      };
+    }
+  } else {
+    indexResult = {
       refreshed: false,
       warnings: [
         'decisions/INDEX.md was not refreshed. Run again with --refresh-index if this root uses the package-generated flat index, or update the project-specific index manually.',
       ],
     };
+  }
 
   const appliedDecisionArtifact = {
     artifact_id: artifactId,
-    decision_id: nextDecisionId,
+    decision_id: appliedDecisionIdForMarker,
     target_path: targetPath,
     applied_at: new Date().toISOString(),
     refreshed_index: indexResult.refreshed,
@@ -478,7 +559,7 @@ async function applyDecisionArtifactLocked(options) {
       ...current.hosted,
       artifacts: (current.hosted?.artifacts ?? []).map((item) =>
         item?.artifact_id === artifactId
-          ? { ...item, local_status: 'applied', local_decision_id: nextDecisionId }
+          ? { ...item, local_status: 'applied', local_decision_id: appliedDecisionIdForMarker }
           : item,
       ),
     },
@@ -494,8 +575,10 @@ async function applyDecisionArtifactLocked(options) {
     hosted: current.hosted ?? null,
     appliedDecisionArtifact,
     reviewPrompt: null,
-    warnings: indexResult.warnings,
-    message: `Applied decision artifact ${artifactId} as D-${String(nextDecisionId).padStart(3, '0')} in ${targetPath}.`,
+    warnings: [...applyWarnings, ...indexResult.warnings],
+    message: alreadyInFile
+      ? `Repaired the marker for decision artifact ${artifactId} (already present in ${targetPath} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')}).`
+      : `Applied decision artifact ${artifactId} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')} in ${targetPath}.`,
   };
 }
 
@@ -1972,6 +2055,10 @@ function renderDecisionEntry(options) {
     `**Decision:** ${options.decision}`,
     `**Rationale:** ${options.rationale}`,
     ...(options.context ? [`**Context:** ${options.context}`] : []),
+    // Provenance makes re-application detectable from the file itself, so a
+    // crash between the file write and the marker update can never cause a
+    // silent duplicate append on retry.
+    ...(options.artifactId ? [`**Source:** hosted docs-review artifact ${options.artifactId}`] : []),
     '',
   ].join('\n');
 }

package/src/index.js

@@ -6,8 +6,11 @@ export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
+export { demoteHosted, promoteHosted } from './mode-transition.js';
 export {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,

package/src/mode-transition.js

@@ -0,0 +1,265 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
+import { withMemoryRootLock } from './serialization.js';
+import { adoptRemoteHead, pushProjectMemory } from './sync.js';
+
+const PROMOTED_MARKER = ['state', 'promoted-root.json'];
+
+/**
+ * D-288 promote: local-primary -> hosted-only as a crash-safe, resumable
+ * two-phase transition. Fresh verified push baseline -> server records the
+ * intent (with a completeness report) -> local changes (project.yaml mode,
+ * promoted-root marker, agent guidance) -> server confirm. `--resume`
+ * continues an interrupted run from whatever state it reached; `--abort`
+ * backs the whole thing out on both sides.
+ */
+export async function promoteHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'promote-hosted', () =>
+    promoteHostedLocked(options, environment, rootDir),
+  );
+}
+
+async function promoteHostedLocked(options, environment, rootDir) {
+  const context = await loadModeAgnosticSyncContext(rootDir, options, environment);
+  const server = await getJson(context, 'status');
+  const localMode = context.project.mode;
+  const notes = [];
+
+  if (options.abort === true) {
+    // A confirmed promotion cannot be aborted: the server is already
+    // hosted-only, and rewriting only the local record would create exactly
+    // the split-brain the two-phase flow exists to prevent. Reversing a
+    // finished cutover is demote-hosted's job.
+    if (server.mode === 'hosted-only' && !server.pending_mode_transition) {
+      throw new Error(
+        'This promotion was already confirmed — the hosted project is hosted-only. '
+        + 'Aborting now would only rewrite the local record and split the two mode records. '
+        + 'Use vibecompass demote-hosted to reverse the cutover on both sides.',
+      );
+    }
+    await postJson(context, 'mode-transition', { action: 'abort' });
+    if (localMode === 'hosted-only') {
+      await writeProjectMode(rootDir, 'local-primary');
+      await removePromotedMarker(rootDir);
+      notes.push('Restored local project.yaml to local-primary and removed the promoted-root marker.');
+    }
+    return {
+      status: 'aborted',
+      rootDir,
+      warnings: notes,
+      message: 'Promotion aborted; the project remains local-primary on both sides.',
+    };
+  }
+
+  if (server.mode === 'hosted-only' && localMode === 'hosted-only' && !server.pending_mode_transition) {
+    await ensurePromotedMarker(rootDir, context);
+    return {
+      status: 'already-promoted',
+      rootDir,
+      warnings: [],
+      message: 'This project is already hosted-only on both sides.',
+    };
+  }
+
+  const resuming = options.resume === true || Boolean(server.pending_mode_transition) || localMode === 'hosted-only';
+  let completeness = null;
+
+  if (localMode === 'local-primary') {
+    // Phase 1: fresh verified baseline. Idempotent push makes retries safe.
+    const pushResult = await pushProjectMemory(
+      { rootDir, syncTarget: options.syncTarget ?? null },
+      environment,
+    );
+    notes.push(`Baseline push: ${pushResult.status} (${pushResult.remoteRevisionId}).`);
+
+    const manifest = JSON.parse(await readFile(path.join(rootDir, 'state', 'manifest.json'), 'utf8'));
+    const begin = await postJson(context, 'mode-transition', {
+      action: 'begin',
+      target_mode: 'hosted-only',
+      expected_manifest_hash: manifest.canonical.manifest_hash,
+    });
+    completeness = begin.completeness ?? null;
+
+    // Phase 2: local changes.
+    await writeProjectMode(rootDir, 'hosted-only');
+    await ensurePromotedMarker(rootDir, context);
+  } else if (resuming) {
+    // Crash-window repair: the mode flipped locally but the marker (or the
+    // confirm) may be missing.
+    await ensurePromotedMarker(rootDir, context);
+  } else {
+    throw new Error(`promote-hosted requires a local-primary root (found mode: ${localMode ?? 'unknown'}).`);
+  }
+
+  // Phase 3: confirm (safe to retry; the server treats a repeated confirm as done).
+  await postJson(context, 'mode-transition', { action: 'confirm', target_mode: 'hosted-only' });
+
+  notes.push(
+    'Agent re-pointing: hosted context is now canonical. In your MCP configuration set VIBECOMPASS_API_KEY '
+    + '(create a key on the hosted Setup page), remove VIBECOMPASS_ROOT, and restart your MCP server. '
+    + 'Agent instruction files keep working for reading; canonical writes belong on the hosted dashboard.',
+  );
+  notes.push(
+    'This root is now a promoted working copy: canonical write commands refuse by default '
+    + '(vibecompass demote-hosted reverses the cutover; VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1 overrides deliberately).',
+  );
+
+  return {
+    status: resuming && localMode !== 'local-primary' ? 'resumed-and-promoted' : 'promoted',
+    rootDir,
+    completeness,
+    warnings: notes,
+    message: 'Promotion complete: the hosted app is now this project\'s source of truth (both mode records agree).',
+  };
+}
+
+/**
+ * D-289 demote: hosted-only -> local-primary. Run from a local root that
+ * holds the hosted content (freshly bootstrapped from the export bundle, or
+ * the original promoted root). Flips both records via the same two-phase
+ * endpoint, then adopts the hosted head as the sync cursor so the first push
+ * works immediately.
+ */
+export async function demoteHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'demote-hosted', () =>
+    demoteHostedLocked(options, environment, rootDir),
+  );
+}
+
+async function demoteHostedLocked(options, environment, rootDir) {
+  const context = await loadModeAgnosticSyncContext(rootDir, options, environment);
+  const server = await getJson(context, 'status');
+  const notes = [];
+
+  if (server.mode === 'local-primary' && context.project.mode === 'local-primary') {
+    return {
+      status: 'already-local-primary',
+      rootDir,
+      warnings: [],
+      message: 'This project is already local-primary on both sides.',
+    };
+  }
+
+  if (server.mode === 'hosted-only') {
+    await postJson(context, 'mode-transition', { action: 'begin', target_mode: 'local-primary' });
+  }
+  if (context.project.mode !== 'local-primary') {
+    await writeProjectMode(rootDir, 'local-primary');
+    notes.push('Local project.yaml mode set to local-primary.');
+  }
+  await removePromotedMarker(rootDir);
+  await postJson(context, 'mode-transition', { action: 'confirm', target_mode: 'local-primary' });
+
+  // Adopt the hosted head as this root's baseline so the first push has the
+  // correct parent (bundle-restored roots already carry it; this makes the
+  // flow correct for any root).
+  const adoption = await adoptRemoteHead(
+    {
+      rootDir,
+      syncTarget: options.syncTarget ?? null,
+      acceptDivergence: options.acceptDivergence === true,
+    },
+    environment,
+  );
+  notes.push(adoption.message);
+
+  return {
+    status: 'demoted',
+    rootDir,
+    warnings: notes,
+    message: 'Demotion complete: this local root is canonical again (local-primary on both sides). Local files win; push to publish changes.',
+  };
+}
+
+async function loadModeAgnosticSyncContext(rootDir, options, environment) {
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+    sourceName: projectFilePath,
+  });
+  const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+  if (!binding) {
+    throw new Error('Mode transitions require a sync binding in project.yaml (run connect-hosted first).');
+  }
+  const credential = ((environment.env ?? process.env)[binding.credentialEnvVar] ?? '').trim();
+  if (!credential) {
+    throw new Error(`Mode transitions require ${binding.credentialEnvVar} to be set.`);
+  }
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('Mode transitions require a fetch implementation.');
+  }
+  return { rootDir, project, binding, credential, fetch: fetchImpl };
+}
+
+function endpointUrl(context, routeName) {
+  const base = context.binding.apiUrl.endsWith('/')
+    ? context.binding.apiUrl
+    : `${context.binding.apiUrl}/`;
+  return new URL(
+    `api/sync/projects/${encodeURIComponent(context.binding.projectId)}/${routeName}`,
+    base,
+  ).href;
+}
+
+async function getJson(context, routeName) {
+  const response = await context.fetch(endpointUrl(context, routeName), {
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${context.credential}`,
+    },
+  });
+  if (!response.ok) {
+    const text = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted ${routeName} failed with ${response.status}${text ? `: ${text}` : ''}`);
+  }
+  return typeof response.json === 'function' ? response.json() : {};
+}
+
+async function postJson(context, routeName, body) {
+  const response = await context.fetch(endpointUrl(context, routeName), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${context.credential}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted ${routeName} failed with ${response.status}${text ? `: ${text}` : ''}`);
+  }
+  return typeof response.json === 'function' ? response.json() : {};
+}
+
+async function writeProjectMode(rootDir, mode) {
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const raw = await readFile(projectFilePath, 'utf8');
+  const next = raw.replace(/^mode:\s*\S+\s*$/m, `mode: ${mode}`);
+  if (next === raw && !new RegExp(`^mode:\\s*${mode}\\s*$`, 'm').test(raw)) {
+    throw new Error(`Could not update the mode line in ${projectFilePath}; edit it to "mode: ${mode}" and re-run with --resume.`);
+  }
+  await writeFile(projectFilePath, next, 'utf8');
+}
+
+async function ensurePromotedMarker(rootDir, context) {
+  const markerPath = path.join(rootDir, ...PROMOTED_MARKER);
+  await mkdir(path.dirname(markerPath), { recursive: true });
+  const marker = {
+    promoted_at: new Date().toISOString(),
+    api_url: context.binding.apiUrl,
+    project_id: context.binding.projectId,
+    note: 'This root was promoted to hosted-only (D-288). The hosted app is canonical; local canonical writes refuse by default.',
+  };
+  await writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+}
+
+async function removePromotedMarker(rootDir) {
+  await rm(path.join(rootDir, ...PROMOTED_MARKER), { force: true });
+}

package/src/serialization.js

@@ -46,7 +46,33 @@ export function memoryRootLockPath(rootDir) {
  * Runs `fn` while holding the serialization lock for `rootDir`. Reentrant:
  * a nested call from inside the lock holder runs immediately.
  */
+// Commands that stay allowed on a promoted root: the transition flows
+// themselves, plus recovery tooling that must be able to repair state.
+const PROMOTED_ROOT_ALLOWED_COMMANDS = new Set([
+  'promote-hosted',
+  'demote-hosted',
+  'bootstrap',
+]);
+
+async function assertNotPromotedRoot(rootDir, label) {
+  if (PROMOTED_ROOT_ALLOWED_COMMANDS.has(label)) return;
+  if (process.env.VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES === '1') return;
+  const markerPath = path.join(rootDir, 'state', 'promoted-root.json');
+  let marker;
+  try {
+    marker = JSON.parse(await readFile(markerPath, 'utf8'));
+  } catch {
+    return;
+  }
+  throw new Error(
+    `This root was promoted to hosted-only${marker?.promoted_at ? ` on ${marker.promoted_at}` : ''}: the hosted app is canonical and local writes here can never sync back (D-288). `
+    + 'Make changes on the hosted dashboard, run vibecompass demote-hosted to make this root canonical again, '
+    + 'or set VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1 to override deliberately.',
+  );
+}
+
 export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
+  await assertNotPromotedRoot(rootDir, label);
   const key = await canonicalizeMemoryRootKey(rootDir);
   const held = heldRoots.getStore();
   if (await findHeldMemoryRootKey(held, key)) {

package/src/status.js

@@ -4,6 +4,7 @@ import { inspectProjectCompatibility } from './compatibility.js';
 import { sha256Text } from './hash.js';
 import { resolveLaneMarkerContext } from './lane-marker.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
 import { inferToolingRootForMemoryRoot, listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -30,12 +31,18 @@ export async function getProjectStatus(options = {}) {
     readAgentFileStatus(rootDir, toolingRootDir),
     readProjectMemoryStatus(rootDir),
   ]);
+  const hostedSync = await readHostedModeCheck(
+    compatibility.projectFilePath,
+    project.mode ?? null,
+    options,
+  );
 
   return {
     generatedAt: new Date().toISOString(),
     rootDir,
     toolingRootDir,
     project,
+    hostedSync,
     compatibility: {
       cliPackageVersion: compatibility.cliPackageVersion,
       package: compatibility.package,
@@ -111,6 +118,13 @@ export function renderStatusText(status) {
     `Generated: ${status.generatedAt}`,
     `Project: ${status.project.name ?? 'Unknown'}`,
     `Mode: ${status.project.mode ?? 'Unknown'}`,
+    ...(status.hostedSync?.status === 'ok' && status.hostedSync.mismatch
+      ? [
+          `WARNING: mode mismatch — local project.yaml says "${status.hostedSync.localMode}" but the hosted project is "${status.hostedSync.hostedMode}". The two mode records are unreconciled: sync and dashboard actions will refuse until they agree. Do not hand-edit mode; a supported promote/demote flow flips both records together.`,
+        ]
+      : status.hostedSync?.status === 'unreachable'
+        ? [`Hosted mode check: unreachable (${status.hostedSync.detail}).`]
+        : []),
     `Root: ${status.rootDir}`,
     `Repos: ${status.project.repos.length > 0 ? status.project.repos.map((repo) => repo.id).join(', ') : 'None recorded'}`,
     `Active lanes: ${formatActiveLanes(status.sessions)}`,
@@ -162,6 +176,7 @@ export function toStatusJson(status) {
   return {
     generatedAt: status.generatedAt,
     rootDir: status.rootDir,
+    hostedSync: status.hostedSync ?? null,
     toolingRootDir: status.toolingRootDir,
     project: status.project,
     compatibility: status.compatibility,
@@ -173,6 +188,69 @@ export function toStatusJson(status) {
   };
 }
 
+/**
+ * Mode-mismatch diagnostic (plan 3.8): compares the local project.yaml mode
+ * against the hosted project's mode via the side-effect-free sync status
+ * endpoint. A hand-edited mode previously wedged a project with opaque 409s
+ * on both sides and no diagnostic anywhere. Network problems degrade to an
+ * "unreachable" note — status stays offline-safe.
+ */
+async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
+  let binding;
+  try {
+    const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+    binding = resolveSyncBinding(config, null);
+  } catch {
+    return { status: 'not-configured' };
+  }
+  if (!binding) return { status: 'not-configured' };
+
+  const env = options.env ?? process.env;
+  const credential = typeof env[binding.credentialEnvVar] === 'string'
+    ? env[binding.credentialEnvVar].trim()
+    : '';
+  if (!credential) {
+    return { status: 'no-credential', credentialEnvVar: binding.credentialEnvVar };
+  }
+
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return { status: 'not-configured' };
+
+  const baseUrl = binding.apiUrl.endsWith('/') ? binding.apiUrl : `${binding.apiUrl}/`;
+  const endpoint = new URL(
+    `api/sync/projects/${encodeURIComponent(binding.projectId)}/status`,
+    baseUrl,
+  );
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const response = await fetchImpl(endpoint.href, {
+      headers: {
+        accept: 'application/json',
+        authorization: `Bearer ${credential}`,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return { status: 'unreachable', detail: `HTTP ${response.status}` };
+    }
+    const data = typeof response.json === 'function' ? await response.json() : {};
+    const hostedMode = typeof data.mode === 'string' ? data.mode : null;
+    return {
+      status: 'ok',
+      hostedMode,
+      localMode,
+      mismatch: Boolean(hostedMode && localMode && hostedMode !== localMode),
+    };
+  } catch (error) {
+    return { status: 'unreachable', detail: error?.message ?? 'network error' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function readProjectSummary(projectFilePath) {
   try {
     const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {

package/src/sync.js

@@ -155,21 +155,28 @@ async function applyPullExportLocked(options, rootDir) {
     throw new Error(`Pull-export bundle at ${outputPath} has no operations.`);
   }
 
-  const applied = [];
+  // Pre-validate EVERY operation before writing anything, and classify
+  // operations whose target already matches the after-state as
+  // already-applied. This makes a retry after a partial failure converge
+  // instead of failing forever on the ops that succeeded last time.
+  const plan = [];
   for (const operation of operations) {
     const relativePath = normalizeCanonicalPath(operation.path);
     const targetPath = path.join(rootDir, relativePath);
     const currentHash = await readCurrentHash(targetPath);
     const expectedBefore = operation.before_content_hash ?? null;
-    if (currentHash !== expectedBefore) {
-      throw new Error(
-        `Cannot apply ${relativePath}: local content hash ${currentHash ?? 'missing'} does not match expected ${expectedBefore ?? 'missing'}. Run pull-preview again or resolve locally.`,
-      );
-    }
 
     if (operation.op === 'delete') {
-      await unlink(targetPath);
-      applied.push({ path: relativePath, status: 'deleted' });
+      if (currentHash === null) {
+        plan.push({ relativePath, targetPath, action: 'skip', status: 'already-deleted' });
+        continue;
+      }
+      if (currentHash !== expectedBefore) {
+        throw new Error(
+          `Cannot apply ${relativePath}: local content hash ${currentHash} does not match expected ${expectedBefore ?? 'missing'}. Run pull-preview again or resolve locally.`,
+        );
+      }
+      plan.push({ relativePath, targetPath, action: 'delete' });
       continue;
     }
 
@@ -180,10 +187,32 @@ async function applyPullExportLocked(options, rootDir) {
     if (afterHash !== operation.after_content_hash) {
       throw new Error(`Exported content hash does not match raw_text for ${relativePath}.`);
     }
+    if (currentHash === afterHash) {
+      plan.push({ relativePath, targetPath, action: 'skip', status: 'already-applied' });
+      continue;
+    }
+    if (currentHash !== expectedBefore) {
+      throw new Error(
+        `Cannot apply ${relativePath}: local content hash ${currentHash ?? 'missing'} does not match expected ${expectedBefore ?? 'missing'}. Run pull-preview again or resolve locally.`,
+      );
+    }
+    plan.push({ relativePath, targetPath, action: 'write', rawText: operation.raw_text });
+  }
 
-    await mkdir(path.dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, ensureTrailingNewline(operation.raw_text), 'utf8');
-    applied.push({ path: relativePath, status: 'written' });
+  const applied = [];
+  for (const step of plan) {
+    if (step.action === 'skip') {
+      applied.push({ path: step.relativePath, status: step.status });
+      continue;
+    }
+    if (step.action === 'delete') {
+      await unlink(step.targetPath);
+      applied.push({ path: step.relativePath, status: 'deleted' });
+      continue;
+    }
+    await mkdir(path.dirname(step.targetPath), { recursive: true });
+    await writeFile(step.targetPath, ensureTrailingNewline(step.rawText), 'utf8');
+    applied.push({ path: step.relativePath, status: 'written' });
   }
 
   bundle.applied_at = new Date().toISOString();
@@ -200,6 +229,220 @@ async function applyPullExportLocked(options, rootDir) {
   };
 }
 
+/**
+ * Re-baselines this root's sync cursor onto the hosted head (D-287 sync
+ * trust): the recovery path for a fresh clone or second device whose
+ * gitignored cursor is missing, which previously hit a permanent 409
+ * needs_rebase. Preserves D-215's inspect-then-choose workflow: a pull
+ * preview always runs first, and pending hosted proposals or conflicts
+ * refuse the adopt unless --accept-divergence is passed.
+ */
+export async function adoptRemoteHead(options = {}, environment = {}) {
+  const context = await loadSyncContext(options, environment);
+  const existingManifest = await readJsonIfPresent(context.manifestPath);
+  const manifestResult = await writeStateManifest(context.rootDir, {
+    sync: existingManifest?.sync,
+  });
+  const manifest = manifestResult.manifest;
+  const cursor = readSyncCursor(manifest.sync, context.binding);
+
+  const response = await postJson(context, 'pull-preview', {
+    state_version: manifest.state_version,
+    base_remote_revision_id: normalizeUuid(cursor.last_successful_remote_revision),
+    local_root_revision: manifest.canonical.local_root_revision,
+    local_manifest_hash: manifest.canonical.manifest_hash,
+    local_documents: buildLocalDocumentSummaries(manifest.documents),
+    include_pending_proposals: true,
+  });
+
+  const targetRemoteRevisionId = normalizeUuid(response.target_remote_revision_id);
+  if (!targetRemoteRevisionId) {
+    throw new Error('The hosted project has no baseline revision to adopt yet. Run vibecompass push first.');
+  }
+
+  const proposals = Array.isArray(response.proposals) ? response.proposals : [];
+  const conflicts = Array.isArray(response.conflicts) ? response.conflicts : [];
+  if ((proposals.length > 0 || conflicts.length > 0) && options.acceptDivergence !== true) {
+    throw new Error(
+      `Refusing to adopt the hosted head: ${proposals.length} pending proposal${proposals.length === 1 ? '' : 's'} and ${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'} exist for this project (D-215: inspect divergence before choosing a baseline). Review with vibecompass pull-preview, then re-run sync-adopt --accept-divergence to adopt anyway.`,
+    );
+  }
+
+  const sync = buildSyncStateWithCursor(manifest.sync, context.binding, {
+    ...cursor,
+    last_successful_remote_revision: targetRemoteRevisionId,
+    last_successful_local_root_revision: manifest.canonical.local_root_revision,
+    last_successful_manifest_hash: manifest.canonical.manifest_hash,
+    last_sync_direction: 'adopt',
+    last_sync_at: new Date().toISOString(),
+    pending_previews: [],
+  });
+  const updatedManifest = await writeStateManifest(context.rootDir, { sync });
+
+  return {
+    status: 'adopted',
+    rootDir: context.rootDir,
+    manifestPath: updatedManifest.manifestPath,
+    remoteRevisionId: targetRemoteRevisionId,
+    proposalCount: proposals.length,
+    conflictCount: conflicts.length,
+    warnings: [
+      'The next push will record this root\'s content as a new revision on top of the adopted head. If local files differ from the hosted head, the hosted content is replaced (visibly, as a new revision).',
+    ],
+    message: `Adopted hosted head ${targetRemoteRevisionId} as this root's sync baseline.`,
+  };
+}
+
+/**
+ * Materializes a complete local memory root from a hosted bootstrap bundle
+ * (D-289): the escape hatch, disaster-recovery, and second-device path. All
+ * document hashes are verified before anything is written (fail closed). For
+ * local-primary bundles with a resolvable sync binding, the bundle's server
+ * head is seeded as the sync cursor so the first push has the correct parent;
+ * hosted-only bundles materialize a fully usable offline root (the server
+ * rejects hosted-only push until the project is demoted).
+ */
+export async function bootstrapFromBundle(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  if (!options.bundlePath) {
+    throw new Error('bootstrap requires --bundle <file> (download it from the hosted Setup page).');
+  }
+  const bundlePath = path.resolve(cwd, options.bundlePath);
+  return withMemoryRootLock(rootDir, 'bootstrap', () =>
+    bootstrapFromBundleLocked(options, rootDir, bundlePath),
+  );
+}
+
+async function bootstrapFromBundleLocked(options, rootDir, bundlePath) {
+  const bundle = await readJsonRequired(bundlePath, 'bootstrap bundle');
+  if (bundle.bundle_kind !== 'bootstrap_export') {
+    throw new Error(
+      `File at ${bundlePath} is not a bootstrap bundle (bundle_kind: ${bundle.bundle_kind ?? 'missing'}).`,
+    );
+  }
+  const documents = Array.isArray(bundle.documents) ? bundle.documents : [];
+  if (documents.length === 0) {
+    throw new Error(`Bootstrap bundle at ${bundlePath} has no documents.`);
+  }
+
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  let existingProjectFile = false;
+  try {
+    await readFile(projectFilePath, 'utf8');
+    existingProjectFile = true;
+  } catch {
+    existingProjectFile = false;
+  }
+  if (existingProjectFile) {
+    throw new Error(
+      `${rootDir} already contains project.yaml. Bootstrap only materializes fresh roots — pick an empty --root or move the existing one aside.`,
+    );
+  }
+
+  // Fail closed BEFORE writing anything: verify every document's hash and
+  // path, and require the bundle to carry project.yaml.
+  let hasProjectFile = false;
+  const validated = documents.map((document) => {
+    const relativePath = normalizeCanonicalPath(document.path);
+    if (document.op !== 'write' || typeof document.raw_text !== 'string') {
+      throw new Error(`Unsupported bootstrap operation for ${relativePath}.`);
+    }
+    const hash = sha256Text(document.raw_text);
+    if (hash !== document.after_content_hash) {
+      throw new Error(
+        `Bootstrap bundle content hash does not match raw_text for ${relativePath}. The bundle is corrupt — download it again.`,
+      );
+    }
+    if (relativePath === 'project.yaml') hasProjectFile = true;
+    return { relativePath, rawText: document.raw_text };
+  });
+  if (!hasProjectFile) {
+    throw new Error('Bootstrap bundle does not include project.yaml.');
+  }
+
+  // Content is written verbatim (no newline normalization) so the local root
+  // byte-matches the hosted head the bundle's cursor points at.
+  const written = [];
+  for (const document of validated) {
+    const targetPath = path.join(rootDir, document.relativePath);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, document.rawText, 'utf8');
+    written.push(document.relativePath);
+  }
+
+  const warnings = [];
+  let manifestPath = null;
+  let cursorSeeded = false;
+  let projectMode = null;
+  try {
+    const project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+    projectMode = typeof project.mode === 'string' ? project.mode : null;
+
+    let sync;
+    const serverHead = bundle.server_head ?? null;
+    if (projectMode === 'local-primary' && serverHead?.remote_revision_id) {
+      const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+      if (binding) {
+        const manifestResult = await writeStateManifest(rootDir);
+        // Fail closed on cursor seeding: the cursor claims "this root's
+        // content IS the server head" — only true when the materialized
+        // manifest hash matches the head hash captured in the bundle. A
+        // mismatched bundle still materializes (files are hash-verified
+        // individually) but must not claim the head as its baseline.
+        const localHash = manifestResult.manifest.canonical.manifest_hash;
+        if (serverHead.manifest_hash && localHash !== serverHead.manifest_hash) {
+          warnings.push(
+            `Sync cursor NOT seeded: the materialized root's manifest hash (${localHash}) does not match the bundle's server head (${serverHead.manifest_hash}). `
+            + 'The files are intact, but run vibecompass sync-adopt (after reviewing divergence) before pushing.',
+          );
+        } else {
+          sync = buildSyncStateWithCursor(manifestResult.manifest.sync, binding, {
+            last_successful_remote_revision: serverHead.remote_revision_id,
+            last_successful_local_root_revision:
+              manifestResult.manifest.canonical.local_root_revision,
+            last_successful_manifest_hash: localHash,
+            last_sync_direction: 'bootstrap',
+            last_sync_at: new Date().toISOString(),
+            pending_previews: [],
+          });
+          cursorSeeded = true;
+        }
+      } else {
+        warnings.push(
+          'No sync binding found in the bundled project.yaml; run connect-hosted before pushing.',
+        );
+      }
+    }
+    const manifestResult = await writeStateManifest(rootDir, sync ? { sync } : undefined);
+    manifestPath = manifestResult.manifestPath;
+  } catch (error) {
+    warnings.push(
+      `Documents were written, but the state manifest could not be generated: ${error.message}`,
+    );
+  }
+
+  if (projectMode === 'hosted-only') {
+    warnings.push(
+      'This is a hosted-only project: the root is fully usable offline, but hosted sync rejects local push until the project is demoted. '
+      + 'To make this root canonical: run vibecompass connect-hosted (with the API URL, project id, and token env var from the hosted Setup page) to add the sync binding, then vibecompass demote-hosted.',
+    );
+  }
+
+  return {
+    status: 'bootstrapped',
+    rootDir,
+    manifestPath,
+    documentCount: written.length,
+    mode: projectMode,
+    cursorSeeded,
+    warnings,
+    message: `Materialized ${written.length} document${written.length === 1 ? '' : 's'} into ${rootDir}${cursorSeeded ? ' and seeded the sync cursor from the bundle head' : ''}.`,
+  };
+}
+
 async function loadSyncContext(options, environment) {
   const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
@@ -210,7 +453,11 @@ async function loadSyncContext(options, environment) {
   });
 
   if (project.mode !== 'local-primary') {
-    throw new Error('Hosted sync commands require project.yaml mode: local-primary.');
+    throw new Error(
+      `Hosted sync commands require project.yaml mode: local-primary (this root says "${project.mode}"). `
+      + 'Mode is recorded twice — locally in project.yaml and on the hosted project — and they must agree. '
+      + 'Run vibecompass status to compare both records; use promote-hosted/demote-hosted to change modes on both sides together instead of hand-editing.',
+    );
   }
 
   const binding = resolveSyncBinding(project, options.syncTarget ?? null);
@@ -220,7 +467,11 @@ async function loadSyncContext(options, environment) {
 
   const credential = normalizeOptionalString((environment.env ?? process.env)[binding.credentialEnvVar]);
   if (!credential) {
-    throw new Error(`Hosted sync command requires ${binding.credentialEnvVar}.`);
+    throw new Error(
+      `Hosted sync command requires ${binding.credentialEnvVar}. New terminals do not inherit one-off exports: `
+      + `re-export it (export ${binding.credentialEnvVar}="<sync token>") or persist it in your shell profile (~/.zshenv or ~/.bashrc). `
+      + 'Lost the token? Rotate it on the hosted dashboard under Setup -> Hosted sync, then export the new value.',
+    );
   }
 
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;