@vibecompass/vibecompass 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.8.0 - 2026-06-12
+
+- Add named sync targets (D-236): `connect-hosted --target <name>` binds one project root to multiple hosted environments (for example `dev` on localhost and `prod` on vibecompass.dev).
+- Add a `sync-target` command to list named targets and switch the default; flat `sync` fields in project.yaml always mirror the default target so older CLIs keep working.
+- Add `--sync-target <name>` to `push`, `pull-preview`, `pull-export`, and `docs-review` for per-command environment selection; unknown target names error instead of falling back.
+- Partition local sync cursor state per target (D-237): each target keeps its own last-pushed revision and pull previews, identity-checked against its URL and project id, so one environment's history can never become another environment's baseline.
+- Carry the existing sync history over when a flat binding is converted into its first named target with the same URL and project id.
+- Record the submitted sync target in the docs-review marker so `--poll-hosted` stays pinned to the environment the run was submitted to.
+
 ## 0.7.0 - 2026-05-30
 
 - Add `docs-review --rebuild` with dry-run preview, scoped architecture paths, and archive-based stale-doc preparation.

package/README.md

@@ -125,7 +125,7 @@ After setup, use these phrases inside your AI coding tool:
 - `planning mode`
 - `review handoff`
 - `address review`
-- `close session`
+- `close session` / `end session`
 - `docs review`
 
 The npm package owns the file mechanics. Your AI session owns reading the
