draftgo-cli 3.0.48 → 3.0.49

package/src/commands/verifyUi.js

@@ -5,6 +5,10 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { configPath, loadProjectConfig } = require('../projectConfig');
+const { loadManifest, getEntry } = require('../worktree/manifest');
+const { canonicalResourceType } = require('../worktree/types');
+const { resolveMetadata } = require('../worktree/backend');
+const { inspectEntry, openMetadataSession } = require('../worktree/status');
 
 const UI_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte']);
 
@@ -77,6 +81,7 @@ function redactUrlTokens(message) {
 }
 
 function executableCandidates() {
+  const explicit = process.env.DRAFTGO_BROWSER_PATH ? [process.env.DRAFTGO_BROWSER_PATH] : [];
   if (process.platform === 'win32') {
     const roots = [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean);
     const rels = [
@@ -84,23 +89,47 @@ function executableCandidates() {
       ['Google', 'Chrome', 'Application', 'chrome.exe'],
       ['Chromium', 'Application', 'chrome.exe'],
     ];
-    return roots.flatMap((root) => rels.map((parts) => path.join(root, ...parts)));
+    return [...explicit, ...roots.flatMap((root) => rels.map((parts) => path.join(root, ...parts)))];
   }
   if (process.platform === 'darwin') {
-    return [
+    return [...explicit,
       '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
       '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
       '/Applications/Chromium.app/Contents/MacOS/Chromium',
     ];
   }
-  return ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+  return [...explicit, '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
 }
 
-async function launchBrowser(chromium, requested) {
+function playwrightCacheCandidates() {
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH
+    || (process.platform === 'win32'
+      ? path.join(process.env.LOCALAPPDATA || '', 'ms-playwright')
+      : path.join(process.env.HOME || '', '.cache', 'ms-playwright'));
+  if (!root || !fs.existsSync(root)) return [];
+  const candidates = [];
+  const visit = (directory, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isFile() && /^(?:chrome(?:-headless-shell)?|chromium|msedge|headless_shell)(?:\.exe)?$/i.test(entry.name)) candidates.push(absolute);
+      else if (entry.isDirectory()) visit(absolute, depth + 1);
+    }
+  };
+  visit(root, 0);
+  return candidates;
+}
+
+async function launchBrowser(chromium, requested, requestedPath) {
   const attempts = [];
+  if (requestedPath) attempts.push({ executablePath: requestedPath, label: `path:${requestedPath}` });
   if (requested && requested !== 'chromium') attempts.push({ channel: requested });
-  for (const executablePath of executableCandidates().filter((candidate) => fs.existsSync(candidate))) {
-    attempts.push({ executablePath });
+  for (const executablePath of [...executableCandidates(), ...playwrightCacheCandidates()].filter((candidate) => fs.existsSync(candidate))) {
+    if (!attempts.some((attempt) => attempt.executablePath === executablePath)) {
+      attempts.push({ executablePath, label: `path:${executablePath}` });
+    }
   }
   if (!requested || requested === 'chromium') attempts.push({});
   for (const channel of ['msedge', 'chrome']) {
@@ -108,14 +137,42 @@ async function launchBrowser(chromium, requested) {
   }
 
   let lastError = null;
+  const attempted = [];
   for (const options of attempts) {
     try {
-      return await chromium.launch({ headless: true, ...options });
+      const { label, ...launchOptions } = options;
+      const browser = await chromium.launch({ headless: true, ...launchOptions });
+      return { browser, selected: label || options.channel || 'playwright-managed', attempted };
     } catch (err) {
       lastError = err;
+      attempted.push(`${options.label || options.channel || 'playwright-managed'}: ${String(err.message || err).split('\n')[0]}`);
     }
   }
-  throw new Error(`未找到可用的 Chromium/Chrome/Edge。${lastError ? ` ${lastError.message.split('\n')[0]}` : ''}`);
+  throw new Error(`未找到可用的 Chromium/Chrome/Edge。请使用 --browser-path <executable> 或 DRAFTGO_BROWSER_PATH。`
+    + `尝试记录：${attempted.join('; ')}`
+    + (lastError ? `；最后错误：${lastError.message.split('\n')[0]}` : ''));
+}
+
+function parseResourceSpec(value) {
+  const raw = String(value || '');
+  const separator = raw.indexOf(':');
+  if (separator <= 0 || separator === raw.length - 1) {
+    throw new Error('--resource 格式必须是 <pages|nav|docs>:<id>。');
+  }
+  return { resourceType: canonicalResourceType(raw.slice(0, separator)), resourceId: raw.slice(separator + 1) };
+}
+
+async function verifyRemoteResource(projectDir, spec) {
+  const { resourceType, resourceId } = parseResourceSpec(spec);
+  const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
+  if (!entry) throw new Error(`${resourceType} ${resourceId} 未 checkout。`);
+  const config = loadProjectConfig(projectDir);
+  const session = await openMetadataSession(config);
+  const remote = await resolveMetadata(config, resourceType, resourceId, {
+    ...session,
+    clientInitialized: true,
+  });
+  return inspectEntry(projectDir, entry, remote);
 }
 
 async function verifyUi(projectDir, positional, flags = {}) {
@@ -136,7 +193,9 @@ async function verifyUi(projectDir, positional, flags = {}) {
     log.err('--mobile-check 只支持 auto、always、never。');
     return 1;
   }
-  const decision = decideMobileCheck(projectDir, mode);
+  const decision = flags.resource
+    ? { run: true, reason: `resource=${flags.resource}` }
+    : decideMobileCheck(projectDir, mode);
   if (!decision.run) {
     log.ok(`跳过 UI smoke check：${decision.reason}`);
     return 0;
@@ -169,7 +228,26 @@ async function verifyUi(projectDir, positional, flags = {}) {
 
   let browser;
   try {
-    browser = await launchBrowser(chromium, flags.browser && String(flags.browser));
+    if (flags.resource) {
+      const resource = await verifyRemoteResource(projectDir, flags.resource);
+      log.info(`UI source: remote committed ${resource.resource_type} ${resource.resource_id}`);
+      log.info(`Remote version: ${resource.remote_version || '-'}; remote hash: ${resource.remote_hash || '-'}`);
+      if (['local_modified', 'diverged'].includes(resource.state)) {
+        log.warn(`Local worktree is not committed (${resource.state}); verify-ui will test the remote version.`);
+      }
+      if (!resource.local_matches_remote && resource.state !== 'local_modified') {
+        throw new Error(`Local and remote content differ (${resource.state}); UI verification stopped.`);
+      }
+    } else {
+      log.info('UI source: remote URL response; no local worktree version was asserted.');
+    }
+    const launch = await launchBrowser(
+      chromium,
+      flags.browser && String(flags.browser),
+      flags['browser-path'] && String(flags['browser-path']),
+    );
+    browser = launch.browser;
+    log.info(`Browser: ${launch.selected}`);
     const page = await browser.newPage({ viewport: { width, height } });
     const consoleErrors = [];
     const pageErrors = [];
@@ -240,3 +318,7 @@ module.exports.gitChangedFiles = gitChangedFiles;
 module.exports.isUiFile = isUiFile;
 module.exports.configuredUiUrl = configuredUiUrl;
 module.exports.redactUrlTokens = redactUrlTokens;
+module.exports.executableCandidates = executableCandidates;
+module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
+module.exports.parseResourceSpec = parseResourceSpec;
+module.exports.verifyRemoteResource = verifyRemoteResource;

package/src/mcp/client.js

@@ -225,16 +225,30 @@ class DraftGoMcpClient {
   }
 
   async initialize(options = {}) {
-    const result = await this.request('initialize', {
-      protocolVersion: options.protocolVersion || this.protocolVersion,
-      capabilities: options.capabilities || {},
-      clientInfo: options.clientInfo || {
-        name: 'draftgo-cli',
-        version: pkg.version,
-      },
-    }, options);
+    if (typeof options.onStage === 'function') options.onStage('initialize', 'started');
+    let result;
+    try {
+      result = await this.request('initialize', {
+        protocolVersion: options.protocolVersion || this.protocolVersion,
+        capabilities: options.capabilities || {},
+        clientInfo: options.clientInfo || {
+          name: 'draftgo-cli',
+          version: pkg.version,
+        },
+      }, options);
+    } catch (error) {
+      if (typeof options.onStage === 'function') options.onStage('initialize', 'failed');
+      throw error;
+    }
+    if (typeof options.onStage === 'function') options.onStage('initialize', 'succeeded', result);
     if (result && result.protocolVersion) this.protocolVersion = result.protocolVersion;
-    await this.notify('notifications/initialized', undefined, options);
+    try {
+      await this.notify('notifications/initialized', undefined, options);
+    } catch (error) {
+      if (typeof options.onStage === 'function') options.onStage('initialized', 'failed');
+      throw error;
+    }
+    if (typeof options.onStage === 'function') options.onStage('initialized', 'succeeded');
     return result;
   }
 
@@ -279,7 +293,15 @@ class DraftGoMcpClient {
 
   async testConnection(options = {}) {
     const initialized = await this.initialize(options);
-    const tools = await this.listAllTools(options);
+    if (typeof options.onStage === 'function') options.onStage('tools/list', 'started');
+    let tools;
+    try {
+      tools = await this.listAllTools(options);
+    } catch (error) {
+      if (typeof options.onStage === 'function') options.onStage('tools/list', 'failed');
+      throw error;
+    }
+    if (typeof options.onStage === 'function') options.onStage('tools/list', 'succeeded', { count: tools.length });
     const requiredTools = options.requiredTools || REQUIRED_DRAFTGO_TOOLS;
     const missing = requiredTools.filter((expected) => !tools.some((tool) =>
       tool && typeof tool.name === 'string' && toolMatches(tool.name, expected)));
@@ -325,21 +347,32 @@ class DraftGoMcpClient {
       },
     ];
     const runPlan = (plan, startIndex = 0) => allWithAbort(plan.map((entry, offset) =>
-      async (queryOptions) => ({
+      async (queryOptions) => {
+        if (typeof options.onStage === 'function') options.onStage(`tools/call:${entry.label}`, 'started');
+        let result;
+        try {
+          result = await this.toolsCall(
+            entry.tool.name,
+            options.toolArguments && startIndex + offset === 0
+              ? options.toolArguments
+              : entry.args,
+            queryOptions,
+          );
+        } catch (error) {
+          if (typeof options.onStage === 'function') options.onStage(`tools/call:${entry.label}`, 'failed');
+          throw error;
+        }
+        if (typeof options.onStage === 'function') options.onStage(`tools/call:${entry.label}`, 'succeeded');
+        return ({
         label: entry.label,
         canonical: entry.canonical,
         name: entry.tool.name,
         arguments: options.toolArguments && startIndex + offset === 0
           ? options.toolArguments
           : entry.args,
-        result: await this.toolsCall(
-          entry.tool.name,
-          options.toolArguments && startIndex + offset === 0
-            ? options.toolArguments
-            : entry.args,
-          queryOptions,
-        ),
-      })), options);
+        result,
+      });
+      }), options);
     const tested = await runPlan(defaultPlan);
     if (!hasDiagnosticOverrides) {
       let discovery = tested.find((entry) => entry.label === 'api:db_meta');

package/src/projectMap.js

@@ -148,8 +148,13 @@ function analyzeProject(projectDir) {
     }
     if (!fs.existsSync(base)) {
       errors.push(`${entry.resource_type} ${entry.resource_id}: checkout base is missing (${entry.base_path}).`);
-    } else if (sha256File(base) !== entry.base_hash) {
-      errors.push(`${entry.resource_type} ${entry.resource_id}: checkout base hash does not match the manifest.`);
+    } else {
+      const actualBaseHash = sha256File(base);
+      if (actualBaseHash !== entry.base_hash) {
+        errors.push(`${entry.resource_type} ${entry.resource_id}: checkout base hash does not match the manifest `
+          + `(manifest=${entry.base_hash}, base=${actualBaseHash}). `
+          + `Run \`draftgo check --remote\` to classify the mismatch before replacing files.`);
+      }
     }
 
     const type = mediaType(entry.content_type);

package/src/worktree/index.js

@@ -15,7 +15,14 @@ const {
   resourceFileName,
   safeIdSegment,
 } = require('./types');
-const { streamToFiles, hashFile, copyFileAtomic, writeJsonAtomic, normalizeSha256 } = require('./streams');
+const {
+  streamToFiles,
+  hashFile,
+  copyFileAtomic,
+  writeJsonAtomic,
+  normalizeSha256,
+  tempPathFor,
+} = require('./streams');
 const {
   loadManifest,
   getEntry,
@@ -24,6 +31,7 @@ const {
   saveManifest,
 } = require('./manifest');
 const { validateContentFile } = require('./validate');
+const { inspectEntry, openMetadataSession, sameVersion } = require('./status');
 
 const CONFLICT_SCHEMA_VERSION = 1;
 
@@ -248,36 +256,148 @@ async function commitResources(projectDir, resourceType, resourceIds, options =
   const session = await createSession(config, options);
   const manifest = loadManifest(projectDir);
   const results = [];
+  const plans = [];
+  const preflightFailures = [];
+
+  const report = (result) => {
+    results.push(result);
+    if (typeof options.onStatus === 'function') options.onStatus(result);
+  };
 
+  // Resolve and validate every target before the first remote write. This prevents
+  // a late local or stale-version error from causing an avoidable partial batch.
   for (const resourceId of ids) {
-    const entry = getEntry(manifest, canonical, resourceId);
-    if (!entry) {
-      throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
-    }
-    if (entry.server !== config.server) {
-      throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
+    try {
+      const entry = getEntry(manifest, canonical, resourceId);
+      if (!entry) {
+        throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
+      }
+      if (entry.server !== config.server) {
+        throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
+      }
+      if (unresolvedConflict(projectDir, canonical, resourceId)) {
+        throw new WorktreeError(
+          'UNRESOLVED_CONFLICT',
+          `${canonical} ${resourceId} has an unresolved conflict; resolve it before committing.`,
+        );
+      }
+
+      const localPath = absolutePath(projectDir, entry.local_path);
+      const current = await hashFile(localPath);
+      const basePath = absolutePath(projectDir, entry.base_path);
+      const base = await hashFile(basePath);
+      if (base.hash !== entry.base_hash) {
+        throw new WorktreeError(
+          'BASE_HASH_MISMATCH',
+          `${canonical} ${resourceId} base hash differs from its manifest; run draftgo check --remote.`,
+          { manifest_hash: entry.base_hash, base_hash: base.hash },
+        );
+      }
+      if (current.hash !== entry.base_hash) validateContentFile(localPath, entry.content_type);
+
+      const fresh = await backend.resolveMetadata(config, canonical, resourceId, {
+        ...options,
+        ...session,
+        clientInitialized: true,
+      });
+      assertMetadataIdentity(fresh, canonical, resourceId);
+      const remoteMatchesBase = fresh.content_hash === entry.base_hash && sameVersion(entry, fresh);
+      if (!remoteMatchesBase) {
+        const state = await inspectEntry(projectDir, entry, fresh);
+        throw new WorktreeError(
+          state.local_matches_remote ? 'COMMITTED_UNRECORDED' : 'REMOTE_VERSION_CHANGED',
+          state.local_matches_remote
+            ? `${canonical} ${resourceId} already equals remote; run ${state.recommendation}.`
+            : `${canonical} ${resourceId} changed remotely; inspect with draftgo check --remote before committing.`,
+          state,
+        );
+      }
+      plans.push({ resourceId, entry, localPath, current, fresh });
+    } catch (error) {
+      if (error.code === 'REMOTE_VERSION_CHANGED') {
+        const entry = getEntry(manifest, canonical, resourceId);
+        try {
+          const conflict = await writeConflict(projectDir, entry, error, config, backend, options, session);
+          error = new WorktreeError(
+            'RESOURCE_VERSION_CONFLICT',
+            `${canonical} ${resourceId} changed remotely; conflict materials were preserved during preflight.`,
+            conflict,
+          );
+        } catch (conflictError) {
+          error = conflictError;
+        }
+      }
+      preflightFailures.push({
+        resource_type: canonical,
+        resource_id: resourceId,
+        status: 'failed',
+        phase: 'preflight',
+        code: error.code || 'PREFLIGHT_FAILED',
+        message: error.message,
+        details: error.details || {},
+      });
     }
-    if (unresolvedConflict(projectDir, canonical, resourceId)) {
-      throw new WorktreeError(
-        'UNRESOLVED_CONFLICT',
-        `${canonical} ${resourceId} has an unresolved conflict; resolve it before committing.`,
+  }
+
+  if (preflightFailures.length) {
+    const failedIds = new Set(preflightFailures.map((item) => String(item.resource_id)));
+    const notStarted = ids.filter((id) => !failedIds.has(String(id))).map((resourceId) => ({
+      resource_type: canonical,
+      resource_id: resourceId,
+      status: 'not_started',
+      phase: 'preflight',
+    }));
+    for (const result of [...preflightFailures, ...notStarted]) report(result);
+    if (ids.length === 1 && preflightFailures.length === 1) {
+      const original = new WorktreeError(
+        preflightFailures[0].code,
+        preflightFailures[0].message,
+        preflightFailures[0].details,
       );
+      throw original;
     }
+    throw new WorktreeError(
+      'BATCH_PREFLIGHT_FAILED',
+      `Commit preflight failed for ${preflightFailures.length} resource(s); no remote content was changed.`,
+      { completed: [], failed: preflightFailures, not_started: notStarted },
+    );
+  }
 
-    const localPath = absolutePath(projectDir, entry.local_path);
-    const current = await hashFile(localPath);
+  function throwBatchFailure(error, index, resourceId, remoteChangePossible = false) {
+    const failed = {
+      resource_type: canonical,
+      resource_id: resourceId,
+      status: 'failed',
+      phase: 'upload',
+      code: error.code || 'COMMIT_FAILED',
+      message: error.message,
+      remote_change_possible: remoteChangePossible,
+    };
+    const notStarted = plans.slice(index + 1).map((plan) => ({
+      resource_type: canonical,
+      resource_id: plan.resourceId,
+      status: 'not_started',
+      phase: 'upload',
+    }));
+    report(failed);
+    for (const item of notStarted) report(item);
+    error.details = {
+      ...(error.details || {}),
+      batch: {
+        completed: results.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+        failed: [failed],
+        not_started: notStarted,
+      },
+    };
+    throw error;
+  }
+
+  for (let index = 0; index < plans.length; index += 1) {
+    const { resourceId, entry, localPath, current, fresh } = plans[index];
     if (current.hash === entry.base_hash) {
-      results.push({ resource_type: canonical, resource_id: resourceId, status: 'unchanged', hash: current.hash });
+      report({ resource_type: canonical, resource_id: resourceId, status: 'unchanged', hash: current.hash });
       continue;
     }
-    validateContentFile(localPath, entry.content_type);
-
-    const fresh = await backend.resolveMetadata(config, canonical, resourceId, {
-      ...options,
-      ...session,
-      clientInitialized: true,
-    });
-    assertMetadataIdentity(fresh, canonical, resourceId);
     const commitMetadata = {
       ...fresh,
       content_type: entry.content_type,
@@ -290,55 +410,147 @@ async function commitResources(projectDir, resourceType, resourceIds, options =
     try {
       responsePayload = await backend.commit(config, commitMetadata, localPath, current, options);
     } catch (error) {
-      if (!isVersionConflict(error)) throw error;
-      const conflict = await writeConflict(projectDir, entry, error, config, backend, options, session);
-      throw new WorktreeError(
-        'RESOURCE_VERSION_CONFLICT',
-        `${canonical} ${resourceId} changed remotely; conflict materials were preserved.`,
-        conflict,
-      );
+      let failure = error;
+      const versionConflict = isVersionConflict(error);
+      if (versionConflict) {
+        const conflict = await writeConflict(projectDir, entry, error, config, backend, options, session);
+        failure = new WorktreeError(
+          'RESOURCE_VERSION_CONFLICT',
+          `${canonical} ${resourceId} changed remotely; conflict materials were preserved.`,
+          conflict,
+        );
+      }
+      throwBatchFailure(failure, index, resourceId, !versionConflict);
     }
 
-    let committed = commitVersion(normalizeCommitPayload(responsePayload));
-    if (!committed.hash || (committed.version == null && committed.revision == null)) {
-      const confirmed = await backend.resolveMetadata(config, canonical, resourceId, {
-        ...options,
-        ...session,
-        clientInitialized: true,
+    try {
+      let committed = commitVersion(normalizeCommitPayload(responsePayload));
+      if (!committed.hash || (committed.version == null && committed.revision == null)) {
+        const confirmed = await backend.resolveMetadata(config, canonical, resourceId, {
+          ...options,
+          ...session,
+          clientInitialized: true,
+        });
+        assertMetadataIdentity(confirmed, canonical, resourceId);
+        committed = {
+          version: confirmed.base_version,
+          revision: confirmed.base_revision,
+          etag: confirmed.etag,
+          hash: confirmed.content_hash,
+          updated_at: confirmed.updated_at,
+          updated_by: confirmed.updated_by,
+        };
+      }
+      if (committed.hash && committed.hash !== current.hash) {
+        throw new WorktreeError(
+          'HASH_MISMATCH',
+          'DraftGo commit response hash differs from the uploaded raw bytes; manifest was not advanced.',
+          { local_hash: current.hash, remote_hash: committed.hash },
+        );
+      }
+
+      await copyFileAtomic(localPath, absolutePath(projectDir, entry.base_path), { expectedHash: current.hash });
+      entry.base_hash = current.hash;
+      entry.content_size = current.size;
+      entry.base_version = committed.version;
+      entry.base_revision = committed.revision;
+      entry.base_etag = committed.etag;
+      entry.updated_at = committed.updated_at;
+      entry.updated_by = committed.updated_by;
+      entry.committed_at = new Date().toISOString();
+      await saveManifest(projectDir, manifest);
+      report({
+        resource_type: canonical,
+        resource_id: resourceId,
+        status: 'committed',
+        hash: current.hash,
+        base_version: entry.base_version,
+        base_revision: entry.base_revision,
       });
-      assertMetadataIdentity(confirmed, canonical, resourceId);
-      committed = {
-        version: confirmed.base_version,
-        revision: confirmed.base_revision,
-        etag: confirmed.etag,
-        hash: confirmed.content_hash,
-        updated_at: confirmed.updated_at,
-        updated_by: confirmed.updated_by,
-      };
+    } catch (error) {
+      throwBatchFailure(error, index, resourceId, true);
+    }
+  }
+  return results;
+}
+
+async function reconcileResources(projectDir, resourceType, resourceIds, options = {}) {
+  const canonical = canonicalResourceType(resourceType);
+  const ids = ensureIds(resourceIds);
+  const config = options.config || loadProjectConfig(projectDir);
+  const backend = backendFor(options);
+  const manifest = loadManifest(projectDir);
+  const session = options.backend && typeof options.backend.resolveMetadata === 'function'
+    ? { client: options.client || {}, tools: options.tools || [] }
+    : await openMetadataSession(config, options);
+  const results = [];
+
+  for (const resourceId of ids) {
+    const entry = getEntry(manifest, canonical, resourceId);
+    if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `${canonical} ${resourceId} is not checked out.`);
+    if (entry.server !== config.server) {
+      throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
     }
-    if (committed.hash && committed.hash !== current.hash) {
+    if (unresolvedConflict(projectDir, canonical, resourceId)) {
       throw new WorktreeError(
-        'HASH_MISMATCH',
-        'DraftGo commit response hash differs from the uploaded raw bytes; manifest was not advanced.',
-        { local_hash: current.hash, remote_hash: committed.hash },
+        'UNRESOLVED_CONFLICT',
+        `${canonical} ${resourceId} has an unresolved conflict; use conflict resolve instead of reconcile.`,
+      );
+    }
+    const remote = await backend.resolveMetadata(config, canonical, resourceId, {
+      ...options, ...session, clientInitialized: true,
+    });
+    assertMetadataIdentity(remote, canonical, resourceId);
+    const status = await inspectEntry(projectDir, entry, remote);
+    if (!status.local_matches_remote) {
+      throw new WorktreeError(
+        'RECONCILE_UNSAFE',
+        `${canonical} ${resourceId} local content does not equal remote; refusing to advance metadata.`,
+        status,
+      );
+    }
+    if (entry.content_type !== remote.content_type || entry.file_extension !== remote.file_extension) {
+      throw new WorktreeError(
+        'RECONCILE_FORMAT_CHANGED',
+        `${canonical} ${resourceId} remote content format changed; use checkout after preserving local work.`,
       );
     }
 
-    await copyFileAtomic(localPath, absolutePath(projectDir, entry.base_path), { expectedHash: current.hash });
-    entry.base_hash = current.hash;
-    entry.content_size = current.size;
-    entry.base_version = committed.version;
-    entry.base_revision = committed.revision;
-    entry.base_etag = committed.etag;
-    entry.updated_at = committed.updated_at;
-    entry.updated_by = committed.updated_by;
-    entry.committed_at = new Date().toISOString();
+    const response = await backend.download(config, remote, options);
+    const basePath = absolutePath(projectDir, entry.base_path);
+    const verifiedRemote = tempPathFor(basePath);
+    let verified;
+    try {
+      verified = await streamToFiles(response.body, [verifiedRemote], {
+        expectedHash: remote.content_hash,
+        expectedSize: remote.content_size,
+      });
+      const localAfterDownload = await hashFile(absolutePath(projectDir, entry.local_path));
+      if (localAfterDownload.hash !== verified.hash) {
+        throw new WorktreeError(
+          'RECONCILE_LOCAL_CHANGED',
+          `${canonical} ${resourceId} local content changed during reconcile; manifest was not advanced.`,
+          { local_hash: localAfterDownload.hash, remote_hash: verified.hash },
+        );
+      }
+      await copyFileAtomic(verifiedRemote, basePath, { expectedHash: verified.hash });
+    } finally {
+      await fs.promises.rm(verifiedRemote, { force: true }).catch(() => {});
+    }
+    entry.base_hash = verified.hash;
+    entry.content_size = verified.size;
+    entry.base_version = remote.base_version;
+    entry.base_revision = remote.base_revision;
+    entry.base_etag = remote.etag;
+    entry.updated_at = remote.updated_at;
+    entry.updated_by = remote.updated_by;
+    entry.reconciled_at = new Date().toISOString();
     await saveManifest(projectDir, manifest);
     results.push({
       resource_type: canonical,
       resource_id: resourceId,
-      status: 'committed',
-      hash: current.hash,
+      status: 'reconciled',
+      hash: verified.hash,
       base_version: entry.base_version,
       base_revision: entry.base_revision,
     });
@@ -454,6 +666,7 @@ module.exports = {
   conflictPaths,
   checkoutResources,
   commitResources,
+  reconcileResources,
   diffResource,
   listConflicts,
   showConflict,