draftgo-cli 3.0.48 → 3.0.49

package/README.md

@@ -170,6 +170,7 @@ draftgo context --task frontend --output json
 draftgo checkout pages 42 43
 # 独立资源可并行编辑；同一资源只由一个 Agent 修改
 draftgo check
+draftgo check --remote                  # 交付前按需对比远端版本/hash
 draftgo verify-ui http://localhost:5173       # UI 变更时
 draftgo diff pages 42
 draftgo diff pages 43
@@ -203,9 +204,10 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | `draftgo context --task <task> --output json` | 精确读取任务 Reference 章节，并复用一个 MCP 会话并行查询项目、资源、API 和数据结构；保留原始结果及来源。 |
 | `draftgo map` | 并行读取 pages、navigations、docs/articles 元数据，再叠加本地 checkout 状态；`--type` 可限制一种类型。 |
 | `draftgo checkout <pages|nav|docs> <id...>` | 下载完整正文和 base，校验 hash 后原子落盘；`--force` 可显式覆盖已修改的本地正文。 |
-| `draftgo check` | 只检查 checkout manifest、worktree 文件、base/hash、扩展名、HTML 结构和已 checkout 导航引用。 |
+| `draftgo check` | 默认只检查本地 checkout；`--remote` 额外对比 local/base/manifest/remote 的版本和 hash。 |
 | `draftgo diff <pages|nav|docs> <id>` | 显示 checkout base 与当前本地正文的差异。 |
 | `draftgo commit <pages|nav|docs> <id...>` | 本地校验后，通过专用 HTTP 上传完整正文并更新 base/manifest。 |
+| `draftgo reconcile <pages|nav|docs> <id...>` | 仅当 local 与经校验的 remote 字节一致时，安全修复落后的 base/manifest 元数据。 |
 | `draftgo conflicts` | 列出未解决冲突；存在冲突时返回非零。`--all` 包括已解决记录。 |
 | `draftgo conflict show <type> <id>` | 显示冲突的 base/local/remote/worktree 路径。 |
 | `draftgo conflict resolve <type> <id>` | 确认 worktree 已合并，把保留的 remote 设为新 base；随后重新 check、diff、commit。 |
@@ -220,6 +222,7 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | `draftgo api <query>` | 通过 MCP `api_search` 查询实时 API 契约。 |
 | `draftgo api search <query>` | `draftgo api <query>` 的显式搜索形式。 |
 | `draftgo api describe <operation_id>` | 通过 MCP `api_describe` 查看指定操作。 |
+| `draftgo api call <operation_id> --input <file>` | 描述后调用实时 operation；JSON 文件严格按 UTF-8 解码并输出状态码、服务端 code 和 request ID。 |
 | `draftgo delete <operation_id> [id]` | 描述并确认后调用实时 MCP `api_call`；支持 `--params JSON`、`--input file` 和 `--yes`。 |
 | `draftgo deploy [<type> <id...>]` | 先 `check`，再按 delivery 模式检查 diff 或 commit。仅 `--delivery local` 可省略 type/id。 |
 | `draftgo auto-push [<type> <id...>]` | `auto_push: true` 时检查并 commit 已 checkout 的变更；有冲突立即停止。 |
@@ -321,7 +324,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 }
 ```
 
-`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。`check` 不访问远端，也不会读取旧全量资源索引。
+`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, remote, remote_error, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。默认 `check` 不访问远端；显式使用 `--remote` 时读取每个 checkout 的实时 metadata，并把 `committed_unrecorded` 等可恢复状态指向 `draftgo reconcile`。它始终不会读取旧全量资源索引。
 
 ## Skill 与领域约定
 
@@ -343,6 +346,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--task <task>`：选择 context 路由；支持 frontend、data、custom-service、aihub、content、project。
 - `--type <type>`：限制 `map` 查询一种正文资源类型；支持 pages、nav/navigations、docs/articles 及其别名。
 - `--strict`：check/deploy/auto-push 将 warnings 视为失败。
