metheus-governance-mcp-cli 0.2.6 → 0.2.7

package/README.md

@@ -2,7 +2,9 @@
 
 Metheus Governance MCP helper CLI.
 
-- `metheus-governance-mcp` (no args): bootstrap mode
+Compatibility note: legacy command alias `metheus-governance-mcp` is still supported.
+
+- `metheus-governance-mcp-cli` (no args): bootstrap mode
   - checks auth token
   - if token is missing/expired, starts `auth login`
   - checks Codex/Claude MCP registration
@@ -23,7 +25,7 @@ npm install -g metheus-governance-mcp-cli
 Run in your project folder:
 
 ```bash
-metheus-governance-mcp --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
 ```
 
 If auth is not ready, login starts automatically, then MCP registration is completed.
@@ -31,7 +33,7 @@ If auth is not ready, login starts automatically, then MCP registration is compl
 ## Setup
 
 ```bash
-metheus-governance-mcp setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
 ```
 
 `project-id` can be omitted if your current folder (or parent) has `.metheus_ctxpack_sync.json`.
@@ -39,7 +41,7 @@ metheus-governance-mcp setup --project-id <project_uuid> --ctxpack-key "<ctxpack
 ## Doctor
 
 ```bash
-metheus-governance-mcp doctor --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
 ```
 
 Checks:
@@ -70,30 +72,35 @@ These tools accept `project_id` and return:
 - missing local cache -> download
 - same version -> keep current
 - newer server version -> update local cache
+- workspace path -> follows active client workspace/root when provided by Codex/Claude
 
 Manual ctxpack pull/update:
 
 ```bash
-metheus-governance-mcp ctxpack pull --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli ctxpack pull --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
 ```
 
 When `workitem.list` returns empty, proxy appends a hint to call `project.summary` first.
 
+For `ctxpack` push conflicts (`ctxpack_conflict` / stale baseline), proxy behavior:
+- standard conflict message with pull/merge/retry guidance
+- auto ctxpack pull-to-local on conflict by default (`--auto-pull-on-conflict=true`)
+
 ## Auth flow (recommended)
 
 1. Auto login and save token once (default flow: `device -> callback -> manual hint`):
 
 ```bash
-metheus-governance-mcp auth login --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli auth login --base-url https://metheus.gesiaplatform.com
 ```
 
 Optional flags:
 
 ```bash
-metheus-governance-mcp auth login --callback-port 43819 --open-browser true
-metheus-governance-mcp auth login --flow device
-metheus-governance-mcp auth login --flow callback --callback-port 43819
-metheus-governance-mcp auth login --client-id metheus-cli --realm master --keycloak-url https://oauth3.gesia.io
+metheus-governance-mcp-cli auth login --callback-port 43819 --open-browser true
+metheus-governance-mcp-cli auth login --flow device
+metheus-governance-mcp-cli auth login --flow callback --callback-port 43819
+metheus-governance-mcp-cli auth login --client-id metheus-cli --realm master --keycloak-url https://oauth3.gesia.io
 ```
 
 Keycloak client requirement for auto login:
@@ -106,25 +113,25 @@ Keycloak client requirement for auto login:
 Manual fallback:
 
 ```bash
-metheus-governance-mcp auth login --manual true --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli auth login --manual true --base-url https://metheus.gesiaplatform.com
 ```
 
 2. Check token status:
 
 ```bash
-metheus-governance-mcp auth status
+metheus-governance-mcp-cli auth status
 ```
 
 3. If token is rotated, set directly:
 
 ```bash
-metheus-governance-mcp auth set --token "<access_token>" --refresh-token "<refresh_token>"
+metheus-governance-mcp-cli auth set --token "<access_token>" --refresh-token "<refresh_token>"
 ```
 
 4. Remove local token:
 
 ```bash
-metheus-governance-mcp auth clear
+metheus-governance-mcp-cli auth clear
 ```
 
 `proxy` priority:

package/cli.mjs

@@ -16,27 +16,31 @@ const DEFAULT_SERVER_NAME = "metheus-governance-mcp";
 const AUTH_STORE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-auth.json");
 const CTXPACK_CACHE_RELATIVE_DIR = path.join(".metheus", "ctxpack-cache");
 const CTXPACK_META_FILENAME = ".metheus_ctxpack_sync.json";
