@dypai-ai/mcp 1.7.1 → 1.7.3

package/src/toolProfiles.js

@@ -8,6 +8,7 @@ export const DEFAULT_MCP_PROFILE = "local";
 
 const STUDIO_WORKER_TOOLS = [
   "bulk_upsert",
+  "dypai_generate_types",
   "dypai_test_endpoint",
   "dypai_validate",
   "execute_sql",
@@ -247,15 +248,17 @@ export function assertStudioInstructionsSanitized(instructions, { allowDebugTool
     throw new Error("Studio instructions must describe orchestrator sync/build/validate");
   }
 
-  const withoutNegatedTypegen = instructions.replace(
-    /endpoint typescript types are handled by studio[^\n]*/gi,
-    "",
-  );
-  if (/\bdypai_generate_types\b/.test(withoutNegatedTypegen)) {
-    throw new Error("Studio instructions must not mention dypai_generate_types");
+  if (!/\bdypai_generate_types\b/.test(instructions)) {
+    throw new Error("Studio instructions must mention dypai_generate_types");
+  }
+  if (!/\bendpoints\.gen\.ts\b/.test(instructions)) {
+    throw new Error("Studio instructions must mention endpoints.gen.ts");
+  }
+  if (!/dypai_validate[\s\S]{0,240}dypai_generate_types|dypai_generate_types[\s\S]{0,240}dypai_validate/i.test(instructions)) {
+    throw new Error("Studio instructions must describe validate then generate types");
   }
-  if (/\bendpoints\.gen\.ts\b/.test(withoutNegatedTypegen)) {
-    throw new Error("Studio instructions must not mention endpoints.gen.ts");
+  if (!/read[^\n]*endpoints\.gen\.ts|read `dypai\/types\//i.test(instructions)) {
+    throw new Error("Studio instructions must tell the agent to read generated endpoint types");
   }
 
 }

package/src/tools/project-deploy-production.js

@@ -4,7 +4,6 @@ import YAML from "yaml"
 import { deployFromSource } from "./deploy.js"
 import { proxyToolCall } from "./proxy.js"
 import { resolveOutDir } from "./sync/path-resolver.js"
-import { refreshLocalStateSnapshot } from "./sync/planner.js"
 
 function resolveWorkspace({ workspace_root, sourceDirectory, root_dir } = {}) {
   if (workspace_root) {
@@ -173,13 +172,13 @@ export const dypaiDeployProductionTool = {
             live_changed: false,
           }
         }
-        try {
-          await refreshLocalStateSnapshot({ projectId: targetProjectId, rootDir })
-        } catch (refreshError) {
-          backend = {
-            ...backend,
-            state_baseline_refresh_warning: refreshError.message,
-          }
+        backend = {
+          ...backend,
+          state_baseline_refresh: {
+            skipped: true,
+            reason: "publish_does_not_prove_local_source_ownership",
+            hint: "Run dypai_pull before editing a just-published endpoint again. Automatic project-wide refresh is disabled to preserve multi-user conflict detection.",
+          },
         }
       }
     }

package/src/tools/project-push.js

@@ -65,8 +65,9 @@ function readProjectIdFromConfig(rootDir) {
 export const dypaiPushProjectTool = {
   name: "dypai_push",
   description:
-    "SAVE CHANGES — push all local DYPAI project changes to Studio/DYPAI without publishing production. " +
+    "SAVE CHANGES — push local DYPAI project changes to Studio/DYPAI without publishing production. " +
     "Backend files under dypai/ are staged as drafts. Frontend files under src/, public/, package.json, and versionable dypai/ source are saved to the Studio branch. " +
+    "Use only_endpoints for an isolated backend push; endpoint-scoped pushes intentionally skip frontend saves and unrelated backend resources. " +
     "Production is never changed by this tool. Use dypai_deploy_production(confirm:true) after explicit user approval to publish live.",
   inputSchema: {
     type: "object",
@@ -113,6 +114,13 @@ export const dypaiPushProjectTool = {
         description: "If false, only pushes backend drafts. Default: true.",
         default: true,
       },
+      only_endpoints: {
+        type: "array",
+        minItems: 1,
+        uniqueItems: true,
+        items: { type: "string" },
+        description: "Explicit backend endpoint allowlist. When set, unrelated backend resources and the frontend save are skipped.",
+      },
     },
     required: [],
   },
@@ -127,6 +135,7 @@ export const dypaiPushProjectTool = {
     force = false,
     skip_validation = false,
     save_frontend = true,
+    only_endpoints = null,
   } = {}) {
     const { workspaceRoot, rootDir, source } = resolveWorkspace({ workspace_root, sourceDirectory, root_dir })
     const targetProjectId = project_id || readProjectIdFromConfig(rootDir)
@@ -165,6 +174,7 @@ export const dypaiPushProjectTool = {
         dry_run,
         force,
         skip_validation,
+        only_endpoints,
       }))
     }
 
@@ -187,6 +197,8 @@ export const dypaiPushProjectTool = {
       skipped: true,
       reason: dry_run
         ? "dry_run"
+        : only_endpoints
+          ? "endpoint_scoped_push"
         : !save_frontend
           ? "save_frontend_false"
           : hasFrontend
@@ -194,7 +206,7 @@ export const dypaiPushProjectTool = {
             : "no_package_json",
     }
 
-    if (!dry_run && save_frontend && hasFrontend) {
+    if (!dry_run && !only_endpoints && save_frontend && hasFrontend) {
       frontend = await deployFromSource({
         sourceDirectory: workspaceRoot,
         project_id: targetProjectId,
@@ -214,7 +226,9 @@ export const dypaiPushProjectTool = {
       frontend_saved: hasFrontend && frontendOk && frontend.skipped !== true,
       live_changed: false,
       next_step: frontendOk
-        ? "Changes are saved to Studio/DYPAI. Test the preview. To publish live, use dypai_deploy_production(confirm:true) after explicit user approval."
+        ? only_endpoints
+          ? `Selected backend endpoint drafts are saved. Test them, then publish only the same allowlist with manage_drafts(operation:'publish', resource_names:${JSON.stringify(only_endpoints)}, confirm:true) after explicit approval.`
+          : "Changes are saved to Studio/DYPAI. Test the preview. To publish live, use dypai_deploy_production(confirm:true) after explicit user approval."
         : "Frontend save failed. Fix the frontend/source issue and run dypai_push again.",
     }
   },

package/src/tools/sync/endpoint-names.js

@@ -0,0 +1,29 @@
+/**
+ * Normalize endpoint names only for migration diagnostics.
+ *
+ * Underscores and hyphens remain distinct endpoint identities at runtime.
+ * This normalized value must never be used for reads or mutations; it only
+ * surfaces legacy pairs such as `create_task` + `create-task`.
+ */
+export function migrationCanonicalEndpointName(name) {
+  return typeof name === "string" ? name.replace(/_/g, "-") : ""
+}
+
+export function findEndpointNameCollisions(endpointsOrNames) {
+  const buckets = new Map()
+  for (const item of endpointsOrNames || []) {
+    const name = typeof item === "string" ? item : item?.name
+    if (!name) continue
+    const canonicalName = migrationCanonicalEndpointName(name)
+    if (!buckets.has(canonicalName)) buckets.set(canonicalName, new Set())
+    buckets.get(canonicalName).add(name)
+  }
+
+  return [...buckets.entries()]
+    .map(([canonical_name, names]) => ({
+      canonical_name,
+      endpoints: [...names].sort(),
+    }))
+    .filter((item) => item.endpoints.length > 1)
+    .sort((a, b) => a.canonical_name.localeCompare(b.canonical_name))
+}

package/src/tools/sync/generate-types.js

@@ -2,13 +2,94 @@
  * Regenerate dypai/types/endpoints.gen.ts from effective Flow/YAML contracts.
  */
 
+import { createHash } from "node:crypto"
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs"
 import { mkdir, writeFile } from "fs/promises"
-import { dirname, join, resolve as resolvePath } from "path"
+import { dirname, isAbsolute, join, resolve as resolvePath, sep } from "path"
 import { runEffectiveWorkflows } from "../../lib/effective-workflows-runner.js"
+import { resolveAndGuard } from "./path-resolver.js"
+import { isStudioProfile, resolveMcpProfile } from "../../toolProfiles.js"
 
-export async function runGenerateEndpointTypes(rootDir, projectId = null) {
+function assertUnderRoot(root, target) {
+  const resolvedRoot = resolvePath(root)
+  const resolvedTarget = resolvePath(target)
+  if (resolvedTarget !== resolvedRoot && !resolvedTarget.startsWith(resolvedRoot + sep)) {
+    throw new Error("Path escapes workspace root")
+  }
+}
+
+function assertNoSymlinkPath(root, target) {
+  const resolvedRoot = resolvePath(root)
+  const resolvedTarget = resolvePath(target)
+  assertUnderRoot(resolvedRoot, resolvedTarget)
+  if (!existsSync(resolvedRoot)) {
+    throw new Error("Workspace root does not exist")
+  }
+
+  const realRoot = realpathSync(resolvedRoot)
+  let cursor = resolvedTarget
+  while (true) {
+    if (existsSync(cursor)) {
+      if (lstatSync(cursor).isSymbolicLink()) {
+        throw new Error(`Symlink paths are not allowed for generated artifacts: ${cursor}`)
+      }
+      assertUnderRoot(realRoot, realpathSync(cursor))
+    }
+    if (cursor === resolvedRoot) break
+    const parent = dirname(cursor)
+    if (
+      parent === cursor
+      || (parent !== resolvedRoot && !parent.startsWith(resolvedRoot + sep))
+    ) {
+      throw new Error("Path escapes workspace root")
+    }
+    cursor = parent
+  }
+}
+
+function hashSnapshotFiles(files) {
+  const parts = (files || [])
+    .map((file) => `${file.path}\0${file.content}`)
+    .sort((a, b) => a.localeCompare(b))
+  return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 16)
+}
+
+async function writeGeneratedArtifacts(resolvedRoot, payload) {
+  const outDir = join(resolvedRoot, "types")
+  assertNoSymlinkPath(resolvedRoot, outDir)
+  await mkdir(outDir, { recursive: true })
+  const typesPath = join(outDir, "endpoints.gen.ts")
+  const contractPath = join(outDir, "endpoints.contract.json")
+  assertNoSymlinkPath(resolvedRoot, typesPath)
+  assertNoSymlinkPath(resolvedRoot, contractPath)
+
+  const writes = []
+  if (payload.typesContent) {
+    writes.push({ path: typesPath, content: payload.typesContent })
+  }
+  if (payload.contractJsonContent) {
+    writes.push({ path: contractPath, content: payload.contractJsonContent })
+  }
+
+  const writtenPaths = []
+  const unchangedPaths = []
+
+  for (const item of writes) {
+    const current = existsSync(item.path) ? readFileSync(item.path, "utf8") : null
+    if (current === item.content) {
+      unchangedPaths.push(item.path)
+      continue
+    }
+    await writeFile(item.path, item.content, "utf8")
+    writtenPaths.push(item.path)
+  }
+
+  return { typesPath, contractPath, writtenPaths, unchangedPaths }
+}
+
+export async function runGenerateEndpointTypes(rootDir, projectId = null, options = {}) {
   const resolvedRoot = resolvePath(rootDir)
-  const result = await runEffectiveWorkflows(resolvedRoot, projectId, ["generate-types"])
+  const result = await runEffectiveWorkflows(resolvedRoot, projectId, ["generate-types"], options.deps)
 
   if (result.unavailable) {
     return {
@@ -35,36 +116,150 @@ export async function runGenerateEndpointTypes(rootDir, projectId = null) {
     }
   }
 
-  if (payload.typesContent && payload.contractJsonContent) {
-    const outDir = join(resolvedRoot, "types")
-    await mkdir(outDir, { recursive: true })
-    const typesPath = join(outDir, "endpoints.gen.ts")
-    const contractPath = join(outDir, "endpoints.contract.json")
-    await writeFile(typesPath, payload.typesContent, "utf8")
-    await writeFile(contractPath, payload.contractJsonContent, "utf8")
+  const errorCount = payload.errorCount ?? 0
+  const warningCount = payload.warningCount ?? 0
+  const diagnosticCount = payload.diagnosticCount ?? 0
+  const diagnostics = Array.isArray(payload.diagnostics) ? payload.diagnostics.slice(0, 10) : []
+  const endpoints = payload.endpoints || []
+  const endpointCount = payload.endpointCount ?? 0
+  const snapshotHash = Array.isArray(payload.files)
+    ? hashSnapshotFiles(payload.files)
+    : options.snapshotHash ?? null
+
+  if (
+    typeof payload.typesContent !== "string"
+    || !payload.typesContent.trim()
+    || typeof payload.contractJsonContent !== "string"
+    || !payload.contractJsonContent.trim()
+  ) {
     return {
-      ok: true,
-      endpointCount: payload.endpointCount ?? 0,
-      typesPath,
-      contractPath,
-      endpoints: payload.endpoints || [],
-      diagnosticCount: payload.diagnosticCount ?? 0,
-      errorCount: payload.errorCount ?? 0,
-      warningCount: payload.warningCount ?? 0,
-      diagnostics: Array.isArray(payload.diagnostics) ? payload.diagnostics.slice(0, 10) : [],
+      ok: false,
+      error: "generate-types returned an incomplete artifact payload",
     }
   }
 
+  try {
+    const contract = JSON.parse(payload.contractJsonContent)
+    if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
+      throw new Error("contract JSON must be an object")
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: `generate-types returned invalid contract JSON: ${error?.message || String(error)}`,
+    }
+  }
+
+  const { typesPath, contractPath, writtenPaths, unchangedPaths } = await writeGeneratedArtifacts(
+    resolvedRoot,
+    payload,
+  )
   return {
     ok: true,
-    endpointCount: payload.endpointCount ?? 0,
-    typesPath: payload.typesPath,
-    contractPath: payload.contractPath,
-    endpoints: payload.endpoints || [],
-    diagnosticCount: payload.diagnosticCount ?? 0,
-    errorCount: payload.errorCount ?? 0,
-    warningCount: payload.warningCount ?? 0,
-    diagnostics: Array.isArray(payload.diagnostics) ? payload.diagnostics.slice(0, 10) : [],
+    endpointCount,
+    typesPath,
+    contractPath,
+    endpoints,
+    diagnosticCount,
+    errorCount,
+    warningCount,
+    diagnostics,
+    contractReady: errorCount === 0,
+    writtenPaths,
+    unchangedPaths,
+    snapshotHash,
+    cached: result.cached === true,
+  }
+}
+
+function resolveGenerateTypesRoot(root_dir = "./dypai") {
+  const profile = resolveMcpProfile(process.env)
+  if (isStudioProfile(profile)) {
+    const workspaceRoot = process.env.DYPAI_WORKSPACE_ROOT
+    if (!workspaceRoot) {
+      return {
+        ok: false,
+        error: {
+          success: false,
+          generated: false,
+          error: "Studio worker requires DYPAI_WORKSPACE_ROOT for endpoint type generation.",
+        },
+      }
+    }
+
+    const resolvedWorkspace = resolvePath(workspaceRoot)
+    const resolvedDypai = resolvePath(resolvedWorkspace, "dypai")
+    const suppliedPath = isAbsolute(root_dir)
+      ? resolvePath(root_dir)
+      : resolvePath(resolvedWorkspace, root_dir)
+    if (suppliedPath !== resolvedDypai) {
+      return {
+        ok: false,
+        error: {
+          success: false,
+          generated: false,
+          error: "Studio endpoint type generation is restricted to the canonical dypai/ directory.",
+          resolved_to: suppliedPath,
+          required_root: resolvedDypai,
+        },
+      }
+    }
+
+    try {
+      assertNoSymlinkPath(resolvedWorkspace, resolvedDypai)
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          success: false,
+          generated: false,
+          error: "Studio dypai/ must be a real directory inside the workspace (symlinks are not allowed).",
+          detail: error?.message || String(error),
+          resolved_to: resolvedDypai,
+          workspace_root: resolvedWorkspace,
+        },
+      }
+    }
+
+    return { ok: true, path: resolvedDypai, source: "env:DYPAI_WORKSPACE_ROOT" }
+  }
+
+  const guarded = resolveAndGuard(root_dir, { tool: "dypai_generate_types", arg_name: "root_dir" })
+  if (!guarded.ok) {
+    return guarded
+  }
+
+  return { ok: true, path: guarded.path, source: guarded.source }
+}
+
+function buildSuccessResponse(outcome) {
+  const generated = outcome.writtenPaths.length > 0
+  const refreshed = generated || outcome.unchangedPaths.length > 0
+  return {
+    success: true,
+    generated: refreshed,
+    files_written: outcome.writtenPaths.map((path) => path.replace(/^.*\/dypai\//, "dypai/")),
+    files_unchanged: outcome.unchangedPaths.map((path) => path.replace(/^.*\/dypai\//, "dypai/")),
+    contract_ready: outcome.contractReady,
+    endpoint_count: outcome.endpointCount,
+    types_path: "dypai/types/endpoints.gen.ts",
+    contract_path: "dypai/types/endpoints.contract.json",
+    endpoints: outcome.endpoints.slice(0, 50),
+    snapshot_hash: outcome.snapshotHash ?? undefined,
+    cached: outcome.cached === true,
+    diagnostics_summary: outcome.diagnosticCount
+      ? {
+          total: outcome.diagnosticCount,
+          errors: outcome.errorCount,
+          warnings: outcome.warningCount,
+          sample: outcome.diagnostics,
+        }
+      : undefined,
+    hint: outcome.contractReady
+      ? outcome.endpointCount
+        ? `Types refreshed for ${outcome.endpointCount} endpoint(s). Read dypai/types/endpoints.gen.ts before wiring frontend.`
+        : "No effective endpoints found — types file is empty."
+      : "Types were written but backend validation reported errors. Fix backend issues, run dypai_validate, then call dypai_generate_types again before frontend work.",
   }
 }
 
@@ -73,7 +268,8 @@ export const dypaiGenerateTypesTool = {
   description:
     "Regenerate frontend endpoint types from the local dypai/ backend (Flow IR + legacy YAML). " +
     "Writes dypai/types/endpoints.gen.ts and dypai/types/endpoints.contract.json. " +
-    "Call after editing dypai/flows/*.flow.ts or endpoint YAML, before frontend work. " +
+    "Call after editing dypai/flows/*.flow.ts or endpoint YAML and after dypai_validate, before frontend work. " +
+    "In Studio worker mode, call this after backend contract edits and before wiring src/. " +
     "Also runs automatically during dypai_push after validation.",
   inputSchema: {
     type: "object",
@@ -91,9 +287,14 @@ export const dypaiGenerateTypesTool = {
   },
 
   async execute({ project_id, root_dir = "./dypai" } = {}) {
+    const resolved = resolveGenerateTypesRoot(root_dir)
+    if (!resolved.ok) {
+      return resolved.error
+    }
+
     const { readLocalConfig } = await import("./planner.js")
     const { getEnvBoundProjectId } = await import("../project-context.js")
-    const rootDir = resolvePath(process.cwd(), root_dir)
+    const rootDir = resolved.path
     const config = await readLocalConfig(rootDir)
     const projectId = project_id || getEnvBoundProjectId() || config?.project_id || null
     const outcome = await runGenerateEndpointTypes(rootDir, projectId)
@@ -101,6 +302,7 @@ export const dypaiGenerateTypesTool = {
       return {
         success: false,
         generated: false,
+        contract_ready: false,
         reason: outcome.reason,
         hint: outcome.warning,
       }
@@ -109,32 +311,18 @@ export const dypaiGenerateTypesTool = {
       return {
         success: false,
         generated: false,
+        contract_ready: false,
         error: outcome.error,
         stderr: outcome.stderr,
       }
     }
-    return {
-      success: true,
-      generated: true,
-      endpoint_count: outcome.endpointCount,
-      types_path: "dypai/types/endpoints.gen.ts",
-      contract_path: "dypai/types/endpoints.contract.json",
-      endpoints: outcome.endpoints.slice(0, 50),
-      diagnostics_summary: outcome.diagnosticCount
-        ? {
-            total: outcome.diagnosticCount,
-            errors: outcome.errorCount,
-            warnings: outcome.warningCount,
-            sample: outcome.diagnostics,
-          }
-        : undefined,
-      hint: outcome.endpointCount
-        ? `Types refreshed for ${outcome.endpointCount} endpoint(s). Frontend can import from dypai/types/endpoints.gen.ts.${outcome.errorCount ? " Backend errors were found; run dypai_validate before trusting frontend call sites." : ""}`
-        : "No effective endpoints found — types file is empty.",
-    }
+    return buildSuccessResponse(outcome)
   },
 }
 
 export const __testing = {
   runGenerateEndpointTypes,
+  resolveGenerateTypesRoot,
+  buildSuccessResponse,
+  writeGeneratedArtifacts,
 }

package/src/tools/sync/planner.js

@@ -16,6 +16,7 @@ import { deserializeEndpoint, serializeEndpoint } from "./codec.js"
 import {
   runEffectiveWorkflows,
 } from "../../lib/effective-workflows-runner.js"
+import { findEndpointNameCollisions } from "./endpoint-names.js"
 
 const ENDPOINT_NAME_RE = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/
 
@@ -71,27 +72,51 @@ export async function readLocalStateSnapshot(rootDir) {
   }
 }
 
+export function mergeLocalStateSnapshot({ currentState, rows, endpointResults, projectId, now = new Date() }) {
+  const compatibleState = currentState?.project_id === projectId ? currentState : null
+  const endpoints = { ...(compatibleState?.endpoints || {}) }
+  const unresolvedEndpoints = { ...(compatibleState?.unresolved_endpoints || {}) }
+  const rowsByName = Object.fromEntries((rows || []).map((row) => [row.name, row]))
+
+  for (const result of endpointResults || []) {
+    if (result?.resource_type && result.resource_type !== "endpoint") continue
+    const name = result?.name
+    if (!name) continue
+    if (result.action === "delete") {
+      delete endpoints[name]
+      delete unresolvedEndpoints[name]
+      continue
+    }
+    const row = rowsByName[name]
+    if (!row) continue
+    endpoints[name] = { id: row.id, updated_at: row.updated_at, revision: row.revision }
+    delete unresolvedEndpoints[name]
+  }
+
+  return {
+    pulled_at: compatibleState?.pulled_at || null,
+    refreshed_at: now.toISOString(),
+    project_id: projectId,
+    endpoints,
+    unresolved_endpoints: unresolvedEndpoints,
+  }
+}
+
 /**
- * Refresh .dypai/state.json from live remote endpoint timestamps.
- * Call after publish/deploy so the next push does not see phantom conflicts.
+ * Merge only the endpoints that a publish response proves were promoted.
+ * A project-wide timestamp refresh is unsafe after a scoped push: unrelated
+ * local files may still be stale and must keep their previous/unresolved
+ * baseline so the next push can block correctly.
  */
-export async function refreshLocalStateSnapshot({ projectId, rootDir }) {
-  if (!projectId || !rootDir) return null
+export async function refreshLocalStateSnapshot({ projectId, rootDir, endpointResults = [] }) {
+  if (!projectId || !rootDir || !endpointResults.length) return null
   const rows = await execSql(projectId, `
-      SELECT id, name, updated_at
+      SELECT id, name, updated_at, revision
       FROM system.endpoints
       ORDER BY name
     `)
-  const successfullyPulledIds = new Set(rows.map((row) => row.id))
-  const state = {
-    pulled_at: new Date().toISOString(),
-    project_id: projectId,
-    endpoints: Object.fromEntries(
-      rows
-        .filter((row) => successfullyPulledIds.has(row.id))
-        .map((row) => [row.name, { id: row.id, updated_at: row.updated_at }]),
-    ),
-  }
+  const currentState = await readLocalStateSnapshot(rootDir)
+  const state = mergeLocalStateSnapshot({ currentState, rows, endpointResults, projectId })
   const statePath = join(rootDir, ".dypai", "state.json")
   await mkdir(join(rootDir, ".dypai"), { recursive: true })
   await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8")
@@ -166,7 +191,7 @@ export async function fetchRemoteState(projectId) {
   const endpoints = await execSql(projectId, `
       SELECT id, name, method, description, workflow_code, input, output,
              allowed_roles, is_tool, tool_description, group_id, is_active,
-             response_cardinality, updated_at
+             response_cardinality, updated_at, revision
       FROM system.endpoints
       ORDER BY name
     `)
@@ -507,6 +532,7 @@ export async function readLocalEffectiveState(rootDir, projectId = null, deps =
     byName[payload.name] = {
       source: "flow",
       file,
+      group: payload.group_name || null,
       pushPayload: payload,
       ...(shadowedMeta ? { shadowed: shadowedMeta } : {}),
     }
@@ -703,19 +729,36 @@ function findMissingCredentials(doc, credNameToId) {
  * was pulled at time T and its remote updated_at is now > T, someone modified
  * it out-of-band since the pull. Report these so the user can pull first.
  */
-function detectConflicts(stateSnapshot, remoteByName) {
+export function detectConflicts(stateSnapshot, remoteByName) {
   if (!stateSnapshot?.endpoints) return []
   const conflicts = []
+  for (const [name, unresolved] of Object.entries(stateSnapshot.unresolved_endpoints || {})) {
+    if (!remoteByName[name]) continue
+    conflicts.push({
+      endpoint: name,
+      snapshot_at: null,
+      remote_updated_at: remoteByName[name]?.updated_at || unresolved.remote_updated_at,
+      remote_revision: remoteByName[name]?.revision || unresolved.remote_revision,
+      reason: unresolved.reason || "local_source_not_reconciled",
+      local_file: unresolved.file,
+    })
+  }
   for (const [name, snap] of Object.entries(stateSnapshot.endpoints)) {
+    if (stateSnapshot.unresolved_endpoints?.[name]) continue
     const remote = remoteByName[name]
     if (!remote) continue
     const snapT = snap.updated_at ? new Date(snap.updated_at).getTime() : 0
     const remoteT = remote.updated_at ? new Date(remote.updated_at).getTime() : 0
-    if (remoteT > snapT + 1000) { // 1s tolerance for clock skew
+    const snapRevision = Number(snap.revision || 0)
+    const remoteRevision = Number(remote.revision || 0)
+    const revisionChanged = snapRevision > 0 && remoteRevision > 0 && remoteRevision !== snapRevision
+    if (revisionChanged || remoteT > snapT + 1000) { // timestamp fallback for old snapshots
       conflicts.push({
         endpoint: name,
         snapshot_at: snap.updated_at,
         remote_updated_at: remote.updated_at,
+        snapshot_revision: snapRevision || undefined,
+        remote_revision: remoteRevision || undefined,
       })
     }
   }
@@ -729,6 +772,17 @@ export function computePlan(local, remote, mapsCtx, { deleteOrphans = false, sta
   const plan = { create: [], update: [], delete: [], unchanged: [] }
   const warnings = []
 
+  const endpointNameCollisions = findEndpointNameCollisions(Object.keys(remote?.byName || {}))
+  if (endpointNameCollisions.length) {
+    warnings.push({
+      type: "canonical_endpoint_name_collisions",
+      count: endpointNameCollisions.length,
+      examples: endpointNameCollisions.slice(0, 25),
+      truncated: endpointNameCollisions.length > 25,
+      hint: "Legacy underscore and canonical hyphen slugs coexist remotely. They are separate APIs; audit callers before deleting either form.",
+    })
+  }
+
   // ── Groups plan ──────────────────────────────────────────────────────
   // Groups are 100% folder-driven: each first-level subfolder in endpoints/
   // IS a group. The remote is made to match the local folder structure
@@ -737,7 +791,7 @@ export function computePlan(local, remote, mapsCtx, { deleteOrphans = false, sta
   // group is re-created automatically. Zero friction.
   const localGroups = new Set()
   for (const entry of Object.values(local.byName)) {
-    const g = entry?.doc?.group
+    const g = entry?.group || entry?.doc?.group || entry?.pushPayload?.group_name
     if (g) localGroups.add(g)
   }
   const remoteGroupNames = new Set(Object.keys(mapsCtx.groupNameToId || {}))