@vibecompass/vibecompass 0.14.0 → 0.15.0

package/src/docs-review.js

@@ -19,6 +19,7 @@ import {
   writeDocsReviewSourceInventory,
 } from './source-inventory.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
+import { formatMissingCredentialError, resolveSyncCredential } from './credential-store.js';
 import { PACKAGE_VERSION } from './version.js';
 import { withMemoryRootLock } from './serialization.js';
 import { listDecisionFileNames, readNextDecisionId } from './decisions.js';
@@ -89,6 +90,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
       rootDir,
       statePath,
       env: environment.env ?? process.env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       fetch: environment.runtime?.fetch ?? globalThis.fetch,
     });
   }
@@ -137,6 +139,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
   const hosted = options.submitHosted
     ? await submitHostedDocsReview({
       env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       project,
       reviewConfig,
       reviewPrompt,
@@ -1588,9 +1591,20 @@ async function submitHostedDocsReview(options) {
     throw new Error('docs-review --submit-hosted requires sync.credential_env_var in project.yaml.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  // D-355: env override, then the local credential store.
+  const submitBinding = {
+    apiUrl: options.runtime.api_url,
+    projectId: options.runtime.project_id,
+    credentialEnvVar,
+    target: options.runtime.sync_target ?? null,
+  };
+  const submitResolution = await resolveSyncCredential(submitBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = submitResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --submit-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(submitBinding, { action: 'docs-review --submit-hosted', detail: submitResolution.detail }));
   }
 
   const endpoint = new URL(
@@ -1758,9 +1772,19 @@ async function pollHostedDocsReview(options) {
     throw new Error('docs-review --poll-hosted requires runtime.credential_env_var in state/docs-review.json.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  const pollBinding = {
+    apiUrl: runtime.api_url,
+    projectId: runtime.project_id,
+    credentialEnvVar,
+    target: runtime.sync_target ?? null,
+  };
+  const pollResolution = await resolveSyncCredential(pollBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = pollResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --poll-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(pollBinding, { action: 'docs-review --poll-hosted', detail: pollResolution.detail }));
   }
 
   const endpoint = new URL(

package/src/index.js

@@ -7,6 +7,16 @@ 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 { loginHosted } from './login.js';
+export {
+  describeCredentialSource,
+  formatMissingCredentialError,
+  listSyncCredentials,
+  removeSyncCredential,
+  resolveCredentialStoreDir,
+  resolveSyncCredential,
+  storeSyncCredential,
+} from './credential-store.js';
 export {
   adoptRemoteHead,
   applyPullExport,

package/src/login.js

@@ -0,0 +1,257 @@
+import { execFile as nodeExecFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { connectHostedProjectMemory } from './init.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
+import {
+  credentialStoreOptionsFrom,
+  normalizeApiUrl,
+  storeSyncCredential,
+} from './credential-store.js';
+import { PACKAGE_VERSION } from './version.js';
+
+/**
+ * Browser device-code sign-in for hosted sync (D-355).
+ *
+ * The CLI asks the hosted app for a device code, shows (and opens) the
+ * verification link plus a short user code, and polls until the signed-in
+ * project owner approves the code in the dashboard. The claim response is the
+ * only place the plaintext token ever exists: the CLI stores it in the local
+ * credential store and, when the root has no sync binding yet, writes the
+ * non-secret binding into project.yaml exactly as `connect-hosted` would.
+ */
+
+export const DEFAULT_HOSTED_API_URL = 'https://vibecompass.dev';
+export const DEFAULT_SYNC_CREDENTIAL_ENV_VAR = 'VIBECOMPASS_SYNC_TOKEN';
+export const DEVICE_AUTH_START_ROUTE = 'api/cli/device-auth';
+export const DEVICE_AUTH_TOKEN_ROUTE = 'api/cli/device-auth/token';
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 600;
+const REQUEST_TIMEOUT_MS = 15_000;
+const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
+
+export async function loginHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const io = environment.io ?? {};
+  const write = (text) => (io.stdout ?? process.stdout).write(text);
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('login requires a fetch implementation.');
+  }
+  const sleep = environment.runtime?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = environment.runtime?.now ?? (() => Date.now());
+
+  let project;
+  try {
+    project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), { sourceName: projectFilePath });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass init" first, then "vibecompass login".`);
+    }
+    throw error;
+  }
+  if (!VALID_MODES.has(project.mode)) {
+    throw new Error('login requires project.yaml mode to be local-only, local-primary, or hosted-only.');
+  }
+
+  const binding = resolveLoginBinding(project, options);
+  const apiUrl = binding?.apiUrl ?? options.apiUrl ?? DEFAULT_HOSTED_API_URL;
+  if (binding && options.apiUrl && normalizeApiUrl(options.apiUrl) !== normalizeApiUrl(binding.apiUrl)) {
+    throw new Error(
+      `--api-url ${options.apiUrl} does not match the bound hosted URL ${binding.apiUrl}${binding.target ? ` for target ${binding.target}` : ''}. `
+      + 'Pass --sync-target <name> to sign in to a different environment, or rebind with connect-hosted.',
+    );
+  }
+  const projectHint = binding?.projectId ?? options.projectId ?? null;
+  const credentialEnvVar = binding?.credentialEnvVar ?? options.credentialEnvVar ?? DEFAULT_SYNC_CREDENTIAL_ENV_VAR;
+
+  // Every network wait (start, each poll, and body reads) is bounded by the
+  // overall deadline so a stalled server can never outlive --poll-timeout.
+  const requestedTimeoutSeconds = positiveNumber(options.pollTimeoutSeconds, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let deadline = now() + requestedTimeoutSeconds * 1000;
+  const timing = { now, deadline: () => deadline };
+
+  const start = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_START_ROUTE, {
+    ...(projectHint ? { project_id: projectHint } : {}),
+    label: options.label ?? os.hostname(),
+    package_version: PACKAGE_VERSION,
+  }, timing);
+  if (!start.ok) {
+    throw new Error(`Hosted sign-in could not start (HTTP ${start.status}${start.body?.error ? `: ${start.body.error}` : ''}). Check the hosted URL ${apiUrl} and try again.`);
+  }
+  const deviceCode = requireString(start.body, 'device_code');
+  const userCode = requireString(start.body, 'user_code');
+  const verificationUri = requireString(start.body, 'verification_uri_complete', 'verification_uri');
+  const expiresIn = positiveNumber(start.body.expires_in, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let intervalMs = positiveNumber(start.body.interval, DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+
+  write('Sign in to VibeCompass\n');
+  write(`Open: ${verificationUri}\n`);
+  write(`Code: ${userCode}\n`);
+  if (!options.noBrowser) {
+    const opened = await openBrowser(verificationUri, environment);
+    write(opened ? 'Opening your browser…\n' : 'Could not open a browser automatically; paste the link into any browser.\n');
+  }
+  write(`Waiting for approval in the dashboard (expires in ${Math.round(expiresIn / 60)} minutes)…\n`);
+
+  deadline = Math.min(deadline, now() + expiresIn * 1000);
+  let claim = null;
+  while (!claim) {
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+    }
+    await sleep(Math.min(intervalMs, remaining));
+    const poll = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_TOKEN_ROUTE, { device_code: deviceCode }, timing);
+    if (poll.ok && poll.body?.status === 'approved') {
+      claim = poll.body;
+      break;
+    }
+    const code = typeof poll.body?.error === 'string' ? poll.body.error : null;
+    if (code === 'authorization_pending') {
+      continue;
+    }
+    if (code === 'slow_down') {
+      intervalMs += 5000;
+      continue;
+    }
+    if (code === 'expired_token') {
+      throw new Error('The sign-in code expired before it was approved. Run "vibecompass login" again.');
+    }
+    if (code === 'access_denied') {
+      throw new Error('The sign-in request was denied in the dashboard.');
+    }
+    throw new Error(`Hosted sign-in failed (HTTP ${poll.status}${code ? `: ${code}` : ''}).`);
+  }
+
+  const token = requireString(claim, 'token');
+  const approvedProject = claim.project && typeof claim.project === 'object' ? claim.project : {};
+  const projectId = requireString(approvedProject, 'id');
+  const projectName = typeof approvedProject.name === 'string' ? approvedProject.name : projectId;
+
+  const stored = await storeSyncCredential(
+    {
+      apiUrl,
+      projectId,
+      token,
+      label: `VibeCompass sync token (${projectName})`,
+      source: 'login',
+      backend: options.credentialStore,
+    },
+    credentialStoreOptionsFrom(environment),
+  );
+
+  const warnings = [];
+  let bindingWritten = null;
+  if (!binding) {
+    bindingWritten = await connectHostedProjectMemory({
+      cwd,
+      rootDir: options.rootDir ?? '.compass',
+      ...(options.syncTarget ? { targetName: options.syncTarget } : {}),
+      sync: { apiUrl, projectId, credentialEnvVar },
+    });
+  } else if (binding.projectId !== projectId) {
+    warnings.push(
+      `This root is bound to project ${binding.projectId}${binding.target ? ` (target ${binding.target})` : ''}, but you approved ${projectName} (${projectId}). `
+      + `The token is stored for the approved project; rebind with "vibecompass connect-hosted${binding.target ? ` --target ${binding.target}` : ''} --sync-api-url ${apiUrl} --sync-project-id ${projectId} --sync-credential-env-var ${credentialEnvVar}" if that was intended.`,
+    );
+  }
+
+  return {
+    apiUrl,
+    project: { id: projectId, name: projectName },
+    credential: claim.credential && typeof claim.credential === 'object' ? claim.credential : null,
+    stored,
+    binding: bindingWritten,
+    previousBinding: binding,
+    mode: bindingWritten?.mode ?? project.mode,
+    warnings,
+  };
+}
+
+function resolveLoginBinding(project, options) {
+  try {
+    return resolveSyncBinding(project, options.syncTarget ?? null);
+  } catch (error) {
+    // An unknown --sync-target may be created by login only when the caller
+    // is explicit about which hosted environment it points at (D-236: a typo
+    // must never silently land in another environment).
+    if (options.syncTarget && options.apiUrl) {
+      return null;
+    }
+    throw new Error(`${error.message} To create it through login, add --api-url <hosted url>.`);
+  }
+}
+
+async function postJson(fetchImpl, apiUrl, routeName, body, timing) {
+  const endpoint = new URL(routeName, apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`);
+  const remaining = timing ? timing.deadline() - timing.now() : REQUEST_TIMEOUT_MS;
+  if (remaining <= 0) {
+    throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.min(REQUEST_TIMEOUT_MS, remaining));
+  try {
+    let response;
+    try {
+      response = await fetchImpl(endpoint.href, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in request to ${endpoint.origin} timed out. Check the connection and run "vibecompass login" again.`);
+      }
+      throw new Error(`Could not reach ${endpoint.origin} (${error?.message ?? 'network error'}).`);
+    }
+    let parsed = null;
+    try {
+      parsed = typeof response.json === 'function' ? await response.json() : null;
+    } catch {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in response from ${endpoint.origin} stalled. Check the connection and run "vibecompass login" again.`);
+      }
+      parsed = null;
+    }
+    return { ok: Boolean(response.ok), status: response.status, body: parsed && typeof parsed === 'object' ? parsed : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function openBrowser(url, environment) {
+  const platform = environment.runtime?.platform ?? process.platform;
+  const execFileImpl = environment.runtime?.execFile ?? nodeExecFile;
+  const [file, args] = platform === 'darwin'
+    ? ['open', [url]]
+    : platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    try {
+      execFileImpl(file, args, { windowsHide: true }, (error) => resolve(!error));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function requireString(source, ...keys) {
+  for (const key of keys) {
+    const value = source?.[key];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return value.trim();
+    }
+  }
+  throw new Error(`Hosted sign-in response is missing ${keys[0]}.`);
+}
+
+function positiveNumber(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/src/mode-transition.js

@@ -2,6 +2,11 @@ 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 {
+  credentialStoreOptionsFrom,
+  formatMissingCredentialError,
+  resolveSyncCredential,
+} from './credential-store.js';
 import { withMemoryRootLock } from './serialization.js';
 import { adoptRemoteHead, pushProjectMemory } from './sync.js';
 
@@ -186,9 +191,10 @@ async function loadModeAgnosticSyncContext(rootDir, options, environment) {
   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();
+  const resolution = await resolveSyncCredential(binding, credentialStoreOptionsFrom(environment));
+  const credential = resolution.credential;
   if (!credential) {
-    throw new Error(`Mode transitions require ${binding.credentialEnvVar} to be set.`);
+    throw new Error(formatMissingCredentialError(binding, { action: 'This mode transition', detail: resolution.detail }));
   }
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== 'function') {

package/src/secret-prompt.js

@@ -0,0 +1,64 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+
+/**
+ * Hidden-input prompt for secrets (D-355). Typed characters are never echoed:
+ * readline runs in terminal mode against a muted output while the visible
+ * prompt text is written to the real stdout. A `runtime.prompt` adapter
+ * (tests, embedders) receives `{ type: 'password', message }` instead.
+ */
+export function canPromptSecret(io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return true;
+  }
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  return Boolean(input?.isTTY);
+}
+
+export async function promptSecret(message, io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return normalizeSecret(await runtime.prompt({ type: 'password', message }));
+  }
+
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  const output = io.stdout ?? process.stdout;
+  if (!input?.isTTY) {
+    throw new Error('Secret prompts require an interactive terminal. Pipe the value with --token-stdin instead.');
+  }
+
+  output.write(`${message}: `);
+  const muted = new Writable({
+    write(_chunk, _encoding, callback) {
+      callback();
+    },
+  });
+  const rl = createInterface({ input, output: muted, terminal: true });
+  try {
+    return normalizeSecret(await rl.question(''));
+  } finally {
+    rl.close();
+    output.write('\n');
+  }
+}
+
+/** Reads one secret from stdin: the first non-empty line, trimmed. */
+export async function readSecretFromStdin(io = {}, runtime = {}) {
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  if (typeof input?.setEncoding === 'function') {
+    input.setEncoding('utf8');
+  }
+  let data = '';
+  for await (const chunk of input) {
+    data += chunk;
+  }
+  const firstLine = data
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line !== '');
+  return firstLine ?? null;
+}
+
+function normalizeSecret(value) {
+  const trimmed = String(value ?? '').trim();
+  return trimmed === '' ? null : trimmed;
+}

package/src/status.js

@@ -5,6 +5,7 @@ import { sha256Text } from './hash.js';
 import { resolveLaneMarkerContext } from './lane-marker.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { resolveSyncBinding } from './sync-binding.js';
+import { describeCredentialSource, resolveSyncCredential } from './credential-store.js';
 import { inferToolingRootForMemoryRoot, listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -68,6 +69,7 @@ export async function getProjectStatus(options = {}) {
       docsReview,
       agentFiles,
       projectMemory,
+      hostedSync,
     }),
   };
 }
@@ -125,6 +127,7 @@ export function renderStatusText(status) {
       : status.hostedSync?.status === 'unreachable'
         ? [`Hosted mode check: unreachable (${status.hostedSync.detail}).`]
         : []),
+    ...formatHostedSyncLines(status.hostedSync),
     `Root: ${status.rootDir}`,
     `Repos: ${status.project.repos.length > 0 ? status.project.repos.map((repo) => repo.id).join(', ') : 'None recorded'}`,
     `Active lanes: ${formatActiveLanes(status.sessions)}`,
@@ -207,16 +210,36 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
   }
   if (!binding) return { status: 'not-configured' };
 
-  const env = options.env ?? process.env;
-  const credential = typeof env[binding.credentialEnvVar] === 'string'
-    ? env[binding.credentialEnvVar].trim()
-    : '';
+  const bindingSummary = {
+    apiUrl: binding.apiUrl,
+    projectId: binding.projectId,
+    target: binding.target ?? null,
+    credentialEnvVar: binding.credentialEnvVar,
+  };
+  // D-355: report only the source of the credential (env / keychain / file /
+  // missing), never its value.
+  const resolution = await resolveSyncCredential(binding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = resolution.credential;
+  const credentialSource = credential ? resolution.source : 'missing';
+  const credentialSourceLabel = credential ? describeCredentialSource(resolution) : 'missing';
   if (!credential) {
-    return { status: 'no-credential', credentialEnvVar: binding.credentialEnvVar };
+    return {
+      status: 'no-credential',
+      credentialEnvVar: binding.credentialEnvVar,
+      credentialSource,
+      credentialSourceLabel,
+      ...(resolution.detail ? { detail: resolution.detail } : {}),
+      binding: bindingSummary,
+    };
   }
 
   const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== 'function') return { status: 'not-configured' };
+  if (typeof fetchImpl !== 'function') {
+    return { status: 'not-configured', credentialSource, credentialSourceLabel, binding: bindingSummary };
+  }
 
   const baseUrl = binding.apiUrl.endsWith('/') ? binding.apiUrl : `${binding.apiUrl}/`;
   const endpoint = new URL(
@@ -234,7 +257,7 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
       signal: controller.signal,
     });
     if (!response.ok) {
-      return { status: 'unreachable', detail: `HTTP ${response.status}` };
+      return { status: 'unreachable', detail: `HTTP ${response.status}`, credentialSource, credentialSourceLabel, binding: bindingSummary };
     }
     const data = typeof response.json === 'function' ? await response.json() : {};
     const hostedMode = typeof data.mode === 'string' ? data.mode : null;
@@ -243,9 +266,12 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
       hostedMode,
       localMode,
       mismatch: Boolean(hostedMode && localMode && hostedMode !== localMode),
+      credentialSource,
+      credentialSourceLabel,
+      binding: bindingSummary,
     };
   } catch (error) {
-    return { status: 'unreachable', detail: error?.message ?? 'network error' };
+    return { status: 'unreachable', detail: error?.message ?? 'network error', credentialSource, credentialSourceLabel, binding: bindingSummary };
   } finally {
     clearTimeout(timer);
   }
@@ -460,13 +486,32 @@ async function readProjectMemoryStatus(rootDir) {
   }
 }
 
-function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles, projectMemory }) {
+function formatHostedSyncLines(hostedSync) {
+  if (!hostedSync?.binding) {
+    return [];
+  }
+  const { binding } = hostedSync;
+  const where = `${binding.apiUrl} (project ${binding.projectId}${binding.target ? `, target ${binding.target}` : ''})`;
+  const credential = hostedSync.credentialSource === 'missing'
+    ? `missing${hostedSync.detail ? ` (${hostedSync.detail})` : ''} — run \`vibecompass login\` to sign in from this terminal`
+    : hostedSync.credentialSourceLabel ?? hostedSync.credentialSource;
+  return [
+    `Hosted sync: ${where}`,
+    `Sync credential: ${credential}`,
+  ];
+}
+
+function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles, projectMemory, hostedSync }) {
   const recommendations = [];
   if (project.status === 'unreadable') {
     recommendations.push('vibecompass init --guided');
     return recommendations;
   }
 
+  if (hostedSync?.status === 'no-credential') {
+    recommendations.push('vibecompass login');
+  }
+
   const packageStatus = compatibility.package.status;
   const stateStatus = compatibility.state.status;
   if (['legacy', 'behind', 'ahead', 'invalid'].includes(packageStatus) || ['missing', 'unreadable', 'unsupported'].includes(stateStatus)) {

package/src/sync.js

@@ -4,6 +4,11 @@ import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { withMemoryRootLock } from './serialization.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import {
+  credentialStoreOptionsFrom,
+  formatMissingCredentialError,
+  resolveSyncCredential,
+} from './credential-store.js';
 import {
   buildSyncStateWithCursor,
   readSyncCursor,
@@ -465,12 +470,14 @@ async function loadSyncContext(options, environment) {
     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)[binding.credentialEnvVar]);
+  // D-355: env var override first, then the local credential store
+  // (keychain or per-user file). The resolved value is used only as the
+  // bearer credential and never written anywhere.
+  const resolution = await resolveSyncCredential(binding, credentialStoreOptionsFrom(environment));
+  const credential = resolution.credential;
   if (!credential) {
     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.',
+      formatMissingCredentialError(binding, { action: 'This hosted sync command', detail: resolution.detail }),
     );
   }
 
@@ -485,6 +492,7 @@ async function loadSyncContext(options, environment) {
     manifestPath,
     fetch: fetchImpl,
     credential,
+    credentialSource: resolution.source,
     apiUrl: binding.apiUrl,
     projectId: binding.projectId,
     syncTarget: binding.target,