+- `--remote`：让 check 按需对比 checkout 的远端版本和 hash；默认仍为快速离线检查。
 - `--force`：init 覆盖已有 Skill；checkout 显式覆盖已修改的本地正文。update 始终刷新目标 Skill。
 - `--purge`：uninstall 时同时删除整个 `.draftgo/` 运行时目录。
 - `--skip-update-check`：update 不访问 npm，直接用当前 CLI 刷新 Skill。
@@ -353,6 +357,8 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
 - `--yes`：跳过支持该选项的交互确认。
 - `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行。
+- `--resource <type:id>`：verify-ui 打开 URL 前对比本地 checkout 与远端已提交版本，并明确报告实际验证来源。
+- `--browser-path <file>`：verify-ui 显式使用浏览器可执行文件；也可设置 `DRAFTGO_BROWSER_PATH`，否则自动查找系统浏览器和 Playwright 缓存。
 - `--token auto|never`：`verify-ui` 默认读取 `.draftgo/config.json`，对与 `server` 同源的地址自动附加 `token=<SAT>`；配置无 SAT、跨源地址或 `never` 模式均不附加。
 - `--screenshot on-failure|always|never`：控制 UI 截图。
 - `--delivery local|preview|deploy`：控制 deploy 行为。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.48",
+  "version": "3.0.49",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/SKILL.md

@@ -50,8 +50,8 @@ context 会校验本地 Reference，返回逐字章节、来源、实时项目/
 
 1. MCP 定位 pages/nav/docs 并读取 metadata。
 2. 批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
-3. 主 Agent 回读全部修改，统一运行 `draftgo check`；页面布局或交互变化时按受众运行 `draftgo verify-ui`。
-4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。
+3. 主 Agent 回读全部修改，统一运行 `draftgo check`；交付前需要核对远端版本时运行 `draftgo check --remote`。
+4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。页面布局或交互变化时在 commit 后用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。
 5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。
 
 完整 manifest、流式传输、哈希和冲突规则见 `references/checkout.md`。

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.48",
+  "version": "3.0.49",
   "entry": "SKILL.md",
   "description": "以 context 聚合编排、Skill/reference 原文、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/checkout.md

@@ -23,6 +23,7 @@ db_meta、AIHub、system_config、roles、users、doc_categories 和普通配置
 ```bash
 draftgo checkout <pages|nav|docs> <id...>
 draftgo commit <pages|nav|docs> <id...>
+draftgo reconcile <pages|nav|docs> <id...>
 draftgo diff <pages|nav|docs> <id>
 draftgo conflicts
 draftgo conflict show <pages|nav|docs> <id>
@@ -91,7 +92,7 @@ base 已变化时必须拒绝覆盖。
 4. 完整正文不得作为 MCP tool 参数发送。
 5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
 