@@ -146,6 +146,28 @@ vibecompass connect-hosted \
 vibecompass push --root .compass
 ```
 
+### Multiple environments
+
+One project can have named sync targets (for example a local dev server and
+production) so you never have to rebind:
+
+```bash
+# add targets once — the first one becomes the default
+vibecompass connect-hosted --root .compass --target dev \
+  --sync-api-url http://localhost:3000 --sync-project-id vc_proj_dev \
+  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
+vibecompass connect-hosted --root .compass --target prod \
+  --sync-api-url https://vibecompass.dev --sync-project-id vc_proj_prod \
+  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN_PROD
+
+# then pick per command, or switch the default
+vibecompass push --root .compass --sync-target prod
+vibecompass sync-target prod --root .compass
+```
+
+Tip: if you already have a single (flat) binding, add it as your first named
+target using the same URL and project id — its sync history carries over.
+
 See https://vibecompass.dev/developers for the full local-primary workflow.
 
 ## JavaScript API

package/package.json

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

package/src/cli.js

@@ -2,7 +2,7 @@
 
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { connectHostedProjectMemory, initializeProjectMemory } from './init.js';
+import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarget } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
@@ -140,6 +140,10 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     });
     io.stdout.write(`Connected hosted VibeCompass for ${result.mode}\n`);
     io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    if (result.syncTarget) {
+      io.stdout.write(`Sync target: ${result.syncTarget.name} (default: ${result.syncTarget.defaultTarget})\n`);
+      io.stdout.write(`Select per command with --sync-target ${result.syncTarget.name}, or switch the default with: vibecompass sync-target ${result.syncTarget.name}\n`);
+    }
     io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
     if (result.mode === 'local-primary') {
       io.stdout.write('Then run: vibecompass push\n');
@@ -150,6 +154,28 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'sync-target') {
+    const result = await setDefaultSyncTarget({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.targetName) {
+      io.stdout.write(
+        result.changed
+          ? `Default sync target set to ${result.defaultTarget}\n`
+          : `Default sync target already ${result.defaultTarget}\n`,
+      );
+      io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    } else {
+      io.stdout.write(`Default sync target: ${result.defaultTarget ?? '(none)'}\n`);
+    }
+    for (const [name, target] of Object.entries(result.targets)) {
+      const marker = name === result.defaultTarget ? '*' : ' ';
+      io.stdout.write(`${marker} ${name}: ${target.api_url} (project ${target.project_id}, env ${target.credential_env_var})\n`);
+    }
+    return 0;
+  }
+
   if (parsed.command === 'status') {
     const result = await getProjectStatus({
       ...parsed.options,
@@ -401,6 +427,10 @@ export function parseCliArgs(argv) {
       return parseConnectHostedArgs(rest);
     }
 
+    if (command === 'sync-target') {
+      return parseSyncTargetArgs(rest);
+    }
+
     if (command === 'status') {
       return parseStatusArgs(rest);
     }
@@ -702,6 +732,9 @@ function parseConnectHostedArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--target':
+        parsed.targetName = value;
+        break;
       case '--sync-api-url':
         parsed.syncApiUrl = value;
         break;
@@ -726,6 +759,7 @@ function parseConnectHostedArgs(argv) {
     command: 'connect-hosted',
     options: {
       rootDir: parsed.rootDir,
+      ...(parsed.targetName ? { targetName: parsed.targetName } : {}),
       ...(syncValues.length > 0
         ? {
             sync: {
@@ -1128,6 +1162,9 @@ function parseDocsReviewArgs(argv) {
       case '--artifact':
         parsed.artifactId = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       case '--max-tokens':
         parsed.maxTokens = value;
         break;
@@ -1145,7 +1182,72 @@ function parseDocsReviewArgs(argv) {
 function parsePushArgs(argv) {
   return {
     command: 'push',
-    options: parseRootOnlyArgs(argv, 'push'),
+    options: parseRootAndSyncTargetArgs(argv, 'push'),
+  };
+}
+
+function parseRootAndSyncTargetArgs(argv, commandName) {
+  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 '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${commandName}.`);
+    }
+  }
+
+  return parsed;
+}
+
+function parseSyncTargetArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      if (parsed.targetName !== undefined) {
+        throw new Error(`Unexpected argument "${token}".`);
+      }
+      parsed.targetName = token;
+      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;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-target.`);
+    }
+  }
+
+  return {
+    command: 'sync-target',
+    options: parsed,
   };
 }
 
@@ -1173,6 +1275,9 @@ function parsePullPreviewArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       default:
         throw new Error(`Unknown flag "${token}".`);
     }
@@ -1206,6 +1311,9 @@ function parsePullExportArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       case '--preview-token':
         parsed.previewToken = value;
         break;
@@ -1364,6 +1472,7 @@ function usageText() {
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
     '  vibecompass connect-hosted [options]',
+    '  vibecompass sync-target [<name>] [options]',
     '  vibecompass status [options]',
     '  vibecompass refresh-workflow [--dry-run|--apply] [options]',
     '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
@@ -1405,10 +1514,17 @@ function usageText() {
     '',
     'Connect-hosted options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --target <name>                      Add or update a named sync target (e.g. dev, prod)',
+    '                                        First named target becomes the default; flat sync fields mirror the default target',
     '  --sync-api-url <url>                 Hosted sync api_url',
     '  --sync-project-id <id>               Hosted sync project_id',
     '  --sync-credential-env-var <name>     Hosted sync env var reference',
-    '                                        Replaces any existing project.yaml sync binding',
+    '                                        Without --target, replaces any existing flat project.yaml sync binding',
+    '',
+    'Sync-target options:',
+    '  vibecompass sync-target              List named sync targets and the current default',
+    '  vibecompass sync-target <name>       Switch the default sync target (re-mirrors flat sync fields)',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
     '',
     'Status options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
@@ -1463,6 +1579,7 @@ function usageText() {
     '',
     'Sync transport options:',
     '  push --root <path>                   Push canonical local project memory to hosted',
+    '  --sync-target <name>                 Use a named sync target for this command (push, pull-preview, pull-export, docs-review)',
     '  pull-preview --root <path>           Preview hosted proposals and remote state',
     '  pull-preview --no-pending-proposals  Exclude pending proposals from preview',
     '  pull-export --proposal <id>          Export a selected proposal; repeatable',

package/src/docs-review.js

@@ -5,6 +5,7 @@ import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
 
 const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v2';
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
@@ -83,6 +84,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     localProvider,
     runLocal: shouldRunLocal(options),
     anthropicEnvVar: options.anthropicEnvVar ?? 'ANTHROPIC_API_KEY',
+    syncTarget: options.syncTarget ?? null,
   });
   const reviewPrompt = renderReviewPrompt({
     project,
@@ -617,11 +619,10 @@ function resolveDocsReviewRuntime(project, options) {
     localProvider &&
     typeof options.env?.[localProvider.credentialEnvVar] === 'string' &&
     options.env[localProvider.credentialEnvVar].trim() !== '';
-  const hasHostedBinding =
-    project?.sync &&
-    typeof project.sync === 'object' &&
-    typeof project.sync.api_url === 'string' &&
-    typeof project.sync.project_id === 'string';
+  // Throws on an explicitly requested unknown/incomplete --sync-target so a
+  // typo can never fall back to a different environment (D-236).
+  const hostedBinding = resolveSyncBinding(project, options.syncTarget ?? null);
+  const hasHostedBinding = Boolean(hostedBinding);
 
   if (mode === 'local-only') {
     if (options.runLocal && !localProvider) {
@@ -663,11 +664,10 @@ function resolveDocsReviewRuntime(project, options) {
     if (hasHostedBinding) {
       return {
         provider: 'hosted',
-        api_url: project.sync.api_url,
-        project_id: project.sync.project_id,
-        ...(typeof project.sync.credential_env_var === 'string'
-          ? { credential_env_var: project.sync.credential_env_var }
-        : {}),
+        api_url: hostedBinding.apiUrl,
+        project_id: hostedBinding.projectId,
+        credential_env_var: hostedBinding.credentialEnvVar,
+        ...(hostedBinding.target ? { sync_target: hostedBinding.target } : {}),
       };
     }
 
@@ -699,11 +699,10 @@ function resolveDocsReviewRuntime(project, options) {
 
     return {
       provider: 'hosted',
-      api_url: project.sync.api_url,
-      project_id: project.sync.project_id,
-      ...(typeof project.sync.credential_env_var === 'string'
-        ? { credential_env_var: project.sync.credential_env_var }
-        : {}),
+      api_url: hostedBinding.apiUrl,
+      project_id: hostedBinding.projectId,
+      credential_env_var: hostedBinding.credentialEnvVar,
+      ...(hostedBinding.target ? { sync_target: hostedBinding.target } : {}),
     };
   }
 
@@ -1107,8 +1106,15 @@ async function submitHostedDocsReview(options) {
     `api/sync/projects/${encodeURIComponent(options.runtime.project_id)}/docs-review`,
     ensureTrailingSlash(options.runtime.api_url),
   );
+  // D-237: the baseline must come from the submitted target's own cursor so a
+  // dev revision can never be sent as another environment's baseline.
+  const submitCursor = readSyncCursor(options.manifest?.manifest?.sync, {
+    target: options.runtime.sync_target ?? null,
+    apiUrl: options.runtime.api_url,
+    projectId: options.runtime.project_id,
+  });
   const baselineRemoteRevisionId = normalizeUuid(
-    options.manifest?.manifest?.sync?.last_successful_remote_revision,
+    submitCursor.last_successful_remote_revision,
   );
   const response = await options.fetch(endpoint.href, {
     method: 'POST',

package/src/init.js

@@ -6,6 +6,13 @@ import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import {
+  assertValidSyncTargetName,
+  buildSyncSectionWithTargets,
+  mirrorTargetCursorToFlat,
+  readSyncTargets,
+  reconcileCursorsAfterConnect,
+} from './sync-binding.js';
 import { PACKAGE_VERSION } from './version.js';
 
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
@@ -68,15 +75,146 @@ export async function connectHostedProjectMemory(options) {
     throw new Error('connect-hosted requires project.yaml mode to be local-primary or hosted-only.');
   }
 
+  const targetName = typeof options?.targetName === 'string' && options.targetName.trim() !== ''
+    ? assertValidSyncTargetName(options.targetName.trim())
+    : null;
+  const existingTargets = readSyncTargets(projectConfig);
+
+  if (!targetName && existingTargets) {
+    throw new Error(
+      `This project uses named sync targets (${Object.keys(existingTargets.targets).join(', ')}). Pass --target <name> to add or update one, or use "vibecompass sync-target <name>" to switch the default.`,
+    );
+  }
+
+  const previousFlatSync = projectConfig.sync && typeof projectConfig.sync === 'object'
+    ? projectConfig.sync
+    : null;
   const sync = normalizeSyncOptions(options?.sync, projectConfig.mode);
-  projectConfig.sync = sync;
+
+  let syncTarget = null;
+  if (targetName) {
+    const targets = { ...(existingTargets?.targets ?? {}) };
+    targets[targetName] = {
+      api_url: sync.api_url,
+      project_id: sync.project_id,
+      credential_env_var: sync.credential_env_var,
+    };
+    const defaultTarget = existingTargets?.defaultTarget ?? targetName;
+    projectConfig.sync = buildSyncSectionWithTargets(targets, defaultTarget);
+    syncTarget = { name: targetName, defaultTarget };
+  } else {
+    projectConfig.sync = sync;
+  }
+
   await writeFile(projectFilePath, serializeProjectConfig(projectConfig), 'utf8');
 
+  // D-237: reconcile manifest cursor state with the (re)bound target —
+  // first-conversion cursor migration, dropping a rebound target's stale
+  // cursor, and re-mirroring/clearing the flat cursor when the default
+  // target's binding changed (so ≤0.7.0 CLIs can't pair the new flat binding
+  // with a previous environment's cursor).
+  if (targetName) {
+    await updateManifestSyncState(rootDir, (manifestSync) =>
+      reconcileCursorsAfterConnect(
+        manifestSync,
+        targetName,
+        { apiUrl: sync.api_url, projectId: sync.project_id },
+        {
+          isDefault: syncTarget.defaultTarget === targetName,
+          isFirstConversion: !existingTargets,
+          flatBindingMatches: Boolean(
+            previousFlatSync &&
+              previousFlatSync.api_url === sync.api_url &&
+              previousFlatSync.project_id === sync.project_id,
+          ),
+        },
+      ),
+    );
+  }
+
   return {
     rootDir,
     projectFilePath,
     mode: projectConfig.mode,
     syncEnvVar: sync.credential_env_var,
+    syncTarget,
+  };
+}
+
+async function updateManifestSyncState(rootDir, updater) {
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      await readFile(path.join(rootDir, 'state', 'manifest.json'), 'utf8'),
+    );
+  } catch {
+    return; // no manifest yet — nothing to migrate
+  }
+
+  const nextSync = updater(
+    manifest?.sync && typeof manifest.sync === 'object' ? manifest.sync : {},
+  );
+  if (!nextSync) {
+    return;
+  }
+
+  await writeStateManifest(rootDir, { sync: nextSync });
+}
+
+export async function setDefaultSyncTarget(options) {
+  const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const projectConfig = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+    sourceName: projectFilePath,
+  });
+
+  const named = readSyncTargets(projectConfig);
+  if (!named) {
+    throw new Error(
+      'No named sync targets are defined in project.yaml. Run "vibecompass connect-hosted --target <name>" to add one.',
+    );
+  }
+
+  const targetName = typeof options?.targetName === 'string' && options.targetName.trim() !== ''
+    ? options.targetName.trim()
+    : null;
+
+  if (!targetName) {
+    return {
+      rootDir,
+      projectFilePath,
+      changed: false,
+      defaultTarget: named.defaultTarget,
+      targets: named.targets,
+    };
+  }
+
+  if (!named.targets[targetName]) {
+    throw new Error(
+      `Unknown sync target "${targetName}". Available targets: ${Object.keys(named.targets).join(', ')}.`,
+    );
+  }
+
+  projectConfig.sync = buildSyncSectionWithTargets(named.targets, targetName);
+  await writeFile(projectFilePath, serializeProjectConfig(projectConfig), 'utf8');
+
+  // D-237: the flat manifest cursor mirrors the default target so ≤0.7.0 CLIs
+  // stay correct; re-mirror it from the new default (clearing it when the new
+  // default has no identity-matching cursor yet).
+  await updateManifestSyncState(rootDir, (manifestSync) =>
+    mirrorTargetCursorToFlat(manifestSync, targetName, {
+      apiUrl: named.targets[targetName].api_url,
+      projectId: named.targets[targetName].project_id,
+    }),
+  );
+
+  return {
+    rootDir,
+    projectFilePath,
+    changed: named.defaultTarget !== targetName,
+    defaultTarget: targetName,
+    targets: named.targets,
   };
 }
 

package/src/setup.js

@@ -139,6 +139,7 @@ export async function resolveConnectHostedCliOptions(options, environment = {})
 
   return {
     rootDir: resolved.rootDir ? toRelativeIfInsideCwd(resolved.rootDir, cwd) : undefined,
+    ...(resolved.targetName ? { targetName: resolved.targetName } : {}),
     sync: resolved.sync,
   };
 }

package/src/status.js

@@ -155,6 +155,20 @@ async function readProjectSummary(projectFilePath) {
             projectId: typeof config.sync.project_id === 'string' ? config.sync.project_id : null,
             credentialSource: typeof config.sync.credential_source === 'string' ? config.sync.credential_source : null,
             credentialEnvVar: typeof config.sync.credential_env_var === 'string' ? config.sync.credential_env_var : null,
+            defaultTarget:
+              typeof config.sync.default_target === 'string' ? config.sync.default_target : null,
+            targets:
+              config.sync.targets && typeof config.sync.targets === 'object'
+                ? Object.entries(config.sync.targets)
+                    .filter(([, target]) => target && typeof target === 'object')
+                    .map(([name, target]) => ({
+                      name,
+                      apiUrl: typeof target.api_url === 'string' ? target.api_url : null,
+                      projectId: typeof target.project_id === 'string' ? target.project_id : null,
+                      credentialEnvVar:
+                        typeof target.credential_env_var === 'string' ? target.credential_env_var : null,
+                    }))
+                : [],
           }
         : null,
     };

package/src/sync-binding.js

@@ -0,0 +1,307 @@
+const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+function normalizeBindingFields(source) {
+  const apiUrl = typeof source?.api_url === 'string' && source.api_url.trim() !== ''
+    ? source.api_url
+    : null;
+  const projectId = typeof source?.project_id === 'string' && source.project_id.trim() !== ''
+    ? source.project_id
+    : null;
+  const credentialEnvVar = typeof source?.credential_env_var === 'string' && source.credential_env_var.trim() !== ''
+    ? source.credential_env_var
+    : null;
+
+  if (!apiUrl || !projectId || !credentialEnvVar) {
+    return null;
+  }
+
+  return { apiUrl, projectId, credentialEnvVar };
+}
+
+export function assertValidSyncTargetName(name) {
+  if (typeof name !== 'string' || !TARGET_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Sync target name "${name}" is invalid. Use lowercase letters, digits, hyphens, or underscores (e.g. dev, prod).`,
+    );
+  }
+  return name;
+}
+
+export function readSyncTargets(projectConfig) {
+  const sync = projectConfig?.sync;
+  if (!sync || typeof sync !== 'object') {
+    return null;
+  }
+
+  const targets = sync.targets && typeof sync.targets === 'object' ? sync.targets : null;
+  if (!targets || Object.keys(targets).length === 0) {
+    return null;
+  }
+
+  const defaultTarget = typeof sync.default_target === 'string' && targets[sync.default_target]
+    ? sync.default_target
+    : null;
+
+  return { defaultTarget, targets };
+}
+
+/**
+ * Resolves the effective hosted sync binding for a command (D-236).
+ *
+ * Resolution order: explicit target name -> sync.default_target -> legacy
+ * flat sync fields. Returns null when no complete binding exists. Throws on
+ * an explicitly requested target that is unknown or incomplete, because a
+ * typo must never silently fall back to a different environment.
+ */
+export function resolveSyncBinding(projectConfig, targetName) {
+  const sync = projectConfig?.sync;
+  if (!sync || typeof sync !== 'object') {
+    if (targetName) {
+      throw new Error(
+        `--sync-target ${targetName} requires a sync section in project.yaml. Run "vibecompass connect-hosted --target ${targetName}" first.`,
+      );
+    }
+    return null;
+  }
+
+  const named = readSyncTargets(projectConfig);
+
+  if (targetName) {
+    const target = named?.targets?.[targetName];
+    if (!target || typeof target !== 'object') {
+      const available = named ? Object.keys(named.targets) : [];
+      throw new Error(
+        `Unknown sync target "${targetName}". ${
+          available.length > 0
+            ? `Available targets: ${available.join(', ')}.`
+            : 'No named sync targets are defined in project.yaml; run "vibecompass connect-hosted --target <name>" to add one.'
+        }`,
+      );
+    }
+
+    const fields = normalizeBindingFields(target);
+    if (!fields) {
+      throw new Error(
+        `Sync target "${targetName}" is incomplete. It must define api_url, project_id, and credential_env_var.`,
+      );
+    }
+
+    return { target: targetName, isDefault: targetName === named.defaultTarget, ...fields };
+  }
+
+  if (named?.defaultTarget) {
+    const fields = normalizeBindingFields(named.targets[named.defaultTarget]);
+    if (fields) {
+      return { target: named.defaultTarget, isDefault: true, ...fields };
+    }
+  }
+
+  const flat = normalizeBindingFields(sync);
+  return flat ? { target: null, isDefault: true, ...flat } : null;
+}
+
+const CURSOR_FIELDS = [
+  'last_successful_remote_revision',
+  'last_successful_local_root_revision',
+  'last_successful_manifest_hash',
+  'last_sync_direction',
+  'last_sync_at',
+  'pending_previews',
+];
+
+function pickCursorFields(source) {
+  const cursor = {};
+  for (const field of CURSOR_FIELDS) {
+    if (source?.[field] !== undefined) {
+      cursor[field] = source[field];
+    }
+  }
+  return cursor;
+}
+
+/**
+ * Reads the sync cursor for the resolved binding (D-237). Legacy flat
+ * bindings keep using the flat manifest.sync fields. Named targets read only
+ * their own cursor, and only when its recorded api_url/project_id identity
+ * matches the current binding — otherwise the cursor is treated as absent so
+ * a stale or cross-environment cursor can never become another environment's
+ * baseline.
+ */
+export function readSyncCursor(manifestSync, binding) {
+  if (!manifestSync || typeof manifestSync !== 'object') {
+    return {};
+  }
+
+  if (!binding?.target) {
+    return pickCursorFields(manifestSync);
+  }
+
+  const cursor = manifestSync.targets?.[binding.target];
+  if (
+    !cursor ||
+    typeof cursor !== 'object' ||
+    cursor.api_url !== binding.apiUrl ||
+    cursor.project_id !== binding.projectId
+  ) {
+    return {};
+  }
+
+  return pickCursorFields(cursor);
+}
+
+/**
+ * Builds the next manifest.sync value after a sync operation for the resolved
+ * binding (D-237). Named targets write into manifest.sync.targets.<name>
+ * (stamped with their api_url/project_id identity); when the binding is the
+ * default target, the flat fields mirror the same cursor so ≤0.7.0 CLIs stay
+ * correct on the default environment. Legacy flat bindings keep writing the
+ * flat fields only.
+ */
+export function buildSyncStateWithCursor(manifestSync, binding, cursor) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const cursorFields = pickCursorFields(cursor);
+
+  if (!binding?.target) {
+    return { ...existing, ...cursorFields };
+  }
+
+  const targets = {
+    ...(existing.targets && typeof existing.targets === 'object' ? existing.targets : {}),
+    [binding.target]: {
+      api_url: binding.apiUrl,
+      project_id: binding.projectId,
+      ...cursorFields,
+    },
+  };
+
+  return {
+    ...existing,
+    ...(binding.isDefault ? cursorFields : {}),
+    targets,
+  };
+}
+
+/**
+ * Migrates a legacy flat manifest cursor into a named target's cursor slot
+ * (D-237). Only applies when the new target's binding values match the flat
+ * binding the cursor was written against, the target has no cursor yet, and
+ * a flat cursor actually exists. Returns the next manifest.sync value, or
+ * null when nothing should change.
+ */
+export function migrateFlatCursorToTarget(manifestSync, targetName, bindingFields) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const targets = existing.targets && typeof existing.targets === 'object' ? existing.targets : {};
+  const flatCursor = pickCursorFields(existing);
+
+  if (targets[targetName] || Object.keys(flatCursor).length === 0) {
+    return null;
+  }
+
+  return {
+    ...existing,
+    targets: {
+      ...targets,
+      [targetName]: {
+        api_url: bindingFields.apiUrl,
+        project_id: bindingFields.projectId,
+        ...flatCursor,
+      },
+    },
+  };
+}
+
+/**
+ * Reconciles manifest cursor state after connect-hosted (re)binds a named
+ * target (D-237). Handles, in order:
+ * 1. first flat→named conversion with matching values: migrate the flat
+ *    cursor into the target's slot;
+ * 2. rebinding an existing target to a different api_url/project_id: drop its
+ *    now-wrong cursor;
+ * 3. when the (re)bound target is the default: re-mirror the flat cursor from
+ *    the target's identity-matching cursor, or clear it — so an older CLI can
+ *    never combine the new flat binding with a previous environment's cursor.
+ * Returns the next manifest.sync value, or null when nothing changes.
+ */
+export function reconcileCursorsAfterConnect(manifestSync, targetName, bindingFields, options = {}) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  let next = existing;
+  let changed = false;
+
+  if (options.isFirstConversion && options.flatBindingMatches) {
+    const migrated = migrateFlatCursorToTarget(next, targetName, bindingFields);
+    if (migrated) {
+      next = migrated;
+      changed = true;
+    }
+  }
+
+  const targetCursor = next.targets?.[targetName];
+  if (
+    targetCursor &&
+    typeof targetCursor === 'object' &&
+    (targetCursor.api_url !== bindingFields.apiUrl ||
+      targetCursor.project_id !== bindingFields.projectId)
+  ) {
+    const targets = { ...next.targets };
+    delete targets[targetName];
+    next = { ...next, targets };
+    changed = true;
+  }
+
+  if (options.isDefault) {
+    const mirrored = mirrorTargetCursorToFlat(next, targetName, bindingFields);
+    if (JSON.stringify(mirrored) !== JSON.stringify(next)) {
+      next = mirrored;
+      changed = true;
+    }
+  }
+
+  return changed ? next : null;
+}
+
+/**
+ * Re-mirrors the flat manifest cursor from a (new default) target's cursor
+ * (D-237). When the target has no identity-matching cursor, the flat cursor
+ * fields are cleared so an older CLI cannot reuse the previous default's
+ * cursor against the new default environment.
+ */
+export function mirrorTargetCursorToFlat(manifestSync, targetName, bindingFields) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const base = {};
+  for (const [key, value] of Object.entries(existing)) {
+    if (!CURSOR_FIELDS.includes(key)) {
+      base[key] = value;
+    }
+  }
+
+  const target = existing.targets?.[targetName];
+  const identityMatches =
+    target &&
+    typeof target === 'object' &&
+    target.api_url === bindingFields.apiUrl &&
+    target.project_id === bindingFields.projectId;
+
+  return identityMatches ? { ...base, ...pickCursorFields(target) } : base;
+}
+
+/**
+ * Builds the project.yaml sync section for a set of named targets. The flat
+ * fields always mirror the default target so older CLIs that only read the
+ * flat binding keep working against the default environment.
+ */
+export function buildSyncSectionWithTargets(targets, defaultTarget) {
+  const defaultFields = normalizeBindingFields(targets[defaultTarget]);
+  if (!defaultFields) {
+    throw new Error(`Default sync target "${defaultTarget}" is incomplete.`);
+  }
+
+  return {
+    provider: 'vibecompass',
+    api_url: defaultFields.apiUrl,
+    project_id: defaultFields.projectId,
+    credential_source: 'env',
+    credential_env_var: defaultFields.credentialEnvVar,
+    default_target: defaultTarget,
+    targets,
+  };
+}

package/src/sync.js

@@ -3,6 +3,11 @@ import path from 'node:path';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import {
+  buildSyncStateWithCursor,
+  readSyncCursor,
+  resolveSyncBinding,
+} from './sync-binding.js';
 
 const DEFAULT_EXPORT_PATH = 'state/pull-export.json';
 
@@ -14,7 +19,8 @@ export async function pushProjectMemory(options = {}, environment = {}) {
   });
   const manifest = manifestResult.manifest;
   const documents = await readPushDocuments(context.rootDir, manifest.documents);
-  const baseRemoteRevisionId = normalizeUuid(manifest.sync?.last_successful_remote_revision);
+  const cursor = readSyncCursor(manifest.sync, context.binding);
+  const baseRemoteRevisionId = normalizeUuid(cursor.last_successful_remote_revision);
   const body = {
     ...(baseRemoteRevisionId ? { base_remote_revision_id: baseRemoteRevisionId } : {}),
     local_root_revision: manifest.canonical.local_root_revision,
@@ -25,15 +31,15 @@ export async function pushProjectMemory(options = {}, environment = {}) {
 
   const response = await postJson(context, 'push', body);
   const now = new Date().toISOString();
-  const sync = {
-    ...(manifest.sync ?? {}),
+  const sync = buildSyncStateWithCursor(manifest.sync, context.binding, {
+    ...cursor,
     last_successful_remote_revision: response.remote_revision_id,
     last_successful_local_root_revision: manifest.canonical.local_root_revision,
     last_successful_manifest_hash: manifest.canonical.manifest_hash,
     last_sync_direction: 'push',
     last_sync_at: now,
     pending_previews: [],
-  };
+  });
   const updatedManifest = await writeStateManifest(context.rootDir, { sync });
 
   return {
@@ -55,10 +61,11 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
     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(manifest.sync?.last_successful_remote_revision),
+    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),
@@ -81,13 +88,13 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
     created_at: response.created_at ?? new Date().toISOString(),
     expires_at: response.expires_at,
   };
-  const sync = {
-    ...(manifest.sync ?? {}),
+  const sync = buildSyncStateWithCursor(manifest.sync, context.binding, {
+    ...cursor,
     pending_previews: [
-      ...(Array.isArray(manifest.sync?.pending_previews) ? manifest.sync.pending_previews : []),
+      ...(Array.isArray(cursor.pending_previews) ? cursor.pending_previews : []),
       previewRecord,
     ].slice(-5),
-  };
+  });
   const updatedManifest = await writeStateManifest(context.rootDir, { sync });
 
   return {
@@ -105,7 +112,7 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
 export async function pullExportProjectMemory(options = {}, environment = {}) {
   const context = await loadSyncContext(options, environment);
   const manifest = await readRequiredManifest(context.manifestPath);
-  const preview = resolvePreview(manifest, options.previewToken);
+  const preview = resolvePreview(manifest, options.previewToken, context.binding);
   const proposalIds = options.proposalIds?.length
     ? options.proposalIds
     : preview.available_proposal_ids ?? [];
@@ -200,18 +207,15 @@ async function loadSyncContext(options, environment) {
   if (project.mode !== 'local-primary') {
     throw new Error('Hosted sync commands require project.yaml mode: local-primary.');
   }
-  if (
-    !project.sync ||
-    typeof project.sync.api_url !== 'string' ||
-    typeof project.sync.project_id !== 'string' ||
-    typeof project.sync.credential_env_var !== 'string'
-  ) {
-    throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml.');
+
+  const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+  if (!binding) {
+    throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml (or a named target under sync.targets).');
   }
 
-  const credential = normalizeOptionalString((environment.env ?? process.env)[project.sync.credential_env_var]);
+  const credential = normalizeOptionalString((environment.env ?? process.env)[binding.credentialEnvVar]);
   if (!credential) {
-    throw new Error(`Hosted sync command requires ${project.sync.credential_env_var}.`);
+    throw new Error(`Hosted sync command requires ${binding.credentialEnvVar}.`);
   }
 
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
@@ -225,8 +229,10 @@ async function loadSyncContext(options, environment) {
     manifestPath,
     fetch: fetchImpl,
     credential,
-    apiUrl: project.sync.api_url,
-    projectId: project.sync.project_id,
+    apiUrl: binding.apiUrl,
+    projectId: binding.projectId,
+    syncTarget: binding.target,
+    binding,
   };
 }
 
@@ -308,9 +314,10 @@ function buildLocalDocumentExtractedSummary(kind, extracted = {}) {
   return {};
 }
 
-function resolvePreview(manifest, previewToken) {
-  const previews = Array.isArray(manifest.sync?.pending_previews)
-    ? manifest.sync.pending_previews
+function resolvePreview(manifest, previewToken, binding) {
+  const cursor = readSyncCursor(manifest.sync, binding);
+  const previews = Array.isArray(cursor.pending_previews)
+    ? cursor.pending_previews
     : [];
   if (previewToken) {
     const match = previews.find((preview) => preview.preview_token === previewToken);