+const CTXPACK_PUSH_TOOL_NAMES = ["ctxpack.push", "ctxpack.update", "ctxpack.save"];
 const CLI_META = loadCLIMeta();
 const CLI_NAME = CLI_META.name || "metheus-governance-mcp-cli";
 const CLI_VERSION = CLI_META.version || "0.0.0";
+const AUTO_CTXPACK_SYNC_INTERVAL_MS = 60 * 1000;
+const autoCtxpackSyncTracker = new Map();
 
 function printUsage() {
+  const cmd = CLI_NAME;
   process.stderr.write(
     [
       "Metheus Governance MCP CLI",
       "",
       "Usage:",
-      "  metheus-governance-mcp [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--flow <auto|device|callback|manual>]",
-      "  metheus-governance-mcp init [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]",
-      "  metheus-governance-mcp setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--name <server_name>]",
-      "  metheus-governance-mcp doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>]",
-      "  metheus-governance-mcp proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--include-drafts <true|false>] [--timeout-seconds <n>]",
-      "  metheus-governance-mcp ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path>] [--timeout-seconds <n>]",
-      "  metheus-governance-mcp auth status",
-      "  metheus-governance-mcp auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]",
-      "  metheus-governance-mcp auth set --token <jwt> [--refresh-token <token>] [--base-url <url>]",
-      "  metheus-governance-mcp auth clear",
-      "  metheus-governance-mcp -v | --version",
+      `  ${cmd} [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--flow <auto|device|callback|manual>]`,
+      `  ${cmd} init [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]`,
+      `  ${cmd} setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--name <server_name>]`,
+      `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>]`,
+      `  ${cmd} proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--include-drafts <true|false>] [--auto-pull-on-conflict <true|false>] [--timeout-seconds <n>]`,
+      `  ${cmd} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path>] [--paths <csv>] [--timeout-seconds <n>]`,
+      `  ${cmd} auth status`,
+      `  ${cmd} auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]`,
+      `  ${cmd} auth set --token <jwt> [--refresh-token <token>] [--base-url <url>]`,
+      `  ${cmd} auth clear`,
+      `  ${cmd} -v | --version`,
       "",
       "Environment:",
       "  METHEUS_TOKEN or MCP_AUTH_TOKEN is used first for proxy requests.",
@@ -109,6 +113,67 @@ function resolveWorkspaceDir(rawPath) {
   return path.resolve(process.cwd());
 }
 
+function fileURIToLocalPath(rawValue) {
+  const value = String(rawValue || "").trim();
+  if (!value || !/^file:\/\//i.test(value)) return "";
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "file:") return "";
+    const pathname = decodeURIComponent(parsed.pathname || "");
+    if (!pathname) return "";
+    if (process.platform === "win32") {
+      // file:///C:/repo -> C:\repo
+      const winPath = pathname.replace(/^\/+([a-zA-Z]:\/)/, "$1").replace(/\//g, "\\");
+      return winPath;
+    }
+    return pathname;
+  } catch {
+    return "";
+  }
+}
+
+function firstNonEmptyString(values) {
+  for (const value of values) {
+    const text = String(value || "").trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
+  const params = safeObject(requestObj?.params);
+  const meta = safeObject(params._meta);
+  const args = safeObject(toolArgs);
+  const rawCandidate = firstNonEmptyString([
+    args.workspace_dir,
+    args.workspaceDir,
+    params.workspace_dir,
+    params.workspaceDir,
+    params.cwd,
+    params.root_path,
+    params.rootPath,
+    params.root_uri,
+    params.rootUri,
+    meta.workspace_dir,
+    meta.workspaceDir,
+    meta.cwd,
+    meta.root_path,
+    meta.rootPath,
+    meta.root_uri,
+    meta.rootUri,
+  ]);
+  const fileCandidate = fileURIToLocalPath(rawCandidate);
+  const candidate = firstNonEmptyString([fileCandidate, rawCandidate]);
+  if (!candidate) return "";
+  return resolveWorkspaceDir(candidate);
+}
+
+function resolveWorkspaceDirForRequest(defaultWorkspaceDir, requestObj, toolArgs) {
+  const requestCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
+  const candidate = firstNonEmptyString([requestCandidate, defaultWorkspaceDir, process.cwd()]);
+  return resolveWorkspaceDir(candidate);
+}
+
 function homeCtxpackCacheRootDir() {
   const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
   if (!home) {
@@ -1258,6 +1323,7 @@ async function runCtxpackPull(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const projectID = String(flags["project-id"] || workspaceMeta.project_id || "").trim();
   const workspaceDir = resolveWorkspaceDir(flags["workspace-dir"] || process.cwd());
+  const pathsCSV = String(flags.paths || "").trim();
   if (!projectID) {
     process.stderr.write("Missing project_id. Use --project-id <uuid> or run inside a synced ctxpack workspace.\n");
     process.exitCode = 1;
@@ -1289,6 +1355,7 @@ async function runCtxpackPull(flags) {
     includeCtxpack: true,
     syncCtxpackLocal: true,
     workspaceDir,
+    ctxpackPaths: pathsCSV,
   });
   process.stdout.write(`${buildProjectSummaryText(summary)}\n`);
 
@@ -1509,6 +1576,110 @@ async function runDoctor(flags) {
     addDoctorCheck(rows, "fail", "ctxpack sync", summary.ctxpack_sync_message || "ctxpack sync failed");
   }
 
+  const localMeta = loadWorkspaceMeta(context.workspaceDir);
+  const localBaseVersionID = firstNonEmptyString([localMeta.base_version_id, localMeta.version_id]);
+  const serverCurrentVersionID = firstNonEmptyString([summary.current_version_id, summary.ctxpack_version_id]);
+  if (summary.ctxpack_id) {
+    if (!serverCurrentVersionID) {
+      addDoctorCheck(rows, "warn", "stale baseline", "server current_version_id is missing");
+    } else if (!localBaseVersionID) {
+      addDoctorCheck(
+        rows,
+        "warn",
+        "stale baseline",
+        "local base_version_id is missing. Run: metheus-governance-mcp ctxpack pull --project-id <project_id>",
+      );
+    } else if (localBaseVersionID !== serverCurrentVersionID) {
+      addDoctorCheck(
+        rows,
+        "fail",
+        "stale baseline",
+        `local ${localBaseVersionID} != server ${serverCurrentVersionID}. Run ctxpack pull before safe push.`,
+      );
+    } else {
+      addDoctorCheck(rows, "ok", "stale baseline", `baseline is current (${serverCurrentVersionID})`);
+    }
+  } else {
+    addDoctorCheck(rows, "warn", "stale baseline", "ctxpack is not available for this project");
+  }
+
+  if (summary.ctxpack_id) {
+    try {
+      const encodedProjectID = encodeURIComponent(context.projectID);
+      const statsRaw = await getJSONWithAuth(
+        `${context.baseURL}/api/v1/projects/${encodedProjectID}/ctxpack/stats`,
+        timeoutSeconds,
+        token,
+      );
+      const stats = safeObject(statsRaw);
+      const strictConflict = Boolean(stats.strict_conflict);
+      const preflightMode = String(stats.preflight_mode || "").trim().toLowerCase() || "off";
+      const directPushMode = String(stats.direct_push_mode || "").trim().toLowerCase() || "unknown";
+      const allowLegacyPush = Boolean(stats.allow_legacy_push);
+      const forceAdminOnly = Boolean(stats.force_admin_only);
+      const readOnlyMode = Boolean(stats.read_only_mode);
+      const mergeMinApprovalsRaw = Number.parseInt(String(stats.merge_min_approvals ?? "1"), 10);
+      const mergeMinApprovals = Number.isFinite(mergeMinApprovalsRaw) ? mergeMinApprovalsRaw : 1;
+
+      if (strictConflict) {
+        addDoctorCheck(rows, "ok", "server policy strict_conflict", "enabled");
+      } else {
+        addDoctorCheck(rows, "warn", "server policy strict_conflict", "disabled (stale overwrite risk)");
+      }
+
+      if (preflightMode === "enforce") {
+        addDoctorCheck(rows, "ok", "server policy preflight_mode", "enforce");
+      } else if (preflightMode === "warn") {
+        addDoctorCheck(rows, "warn", "server policy preflight_mode", "warn (blocking not enabled yet)");
+      } else {
+        addDoctorCheck(rows, "warn", "server policy preflight_mode", `${preflightMode || "off"} (recommended: enforce)`);
+      }
+
+      if (directPushMode === "disabled") {
+        addDoctorCheck(rows, "ok", "server policy direct_push_mode", "disabled (merge-request workflow)");
+      } else if (directPushMode === "admin_only") {
+        addDoctorCheck(rows, "ok", "server policy direct_push_mode", "admin_only (merge-first default)");
+      } else if (directPushMode === "enabled") {
+        addDoctorCheck(rows, "warn", "server policy direct_push_mode", "enabled (writer direct push is open)");
+      } else {
+        addDoctorCheck(rows, "warn", "server policy direct_push_mode", directPushMode || "unknown");
+      }
+
+      if (mergeMinApprovals >= 2) {
+        addDoctorCheck(rows, "ok", "server policy merge_min_approvals", String(mergeMinApprovals));
+      } else if (mergeMinApprovals === 1) {
+        addDoctorCheck(rows, "warn", "server policy merge_min_approvals", "1 (recommended: >=2 for team review)");
+      } else {
+        addDoctorCheck(rows, "fail", "server policy merge_min_approvals", String(mergeMinApprovals));
+      }
+
+      if (allowLegacyPush) {
+        addDoctorCheck(rows, "warn", "server policy allow_legacy_push", "enabled (recommended: false)");
+      } else {
+        addDoctorCheck(rows, "ok", "server policy allow_legacy_push", "disabled");
+      }
+
+      if (forceAdminOnly) {
+        addDoctorCheck(rows, "ok", "server policy force_admin_only", "enabled");
+      } else {
+        addDoctorCheck(rows, "warn", "server policy force_admin_only", "disabled (writers may force/rollback)");
+      }
+
+      if (readOnlyMode) {
+        addDoctorCheck(rows, "warn", "server mode", "ctxpack read-only mode is enabled");
+      } else {
+        addDoctorCheck(rows, "ok", "server mode", "ctxpack writable");
+      }
+    } catch (err) {
+      addDoctorCheck(
+        rows,
+        "warn",
+        "server ctxpack policy",
+        `unable to read /ctxpack/stats (${String(err?.message || err)})`,
+      );
+    }
+  }
+
   const smokeCalls = [
     {
       tool: "workitem.list",
@@ -1854,6 +2025,7 @@ function hasAllCtxpackFiles(baseDir, files) {
 function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir }) {
   const ctxpackID = String(ctxpack?.ctxpack_id || "").trim();
   const version = String(ctxpack?.version || "").trim();
+  const versionID = String(ctxpack?.version_id || ctxpack?.current_version_id || "").trim();
   const status = String(ctxpack?.status || "").trim() || "draft";
   const files = normalizeCtxpackFiles(ctxpack?.files);
   const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir);
@@ -1871,14 +2043,15 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir
     };
   }
 
-  const remoteSig = `${ctxpackID}|${version}|${status}|${files.length}`;
+  const remoteSig = `${ctxpackID}|${versionID}|${version}|${status}|${files.length}`;
   const previousMeta = loadCtxpackMeta(metaPath);
   const previousSig = previousMeta
-    ? `${String(previousMeta.ctxpack_id || "").trim()}|${String(previousMeta.version || "").trim()}|${String(previousMeta.status || "").trim()}|${Number.parseInt(String(previousMeta.files_count || 0), 10) || 0}`
+    ? `${String(previousMeta.ctxpack_id || "").trim()}|${String(previousMeta.version_id || "").trim()}|${String(previousMeta.version || "").trim()}|${String(previousMeta.status || "").trim()}|${Number.parseInt(String(previousMeta.files_count || 0), 10) || 0}`
     : "";
   const payload = {
     project_id: projectID,
     ctxpack_id: ctxpackID,
+    version_id: versionID,
     version,
     status,
     files_count: files.length,
@@ -1943,6 +2116,7 @@ async function loadProjectSummaryForTool({
   includeCtxpack,
   syncCtxpackLocal,
   workspaceDir,
+  ctxpackPaths,
 }) {
   const encodedProjectID = encodeURIComponent(projectID);
   let projectRaw = null;
@@ -1980,6 +2154,7 @@ async function loadProjectSummaryForTool({
   let agendaSource = "";
   let ctxpackID = "";
   let ctxpackVersion = "";
+  let ctxpackVersionID = "";
   let ctxpackFileCount = 0;
   let ctxpackSyncStatus = includeCtxpack && syncCtxpackLocal ? "not_attempted" : "disabled";
   let ctxpackSyncMessage = "";
@@ -1987,7 +2162,12 @@ async function loadProjectSummaryForTool({
   let ctxpackLocalFileCount = 0;
   if (includeCtxpack) {
     try {
-      const ctxpackRaw = await getJSONWithAuth(`${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack`, timeoutSeconds, token);
+      const pathQuery = String(ctxpackPaths || "").trim();
+      const ctxpackURL =
+        pathQuery.length > 0
+          ? `${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack?paths=${encodeURIComponent(pathQuery)}`
+          : `${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack`;
+      const ctxpackRaw = await getJSONWithAuth(ctxpackURL, timeoutSeconds, token);
       const ctxpack = safeObject(ctxpackRaw);
       const extracted = extractAgendaFromFiles(ctxpack.files);
       agenda = extracted.agenda;
@@ -1995,6 +2175,7 @@ async function loadProjectSummaryForTool({
       ctxpackFileCount = extracted.ctxpackFileCount;
       ctxpackID = String(ctxpack.ctxpack_id || "").trim();
       ctxpackVersion = String(ctxpack.version || "").trim();
+      ctxpackVersionID = String(ctxpack.version_id || "").trim();
       if (syncCtxpackLocal) {
         const syncResult = syncCtxpackToLocalCache({
           siteBaseURL,
@@ -2035,7 +2216,10 @@ async function loadProjectSummaryForTool({
     member_count: Number(project.member_count || 0),
     created_at: String(project.created_at || "").trim(),
     ctxpack_id: ctxpackID,
+    ctxpack_version_id: ctxpackVersionID,
     ctxpack_version: ctxpackVersion,
+    base_version_id: ctxpackVersionID,
+    current_version_id: ctxpackVersionID,
     ctxpack_file_count: ctxpackFileCount,
     ctxpack_sync_status: ctxpackSyncStatus,
     ctxpack_sync_message: ctxpackSyncMessage,
@@ -2130,6 +2314,75 @@ function appendProjectHintToInitialize(responseObj, args) {
   return responseObj;
 }
 
+async function maybeAutoSyncCtxpackForCall({
+  requestObj,
+  toolName,
+  toolArgs,
+  args,
+  token,
+  workspaceDir,
+}) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return null;
+  if (!token) return null;
+  if (LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) return null;
+  if (String(toolName || "").trim().toLowerCase() === "ctxpack.ensure") return null;
+
+  const projectID = firstNonEmptyString([
+    toolArgs?.project_id,
+    toolArgs?.projectID,
+    args.projectID,
+  ]);
+  if (!isUUID(projectID)) return null;
+
+  const workspacePath = resolveWorkspaceDir(workspaceDir || process.cwd());
+  const trackerKey = `${workspacePath}::${projectID}`;
+  const now = Date.now();
+  const lastAt = Number(autoCtxpackSyncTracker.get(trackerKey) || 0);
+  if (lastAt > 0 && now-lastAt < AUTO_CTXPACK_SYNC_INTERVAL_MS) {
+    return null;
+  }
+  autoCtxpackSyncTracker.set(trackerKey, now);
+
+  try {
+    return await loadProjectSummaryForTool({
+      siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+      projectID,
+      token,
+      timeoutSeconds: args.timeoutSeconds,
+      includeCtxpack: true,
+      syncCtxpackLocal: true,
+      workspaceDir: workspacePath,
+    });
+  } catch {
+    return null;
+  }
+}
+
+function appendAutoCtxpackSyncHint(responseObj, summary) {
+  const status = String(summary?.ctxpack_sync_status || "").trim();
+  if (!status || status === "disabled" || status === "not_attempted" || status === "current") {
+    return responseObj;
+  }
+  const result = safeObject(responseObj.result);
+  const content = ensureArray(result.content);
+  if (!content.length) return responseObj;
+  const first = safeObject(content[0]);
+  if (String(first.type || "").trim() !== "text") return responseObj;
+  const text = String(first.text || "");
+  if (!text.trim() || text.includes("ctxpack_auto_sync:")) return responseObj;
+
+  let suffix = `ctxpack_auto_sync: ${status}`;
+  const localPath = String(summary?.ctxpack_local_path || "").trim();
+  if (localPath) suffix += ` (${localPath})`;
+  const message = String(summary?.ctxpack_sync_message || "").trim();
+  if (message) suffix += ` - ${message}`;
+
+  content[0] = { ...first, text: `${text}\n\n${suffix}` };
+  result.content = content;
+  responseObj.result = result;
+  return responseObj;
+}
+
 async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
   const result = safeObject(responseObj.result);
   const content = ensureArray(result.content);
@@ -2221,7 +2474,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
   return responseObj;
 }
 
-function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs) {
+function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj) {
   const result = safeObject(responseObj.result);
   const content = ensureArray(result.content);
   if (!content.length) return responseObj;
@@ -2243,13 +2496,16 @@ function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs) {
     toolArgs?.project_id || toolArgs?.projectID || envelope.project_id || args.projectID || "",
   ).trim();
   if (!projectID || !isUUID(projectID)) return responseObj;
+  const workspaceDir = resolveWorkspaceDirForRequest(args.workspaceDir || process.cwd(), requestObj, toolArgs);
 
   const syncResult = syncCtxpackToLocalCache({
     siteBaseURL: normalizeSiteBaseURL(args.baseURL),
     projectID,
     ctxpack: body,
-    workspaceDir: args.workspaceDir,
+    workspaceDir,
   });
+  const baseVersionID = firstNonEmptyString([body.base_version_id, body.version_id, body.current_version_id]);
+  const currentVersionID = firstNonEmptyString([body.current_version_id, body.version_id, body.base_version_id]);
 
   const lines = [
     "",
@@ -2264,16 +2520,189 @@ function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs) {
   if (syncResult.workspace_path) {
     lines.push(`ctxpack_workspace_path: ${String(syncResult.workspace_path)}`);
   }
+  if (baseVersionID) {
+    lines.push(`ctxpack_base_version_id: ${baseVersionID}`);
+  }
+  if (currentVersionID) {
+    lines.push(`ctxpack_current_version_id: ${currentVersionID}`);
+  }
 
   content[0] = {
     ...first,
     text: `${text}\n${lines.join("\n")}`,
   };
   result.content = content;
+  const structured = safeObject(result.structuredContent);
+  result.structuredContent = {
+    ...structured,
+    sync_status: String(syncResult.sync_status || "error"),
+    base_version_id: baseVersionID,
+    current_version_id: currentVersionID,
+    local_workspace_path: String(syncResult.workspace_path || workspaceDir),
+    local_ctxpack_path: String(syncResult.local_path || ""),
+  };
   responseObj.result = result;
   return responseObj;
 }
 
+function injectCtxpackPushDefaults(requestObj, toolName, workspaceDir) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
+  const normalizedTool = String(toolName || "").trim().toLowerCase();
+  if (!CTXPACK_PUSH_TOOL_NAMES.includes(normalizedTool)) {
+    return requestObj;
+  }
+
+  const params = safeObject(requestObj.params);
+  const rawArgs = safeObject(params.arguments ?? params.args);
+  if (String(rawArgs.base_version_id || "").trim() && String(rawArgs.push_mode || "").trim()) {
+    return requestObj;
+  }
+
+  const workspaceMeta = loadWorkspaceMeta(workspaceDir);
+  const baseVersionID = firstNonEmptyString([
+    rawArgs.base_version_id,
+    workspaceMeta.base_version_id,
+    workspaceMeta.version_id,
+  ]);
+  const nextArgs = { ...rawArgs };
+  if (!String(nextArgs.base_version_id || "").trim() && isUUID(baseVersionID)) {
+    nextArgs.base_version_id = baseVersionID;
+  }
+  if (!String(nextArgs.push_mode || "").trim()) {
+    nextArgs.push_mode = "safe";
+  }
+
+  const nextParams = { ...params };
+  nextParams.arguments = nextArgs;
+  const patched = { ...requestObj, params: nextParams };
+  return patched;
+}
+
+function collectChangedPathsForPreflight(rawArgs) {
+  const args = safeObject(rawArgs);
+  const explicit = ensureArray(args.changed_paths ?? args.changedPaths);
+  const raw = explicit.length > 0 ? explicit : ensureArray(args.files).map((file) => safeObject(file).path);
+  const dedup = new Set();
+  const out = [];
+  for (const value of raw) {
+    const text = String(value || "").trim();
+    if (!text || dedup.has(text)) continue;
+    dedup.add(text);
+    out.push(text);
+  }
+  return out;
+}
+
+async function injectCtxpackPreflightToken(requestObj, toolName, toolArgs, args, token, workspaceDir) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
+  if (!token) return requestObj;
+
+  const normalizedTool = String(toolName || "").trim().toLowerCase();
+  if (!CTXPACK_PUSH_TOOL_NAMES.includes(normalizedTool)) {
+    return requestObj;
+  }
+
+  const params = safeObject(requestObj.params);
+  const rawArgs = safeObject(params.arguments ?? params.args);
+  if (String(rawArgs.preflight_token || rawArgs.preflightToken || "").trim()) {
+    return requestObj;
+  }
+
+  const projectID = firstNonEmptyString([
+    rawArgs.project_id,
+    rawArgs.projectID,
+    toolArgs?.project_id,
+    toolArgs?.projectID,
+    args.projectID,
+  ]);
+  if (!isUUID(projectID)) {
+    return requestObj;
+  }
+
+  const workspaceMeta = loadWorkspaceMeta(workspaceDir);
+  const baseVersionID = firstNonEmptyString([
+    rawArgs.base_version_id,
+    rawArgs.baseVersionID,
+    workspaceMeta.base_version_id,
+    workspaceMeta.version_id,
+  ]);
+  if (!isUUID(baseVersionID)) {
+    return requestObj;
+  }
+
+  const changedPaths = collectChangedPathsForPreflight(rawArgs);
+  const payload = {
+    base_version_id: baseVersionID,
+  };
+  if (changedPaths.length > 0) {
+    payload.changed_paths = changedPaths;
+  }
+
+  try {
+    const baseURL = normalizeSiteBaseURL(args.baseURL);
+    const preflightURL = `${baseURL}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack/preflight`;
+    const responseText = await postJSON(preflightURL, args.timeoutSeconds, token, payload);
+    const responseBody = safeObject(tryJsonParse(responseText));
+    const preflightID = firstNonEmptyString([responseBody.preflight_id, responseBody.preflightID, responseBody.id]);
+    if (!preflightID) return requestObj;
+
+    const nextArgs = { ...rawArgs, preflight_token: preflightID };
+    if (!ensureArray(rawArgs.changed_paths ?? rawArgs.changedPaths).length && changedPaths.length > 0) {
+      nextArgs.changed_paths = changedPaths;
+    }
+    const nextParams = { ...params, arguments: nextArgs };
+    return { ...requestObj, params: nextParams };
+  } catch {
+    // Best-effort: if preflight auto-issue fails, server-side validation still enforces policy.
+    return requestObj;
+  }
+}
+
+async function appendCtxpackConflictHintToErrorResponse(responseObj, args, toolName, toolArgs, token, workspaceDir) {
+  const out = safeObject(responseObj);
+  const errObj = safeObject(out.error);
+  const message = String(errObj.message || "").trim();
+  if (!message) return responseObj;
+  const normalizedTool = String(toolName || "").trim().toLowerCase();
+  const normalizedMessage = message.toLowerCase();
+  const isCtxpackConflict = normalizedMessage.includes("ctxpack_conflict") || normalizedMessage.includes("ctxpack conflict");
+  if (!isCtxpackConflict) return responseObj;
+  if (!normalizedTool.startsWith("ctxpack.")) return responseObj;
+
+  const projectIDHint = firstNonEmptyString([
+    toolArgs?.project_id,
+    toolArgs?.projectID,
+    args.projectID,
+    "<project_id>",
+  ]);
+  const baseURL = normalizeSiteBaseURL(args.baseURL);
+  let autoPullHint = "";
+  if (args.autoPullOnConflict && token && isUUID(projectIDHint)) {
+    try {
+      const encodedProjectID = encodeURIComponent(projectIDHint);
+      const ctxpackRaw = await getJSONWithAuth(
+        `${baseURL}/api/v1/projects/${encodedProjectID}/ctxpack`,
+        args.timeoutSeconds,
+        token,
+      );
+      const syncResult = syncCtxpackToLocalCache({
+        siteBaseURL: baseURL,
+        projectID: projectIDHint,
+        ctxpack: safeObject(ctxpackRaw),
+        workspaceDir,
+      });
+      autoPullHint = ` auto-pull: ${String(syncResult.sync_status || "error")}${
+        syncResult.local_path ? ` (${String(syncResult.local_path)})` : ""
+      }`;
+    } catch (err) {
+      autoPullHint = ` auto-pull failed: ${String(err?.message || err)}`;
+    }
+  }
+  const hint = `stale baseline detected. run 'metheus-governance-mcp ctxpack pull --project-id ${projectIDHint} --base-url ${baseURL}', merge local edits, then retry safe push.${autoPullHint}`;
+  const nextError = { ...errObj, message: `${message}; ${hint}` };
+  return { ...out, error: nextError };
+}
+
 async function runProxy(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const args = {
@@ -2282,11 +2711,13 @@ async function runProxy(flags) {
     ctxpackKey: String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim(),
     workspaceDir: resolveWorkspaceDir(flags["workspace-dir"] || process.cwd()),
     includeDrafts: boolFromRaw(flags["include-drafts"], true),
+    autoPullOnConflict: boolFromRaw(flags["auto-pull-on-conflict"], true),
     timeoutSeconds: intFromRaw(flags["timeout-seconds"], 30),
   };
   const gatewayURL = buildGatewayURL(args);
   let lastRefreshAttemptAtMs = 0;
   let lastRefreshError = "";
+  let sessionWorkspaceDir = "";
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -2344,6 +2775,29 @@ async function runProxy(flags) {
     }
 
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
+    const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
+    if (requestWorkspaceCandidate) {
+      sessionWorkspaceDir = requestWorkspaceCandidate;
+    }
+    const requestWorkspaceDir = resolveWorkspaceDir(
+      firstNonEmptyString([
+        requestWorkspaceCandidate,
+        sessionWorkspaceDir,
+        args.workspaceDir,
+        process.cwd(),
+      ]),
+    );
+    let autoSyncSummary = null;
+    if (isJsonRpcMethod(requestObj, "tools/call")) {
+      autoSyncSummary = await maybeAutoSyncCtxpackForCall({
+        requestObj,
+        toolName,
+        toolArgs,
+        args,
+        token,
+        workspaceDir: requestWorkspaceDir,
+      });
+    }
     if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) {
       const projectID = String(toolArgs.project_id || toolArgs.projectID || args.projectID || "").trim();
       if (!projectID) {
@@ -2378,7 +2832,7 @@ async function runProxy(flags) {
           timeoutSeconds: args.timeoutSeconds,
           includeCtxpack,
           syncCtxpackLocal,
-          workspaceDir: args.workspaceDir,
+          workspaceDir: requestWorkspaceDir,
         });
         const text = buildProjectSummaryText(summary);
         process.stdout.write(
@@ -2403,11 +2857,32 @@ async function runProxy(flags) {
     }
 
     try {
-      const responseText = await postJSON(gatewayURL, args.timeoutSeconds, token, requestObj);
+      const requestWithDefaults = injectCtxpackPushDefaults(requestObj, toolName, requestWorkspaceDir);
+      const outboundRequestObj = await injectCtxpackPreflightToken(
+        requestWithDefaults,
+        toolName,
+        toolArgs,
+        args,
+        token,
+        requestWorkspaceDir,
+      );
+      const responseText = await postJSON(gatewayURL, args.timeoutSeconds, token, outboundRequestObj);
       if (responseText) {
         const parsed = parseGatewayResponseText(responseText);
-        if (parsed && !parsed.error) {
+        if (parsed) {
           let patched = parsed;
+          if (parsed.error) {
+            patched = await appendCtxpackConflictHintToErrorResponse(
+              patched,
+              args,
+              toolName,
+              toolArgs,
+              token,
+              requestWorkspaceDir,
+            );
+            process.stdout.write(`${JSON.stringify(patched)}\n`);
+            return;
+          }
           if (isJsonRpcMethod(requestObj, "tools/list")) {
             patched = appendLocalToolToToolsList(patched);
           } else if (isJsonRpcMethod(requestObj, "initialize")) {
@@ -2415,7 +2890,10 @@ async function runProxy(flags) {
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
             patched = await appendWorkitemListHints(patched, args, toolArgs, token);
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "ctxpack.ensure") {
-            patched = appendCtxpackEnsureSyncHints(patched, args, toolArgs);
+            patched = appendCtxpackEnsureSyncHints(patched, args, toolArgs, requestObj);
+          }
+          if (autoSyncSummary) {
+            patched = appendAutoCtxpackSyncHint(patched, autoSyncSummary);
           }
           process.stdout.write(`${JSON.stringify(patched)}\n`);
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [