@vibecompass/vibecompass 0.3.0 → 0.3.3

package/src/docs-review.js

@@ -1,7 +1,8 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { parseFrontmatter } from './frontmatter.js';
+import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 export async function preflightDocsReview(options = {}, environment = {}) {
@@ -20,6 +21,15 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     });
   }
 
+  if (options.applyDecisionArtifact) {
+    return applyDecisionArtifact({
+      rootDir,
+      statePath,
+      artifactId: options.artifactId,
+      refreshIndex: options.refreshIndex,
+    });
+  }
+
   if (options.complete) {
     return completeDocsReview({
       rootDir,
@@ -29,6 +39,15 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     });
   }
 
+  if (options.pollHosted) {
+    return pollHostedDocsReview({
+      rootDir,
+      statePath,
+      env: environment.env ?? process.env,
+      fetch: environment.runtime?.fetch ?? globalThis.fetch,
+    });
+  }
+
   const projectFilePath = path.join(rootDir, 'project.yaml');
   const project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
     sourceName: projectFilePath,
@@ -63,6 +82,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
       reviewPrompt,
       rootDir,
       runtime,
+      manifest: await writeStateManifest(rootDir),
       fetch: environment.runtime?.fetch ?? globalThis.fetch,
     })
     : null;
@@ -144,6 +164,7 @@ async function completeDocsReview(options) {
     runtime: current.runtime ?? null,
     hosted: current.hosted ?? null,
     applied: current.applied ?? null,
+    appliedDecisionArtifact: current.applied_decision_artifact ?? null,
     reviewPrompt: null,
     warnings: [],
     message: 'Docs-review marker completed. Future start-session warnings can treat this root as reviewed.',
@@ -209,6 +230,104 @@ async function applyDocsReviewOutput(options) {
   };
 }
 
+async function applyDecisionArtifact(options) {
+  const current = await readDocsReviewMarker(options.statePath);
+  const artifactId = normalizeOptionalString(options.artifactId);
+  if (!artifactId) {
+    throw new Error('docs-review --apply-decision-artifact requires --artifact <artifact-id>.');
+  }
+
+  const artifact = (current.hosted?.artifacts ?? []).find(
+    (item) => item?.artifact_id === artifactId,
+  );
+  if (!artifact) {
+    throw new Error(`Decision artifact ${artifactId} was not found in ${options.statePath}. Run docs-review --poll-hosted first.`);
+  }
+  if (artifact.artifact_type !== 'decision_recommendation') {
+    throw new Error(`Artifact ${artifactId} is ${artifact.artifact_type}, not decision_recommendation.`);
+  }
+
+  const content = artifact.content ?? {};
+  const targetPath = normalizeDecisionTargetPath(
+    content.target_path ?? artifact.target_path ?? 'decisions/cross-cutting.md',
+  );
+  const title = normalizeOptionalString(content.title ?? artifact.title);
+  const decision = normalizeOptionalString(content.decision ?? artifact.summary);
+  const rationale = normalizeOptionalString(content.rationale);
+  const context = normalizeOptionalString(content.context);
+
+  if (!title || !decision) {
+    throw new Error(`Decision artifact ${artifactId} must include title and decision content.`);
+  }
+  if (!rationale) {
+    throw new Error(`Decision artifact ${artifactId} must include a non-empty rationale before it can be appended locally.`);
+  }
+
+  const nextDecisionId = await readNextDecisionId(options.rootDir);
+  const targetFilePath = path.join(options.rootDir, targetPath);
+  await mkdir(path.dirname(targetFilePath), { recursive: true });
+
+  let existingContent = '';
+  try {
+    existingContent = await readFile(targetFilePath, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    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)
+    : {
+      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,
+    target_path: targetPath,
+    applied_at: new Date().toISOString(),
+    refreshed_index: indexResult.refreshed,
+  };
+  await writeDocsReviewMarker(options.statePath, {
+    ...current,
+    applied_decision_artifact: appliedDecisionArtifact,
+    hosted: {
+      ...current.hosted,
+      artifacts: (current.hosted?.artifacts ?? []).map((item) =>
+        item?.artifact_id === artifactId
+          ? { ...item, local_status: 'applied', local_decision_id: nextDecisionId }
+          : item,
+      ),
+    },
+  });
+
+  return {
+    rootDir: options.rootDir,
+    statePath: options.statePath,
+    status: current.status ?? 'hosted-review-completed',
+    llm: current.llm ?? null,
+    model: current.model ?? null,
+    runtime: current.runtime ?? null,
+    hosted: current.hosted ?? null,
+    appliedDecisionArtifact,
+    reviewPrompt: null,
+    warnings: indexResult.warnings,
+    message: `Applied decision artifact ${artifactId} as D-${String(nextDecisionId).padStart(3, '0')} in ${targetPath}.`,
+  };
+}
+
 async function readDocsReviewMarker(statePath) {
   try {
     return JSON.parse(await readFile(statePath, 'utf8'));
@@ -224,9 +343,11 @@ async function readDocsReviewMarker(statePath) {
 function validateDocsReviewMode(options) {
   const enabled = [
     options.submitHosted ? '--submit-hosted' : null,
+    options.pollHosted ? '--poll-hosted' : null,
     options.runLocal ? '--run-local' : null,
     options.runLocalAnthropic ? '--run-local-anthropic' : null,
     options.applyOutput ? '--apply-output' : null,
+    options.applyDecisionArtifact ? '--apply-decision-artifact' : null,
     options.complete ? '--complete' : null,
   ].filter(Boolean);
 
@@ -534,6 +655,9 @@ async function submitHostedDocsReview(options) {
     `api/sync/projects/${encodeURIComponent(options.runtime.project_id)}/docs-review`,
     ensureTrailingSlash(options.runtime.api_url),
   );
+  const baselineRemoteRevisionId = normalizeUuid(
+    options.manifest?.manifest?.sync?.last_successful_remote_revision,
+  );
   const response = await options.fetch(endpoint.href, {
     method: 'POST',
     headers: {
@@ -550,11 +674,28 @@ async function submitHostedDocsReview(options) {
         mode: options.project.mode,
         repos: Array.isArray(options.project.repos) ? options.project.repos : [],
       },
+      ...(baselineRemoteRevisionId
+        ? { baseline_remote_revision_id: baselineRemoteRevisionId }
+        : {}),
+      local_root_revision: options.manifest?.manifest?.canonical?.local_root_revision,
+      evidence_scope: {
+        manifest_hash: options.manifest?.manifest?.canonical?.manifest_hash,
+        document_count: options.manifest?.manifest?.canonical?.document_count,
+        warning_count: options.manifest?.manifest?.canonical?.warning_count,
+      },
     }),
   });
 
   if (!response.ok) {
     const body = typeof response.text === 'function' ? await response.text() : '';
+    const details = parseJsonObject(body);
+    if (details?.error) {
+      const nextStep = details.next_step ? ` Next step: ${details.next_step}` : '';
+      throw new Error(
+        `Hosted docs-review request failed with ${response.status}: ${details.error}${nextStep}`,
+      );
+    }
+
     throw new Error(`Hosted docs-review request failed with ${response.status}${body ? `: ${body}` : ''}`);
   }
 
@@ -569,6 +710,116 @@ async function submitHostedDocsReview(options) {
     endpoint: endpoint.href,
     run_id: runId,
     status: normalizeOptionalString(body.status) ?? 'accepted',
+    phase: normalizeOptionalString(body.phase),
+  };
+}
+
+function parseJsonObject(value) {
+  if (!value) return null;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function pollHostedDocsReview(options) {
+  const marker = await readDocsReviewMarker(options.statePath);
+  const runtime = marker.runtime;
+  const hosted = marker.hosted;
+
+  if (runtime?.provider !== 'hosted' || !runtime.api_url || !runtime.project_id) {
+    throw new Error('docs-review --poll-hosted requires a hosted docs-review marker.');
+  }
+
+  const runId = normalizeOptionalString(hosted?.run_id);
+  if (!runId) {
+    throw new Error('docs-review --poll-hosted requires hosted.run_id in state/docs-review.json.');
+  }
+
+  const credentialEnvVar = runtime.credential_env_var;
+  if (!credentialEnvVar) {
+    throw new Error('docs-review --poll-hosted requires runtime.credential_env_var in state/docs-review.json.');
+  }
+
+  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  if (!credential) {
+    throw new Error(`docs-review --poll-hosted requires ${credentialEnvVar}.`);
+  }
+
+  const endpoint = new URL(
+    `api/sync/projects/${encodeURIComponent(runtime.project_id)}/runs/${encodeURIComponent(runId)}`,
+    ensureTrailingSlash(runtime.api_url),
+  );
+  const response = await options.fetch(endpoint.href, {
+    method: 'GET',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${credential}`,
+    },
+  });
+
+  if (!response.ok) {
+    const body = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted docs-review poll failed with ${response.status}${body ? `: ${body}` : ''}`);
+  }
+
+  const body = typeof response.json === 'function' ? await response.json() : {};
+  const {
+    phase: _oldPhase,
+    prompt_version: _oldPromptVersion,
+    parser_version: _oldParserVersion,
+    proposal_ids: _oldProposalIds,
+    artifact_ids: _oldArtifactIds,
+    artifacts: _oldArtifacts,
+    warnings: _oldWarnings,
+    error_code: _oldErrorCode,
+    error_message: _oldErrorMessage,
+    ...hostedBase
+  } = hosted;
+  const hostedStatus = normalizeOptionalString(body.status) ?? hosted.status ?? 'accepted';
+  const hostedErrorMessage = normalizeOptionalString(body.error_message);
+  const updatedHosted = {
+    ...hostedBase,
+    endpoint: hosted.endpoint,
+    run_id: runId,
+    status: hostedStatus,
+    ...(normalizeOptionalString(body.phase) ? { phase: normalizeOptionalString(body.phase) } : {}),
+    ...(normalizeOptionalString(body.prompt_version) ? { prompt_version: normalizeOptionalString(body.prompt_version) } : {}),
+    ...(normalizeOptionalString(body.parser_version) ? { parser_version: normalizeOptionalString(body.parser_version) } : {}),
+    ...(Array.isArray(body.proposal_ids) ? { proposal_ids: body.proposal_ids } : {}),
+    ...(Array.isArray(body.artifact_ids) ? { artifact_ids: body.artifact_ids } : {}),
+    ...(Array.isArray(body.artifacts) ? { artifacts: body.artifacts } : {}),
+    ...(Array.isArray(body.warnings) ? { warnings: body.warnings } : {}),
+    ...(normalizeOptionalString(body.error_code) ? { error_code: normalizeOptionalString(body.error_code) } : {}),
+    ...(hostedErrorMessage ? { error_message: hostedErrorMessage } : {}),
+  };
+  const markerStatus = markerStatusForHostedRunStatus(hostedStatus);
+  const message = hostedStatus === 'failed' && hostedErrorMessage
+    ? `Hosted docs-review run ${runId} is failed: ${hostedErrorMessage}`
+    : `Hosted docs-review run ${runId} is ${updatedHosted.status}.`;
+
+  const updatedMarker = {
+    ...marker,
+    status: markerStatus,
+    hosted: updatedHosted,
+  };
+  await writeDocsReviewMarker(options.statePath, updatedMarker);
+
+  return {
+    rootDir: options.rootDir,
+    statePath: options.statePath,
+    status: markerStatus,
+    llm: marker.llm ?? null,
+    model: marker.model ?? null,
+    runtime,
+    hosted: updatedHosted,
+    reviewPrompt: null,
+    warnings: (updatedHosted.warnings ?? []).map((warning) =>
+      warning?.message ? `${warning.code ?? 'hosted_warning'}: ${warning.message}` : String(warning),
+    ),
+    message,
   };
 }
 
@@ -595,6 +846,162 @@ function normalizeOptionalString(value) {
   return trimmed ? trimmed : null;
 }
 
+function normalizeUuid(value) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return null;
+  }
+
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(normalized)
+    ? normalized
+    : null;
+}
+
+function normalizeDecisionTargetPath(value) {
+  const normalized = normalizeBlockPath(value);
+  if (
+    !normalized.startsWith('decisions/') ||
+    !normalized.endsWith('.md') ||
+    normalized.split('/').length !== 2 ||
+    normalized.split('/').some((part) => part === '..' || part === '') ||
+    ['decisions/INDEX.md', 'decisions/README.md', 'decisions/EXAMPLE.md'].includes(normalized)
+  ) {
+    throw new Error(`Decision artifact target must be a decisions/*.md domain file. Invalid path: ${value}`);
+  }
+
+  return normalized;
+}
+
+async function readNextDecisionId(rootDir) {
+  const decisionsDir = path.join(rootDir, 'decisions');
+  let max = 0;
+
+  for (const fileName of await listDecisionFileNames(decisionsDir)) {
+    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
+    for (const match of content.matchAll(/^###\s+D-(\d+)\b/gm)) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+
+  return max + 1;
+}
+
+async function listDecisionFileNames(decisionsDir) {
+  try {
+    return (await readdir(decisionsDir))
+      .filter((fileName) =>
+        fileName.endsWith('.md') &&
+        !['INDEX.md', 'README.md', 'EXAMPLE.md'].includes(fileName),
+      )
+      .sort((left, right) => left.localeCompare(right));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+function renderDecisionEntry(options) {
+  const decisionNumber = `D-${String(options.decisionId).padStart(3, '0')}`;
+  return [
+    `### ${decisionNumber} — ${options.title}`,
+    '',
+    `**Timestamp:** ${formatDecisionTimestamp(new Date())}`,
+    `**Decision:** ${options.decision}`,
+    `**Rationale:** ${options.rationale}`,
+    ...(options.context ? [`**Context:** ${options.context}`] : []),
+    '',
+  ].join('\n');
+}
+
+function formatDecisionTimestamp(date) {
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absoluteOffset = Math.abs(offsetMinutes);
+  const offsetHours = String(Math.floor(absoluteOffset / 60)).padStart(2, '0');
+  const offsetRemainder = String(absoluteOffset % 60).padStart(2, '0');
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, '0');
+  const dd = String(date.getDate()).padStart(2, '0');
+  const hh = String(date.getHours()).padStart(2, '0');
+  const min = String(date.getMinutes()).padStart(2, '0');
+
+  return `${yyyy}-${mm}-${dd} ${hh}:${min} ${formatTimeZoneAbbreviation(date) ?? `UTC${sign}${offsetHours}:${offsetRemainder}`}`;
+}
+
+function formatTimeZoneAbbreviation(date) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZoneName: 'short',
+    }).formatToParts(date);
+    const zone = parts.find((part) => part.type === 'timeZoneName')?.value;
+    return zone && !/^GMT[+-]/.test(zone) ? zone : null;
+  } catch {
+    return null;
+  }
+}
+
+async function refreshDecisionIndex(rootDir) {
+  const decisionsDir = path.join(rootDir, 'decisions');
+  const indexPath = path.join(decisionsDir, 'INDEX.md');
+  const warnings = [];
+  const rows = [];
+
+  for (const fileName of await listDecisionFileNames(decisionsDir)) {
+    const relativePath = `decisions/${fileName}`;
+    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
+    for (const match of content.matchAll(/^###\s+D-(\d+)\s+—\s+(.+)$/gm)) {
+      rows.push({
+        id: Number(match[1]),
+        title: match[2].trim(),
+        domainFile: fileName,
+      });
+    }
+    if (!content.match(/^###\s+D-(\d+)\s+—\s+(.+)$/m)) {
+      warnings.push(`No indexable decisions found in ${relativePath}.`);
+    }
+  }
+
+  rows.sort((left, right) => left.id - right.id);
+  await mkdir(decisionsDir, { recursive: true });
+  await writeFile(indexPath, renderDecisionIndex(rows), 'utf8');
+  return { refreshed: true, warnings };
+}
+
+function renderDecisionIndex(rows) {
+  return [
+    '# Decision Index',
+    '',
+    'All decisions in chronological order. Each entry links to its domain file.',
+    '',
+    '> **Rule:** Decisions are append-only — never modify existing entries.',
+    '',
+    '| # | Decision | Domain |',
+    '|---|----------|--------|',
+    ...rows.map((row) => {
+      const decisionNumber = `D-${String(row.id).padStart(3, '0')}`;
+      const domain = path.basename(row.domainFile, '.md');
+      return `| ${decisionNumber} | ${row.title} | [${domain}](${row.domainFile}) |`;
+    }),
+    '',
+  ].join('\n');
+}
+
+function markerStatusForHostedRunStatus(status) {
+  if (status === 'completed') {
+    return 'hosted-review-completed';
+  }
+
+  if (status === 'failed') {
+    return 'hosted-review-failed';
+  }
+
+  if (status === 'needs_rebase') {
+    return 'hosted-review-needs-rebase';
+  }
+
+  return 'hosted-review-requested';
+}
+
 function normalizeMaxTokens(value) {
   if (value === undefined || value === null) {
     return 16000;

package/src/index.js

@@ -1,6 +1,12 @@
 export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
+export {
+  applyPullExport,
+  pullExportProjectMemory,
+  pullPreviewProjectMemory,
+  pushProjectMemory,
+} from './sync.js';
 export { scanProjectMemory } from './project-memory.js';
 export {
   closeProjectSession,

package/src/init.js

@@ -5,6 +5,7 @@ import { writeStateManifest } from './manifest.js';
 import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
+import { parseSimpleYaml } from './simple-yaml.js';
 
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
 
@@ -41,6 +42,39 @@ export async function initializeProjectMemory(options) {
   };
 }
 
+export async function connectHostedProjectMemory(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');
+  let projectConfig;
+  try {
+    projectConfig = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass init" first.`);
+    }
+
+    throw error;
+  }
+
+  if (!['local-primary', 'hosted-only'].includes(projectConfig.mode)) {
+    throw new Error('connect-hosted requires project.yaml mode to be local-primary or hosted-only.');
+  }
+
+  const sync = normalizeSyncOptions(options?.sync, projectConfig.mode);
+  projectConfig.sync = sync;
+  await writeFile(projectFilePath, serializeProjectConfig(projectConfig), 'utf8');
+
+  return {
+    rootDir,
+    projectFilePath,
+    mode: projectConfig.mode,
+    syncEnvVar: sync.credential_env_var,
+  };
+}
+
 function normalizeInitOptions(options) {
   if (!options || typeof options !== 'object') {
     throw new Error('initializeProjectMemory requires an options object.');
@@ -91,30 +125,9 @@ function normalizeInitOptions(options) {
     };
   });
 
-  const syncOptions = preparedOptions.sync ?? null;
-  let sync = undefined;
-  if (syncOptions) {
-    if (preparedOptions.mode !== 'local-primary') {
-      throw new Error('sync configuration is only supported when mode is local-primary.');
-    }
-
-    const requiredFields = ['apiUrl', 'projectId', 'credentialEnvVar'];
-    const missing = requiredFields.filter((field) => typeof syncOptions[field] !== 'string' || syncOptions[field].trim() === '');
-
-    if (missing.length > 0) {
-      throw new Error(
-        `sync configuration is incomplete. Missing: ${missing.join(', ')}.`,
-      );
-    }
-
-    sync = {
-      provider: 'vibecompass',
-      api_url: syncOptions.apiUrl,
-      project_id: syncOptions.projectId,
-      credential_source: 'env',
-      credential_env_var: syncOptions.credentialEnvVar,
-    };
-  }
+  const sync = preparedOptions.sync
+    ? normalizeSyncOptions(preparedOptions.sync, preparedOptions.mode)
+    : undefined;
 
   const projectConfig = {
     format_version: 1,
@@ -149,6 +162,33 @@ function normalizeInitOptions(options) {
   };
 }
 
+function normalizeSyncOptions(syncOptions, mode) {
+  if (!syncOptions || typeof syncOptions !== 'object') {
+    throw new Error('sync configuration must be an object.');
+  }
+
+  if (!['local-primary', 'hosted-only'].includes(mode)) {
+    throw new Error('sync configuration is only supported when mode is local-primary or hosted-only.');
+  }
+
+  const requiredFields = ['apiUrl', 'projectId', 'credentialEnvVar'];
+  const missing = requiredFields.filter((field) => typeof syncOptions[field] !== 'string' || syncOptions[field].trim() === '');
+
+  if (missing.length > 0) {
+    throw new Error(
+      `sync configuration is incomplete. Missing: ${missing.join(', ')}.`,
+    );
+  }
+
+  return {
+    provider: 'vibecompass',
+    api_url: syncOptions.apiUrl,
+    project_id: syncOptions.projectId,
+    credential_source: 'env',
+    credential_env_var: syncOptions.credentialEnvVar,
+  };
+}
+
 function buildAgentFilesMetadata(metadata) {
   const existingAgentFiles = metadata?.agent_files && typeof metadata.agent_files === 'object'
     ? metadata.agent_files

package/src/manifest.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -59,8 +59,12 @@ export function generateStateManifest(scanResult, options = {}) {
 export async function writeStateManifest(rootDir, options = {}) {
   const scanResult = await scanProjectMemory(rootDir);
   const activeSessions = await readActiveSessionsForManifest(rootDir);
+  const existingSync = Object.hasOwn(options, 'sync')
+    ? options.sync
+    : await readExistingSyncState(rootDir);
   const manifest = generateStateManifest(scanResult, {
     ...options,
+    ...(existingSync ? { sync: existingSync } : {}),
     ...(activeSessions ? { activeSessions } : {}),
   });
   const stateDir = path.join(rootDir, 'state');
@@ -76,6 +80,19 @@ export async function writeStateManifest(rootDir, options = {}) {
   };
 }
 
+async function readExistingSyncState(rootDir) {
+  try {
+    const existing = JSON.parse(
+      await readFile(path.join(rootDir, 'state', 'manifest.json'), 'utf8'),
+    );
+    return existing?.sync && typeof existing.sync === 'object'
+      ? existing.sync
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 async function readActiveSessionsForManifest(rootDir) {
   const sessions = await listProjectSessions({ rootDir });
   if (sessions.lanes.length === 0 && !sessions.current) {