-推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` 和必要的 `draftgo verify-ui` -> `draftgo diff` -> commit。
+推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
 单个 commit 成功不自动写 changelog。只有整个任务统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行一次 `draftgo changelog add "<完成结果>"`。任何检查失败、409/412 或交付失败都不得写入。
 

package/src/cli.js

@@ -12,6 +12,8 @@ const VALUE_FLAGS = new Set([
   'output',
   'url',
   'browser',
+  'browser-path',
+  'resource',
   'mobile-check',
   'screenshot',
   'selector',

package/src/commandRegistry.js

@@ -15,6 +15,7 @@ const commands = [
   { name: 'mcp', run: (dir, args, flags) => require('./commands/mcp')(dir, args, flags) },
   { name: 'checkout', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
   { name: 'commit', run: (dir, args, flags) => require('./commands/commit')(dir, args, flags) },
+  { name: 'reconcile', run: (dir, args, flags) => require('./commands/reconcile')(dir, args, flags) },
   { name: 'diff', run: (dir, args, flags) => require('./commands/diff')(dir, args, flags) },
   { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },
   { name: 'conflict', run: (dir, args, flags) => require('./commands/conflict')(dir, args, flags) },

package/src/commands/api.js

@@ -1,9 +1,105 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const log = require('../logger');
+const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
 
+function readCallInput(projectDir, flags) {
+  const raw = flags.input
+    ? fs.readFileSync(path.resolve(projectDir, String(flags.input)))
+    : flags.params ? Buffer.from(String(flags.params), 'utf8') : Buffer.from('{}', 'utf8');
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(raw);
+  const value = JSON.parse(text);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('API call input must be a UTF-8 JSON object.');
+  }
+  return value;
+}
+
+function diagnosticResult(operationId, result) {
+  const source = result && typeof result === 'object' ? result : { data: result };
+  const statusCode = source.status_code ?? source.statusCode ?? source.status ?? null;
+  const headerRequestId = source.headers
+    && (source.headers['x-request-id'] || source.headers['X-Request-Id']);
+  const requestId = source.request_id ?? source.requestId ?? headerRequestId ?? null;
+  const error = source.error && typeof source.error === 'object' ? source.error : null;
+  return {
+    operation_id: operationId,
+    status_code: statusCode,
+    server_code: error && error.code || source.code || null,
+    request_id: requestId,
+    result,
+  };
+}
+
+function diagnosticError(operationId, error) {
+  const source = error && (error.details || error.data) || {};
+  const nested = source.error && typeof source.error === 'object' ? source.error : {};
+  return {
+    operation_id: operationId,
+    status_code: (error && error.status) ?? source.status_code ?? source.status ?? null,
+    server_code: nested.code || source.code || error && error.code || null,
+    request_id: source.request_id || source.requestId || nested.request_id || null,
+    error: { message: error && error.message || String(error) },
+  };
+}
+
+function printCallError(operationId, error, flags) {
+  const diagnostic = diagnosticError(operationId, error);
+  if (flags.output === 'json') console.log(JSON.stringify(diagnostic, null, 2));
+  else {
+    log.err(`DraftGo operation failed: ${operationId}`);
+    log.info(`status=${diagnostic.status_code ?? '-'} code=${diagnostic.server_code ?? '-'} request_id=${diagnostic.request_id ?? '-'}`);
+    log.err(diagnostic.error.message);
+  }
+  return 1;
+}
+
+async function callOperation(projectDir, operationId, flags = {}) {
+  if (!operationId) {
+    log.err('Usage: draftgo api call <operation_id> --input <json-file>');
+    return 1;
+  }
+  let session;
+  let description;
+  let input;
+  try {
+    const config = loadProjectConfig(projectDir);
+    session = await openToolSession(config, [TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall]);
+    description = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+    input = readCallInput(projectDir, flags);
+  } catch (error) {
+    return printCallError(operationId, error, flags);
+  }
+  const destructive = description && (description.destructive === true
+    || description.operation && description.operation.destructive === true);
+  if (destructive && !flags.yes && !flags.y) {
+    const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
+    if (!approved) return 0;
+  }
+  let result;
+  try {
+    result = await callStructured(session, TOOL_NAMES.apiCall, {
+      ...input,
+      operation_id: operationId,
+      ...(destructive ? { confirm: true } : {}),
+    });
+  } catch (error) {
+    return printCallError(operationId, error, flags);
+  }
+  const diagnostic = diagnosticResult(operationId, result);
+  if (flags.output === 'json') console.log(JSON.stringify(diagnostic, null, 2));
+  else {
+    log.ok(`DraftGo operation completed: ${operationId}`);
+    log.info(`status=${diagnostic.status_code ?? '-'} code=${diagnostic.server_code ?? '-'} request_id=${diagnostic.request_id ?? '-'}`);
+    console.log(JSON.stringify(result, null, 2));
+  }
+  return 0;
+}
+
 function printResult(title, result) {
   log.title(title);
   if (Array.isArray(result)) {
@@ -19,6 +115,7 @@ function printResult(title, result) {
 
 async function apiCommand(projectDir, positional, flags = {}) {
   const first = String(positional[0] || '').toLowerCase();
+  if (first === 'call') return callOperation(projectDir, String(positional[1] || ''), flags);
   const describe = first === 'describe';
   const queryParts = first === 'search' || describe ? positional.slice(1) : positional;
   const query = queryParts.join(' ').trim();
@@ -39,3 +136,8 @@ async function apiCommand(projectDir, positional, flags = {}) {
 }
 
 module.exports = apiCommand;
+module.exports.readCallInput = readCallInput;
+module.exports.diagnosticResult = diagnosticResult;
+module.exports.diagnosticError = diagnosticError;
+module.exports.printCallError = printCallError;
+module.exports.callOperation = callOperation;

package/src/commands/autoPush.js

@@ -37,7 +37,7 @@ async function autoPush(projectDir, positional, flags = {}) {
     return 1;
   }
 
-  const checkCode = check(projectDir, { strict: flags.strict });
+  const checkCode = await check(projectDir, { strict: flags.strict });
   if (checkCode !== 0) {
     log.err('auto-push stopped because local validation failed.');
     return checkCode;

package/src/commands/check.js

@@ -4,16 +4,37 @@ const fs = require('fs');
 const path = require('path');
 const log = require('../logger');
 const { analyzeProject } = require('../projectMap');
+const { inspectRemoteCheckouts } = require('../worktree/status');
 
 function legacyCacheDetected(projectDir) {
   return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
     .some((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
 }
 
-function check(projectDir, flags = {}) {
+async function check(projectDir, flags = {}) {
   const result = analyzeProject(projectDir);
+  let remote = null;
+  let remoteError = null;
+  if (flags.remote) {
+    try {
+      remote = await inspectRemoteCheckouts(projectDir);
+      for (const entry of remote) {
+        if (!['clean', 'clean_local', 'local_modified'].includes(entry.state)) {
+          const detail = `${entry.resource_type} ${entry.resource_id}: ${entry.state}`
+            + ` (local=${entry.local_hash || '-'}, base=${entry.manifest_hash || '-'}, `
+            + `remote=${entry.remote_hash || '-'}, remote_version=${entry.remote_version || '-'})`
+            + (entry.recommendation ? `; run ${entry.recommendation}` : '');
+          result.errors.push(detail);
+        }
+      }
+    } catch (error) {
+      remoteError = { code: error.code || 'REMOTE_CHECK_FAILED', message: error.message };
+      result.errors.push(`Remote checkout check failed: ${error.message}`);
+    }
+  }
+  const output = { ...result, remote, remote_error: remoteError };
   if (flags.output === 'json') {
-    console.log(JSON.stringify({ ...result, legacy_cache_ignored: legacyCacheDetected(projectDir) }, null, 2));
+    console.log(JSON.stringify({ ...output, legacy_cache_ignored: legacyCacheDetected(projectDir) }, null, 2));
     return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
   }
 
@@ -21,6 +42,7 @@ function check(projectDir, flags = {}) {
   log.info(`Checked-out pages: ${result.map.pages.length}`);
   log.info(`Checked-out navigations: ${result.map.navigations.length}`);
   log.info(`Checked-out docs: ${result.map.docs.length}`);
+  if (remote) log.info(`Remote checkout comparison: ${remote.length} resource(s)`);
   for (const message of result.errors) log.err(message);
   for (const detail of result.warningDetails) log.warn(`[${detail.code}/${detail.confidence}] ${detail.message}`);
   if (legacyCacheDetected(projectDir)) log.dim('  Legacy .draftgo index caches were detected and ignored.');

package/src/commands/commit.js

@@ -9,11 +9,37 @@ async function commit(projectDir, positional, flags = {}) {
     log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
     return 1;
   }
-  const results = await commitResources(projectDir, resourceType, ids);
-  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
-  else for (const result of results) {
-    if (result.status === 'unchanged') log.dim(`${result.resource_type} ${result.resource_id}: unchanged`);
-    else log.ok(`Committed ${result.resource_type} ${result.resource_id}`);
+  const streamed = [];
+  const printStatus = (result) => {
+    streamed.push(result);
+    if (flags.output === 'json') return;
+    if (result.status === 'committed') log.ok(`${result.resource_type} ${result.resource_id}: committed`);
+    else if (result.status === 'unchanged') log.dim(`${result.resource_type} ${result.resource_id}: unchanged`);
+    else if (result.status === 'failed') log.err(`${result.resource_type} ${result.resource_id}: failed (${result.code}) - ${result.message}`
+      + (result.remote_change_possible ? ' Remote change is possible; run draftgo check --remote.' : ''));
+    else log.warn(`${result.resource_type} ${result.resource_id}: not started`);
+  };
+  try {
+    const results = await commitResources(projectDir, resourceType, ids, { onStatus: printStatus });
+    if (flags.output === 'json') console.log(JSON.stringify({
+      completed: results.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: [],
+      not_started: [],
+    }, null, 2));
+  } catch (error) {
+    const batch = error.details && (error.details.batch || error.details);
+    const summary = batch && Array.isArray(batch.completed) ? batch : {
+      completed: streamed.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: streamed.filter((item) => item.status === 'failed'),
+      not_started: streamed.filter((item) => item.status === 'not_started'),
+    };
+    if (flags.output === 'json') console.log(JSON.stringify({ error: {
+      code: error.code || 'COMMIT_FAILED', message: error.message,
+    }, ...summary }, null, 2));
+    else log.err(`Commit batch stopped: ${summary.completed.length} completed, `
+      + `${summary.failed.length} failed, ${summary.not_started.length} not started. `
+      + `${summary.completed.length ? 'Remote changes already occurred for completed resources.' : 'No remote content was changed.'}`);
+    return 1;
   }
   return 0;
 }

package/src/commands/deploy.js

@@ -11,7 +11,7 @@ async function deploy(projectDir, positional, flags = {}) {
   }
 
   log.step('deploy: validating checked-out content...');
-  const checkCode = check(projectDir, { strict: flags.strict });
+  const checkCode = await check(projectDir, { strict: flags.strict });
   if (checkCode !== 0) {
     log.err('Deploy stopped because local validation failed.');
     return checkCode;

package/src/commands/help.js

@@ -45,8 +45,10 @@ Usage:
   draftgo checkout <type> <id...>  Download pages/nav/docs body + verified base.
                                     --force explicitly replaces local changes.
   draftgo check                    Validate checked-out worktree/base files only.
+                                    --remote also compares remote hash/version.
   draftgo diff <type> <id>         Show checkout base versus local body.
   draftgo commit <type> <id...>    Validate and upload complete checked-out bodies.
+  draftgo reconcile <type> <id...> Repair stale metadata only when local equals remote.
   draftgo conflicts                List unresolved conflicts; --all includes resolved.
   draftgo conflict show <type> <id>
                                     Show preserved base/local/remote paths.
@@ -58,6 +60,8 @@ Usage:
   draftgo api <query>              Search the live API contract through MCP.
   draftgo api describe <operation_id>
                                     Describe one live API operation through MCP.
+  draftgo api call <operation_id> --input <json-file>
+                                    Call one described operation with UTF-8 JSON.
   draftgo delete <operation_id> [id]
                                     Confirm and call a live delete operation.
                                     Legacy <type> <id> works only when unambiguous.
@@ -106,10 +110,11 @@ Important flags:
                            content | project.
   --type <type>            (map) pages | nav/navigations | docs/articles.
   --strict                 Treat check warnings as failures.
+  --remote                 (check) Compare checkout hashes/versions with remote.
   --yes                    Skip supported confirmation prompts.
   --operation-id <id>      (delete) Select an operation explicitly.
-  --params <json>          (delete) Pass an API parameter object.
-  --input <file>           (delete) Read the parameter object from JSON.
+  --params <json>          (api call/delete) Pass an API parameter object.
+  --input <file>           (api call/delete) Read a UTF-8 JSON parameter object.
   --delivery <mode>        (deploy) local | preview | deploy.
   --dry-run                (push) Show diffs without committing.
   --mobile-check <mode>    (verify-ui) auto | always | never.
@@ -117,6 +122,9 @@ Important flags:
                            SAT to same-origin URLs as the token query parameter.
   --screenshot <mode>      (verify-ui) on-failure | always | never.
   --browser <name>         (verify-ui) chromium | chrome | msedge.
+  --browser-path <file>    (verify-ui) Explicit browser executable; environment
+                           fallback: DRAFTGO_BROWSER_PATH.
+  --resource <type:id>     (verify-ui) Compare local and remote content first.
   --selector <css>         (verify-ui) Require a visible key element.
   --width/--height <px>    (verify-ui) Override the default 390x844 viewport.
 

package/src/commands/map.js

@@ -4,11 +4,10 @@ const fs = require('fs');
 const path = require('path');
 const log = require('../logger');
 const { loadProjectConfig } = require('../projectConfig');
-const { loadManifest, absolutePath } = require('../worktree/manifest');
-const { hashFile } = require('../worktree/streams');
 const { canonicalResourceType } = require('../worktree/types');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
 const { allWithAbort } = require('../mcp/parallel');
+const { inspectRemoteCheckouts } = require('../worktree/status');
 
 const REMOTE_RESOURCE_TYPES = Object.freeze({
   pages: 'pages',
@@ -82,23 +81,6 @@ async function listRemoteResources(session, resourceTypes = DEFAULT_REMOTE_RESOU
   return groups.flat();
 }
 
-async function localCheckouts(projectDir) {
-  const manifest = loadManifest(projectDir);
-  const entries = [];
-  for (const entry of Object.values(manifest.entries)) {
-    const local = absolutePath(projectDir, entry.local_path);
-    let currentHash = null;
-    if (fs.existsSync(local)) currentHash = (await hashFile(local)).hash;
-    entries.push({
-      ...entry,
-      exists: currentHash !== null,
-      current_hash: currentHash,
-      changed: currentHash !== null && currentHash !== entry.base_hash,
-    });
-  }
-  return entries;
-}
-
 function legacyCaches(projectDir) {
   return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
     .filter((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
@@ -113,7 +95,20 @@ async function mapCommand(projectDir, flags = {}) {
       (options) => callStructured(session, TOOL_NAMES.projectOverview, {}, options),
       (options) => listRemoteResources(session, resourceTypes, options),
     ], options),
-    () => localCheckouts(projectDir),
+    async (options) => {
+      const remoteStatus = await inspectRemoteCheckouts(projectDir, {
+        config,
+        client: session.client,
+        tools: session.tools,
+        signal: options.signal,
+      });
+      return remoteStatus.map((entry) => ({
+        ...entry,
+        exists: entry.local_hash !== null,
+        current_hash: entry.local_hash,
+        changed: entry.local_hash !== null && entry.local_hash !== entry.base_hash,
+      }));
+    },
   ]);
   const [overview, resources] = remote;
   const result = {
@@ -138,8 +133,11 @@ async function mapCommand(projectDir, flags = {}) {
   for (const [type, count] of [...counts.entries()].sort()) log.plain(`  ${type}: ${count}`);
   log.info(`Local checkouts: ${checkouts.length}`);
   for (const entry of checkouts) {
-    const state = !entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean';
-    log.plain(`  ${entry.resource_type} ${entry.resource_id}: ${state} (${entry.local_path})`);
+    const state = entry.state || (!entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean');
+    log.plain(`  ${entry.resource_type} ${entry.resource_id}: ${state}`
+      + ` local=${entry.local_hash || entry.current_hash || '-'} base=${entry.manifest_hash || entry.base_hash || '-'} remote=${entry.remote_hash || '-'} `
+      + `version=${entry.manifest_version ?? '-'}->${entry.remote_version ?? '-'} `
+      + `(${entry.local_path})`);
   }
   if (result.legacy_cache.detected.length) {
     log.warn(`Ignored legacy cache indexes: ${result.legacy_cache.detected.join(', ')}`);

package/src/commands/mcp.js

@@ -13,6 +13,20 @@ const {
 const { serveStdio } = require('../mcp/stdio');
 const { parseTimeout } = require('../timeout');
 
+function classifyMcpFailure(error) {
+  const message = String(error && error.message || error || '');
+  const code = error && error.code;
+  const status = error && error.status;
+  if (status === 401 || status === 403) return 'SAT authentication or authorization failed.';
+  if (/session|uninitialized|initialize first|not initialized/i.test(message)
+      || ['SESSION_EXPIRED', 'MCP_SESSION_EXPIRED', -32002].includes(code)) {
+    return 'The MCP session was lost or the server rejected the initialized state; check sticky sessions and service restarts.';
+  }
+  if (status >= 500) return 'The MCP service returned a server error; inspect the service request ID and logs.';
+  if (/tools\/call|tool/i.test(message)) return 'Tool invocation failed after protocol setup; inspect the tool contract and server handler.';
+  return 'Connection or MCP protocol negotiation failed.';
+}
+
 function targetArgs(positional, flags) {
   const values = positional.slice();
   if (flags.target) values.push(...String(flags.target).split(','));
@@ -87,19 +101,27 @@ function status(projectDir, positional = [], flags = {}) {
 
 async function test(projectDir, _positional = [], flags = {}) {
   let config;
+  const stages = [];
   try {
     config = loadProjectConfig(projectDir);
     const result = await testConnection(config, {
       timeoutMs: parseTimeout(flags.timeout),
+      onStage(stage, status) {
+        stages.push({ stage, status });
+        if (status === 'succeeded') log.ok(`MCP ${stage} succeeded.`);
+        else if (status === 'failed') log.err(`MCP ${stage} failed.`);
+        else log.step(`MCP ${stage}...`);
+      },
     });
-    log.ok('DraftGo MCP initialize succeeded.');
-    log.ok(`tools/list returned ${result.tools.length} tools.`);
-    log.ok(`tools/call succeeded: ${result.testedCalls.join(', ')}`);
+    log.ok(`MCP diagnostic completed: ${result.testedCalls.length} tools/call checks passed.`);
     log.dim(`  protocol: ${result.protocolVersion}`);
     return 0;
   } catch (error) {
     const token = config && String(config.token || config.sat || '');
     log.err(redactText(error && error.message ? error.message : error, [token]));
+    const last = stages[stages.length - 1];
+    if (last) log.info(`MCP diagnostic stopped at ${last.stage} (${last.status}).`);
+    log.info(classifyMcpFailure(error));
     return 1;
   }
 }
@@ -125,3 +147,4 @@ mcp.serve = serve;
 mcp.printUsage = printUsage;
 
 module.exports = mcp;
+module.exports.classifyMcpFailure = classifyMcpFailure;

package/src/commands/reconcile.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const log = require('../logger');
+const { reconcileResources } = require('../worktree');
+
+async function reconcile(projectDir, positional, flags = {}) {
+  const [resourceType, ...ids] = positional;
+  if (!resourceType || !ids.length) {
+    log.err('Usage: draftgo reconcile <pages|nav|docs> <id...>');
+    return 1;
+  }
+  const results = await reconcileResources(projectDir, resourceType, ids);
+  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
+  else for (const result of results) {
+    log.ok(`Reconciled ${result.resource_type} ${result.resource_id} -> ${result.base_version ?? result.base_revision}`);
+  }
+  return 0;
+}
+
+module.exports = reconcile;